The pithy-xml Reference Manual

Table of Contents

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

The pithy-xml Reference Manual

This is the pithy-xml Reference Manual, generated automatically by Declt version 2.3 "Robert April" on Tue Feb 20 09:10:44 2018 GMT+0.


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

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.


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

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 (file)

Component

pithy-xml.lisp (file)


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

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 files   [Contents][Index]

3.1.1 pithy-xml.asd

Location

pithy-xml.asd

Systems

pithy-xml (system)


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

3.1.2 pithy-xml/pithy-xml.lisp

Parent

pithy-xml (system)

Location

pithy-xml.lisp

Packages
Exported Definitions
Internal Definitions

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

4 Packages

Packages are listed by definition order.


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

4.1 html

Source

pithy-xml.lisp (file)

Nickname

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


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

4.2 xml-schema-instance

Source

pithy-xml.lisp (file)

Nickname

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


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

4.3 xml-schema

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

Source

pithy-xml.lisp (file)

Nicknames

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

4.4 xmlns

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

Source

pithy-xml.lisp (file)

Nicknames

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

4.5 pithy-xml.xml

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

Source

pithy-xml.lisp (file)

Nickname

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


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

4.6 pithy-xml

Source

pithy-xml.lisp (file)

Use List

common-lisp

Exported Definitions
Internal Definitions

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

5 Definitions

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


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

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [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 (file)

Special Variable: *make-xml-namespace*

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

Package

pithy-xml

Source

pithy-xml.lisp (file)

Special Variable: *namespace-bindings*

The active mappings from qualifiers to namespaces.

Package

pithy-xml

Source

pithy-xml.lisp (file)

Special Variable: *xml-acronyms*

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

Package

pithy-xml

Source

pithy-xml.lisp (file)

Special Variable: *xml-entities*
Package

pithy-xml

Source

pithy-xml.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

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 (file)

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 (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.3 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 (file)

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 (file)

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 (file)

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 (file)

Function: parse-xml-element ELEMENT

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

Package

pithy-xml

Source

pithy-xml.lisp (file)

Function: print-xml SEXPR &key STREAM INDENT-LEVEL INDENTATION (NO-NAMESPACE-BINDING *PRINT-NO-NAMESPACE-BINDING*) (NAMESPACE-BINDINGS *NAMESPACE-BINDINGS*) (DEFAULT-NAMESPACE *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 (file)

Function: read-xml STREAM-OR-STRING &key TYPE (DEFAULT-NAMESPACE *DEFAULT-NAMESPACE*) (NAMESPACE-BINDINGS *NAMESPACE-BINDINGS*) PREPEND

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

Package

pithy-xml

Source

pithy-xml.lisp (file)

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 (file)

Function: read-xml-file PATH &key EXTERNAL-FORMAT TYPE (XML-ENTITIES *XML-ENTITIES*)

Read all the contents from file at PATH.

Package

pithy-xml

Source

pithy-xml.lisp (file)

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 (file)


Previous: , Up: Exported definitions   [Contents][Index]

5.1.4 Types

Type: xml-comment ()

An XML comment.

Package

pithy-xml

Source

pithy-xml.lisp (file)

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 (file)


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

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Special variables

Special Variable: *default-namespace*
Package

pithy-xml

Source

pithy-xml.lisp (file)

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 (file)

Special Variable: *namespace-plists*

Properties for each namespace/package.

Package

pithy-xml

Source

pithy-xml.lisp (file)

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 (file)

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

When encountering an unknown package, map to default namespace?

Package

pithy-xml

Source

pithy-xml.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.2 Functions

Function: default-set-external-format STREAM ENCODING

Attempt to verify that STREAM is compatible with ENCODING.

Package

pithy-xml

Source

pithy-xml.lisp (file)

Function: parse-doctype DOCTYPE
Package

pithy-xml

Source

pithy-xml.lisp (file)

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 (file)

Function: unquote STRING
Package

pithy-xml

Source

pithy-xml.lisp (file)

Function: xml-file-encoding PATH

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

Package

pithy-xml

Source

pithy-xml.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

5.2.3 Types

Type: xs%boolean ()

xs:boolean

Package

pithy-xml

Source

pithy-xml.lisp (file)

Type: xs%int ()

xs:int

Package

pithy-xml

Source

pithy-xml.lisp (file)

Type: xs%integer ()

xs:integer

Package

pithy-xml

Source

pithy-xml.lisp (file)

Type: xs%long ()

xs:long

Package

pithy-xml

Source

pithy-xml.lisp (file)

Type: xs%string ()

xs:string

Package

pithy-xml

Source

pithy-xml.lisp (file)


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

Appendix A Indexes


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

A.1 Concepts

Jump to:   F   L   P  
Index Entry  Section

F
File, Lisp, pithy-xml.asd: The pithy-xml<dot>asd file
File, Lisp, pithy-xml/pithy-xml.lisp: The pithy-xml/pithy-xml<dot>lisp file

L
Lisp File, pithy-xml.asd: The pithy-xml<dot>asd file
Lisp File, pithy-xml/pithy-xml.lisp: The pithy-xml/pithy-xml<dot>lisp file

P
pithy-xml.asd: The pithy-xml<dot>asd file
pithy-xml/pithy-xml.lisp: The pithy-xml/pithy-xml<dot>lisp file

Jump to:   F   L   P  

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: Exported functions

D
default-set-external-format: Internal functions
define-xml-namespace: Exported macros
define-xml-namespace-by-schema: Exported macros

E
entity: Exported functions

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

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

P
parse-doctype: Internal functions
parse-xml-element: Exported functions
print-xml: Exported functions

R
read-schema-symbols: Internal functions
read-xml: Exported functions
read-xml-document: Exported functions
read-xml-file: Exported functions

U
unquote: Internal functions

X
xml-file-encoding: Internal functions
xml-intern: Exported functions

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

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

A.3 Variables

Jump to:   *  
S  
Index Entry  Section

*
*default-namespace*: Internal special variables
*default-set-external-format*: Exported special variables
*intern-unknown-symbols*: Internal special variables
*make-xml-namespace*: Exported special variables
*namespace-bindings*: Exported special variables
*namespace-plists*: Internal special variables
*print-no-namespace-binding*: Internal special variables
*unknown-package-is-default-namespace-p*: Internal special variables
*xml-acronyms*: Exported special variables
*xml-entities*: Exported special variables

S
Special Variable, *default-namespace*: Internal special variables
Special Variable, *default-set-external-format*: Exported special variables
Special Variable, *intern-unknown-symbols*: Internal special variables
Special Variable, *make-xml-namespace*: Exported special variables
Special Variable, *namespace-bindings*: Exported special variables
Special Variable, *namespace-plists*: Internal special variables
Special Variable, *print-no-namespace-binding*: Internal special variables
Special Variable, *unknown-package-is-default-namespace-p*: Internal special variables
Special Variable, *xml-acronyms*: Exported special variables
Special Variable, *xml-entities*: Exported special variables

Jump to:   *  
S  

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

A.4 Data types

Jump to:   H   P   S   T   X  
Index Entry  Section

H
html: The html package

P
Package, html: The html package
Package, pithy-xml: The pithy-xml package
Package, pithy-xml.xml: The pithy-xml<dot>xml package
Package, xml-schema: The xml-schema package
Package, xml-schema-instance: The xml-schema-instance package
Package, xmlns: The xmlns package
pithy-xml: The pithy-xml system
pithy-xml: The pithy-xml package
pithy-xml.xml: The pithy-xml<dot>xml package

S
System, pithy-xml: The pithy-xml system

T
Type, xml-comment: Exported types
Type, xml-element: Exported types
Type, xs%boolean: Internal types
Type, xs%int: Internal types
Type, xs%integer: Internal types
Type, xs%long: Internal types
Type, xs%string: Internal types

X
xml-comment: Exported types
xml-element: Exported types
xml-schema: The xml-schema package
xml-schema-instance: The xml-schema-instance package
xmlns: The xmlns package
xs%boolean: Internal types
xs%int: Internal types
xs%integer: Internal types
xs%long: Internal types
xs%string: Internal types

Jump to:   H   P   S   T   X