About cxml:
Other functions in cxml
- qname -- Qualified name, a string.
- value -- Any value understood by unparse-attribute, in particular strings.
Collects an attribute for the start tag that is currently being written.
This function may only be called during the extent of a use of with-element or with-element*, and only before the first child node has been written.
An attribute for the current element is recorded using the namespace prefix and local name specified by qname. The attribute's namespace prefix is resolved to a namespace URI using the bindings established by with-namespace,and that namespace URI is used for the attribute.
- prefix -- Namespace prefix, a string.
- lname -- Local name, a string.
- value -- Any value understood by unparse-attribute, in particular strings.
Collects an attribute for the start tag that is currently being written.
This function may only be called during the extent of a use of with-element or with-element*, and only before the first child node has been written.
An attribute for the current element is recorded using the namespace prefix and local name specified by arguments. prefix is resolved to a namespace URI using the bindings established by with-namespace, and that namespace URI is used for the attribute.
- instance -- A broadcast-handler
Returns the list of SAX handlers that arechained to this broadcast handler.
- data -- Sstring.
Writes a CDATA section to the current output sink, using data as its contents.
Note: It is currently the caller's responsibily to ensure that the CDATA section will not contain forbidden character sequences.
No documentation string. Possibly unimplemented or incomplete.
- data -- Sstring.
Writes a comment to the current output sink, using data as its contents.
Note: It is currently the caller's responsibily to ensure that data does not contain character sequences forbidden for comments.
- name -- Element name, a string.
- public-id -- String
- system-id -- A system ID as a puri:uri.
- internal-subset -- nil or a string
Writes a doctype declaration to the current output sink, using the specified name, public ID, system ID, and optionally an internal subset.
No documentation string. Possibly unimplemented or incomplete.
- handlers -- A list of SAX handlers.
Creates a SAX handler which passes every event it receives on to each handler specified as an argument to this function.
See broadcast-handler for details.
No documentation string. Possibly unimplemented or incomplete.
- stream -- A character stream.
Returns a handler that writes processes SAX events by writing an equivalent XML document to stream.
The sink will return stream as a result from sax:end-document.
All sink creation functions share the same keyword arguments. Refer to make-octet-vector-sink for details on keyword arguments.
No documentation string. Possibly unimplemented or incomplete.
- chained-handler -- A SAX handler.
Return a SAX handler that performs DOM 3-style namespace normalization on attribute lists in sax:start-element events before passing them on the next handler.
- stream -- An (unsigned-byte 8) stream.
Returns a handler that writes processes SAX events by writing an equivalent XML document to stream.
The sink will return stream as a result from sax:end-document.
All sink creation functions share the same keyword arguments. Refer to make-octet-vector-sink for details on keyword arguments.
- canonical -- canonical form, one of NIL, T, 1, 2. If specified, serialization in canonical form is enabled. The two canonical forms are useful to allow comparisons of XML documents and their content model by character-by-character comparisons of their serialized representation.
- indentation -- indentation level. An integer or nil. If specified, a pretty-printing indentation mode is enabled. Note that indentation as implemented currently changes the content model unconditionally, and is usually helpful only for debugging purposes.
- encoding -- the character encoding to use. A string or keyword. Values are interpreted by Babel. nil is also allowed and means UTF-8.
- omit-xml-declaration -- Boolean. If true, no XML declaration is written.
Returns a handler that writes processes SAX events by writing an equivalent XML document to a newly allocated vector of (unsigned-byte 8).
The following values for canonical are allowed:
- t or 1: Canonical XML
- 2: Second Canonical Form
- NIL: Use a more readable non-canonical representation.
The sink will return the vector as a result from sax:end-document.
An internal subset will be included in the result regardless of the canonical setting. It is the responsibility of the caller to not report an internal subset for canonical <= 1, or only notations as required for canonical = 2. For example, the include-doctype argument to dom:map-document should be set to nil for the former behaviour and :canonical-notations for the latter.
No documentation string. Possibly unimplemented or incomplete.
Returns a handler that writes processes SAX events by writing an equivalent XML document to a newly allocated string of unicode characters (or on implementations without unicode support: a rod).
The sink will return the string (or rod) as a result from sax:end-document.
All sink creation functions share the same keyword arguments. Refer to make-octet-vector-sink for details on keyword arguments.
No documentation string. Possibly unimplemented or incomplete.
Returns a handler that writes processes SAX events by writing an equivalent XML document to a newly allocated string of unicode characters.
The sink will return the string as a result from sax:end-document.
All sink creation functions share the same keyword arguments. Refer to make-octet-vector-sink for details on keyword arguments.
- dtd -- An dtd instance.
- root -- Element name, a string.
Create a SAX handler which validates against a DTD instance. The document's root element must be named root. Used with dom:map-document, this validates a document object as if by re-reading it with a validating parser, except that declarations recorded in the document instance are completely ignored.
Example:
(let ((d (parse-file "~/test.xml" (cxml-dom:make-dom-builder))) (x (parse-dtd-file "~/test.dtd"))) (dom:map-document (cxml:make-validator x #"foo") d))
No documentation string. Possibly unimplemented or incomplete.
- input -- A string, pathname, octet vector, or stream.
- handler -- A SAX handler
- validate -- Boolean. Defaults to nil. If true, parse in validating mode, i.e. assert that the document contains a DOCTYPE declaration and conforms to the DTD declared.
- dtd -- unless nil, an extid instance specifying the external subset to load. This options overrides the extid specified in the document type declaration, if any. See below for make-extid. This option is useful for verification purposes together with the root and disallow-internal-subset arguments.
- root -- The expected root element name, or nil (the default). If specified, this argument overrides the name stated in the input's DOCTYPE (if any).
- entity-resolver -- nil or a function of two arguments which is invoked for every entity referenced by the document with the entity's Public ID (a rod) and System ID (an URI object) as arguments. The function may either return nil, CXML will then try to resolve the entity as usual. Alternatively it may return a Common Lisp stream specialized on (unsigned-byte 8) which will be used instead. (It may also signal an error, of course, which can be useful to prohibit parsed XML documents from including arbitrary files readable by the parser.)
- disallow-internal-subset -- Boolean. If true, signal an error if the document contains an internal subset.
- recode -- Boolean. (Ignored on Lisps with Unicode support.) Recode rods to UTF-8 strings. Defaults to true. Make sure to use utf8-dom:make-dom-builder if this option is enabled and rune-dom:make-dom-builder otherwise.
Parse an XML document from input, which can be a string, pathname, octet vector, or stream.
Return values from this function depend on the SAX handler used. This is an old-style convenience wrapper around the new-style interface parse.
Parse an XML document from filename, and signal SAX events to handler while doing so.
All SAX parsing functions share the same keyword arguments. Refer to parse for details on keyword arguments.
- filename -- An pathname designator.
- handler -- A SAX handler
Parse declarations from filename and return an object representing the DTD, suitable as an argument to validate with parse.
- stream -- An (unsigned-byte 8) stream.
- handler -- A SAX handler
Parse declarations from stream and return an object representing the DTD, suitable as an argument to validate with parse.
- uri -- a string or nil
- qname -- a string or nil
- handler -- a SAX handler
- public-id -- a string or nil
- system-id -- a puri:uri or nil
- entity-resolver -- nil or a function of two arguments which is invoked for every entity referenced by the document with the entity's Public ID (a rod) and System ID (an URI object) as arguments. The function may either return nil, CXML will then try to resolve the entity as usual. Alternatively it may return a Common Lisp stream specialized on (unsigned-byte 8) which will be used instead. (It may also signal an error, of course, which can be useful to prohibit parsed XML documents from including arbitrary files readable by the parser.)
- recode -- Boolean. (Ignored on Lisps with Unicode support.) Recode rods to UTF-8 strings. Defaults to true. Make sure to use utf8-dom:make-dom-builder if this option is enabled and rune-dom:make-dom-builder otherwise.
Simulate parsing of a document with a document element qname having no attributes except for an optional namespace declaration to uri. If an external ID is specified (system-id, public-id), find, parse, and report this DTD as if with parse-file, using the specified entity resolver.
- filename -- An pathname designator.
- handler -- A SAX handler
This is an old-style convenience wrapper around the new-style interface parse.
Parse an XML document from filename, and signal SAX events to handler while doing so.
All SAX parsing functions share the same keyword arguments. Refer to parse for details on keyword arguments.
- octets -- An (unsigned-byte 8) vector.
- handler -- A SAX handler
This is an old-style convenience wrapper around the new-style interface parse.
Parse an XML document from octets, and signal SAX events to handler while doing so.
All SAX parsing functions share the same keyword arguments. Refer to parse for details on keyword arguments.
- string -- An string of unicode characters.
- handler -- A SAX handler
This is an old-style convenience wrapper around the new-style interface parse.
Parse an XML document from string, and signal SAX events to handler while doing so.
Note: This function assumes that string has already been decoded into Unicode runes and ignores the encoding specified in the XML declaration, if any.
All SAX parsing functions share the same keyword arguments. Refer to parse for details on keyword arguments.
- stream -- An (unsigned-byte 8) stream
- handler -- A SAX handler
This is an old-style convenience wrapper around the new-style interface parse.
Parse an XML document from stream, and signal SAX events to handler while doing so.
All SAX parsing functions share the same keyword arguments. Refer to parse for details on keyword arguments.
- target -- Sstring.
- data -- Sstring.
Writes a processing instruction to the current output sink, using target and data as its contents.
Note: It is currently the caller's responsibily to ensure that target and data do not contain character sequences forbidden for processing instruction contents.
No documentation string. Possibly unimplemented or incomplete.
No documentation string. Possibly unimplemented or incomplete.
No documentation string. Possibly unimplemented or incomplete.
No documentation string. Possibly unimplemented or incomplete.
No documentation string. Possibly unimplemented or incomplete.
No documentation string. Possibly unimplemented or incomplete.
- data -- Sstring.
Writes a text node to the current output sink, using data as its contents.
Note: It is currently the caller's responsibily to ensure that data does not contain characters forbidden for character data.
- data -- Sstring.
If supported by the current output sink, writes character data directly to the sink's target.
Use of this function is often an indicator of bad design. Avoid it if you can. (Implementation note: This function is supported because XSLT's XML output method requires it.)
No documentation string. Possibly unimplemented or incomplete.
No documentation string. Possibly unimplemented or incomplete.
No documentation string. Possibly unimplemented or incomplete.
No documentation string. Possibly unimplemented or incomplete.
No documentation string. Possibly unimplemented or incomplete.
No documentation string. Possibly unimplemented or incomplete.
No documentation string. Possibly unimplemented or incomplete.
No documentation string. Possibly unimplemented or incomplete.
No documentation string. Possibly unimplemented or incomplete.
No documentation string. Possibly unimplemented or incomplete.
No documentation string. Possibly unimplemented or incomplete.
Other macros in cxml
- qname -- A string, evaluated.
- body -- forms, an implicit progn
Writes an element to the current output sink.
This macro is a convenience wrapper around with-element*.
qname is parsed to determine the element's namespace prefix and local name. Then with-element* is called on body using the resulting values.
- prefix -- Namespace prefix, a string (evaluated).
- lname -- Local name, a string (evaluated).
- body -- forms, an implicit progn
Writes an element to the current output sink.
First, prefix is resolved to a namespace URI using the bindings established by with-namespace.
Next, body is evaluated as an implicit progn. During this time, attributes for the element can be specified using attribute.
Once information on the start tag is complete, start-element on the current output sink, using the specified namespace prefix and local name specified by the arguments, the namespace URI computed as described above,and including all attributes collected so far.
Information on the start tag is considered complete once the first of the following situations occurs:
- Before any child node of the element is written, e.g. using an inner call of with-element,
- Before the body of with-ouptut-sink is evaluated.
- After the end of body has been reached.
Finally, sax:end-element is used to write an end tag, using the same qualified name and namespace information as above.
- prefix -- Namespace prefix, a string (evaluated).
- uri -- Namespace URI, a string (evaluated).
- body -- forms, an implicit progn
Registers prefix as a name for the namespace URI uri for the extent of body.
Namespace bindings established by with-namespace are used by with-element and with-element* as well as attribute and attribute*.
- var -- A symbol, not evaluated.
- body -- forms, an implicit progn
Allows safe use of manual calls to SAX functions during the extent of with-xml-output,
Determines the current output sink established by with-xml-output, as used by convenience serialization functions. Writes delayed serialization events to the sink. Binds local variable var to the sink and evaluates body as an implicit progn.
The consequences are undefined if this macro is used outside of the extent of a call to with-xml-output.
See with-xml-output for details on delayed events.
- sink -- A SAX handler, evaluated
- body -- forms
Evaluates sink and establishes it as the current output sink for the following "convenience serialization" macros and functions: with-element, with-namespace, doctype, with-element*, attribute, attribute*, text comment, processing-instruction, unescaped.
Before body is evaluated, sax:start-document is signalled to the sink. Afterwards, sax:end-document is signalled.
Note that convenience serialization delays some serialization events. For example, with-element delays signalling an opening tag using sax:start-element until it has information about all possible attributes of the element. Because of this delay, it is not usually safe to signal SAX events to the sink during the extent of with-xml-output. However, with-output-sink can be used to force output of delayed events, allowing direct use of the sink.
Example:
(with-xml-output (make-octet-stream-sink stream) (with-element "foo" (attribute "xyz" "abc") (with-element "bar" (attribute "blub" "bla")) (text "Hi there.")))
Other classes in cxml
You can subclass broadcast-handler to modify the events before they are being passed on. Define methods on your handler class for the events to be modified. All other events will pass through to the chained handlers unmodified.
Broadcast handler functions return the result of calling the event function on the last handler in the list. In particular, the overall result from sax:end-document will be ignored for all other handlers.
This class is still included for compatibility with older versions of CXML which did not include the more general broadcast-handler yet, but has been retrofitted as a subclass of the latter.
Note for validating mode: Sometimes violations of well-formedness are first detected as validity errors by the parser and signalled as instances of validity-error rather than well-formedness-violation.
Other variables in cxml
No documentation string. Possibly unimplemented or incomplete.
No documentation string. Possibly unimplemented or incomplete.
No documentation string. Possibly unimplemented or incomplete.
No documentation string. Possibly unimplemented or incomplete.
Index of exported symbols
cxml: | *cache-all-dtds*, variable (undocumented) |
cxml: | *catalog*, variable (undocumented) |
cxml: | *dtd-cache*, variable (undocumented) |
cxml: | *prefer*, variable (undocumented) |
cxml: | attribute, function |
cxml: | attribute*, function |
cxml: | broadcast-handler, class |
cxml: | broadcast-handler-handlers, function |
cxml: | cdata, function |
cxml: | clear-dtd-cache, function (undocumented) |
cxml: | close-xstream, function (undocumented) |
cxml: | comment, function |
cxml: | doctype, function |
cxml: | fpeek-rune, function (undocumented) |
cxml: | fread-rune, function (undocumented) |
cxml: | getdtd, function (undocumented) |
cxml: | make-broadcast-handler, function |
cxml: | make-catalog, function (undocumented) |
cxml: | make-character-stream-sink, function |
cxml: | make-dtd-cache, function (undocumented) |
cxml: | make-extid, function |
cxml: | make-namespace-normalizer, function |
cxml: | make-octet-stream-sink, function |
cxml: | make-octet-vector-sink, function |
cxml: | make-recoder, function (undocumented) |
cxml: | make-rod-sink, function |
cxml: | make-rod-xstream, function (undocumented) |
cxml: | make-source, function (undocumented) |
cxml: | make-string-sink, function |
cxml: | make-validator, function |
cxml: | make-whitespace-normalizer, function (undocumented) |
cxml: | make-xstream, function (undocumented) |
cxml: | parse, function |
cxml: | parse-dtd-file, function |
cxml: | parse-dtd-stream, function |
cxml: | parse-empty-document, function |
cxml: | parse-file, function |
cxml: | parse-octets, function |
cxml: | parse-rod, function |
cxml: | parse-stream, function |
cxml: | peek-rune, macro |
cxml: | processing-instruction, function |
cxml: | proxy-chained-handler, function (undocumented) |
cxml: | read-rune, macro |
cxml: | remdtd, function (undocumented) |
cxml: | resolve-extid, function (undocumented) |
cxml: | resolve-uri, function (undocumented) |
cxml: | rod-to-utf8-string, function (undocumented) |
cxml: | sax-proxy, class |
cxml: | sink-encoding, function (undocumented) |
cxml: | sink-omit-xml-declaration-p, function (undocumented) |
cxml: | text, function |
cxml: | unescaped, function |
cxml: | unparse-attribute, function (undocumented) |
cxml: | unread-rune, function |
cxml: | utf8-string-to-rod, function (undocumented) |
cxml: | validity-error, function (undocumented) |
cxml: | validity-error, class |
cxml: | well-formedness-violation, class |
cxml: | with-element, macro |
cxml: | with-element*, macro |
cxml: | with-namespace, macro |
cxml: | with-output-sink, macro |
cxml: | with-xml-output, macro |
cxml: | xml-parse-error, class |
cxml: | xstream-column-number, function (undocumented) |
cxml: | xstream-encoding, function |
cxml: | xstream-line-number, function |
cxml: | xstream-plist, function |
cxml: | xstream-position, function (undocumented) |