The pithy-xml Reference Manual

Next: , Previous: , Up: (dir)   [Contents][Index]

The pithy-xml Reference Manual

This is the pithy-xml Reference Manual, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon Aug 15 05:35:16 2022 GMT+0.

Table of Contents


1 Introduction

Read and write XML as lisp objects. Syntax somewhat similar to that of
CL-WHO.

Disregarding interning (see below), an XML element ...
is represented in either of two ways:

  (:foo :a 1 ...)  or  ((:foo :a 1) ...)

READ-XML will always return the latter form, because it is more
consistent for processing. The former is perhaps more convenient to
write: the element's content starts with the first
non-keyword/value-pair.

Tag names etc. are mapped to (and from) lisp symbols. XML namespaces
are represented as lisp packages, into which symbols are
interned. Note that XML namespaces are named by (globally unique)
URLs, although you'll probably find it convenient to provide
short-hand names (see DEFINE-XML-NAMESPACE). Read/print-xml will keep
track of namespace bindings. In the following example, the same "foo"
is referenced in the two XML fragments, using first "qualified names"
and second "namespace defaulting":

> (equal (cdr (read-xml "42"))
         (print (cdr (read-xml "42"))))

((NN:FOO "42"))
=> T


XML comments are represented as (pithy-xml:xml-comment "text"). If you
don't care about XML namespaces, use keywords. For example:

PITHY-XML> (read-xml (print (print-xml '(:element :attribute 1 (:sub-element 42)))))
"
   42
 " 
=> (((:ELEMENT :ATTRIBUTE "1") ((:SUB-ELEMENT) "42")))



Here's an example of using DEFINE-XML-NAMESPACE-BY-SCHEMA:

  (define-xml-namespace-by-schema
      xmldsig
      "http://www.w3.org/2000/09/xmldsig#"
    "~/src/xml-schemas/xmldsig-core-schema.xsd"
    (:acronyms "HMAC" "SKI" "CRL" "PGP" "SPKI" "DSA" "RSA" "ID")
    (:documentation "http://www.w3.org/TR/xmldsig-core/"))


Pithy-XML does not support all features of XML. There are various
issues with defining entities, CDATA, etc that I've yet to have use
for, and therefore have not implemented. Feel free to improve on this.


2 Systems

The main system appears first, followed by any subsystem dependency.


Previous: , Up: Systems   [Contents][Index]

2.1 pithy-xml

Source

pithy-xml.asd.

Child Component

pithy-xml.lisp (file).


3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp   [Contents][Index]

3.1.1 pithy-xml/pithy-xml.asd

Source

pithy-xml.asd.

Parent Component

pithy-xml (system).

ASDF Systems

pithy-xml.


3.1.2 pithy-xml/pithy-xml.lisp

Source

pithy-xml.asd.

Parent Component

pithy-xml (system).

Packages
Public Interface
Internals

4 Packages

Packages are listed by definition order.


Next: , Previous: , Up: Packages   [Contents][Index]

4.1 html

Source

pithy-xml.lisp.

Nickname

http://www.w3.org/1999/xhtml


Next: , Previous: , Up: Packages   [Contents][Index]

4.2 xml-schema-instance

Source

pithy-xml.lisp.

Nickname

http://www.w3.org/2001/xmlschema-instance


Next: , Previous: , Up: Packages   [Contents][Index]

4.3 xmlns

http://www.w3.org/TR/REC-xml-names/

Source

pithy-xml.lisp.

Nicknames
  • pithy-xml.xmlns
  • http://www.w3.org/2000/xmlns/

Next: , Previous: , Up: Packages   [Contents][Index]

4.4 pithy-xml

Source

pithy-xml.lisp.

Use List

common-lisp.

Public Interface
Internals

Next: , Previous: , Up: Packages   [Contents][Index]

4.5 xml-schema

Symbols from the XML meta-schema at http://www.w3.org/2001/XMLSchema.xsd

Source

pithy-xml.lisp.

Nicknames
  • xsd
  • http://www.w3.org/2001/xmlschema

Previous: , Up: Packages   [Contents][Index]

4.6 pithy-xml.xml

http://www.w3.org/TR/REC-xml-names/

Source

pithy-xml.lisp.

Nickname

http://www.w3.org/xml/1998/namespace


5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Public Interface


Next: , Previous: , Up: Public Interface   [Contents][Index]

5.1.1 Special variables

Special Variable: *default-set-external-format*

Function to be called to set a STREAM’s EXTERNAL-FORMAT.

Package

pithy-xml.

Source

pithy-xml.lisp.

Special Variable: *make-xml-namespace*

Called whenver a non-existing namespace is encountered. Return package to use.

Package

pithy-xml.

Source

pithy-xml.lisp.

Special Variable: *namespace-bindings*

The active mappings from qualifiers to namespaces.

Package

pithy-xml.

Source

pithy-xml.lisp.

Special Variable: *xml-acronyms*

Default list of acronyms. These strings will not be (de)camelized.

Package

pithy-xml.

Source

pithy-xml.lisp.

Special Variable: *xml-entities*
Package

pithy-xml.

Source

pithy-xml.lisp.


5.1.2 Macros

Macro: define-xml-namespace (name url &rest options)

Define a package/namespace. NAME is a short-hand name, while URL is the canonical XML namespace name which will become a nickname for the package. Extra options are ACRONYMS which lists a set of acronyms (for tweaking the XML<->symbol mapping), and LOCK which is whether symbols should automatically be interned for this package/namespace by READ-XML.

Package

pithy-xml.

Source

pithy-xml.lisp.

Macro: define-xml-namespace-by-schema (name url schema-path &rest options)

Declare a namespace by reading symbols from an XML schema file. Defaults :LOCK to true.

Package

pithy-xml.

Source

pithy-xml.lisp.


Next: , Previous: , Up: Public Interface   [Contents][Index]

5.1.3 Ordinary functions

Function: camel (stream string &optional colon at)

Convert a hyphenated-name to CamelCase, unless it already is. Encode XML entities. Convert ’%’ to ’:’.

Package

pithy-xml.

Source

pithy-xml.lisp.

Function: entity (stream content &optional colon at)

Print CONTENT to STREAM, encoding characters with XML entities according to *XML-ENTITIES*.

Package

pithy-xml.

Source

pithy-xml.lisp.

Function: find-descendant (parent &rest path)

Locate a descendant of PARENT according to PATH. Each path element either names the child element, or is an integer child index.

Package

pithy-xml.

Source

pithy-xml.lisp.

Function: map-elements (function document)

For each element in DOCUMENT, apply FUNCTION to the name and attribute plist. Recurse into contents when FUNCTION returns true.

Package

pithy-xml.

Source

pithy-xml.lisp.

Function: parse-xml-element (element)

Return the element’s contents, attributes, and name.

Package

pithy-xml.

Source

pithy-xml.lisp.

Function: print-xml (sexpr &key stream indent-level indentation no-namespace-binding namespace-bindings default-namespace)

Serialize sexpr into XML.
Return a boolean indicating if sexpr was ’complex’ enough to requre a newline and indentation. The syntax is approximately like that of CL-WHO.

Package

pithy-xml.

Source

pithy-xml.lisp.

Function: read-xml (stream-or-string &key type default-namespace namespace-bindings prepend)

Read the first XML element from STREAM-OR-STRING that matches TYPE.

Package

pithy-xml.

Source

pithy-xml.lisp.

Function: read-xml-document (document-stream-or-string &rest key-args &key set-external-format type namespace-mode default-namespace namespace-bindings)

Like READ-XML, but process encoding directives by applying SET-EXTERNAL-FORMAT to the stream and encoding, if specified in the document.

Package

pithy-xml.

Source

pithy-xml.lisp.

Function: read-xml-file (path &key external-format type xml-entities)

Read all the contents from file at PATH.

Package

pithy-xml.

Source

pithy-xml.lisp.

Function: xml-intern (string &key stringp)

Decamelize, intern, etc. STRING into a symbol, or just the string if STRINGP is true.

Package

pithy-xml.

Source

pithy-xml.lisp.


5.1.4 Types

Type: xml-comment ()

An XML comment.

Package

pithy-xml.

Source

pithy-xml.lisp.

Type: xml-element (&optional name content)

Either (name ...) or ((name ...) ...), or any element that is not a comment.

Package

pithy-xml.

Source

pithy-xml.lisp.


5.2 Internals


Next: , Previous: , Up: Internals   [Contents][Index]

5.2.1 Special variables

Special Variable: *default-namespace*
Package

pithy-xml.

Source

pithy-xml.lisp.

Special Variable: *intern-unknown-symbols*

When encountering a symbol that doesn’t already exist in the namespace, and LOCK us undefined for the namespace, intern it?

Package

pithy-xml.

Source

pithy-xml.lisp.

Special Variable: *namespace-plists*

Properties for each namespace/package.

Package

pithy-xml.

Source

pithy-xml.lisp.

Special Variable: *print-no-namespace-binding*

What to do when printing a symbol and there is no current binding for the namespace? If NIL, fail. If T, print name without namespace prefix. If :PACKAGE-NAME, use the package’s name as namespace prefix.

Package

pithy-xml.

Source

pithy-xml.lisp.

Special Variable: *unknown-package-is-default-namespace-p*

When encountering an unknown package, map to default namespace?

Package

pithy-xml.

Source

pithy-xml.lisp.


Next: , Previous: , Up: Internals   [Contents][Index]

5.2.2 Ordinary functions

Function: default-set-external-format (stream encoding)

Attempt to verify that STREAM is compatible with ENCODING.

Package

pithy-xml.

Source

pithy-xml.lisp.

Function: parse-doctype (doctype)
Package

pithy-xml.

Source

pithy-xml.lisp.

Function: read-schema-symbols (path &key expect-namespace)

Extract the relevant symbols from an XML schema in PATH.

Package

pithy-xml.

Source

pithy-xml.lisp.

Function: unquote (string)
Package

pithy-xml.

Source

pithy-xml.lisp.

Function: xml-file-encoding (path)

Return the file encoding declared for the file at PATH, if any.

Package

pithy-xml.

Source

pithy-xml.lisp.


5.2.3 Types

Type: xs%boolean ()

xs:boolean

Package

pithy-xml.

Source

pithy-xml.lisp.

Type: xs%int ()

xs:int

Package

pithy-xml.

Source

pithy-xml.lisp.

Type: xs%integer ()

xs:integer

Package

pithy-xml.

Source

pithy-xml.lisp.

Type: xs%long ()

xs:long

Package

pithy-xml.

Source

pithy-xml.lisp.

Type: xs%string ()

xs:string

Package

pithy-xml.

Source

pithy-xml.lisp.


Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts


Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   C   D   E   F   M   P   R   U   X  
Index Entry  Section

C
camel: Public ordinary functions

D
default-set-external-format: Private ordinary functions
define-xml-namespace: Public macros
define-xml-namespace-by-schema: Public macros

E
entity: Public ordinary functions

F
find-descendant: Public ordinary functions
Function, camel: Public ordinary functions
Function, default-set-external-format: Private ordinary functions
Function, entity: Public ordinary functions
Function, find-descendant: Public ordinary functions
Function, map-elements: Public ordinary functions
Function, parse-doctype: Private ordinary functions
Function, parse-xml-element: Public ordinary functions
Function, print-xml: Public ordinary functions
Function, read-schema-symbols: Private ordinary functions
Function, read-xml: Public ordinary functions
Function, read-xml-document: Public ordinary functions
Function, read-xml-file: Public ordinary functions
Function, unquote: Private ordinary functions
Function, xml-file-encoding: Private ordinary functions
Function, xml-intern: Public ordinary functions

M
Macro, define-xml-namespace: Public macros
Macro, define-xml-namespace-by-schema: Public macros
map-elements: Public ordinary functions

P
parse-doctype: Private ordinary functions
parse-xml-element: Public ordinary functions
print-xml: Public ordinary functions

R
read-schema-symbols: Private ordinary functions
read-xml: Public ordinary functions
read-xml-document: Public ordinary functions
read-xml-file: Public ordinary functions

U
unquote: Private ordinary functions

X
xml-file-encoding: Private ordinary functions
xml-intern: Public ordinary functions

Jump to:   C   D   E   F   M   P   R   U   X