This site is a static rendering of the Trac instance that was used by R7RS-WG1 for its work on R7RS-small (PDF), which was ratified in 2013. For more information, see Home. For a version of this page that may be more recent, see MicroXmlCowan in WG2's repo for R7RS-large.

Micro­Xml­Cowan

cowan
2017-08-11 00:30:17
4history
source

Events

A MicroXML event is a list representing a parsing event, in one of the following formats. Stack is a list of element names currently being processed; the first element of the list is the current element.

($start stack attr-list)

Represents a start-tag. Attr-list is a JSO representing the attributes.

($end stack)

Represents an end-tag.

($text text)

Represents character content. Text is the character content as a string.

($error stack error-code . other)

Represents a parsing error. Error-code is a symbol. Other is implementation-dependent.

($pi stack target content)

Represents a processing instruction (which is not part of MicroXML). Target is a symbol; content is a string.

($eof)

Represents the end of the document.

SXML

MicroXML uses a simplified version of SXML as the internal representation of documents. Each SXML element is a list whose first member is a symbol representing the element name, whose second member is a JSO mapping the attribute names (as symbols) to their values (as strings), and whose remaining members (if any) are either SXML elements or strings.

Input-output

Options is a list of symbols that control how MicroXML is written. All implementations recognize apos to wrap attribute values in apostrophes, empty to write empty tags for empty elements, and ascii to escape all characters outside the ASCII range. Other symbols are also allowed.

(uxml->sxml port [ handler ])

Reads a MicroXML document from port and returns the SXML equivalent. The procedure handler is invoked when a $error or $pi event is produced. The default handler signals an error that satisfies uxml-error?. If the handler is #f, errors and processing instructions are ignored.

(sxml->uxml element port options)

Writes the SXML element in MicroXML format to port, using the symbols in options.

(make-uxml-generator port)

Returns a generator of event objects representing a MicroXML document read from port.

(make-sxml-generator element)

Returns a generator of event objects representing the SXML element.

(event-generator->uxml gen port options)

Invokes the generator gen to obtain event objects and writes the corresponding MicroXML document to port, using the symbols in options. If the resulting document would not be well-formed MicroXML, an error is signaled that satisfies uxml-error?.

(event-generator->sxml gen)

Invokes the generator gen to obtain event objects, constructs the corresponding SXML element, and returns it. If the resulting object would not be well-formed SXML, an error is signaled that satisfies uxml-error?.

(write-xml port options)

Returns a procedure that accepts an event object. When invoked repeatedly, it writes the corresponding MicroXML representation to port using the symbols in options. If the resulting document would not be well-formed MicroXML, an error is signaled that satisfies uxml-error?.

(build-sxml)

Returns a procedure that accepts an event object. When invoked repeatedly, it builds the corresponding SXML representation. If the document has been fully built, the procedure returns the SXML element; if not, it returns #f. If the resulting document would not be well-formed MicroXML, an error is signaled that satisfies uxml-error?.

Predicates

(sxml-element? obj)

Returns #t if obj is an SXML element and #f otherwise. The procedure checks that obj is a list whose first element is a symbol and the second element is a JSO; further elements of the list are not examined.

(sxml-empty? element)

Returns #t if element is an empty SXML element and #f otherwise.

(sxml-wf-name? string attribute)

Returns #t if string matches the MicroXML name production if attribute? is false, or the MicroXML attribute name production if attribute? is true; returns #f otherwise.

(sxml-wf-string? string)

Returns #t if all the characters in string are allowed in MicroXML character content and #f otherwise.

(sxml-wf-element? element)

Returns #t if element is well-formed. The first element of element must be a symbol whose print name satisfies sxml-wf-name. The second element of element must be a JSO that maps symbols to strings that satisfy sxml-wf-string?. The remaining elements must be either strings that satisfy sxml-wf-string? or lists that satisfy sxml-wf-element?.

(sxml-attribute? element attr-name)

Returns #t if attr-name (a symbol) is an attribute of element and #f otherwise.

(id-valid? element id-mapping idref-list)

Returns #t if all idref attributes contain valid ids. An id is valid if it appears as a key in id-mapping (see make-id-mapping). Idref-list is a list of 2-element sublists, where the first element of each sublist is an element name and the second element is an attribute name.

(sxml-language? element language)

Returns #t if the language of element, as specified by the value of a lang or xml:lang attribute (the latter is not well-formed MicroXML but is supported for backward compatibility) matches language. If element has no such attribute, the language of the nearest ancestor of element that has such an attribute is used. If there is no such attribute at all, then sxml-language? returns #f.

The attribute value matches language if, in a case-insensitive comparison, language exactly equals the attribute value, or if language exactly equals a prefix of the attribute value such that the first character following the prefix is "-".

Element procedures

(sxml-name element)

Returns the name of element as a symbol.

(sxml-set-name element name)

(sxml-set-name! element name)

Changes the name of element to the symbol name, purely or with mutation.

(sxml-attr-list element)

Returns the attribute list of element as a JSO.

(sxml-set-attr-list element jso)

(sxml-set-attr-list! element jso)

Changes the attribute list of element to jso, purely or with mutation.

(sxml-contentelement)

Returns the name of element as a list.

(sxml-set-content element list)

(sxml-set-content! element list)

Changes the content of element to the list, purely or with mutation.

(sxml-value element)

Returns the results of concatenating all string content children in element and all its descendants in depth-first left-to-right preorder.

(sxml-defaults element attribute-defaults element-defaults inherited-attributes)

(sxml-defaults! element attribute-defaults element-defaults inherited-attributes)

Returns element with default values expanded in itself and all its descendants (purely or with mutation) as follows:

(sxml-element position element parent-map)

Returns the position of element among the element children of the parent of element as an exact integer, with 1 meaning the first element child. If there is no parent, return 0.

(sxml-element-size element)

Return the number of content children of 'element'' as an exact integer.

(sxml-normalize-element! element)

Returns a normalized version (using mutation) of an SXML element that does not necessarily conform to the definition. In particular:

(sxml-trace element traceproc)

Displays information on (current-error-port) about element. The precise nature of the information displayed is undefined, except that it should end with a newline. Element is returned.

(sxml-root element)

Returns the root element of element.

(sxml-parent element)

Uses the parent link to determine the parent of element and returns it, or #f if there is none. The parent link is stored as an attribute named $parent whose value is a SRFI 111 box containing the parent element. This pseudo-attribute is ignored by all other attribute processing. The box is used to prevent SXML elements from being circular tree structure.

(sxml-detach-parent! element parent-mapping)

Removes the mapping from element to its parent from parent-mapping. If element does not have a parent, nothing is done. Returns an unspecified value.

(sxml-make-id-mapping document)

Creates an id mapping based on the SXML element document. An id mapping is an opaque object that maps an id (a symbol) to an element. The element and all its descendants are checked for the presence of an attribute named id or xml:id (the latter is not well-formed MicroXML but is allowed in SXML for backward compatibility). If found, an entry is created in the id mapping that maps the corresponding attribute value as a symbol to the element. Returns the id mapping.

(sxml-id id id-mapping)

Looks up the symbol id in id-mapping and returns the corresponding element, or #f if there is none.

String procedures

(uxml-escape-string string attribute? apos? ascii?)

Converts string to contain the necessary entity references for MicroXML. If attribute? is false, only < & > are escaped. Otherwise, if apos? is true, ' is escaped, but if not, " is escaped. Finally, if ascii? is true, non-ASCII characters are escaped with numeric character references. All other characters are left unchanged. The escaped result is returned.

(uxml-unescape-string string)

Converts string by translating all MicroXML escapes, both entity references and numeric character references, to single characters. All other characters are left unchanged. The result is returned.

(uxml-normalize-space string)

Returns a string that is equal to string, but with all leading and trailing whitespace removed, and all other consecutive whitespace characters replaced by a single space.

Boolean conversions

These use the conventions of XPath and XML Schema.

(sxml-string->boolean string)

Converts the strings "1" and "true" to #t, and the strings "0" and false to #f. If any other string is passed, an error is signaled that satisfies uxml-error?.

(sxml-boolean->string boolean)

Converts #t to "true" and #f to "false".

(sxml-number->boolean number)

If number returns #t when zero? is applied to it, returns #f; otherwise returns #t;

(sxml-boolean->number boolean)

If boolean is true, returns 1, otherwise returns 0.

Axis procedures

The following procedures are generator operations: they accept a generator (of SXML elements) and return a generator (also of SXML elements). After the sxml- prefix, they begin with g, using the convention of SRFI 121 for generator operations.

(sxml-gparent gen)

Returns a generator of SXML elements which invokes SXML elements from gen and returns their parent elements on successive invocations.

(sxml-gancestor gen)

Returns a generator of SXML elements which invokes SXML elements from gen and returns their ancestor elements from parent to root on successive invocations.

(sxml-gancestor-or-self gen)

Returns a generator of SXML elements which invokes SXML elements from gen and returns their element itself and then its ancestor elements from parent to root on successive invocations.

(sxml-gchild gen)

Returns a generator of SXML elements which invokes SXML elements from gen and returns their descendant elements in depth-first order from left to right on successive invocations.

(sxml-gdescendant gen)

Returns a generator of SXML elements which invokes SXML elements from gen and returns their child elements from left to right on successive invocations.

(sxml-gdescendant-or-self gen)

Returns a generator of SXML elements which invokes SXML elements from gen and returns their element itself and then its child elements from left to right on successive invocations.

(sxml-gfollowing gen)

Returns a generator of SXML elements which invokes SXML elements from gen and returns all of their following elements in document order on successive invocations.

(sxml-gfollowing-or-self gen)

Returns a generator of SXML elements which invokes SXML elements from gen and returns the elements themselves and then all of their following elements in document order on successive invocations.

(sxml-gpreceding gen)

Returns a generator of SXML elements which invokes SXML elements from gen and returns all of their preceding elements in reverse document order on successive invocations.

(sxml-gpreceding-or-self gen)

Returns a generator of SXML elements which invokes SXML elements from gen and returns the elements themselves and then all of their preceding elements in reverse document order on successive invocations.

Paths

sxml-path

Error handling

Errors are signaled using objects of a disjoint type. They contain an $error or $pi event.

(uxml-error? obj)

Returns #t if obj belongs to the error type, and #f otherwise.

(uxml-error-event xml-error)

Returns an $error or $pi event (i.e. a list) encapsulated in an error object.