Common Lisp Package: CXML-STP

STP is a data structure for well-formed XML documents. @begin[Parsing and Serializing]{section} To parse into STP, use an STP builder together with a function generating SAX events: @aboutfun{make-builder} Serialize STP by sending SAX events for the tree to a sink: @aboutfun{serialize} @end{section} @begin[Names and Namespace URIs]{section} STP represents namespace-well-formed documents only. All functions accepting names take a local-name and and a namespace URI as an argument. Qualified names are accepted where it makes sense, and named nodes have a namespace prefix that is taken into account for well-formedness checks. There are two kinds of named nodes: @class{element} and @class{attribute}. Their slots are: @aboutfun{local-name} @aboutfun{namespace-uri} @aboutfun{namespace-prefix} For @code{element}, all of the above can be changed using SETF (subject to well-formedness checks). For attribute, @fun{local-name} can be changed directly, while URI and prefix always have to be changed in the same step using @fun{rename-attribute}. A node's qualified name can be be queried: @aboutfun{qualified-name} @code{of-name} is convenient when searching for elements or attributes: @aboutfun{of-name} @end{section} @begin[Subclasses of Node]{section} All STP nodes have a common superclass. @aboutclass{node} Documents and elements can have children: @aboutclass{parent-node} @aboutclass{document} @aboutclass{element} Attributes belong to an @code{element}: @aboutclass{attribute} Other kinds of nodes: @aboutclass{comment} @aboutclass{document-type} @aboutclass{processing-instruction} @aboutclass{text} @end{section} @begin[Creating nodes]{section} Nodes are created using the following functions: @aboutfun{make-attribute} @aboutfun{make-comment} @aboutfun{make-document} @aboutfun{make-document-type} @aboutfun{make-element} @aboutfun{make-processing-instruction} @aboutfun{make-text} In addition, nodes can be copied including all their children: @aboutfun{copy} @end{section} @begin[Listing Child Nodes]{section} Nodes have an optional parent node and can have children. @aboutfun{parent} If a node has a @class{document} as its ancestor, it can be found using the @fun{document} function. @aboutfun{document} Since the @code{parent} slot needs to be updated when children are added or removed, the sequence of children is not exposed as a mutable Common Lisp sequence. @aboutfun{list-children} @aboutfun{map-children} @aboutmacro{do-children} The following DOM-like functions are also offered: @aboutfun{nth-child} @aboutfun{first-child} @aboutfun{last-child} @aboutfun{previous-sibling} @aboutfun{next-sibling} A wide variety of sequence-related functions is offered that work like the Common Lisp functions of the same name, but without the need to call @fun{list-children} first: @aboutfun{find-child} @aboutfun{find-child-if} @aboutfun{child-position} @aboutfun{child-position-if} @aboutfun{count-children} @aboutfun{count-children-if} @aboutfun{filter-children} The functions listed above walk only across the direct children of the parent node. In addition, the node hierarchy can be mapped recursively using these functions: @aboutfun{map-recursively} @aboutmacro{do-recursively} @aboutfun{find-recursively} @aboutfun{filter-recursively} @end{section} @begin[Adding and Removing Child Nodes]{section} While all nodes can be asked for their children, only documents and elements permit actually adding children. (For all other nodes, the sequence of children appears as empty.) The most flexible function capable of changing the child nodes is @fun{replace-children}. Perhaps more common is @fun{insert-child}, a specialized version for only one new child. @aboutfun{replace-children} @aboutfun{insert-child} Various convenience functions are offered in addition: @aboutfun{prepend-child} @aboutfun{append-child} @aboutfun{delete-child} @aboutfun{delete-child-if} @aboutfun{delete-nth-child} @aboutfun{insert-child-before} @aboutfun{insert-child-after} @aboutfun{replace-child} A node can also be deleted from its parent directly using @fun{detach}. @aboutfun{detach} @fun{detach} also works for attributes. @end{section} @begin[Elements and their Attributes]{section} In addition to their children, elements have attributes and "extra namespaces". Attributes themselves are nodes and be accessed using these functions: @aboutfun{add-attribute} @aboutfun{remove-attribute} @aboutfun{find-attribute-named} @aboutfun{find-attribute-if} @aboutfun{list-attributes} @aboutfun{map-attributes} @aboutmacro{with-attributes} As a shortcut, the @fun{attribute-value} and its @code{setf} function allow access to attribute values by name, without having to look up the attribute node first: @aboutfun{attribute-value} There are three ways to declare a namespace: Using the name of the element, using the name of one of its attributes, or using an "extra namespace". A prefix can be looked up from any of these local declarations. It is also possible to look up a namespace while taking into account all declarations on parent elements. @aboutfun{find-local-namespace} @aboutfun{find-namespace} Extra namespaces are needed only when a namespace must be declared even though there is no element or attribute referencing it through its name. For example, an attribute declared with type @code{QName} using RelaxNG/XSD must reference a namespace in scope. @aboutfun{add-extra-namespace} @aboutfun{remove-extra-namespace} @aboutfun{find-extra-namespace} @aboutfun{map-extra-namespaces} @end{section}

README:

FUNCTION

Public

ADD-ATTRIBUTE (ELEMENT ATTRIBUTE)

@arg[element]{an instance of @class{element}} @arg[attribute]{an instance of @class{attribute}} @short{Add a new attribute to @code{element} or replace an existing attribute node of the same name.} It is an error if the attribute's namespace conflicts with existing namespace declarations on this element.

ADD-EXTRA-NAMESPACE (ELEMENT PREFIX URI)

@arg[prefix]{string, an NCName} @arg[uri]{string, a namespace URI} @arg[element]{an instance of @class{element}} @return{@code{uri}} @short{Add an extra namespace to @code{element} that maps @code{prefix} to @code{uri}.} It is an error if the new namespace conflicts with existing namespace declarations on this element.

APPEND-CHILD (PARENT CHILD)

@arg[child]{a @class{node}} @arg[parent]{a @class{parent-node}} Adds @code{child} as the last child of @code{parent}, if allowed. Signals an error if the child already has a parent.

ATTRIBUTE (&REST KEYS)

@unexport{}

ATTRIBUTE-VALUE (ELEMENT NAME &OPTIONAL (URI URIP))

@arg[element]{an instance of @class{element}} @arg[name]{string, an NCName} @arg[uri]{string, a namespace URI} @return{a string or nil} @short{Searches for an attribute node of @code{element} with the specified local name and namespace URI and returns its value.} Returns nil if no such attribute was found.

CHILD-POSITION (VALUE PARENT &REST ARGS &KEY FROM-END (START 0) END KEY TEST)

@arg[value]{an object} @arg[parent]{a @class{node}} @arg[from-end]{a generalized boolead} @arg[start, end]{bounding index designators for @code{parent}'s child list} @arg[key]{a designator for a function of one argument, or nil} @arg[test]{a designator for a function of two arguments, or nil} @return{a @class{node} or nil} Searches for a child node of @code{parent} that satisfies the @code{test} and returns its position. @see{child-position-if}

CHILD-POSITION-IF (PREDICATE PARENT &REST ARGS &KEY FROM-END (START 0) END KEY)

@arg[predicate]{a designator for a function of one argument that returns a generalized boolean} @arg[parent]{a @class{node}} @arg[from-end]{a generalized boolead} @arg[start, end]{bounding index designators for @code{parent}'s child list} @arg[key]{a designator for a function of one argument, or nil} @arg[test]{a designator for a function of two arguments, or nil} @return{a @class{node} or nil} Searches for a child node of @code{parent} that satisfies the @code{test} and returns its position. @see{child-position}

COMMENT (&REST KEYS)

@unexport{}

COUNT-CHILDREN (VALUE PARENT &REST ARGS &KEY FROM-END (START 0) END KEY TEST)

@arg[value]{an object} @arg[parent]{a @class{node}} @arg[from-end]{a generalized boolead} @arg[start, end]{bounding index designators for @code{parent}'s child list} @arg[key]{a designator for a function of one argument, or nil} @arg[test]{a designator for a function of two arguments, or nil} @return{a non-negative integer less than or equal to the number of child nodes} Counts (and returns the number of) @code{parent}'s child nodes satisfying the test. @see{number-of-children} @see{count-children-if}

COUNT-CHILDREN-IF (PREDICATE PARENT &REST ARGS &KEY FROM-END (START 0) END KEY)

@arg[predicate]{a designator for a function of one argument that returns a generalized boolean} @arg[parent]{a @class{node}} @arg[from-end]{a generalized boolead} @arg[start, end]{bounding index designators for @code{parent}'s child list} @arg[key]{a designator for a function of one argument, or nil} @return{a non-negative integer less than or equal to the number of child nodes} Counts (and returns the number of) @code{parent}'s child nodes satisfying @code{predicate}. @see{number-of-children} @see{count-children}

DELETE-CHILD (CHILD PARENT &KEY FROM-END TEST START END COUNT KEY)

@arg[child]{an object} @arg[parent]{a @class{node}} @arg[from-end]{a generalized boolead} @arg[start, end]{bounding index designators for @code{parent}'s child list} @arg[key]{a designator for a function of one argument, or nil} @arg[test]{a designator for a function of two arguments, or nil} @return{a @class{node} or nil} Searches for a child node of @code{parent} that satisfies the @code{test} and removes it, if allowed.

DELETE-CHILDREN (PARENT)

@arg[parent]{an @class{element}} @return{nil} Deletes all children of @code{element}.

DELETE-NTH-CHILD (IDX PARENT)

@arg[idx]{a non-negative integer} @arg[parent]{a @class{parent-node}} Removes child @code{idx} of @code{parent}, if allowed.

DOCUMENT (NODE)

@arg[node]{an instance of @class{node}} @return{a @class{document} or nil} @short{Returns the document node ancestor of @code{node}.} Returns the @class{document} node that is the @fun{root} of @code{node} or @code{nil} if the root node is not a document.

DOCUMENT-ELEMENT (DOCUMENT)

@arg[document]{a @class{document}} @return{an @class{element}} This function returns the child node that is an element. @see{document-type}

DOCUMENT-TYPE (DOCUMENT)

@arg[document]{a @class{document}} @return{a @class{document-type}, or nil} This function returns the child node that is a document type, or nil. @see{document-element}

ELEMENT (&REST KEYS)

@unexport{}

FILTER-CHILDREN (PREDICATE PARENT &REST ARGS &KEY FROM-END (START 0) END COUNT KEY)

@arg[predicate]{a designator for a function of one argument that returns a generalized boolean} @arg[parent]{a @class{node}} @arg[from-end]{a generalized boolead} @arg[start, end]{bounding index designators for @code{parent}'s child list} @arg[key]{a designator for a function of one argument, or nil} @arg[test]{a designator for a function of two arguments, or nil} @arg[count]{an integer or nil} @return{a sequence containing nodes} @short{Return a list of child nodes of @code{parent} from which nodes that do not satisfy @code{predicate} have been removed.} This function returns the same list as @code{remove-if-not} on the result of @fun{list-children}.

FILTER-RECURSIVELY (TEST NODE &KEY KEY)

@arg[test]{a designator for a function of one argument that returns a generalized boolean} @arg[node]{a @class{node}} @arg[key]{a designator for a function of one argument, or nil} @arg[test]{a designator for a function of two arguments, or nil} @return{a sequence containing nodes} Return a list of descendant nodes of @code{node} in pre-order, from which nodes that do not satisfy @code{predicate} have been removed.

FIND-ATTRIBUTE-IF (TEST ELEMENT)

@arg[test]{a designator for a function of one argument.} @arg[element]{an instance of @class{element}} @return{an @class{attribute} or nil} @short{Searches for an attribute node of @code{element} satisfying @code{test}} Returns nil if no such attribute was found.

FIND-ATTRIBUTE-NAMED (ELEMENT NAME &OPTIONAL (URI ))

@arg[element]{an instance of @class{element}} @arg[name]{string, an NCName} @arg[uri]{string, a namespace URI} @return{an @class{attribute} or nil} @short{Searches for an attribute node of @code{element} with the specified local name and namespace URI and returns it.} Returns nil if no such attribute was found.

FIND-CHILD (VALUE PARENT &REST ARGS &KEY FROM-END (START 0) END KEY TEST)

@arg[value]{an object} @arg[parent]{a @class{node}} @arg[from-end]{a generalized boolead} @arg[start, end]{bounding index designators for @code{parent}'s child list} @arg[key]{a designator for a function of one argument, or nil} @arg[test]{a designator for a function of two arguments, or nil} @return{a @class{node} or nil} Searches for a child node of @code{parent} that satisfies the @code{test} and returns it. @see{find-child-if}

FIND-CHILD-IF (PREDICATE PARENT &REST ARGS &KEY FROM-END (START 0) END KEY)

@arg[predicate]{a designator for a function of one argument that returns a generalized boolean} @arg[parent]{a @class{node}} @arg[from-end]{a generalized boolead} @arg[start, end]{bounding index designators for @code{parent}'s child list} @arg[key]{a designator for a function of one argument, or nil} @return{a @class{node} or nil} Searches for a child node of @code{parent} that satisfies @code{predicate} and returns it. @see{find-child}

FIND-EXTRA-NAMESPACE (PREFIX ELEMENT)

@arg[prefix]{a string} @arg[element]{an instance of @class{element}} @return{the namespace URI (a string), or nil} Find the extra namespace named @code{prefix} declared on @code{element} and return its namespace URI, or return nil if no such namespace was found.

FIND-LOCAL-NAMESPACE (PREFIX ELEMENT)

@arg[prefix]{a string} @arg[element]{an instance of @class{element}} @return{the namespace URI (a string), or nil} @short{Find the namespace @code{prefix} declared on @code{element} and return its namespace URI, or return nil if no such namespace was found.} The namespaces considered by this function are: The namespace of the element itself. The namespaces of element's attributes. Extra namespaces declared by the element. The "xmlns" namespace, which is always fixed.

FIND-NAMESPACE (PREFIX ELEMENT)

@arg[prefix]{a string} @arg[element]{an instance of @class{element}} @return{the namespace URI (a string), or nil} @short{Find the namespace @code{prefix} declared on @code{element} or its parent and return its namespace URI, or return nil if no such namespace was found.} This functions returns the same result as @fun{find-local-namespace} if the namespace is declared directly on @code{element}. Otherwise it takes into account namespaces declared on parent elements.

FIND-RECURSIVELY (ITEM NODE &KEY KEY TEST)

@arg[item]{an object} @arg[node]{a @class{node}} @arg[key]{a designator for a function of one argument, or nil} @arg[test]{a designator for a function of two arguments, or nil} @return{a @class{node} or nil} Searches in pre-order for the first descendant of @code{node} that satisfies the @code{test} and returns it. @see{find-child-if}

FIND-RECURSIVELY-IF (PREDICATE NODE &KEY KEY)

@arg[test]{a designator for a function of one argument that returns a generalized boolean} @arg[node]{a @class{node}} @arg[key]{a designator for a function of one argument, or nil} @return{a @class{node} or nil} Searches in pre-order for the first descendant of @code{node} that satisfies the @code{test} and returns it. @see{find-child-if}

FIRST-CHILD (NODE)

@arg[node]{a @class{node}} @return{a @class{node} or nil} Returns first child of @code{node}, or nil.

INSERT-CHILD-AFTER (PARENT NEW-CHILD REF-CHILD)

@arg[parent]{a @class{parent-node}} @arg[new-child]{a @class{node}} @arg[ref-child]{a @class{node}} @short{Adds @code{new-child} after @code{ref-child} as a child node of @code{parent}, if allowed.} Signals an error if the child already has a parent. Also signals an error if @code{ref-child} is not a child of @code{parent}.

INSERT-CHILD-BEFORE (PARENT NEW-CHILD REF-CHILD)

@arg[parent]{a @class{parent-node}} @arg[new-child]{a @class{node}} @arg[ref-child]{a @class{node}} @short{Adds @code{new-child} before @code{ref-child} as a child node of @code{parent}, if allowed.} Signals an error if the child already has a parent. Also signals an error if @code{ref-child} is not a child of @code{parent}.

LAST-CHILD (NODE)

@arg[node]{a @class{node}} @return{a @class{node} or nil} Returns last child of @code{node}, or nil.

LIST-ATTRIBUTES (ELEMENT)

@arg[element]{an @class{element}} @return{a list of @class{attribute} nodes} Returns a freshly consed list containing the attributes of @code{element}.

LIST-CHILDREN (NODE)

@arg[node]{a @class{node}} @return{a list of nodes} Returns a freshly consed list containing the child nodes of @code{node}.

MAKE-ATTRIBUTE (VALUE NAME &OPTIONAL (URI ))

@arg[value]{a string containing XML characters only} @arg[name]{a string, either a QName or an NCName} @arg[uri]{a string, the namespace URI} @return{an @class{attribute}} @short{This function creates an attribute node of the given value and name.} @see{element}

MAKE-BUILDER

@return{STP builder, a SAX handler} @short{This function creates SAX handler that constructs an STP document.} The builder processes SAX events and can be used with any function generating such events, in particular with cxml:parse-file. Examples. Parsing a file: @begin{pre}(cxml:parse #p"example.xml" (stp:make-builder))@end{pre} Parsing a string: @begin{pre}(cxml:parse "<example/>" (stp:make-builder))@end{pre} @see{serialize}

MAKE-COMMENT (DATA)

@arg[data]{a string containing XML characters only} @return{an @class{comment}} @short{This function creates a comment node.} @code{data} must not contain two consecutive dashes, or a dash at the end.

MAKE-DOCUMENT (DOCUMENT-ELEMENT)

@arg[document-element]{an @class{element}} @return{an @class{document}} @short{This function creates document.} The given element is used as the document's only initial child.

MAKE-DOCUMENT-TYPE (ROOT-ELEMENT-NAME &OPTIONAL SYSTEM-ID PUBLIC-ID INTERNAL-SUBSET)

@arg[root-element-name]{string, a Name} @arg[system-id]{a string allowed as a system ID} @arg[public-id]{a string allowed as a public ID} @arg[internal-subset]{a well-formed internal subset as a string} @return{an @class{documen-type}} @short{This function creates a document-type node.} @see{document}

MAKE-ELEMENT (NAME &OPTIONAL (URI ))

@arg[name]{string, a QName or NCName} @arg[uri]{a string, the namespace URI} @return{an @class{element}} @short{This function creates an element node of the given name.}

MAKE-PROCESSING-INSTRUCTION (TARGET DATA)

@arg[target]{string, an NCName} @arg[data]{string containing XML characters only} @return{an @class{processing-instruction}} @short{This function creates a processing instruction.} @code{target} must not equal "xml". @code{data} must not contain the substring "?>".

MAKE-TEXT (DATA)

@arg[data]{a string containing XML characters only} @return{an @class{text}} @short{This function creates a text node.}

MAP-ATTRIBUTES (RESULT-TYPE FN ELEMENT)

@arg[result-type]{a sequence type specifier, or nil} @arg[fn]{a designator for a function of one argument} @arg[element]{an instance of @class{element}} @return{an sequence of @code{result-type}, or nil} @short{Applies @code{fn} to each attribute nodes of @code{element}.} The @code{result-type} specifies the type of the resulting sequence. @code{map-children} returns nil if @code{result-type} is nil.

MAP-EXTRA-NAMESPACES (FN ELEMENT)

@arg[fn]{a designator for a function of two arguments} @arg[element]{an instance of @class{element}} @return{nil} Call fn for each extra namespace declared on @code{element} with namespace prefix and URI as arguments.

MAP-RECURSIVELY (FN NODE)

@arg[fn]{a designator for a function of one argument} @arg[node]{a @class{node}} @return{nil} Applies @code{fn} to successive descendants of @code{node} in pre-order.

NEXT-SIBLING (NODE)

@arg[node]{a @class{node}} @return{a @class{node} or nil} @short{Returns the child following @code{node} in the child list of its parent.} Signals an error if @code{node} has no parent or is the last child of its parent.

NTH-CHILD (N PARENT)

@arg[n]{a non-negative integer} @arg[parent]{a @class{node}} @return{a @class{node}} @short{Returns child node @code{n} of @code{parent}}, or signals an error if n is negative or as large or larger that the number of child nodes.

NUMBER-OF-CHILDREN (PARENT)

@arg[parent]{a @class{node}} @return{the number of child nodes} Returns the number of @code{parent}'s child nodes. @see{count-children}

OF-NAME (NAME &OPTIONAL (URI ))

@arg[name]{an NCName string or @code{nil}} @arg[uri]{a string, the namespace URI} @return{an function of one argument} @short{This function creates a test function for nodes of this name.} The function returned will return T if the argument is an instance of @class{attribute} or @class{element} and has the specified local-name and namespace URI, and will return NIL otherwise. If local-name is nil, only the namespace URI is considered for comparison. @see{local-name} @see{namespace-uri}

PARENT-NODE (&REST KEYS)

@unexport{}

PREPEND-CHILD (PARENT CHILD)

@arg[parent]{a @class{parent-node}} @arg[child]{a @class{node}} @short{Adds @code{child} as the first child of @code{parent}, if allowed.} Signals an error if the child already has a parent.

PREVIOUS-SIBLING (NODE)

@arg[node]{a @class{node}} @return{a @class{node} or nil} @short{Returns the child preceding @code{node} in the child list of its parent.} Signals an error if @code{node} has no parent or is the first child of its parent.

PROCESSING-INSTRUCTION (&REST KEYS)

@unexport{}

QUALIFIED-NAME (NODE)

@arg[node]{an @class{element} or @class{attribute}} @return{string, a QName} @short{Returns the node's qualified name.} The qualified name is computed as prefix ':' local-name. @see{local-name} @see{namespace-uri} @see{namespace-prefix}

REMOVE-ATTRIBUTE (ELEMENT ATTRIBUTE)

@arg[element]{an instance of @class{element}} @arg[attribute]{an instance of @class{attribute}} @return{the attribute} @short{Remove an attribute node from @code{element}.} It is an error if @code{attribute} is not an attribute of @code{element}.

REMOVE-EXTRA-NAMESPACE (ELEMENT PREFIX)

@arg[prefix]{string, an NCName} @arg[element]{an instance of @class{element}} @return{@code{uri}} Removed the extra namespace declared on @code{element} for @code{prefix}.

RENAME-ATTRIBUTE (ATTRIBUTE PREFIX URI)

@arg[attribute]{the @class{attribute} to be renamed} @arg[prefix]{string, an NCName} @arg[uri]{a string, the namespace URI} @return{the attribute} @short{This function changed namespace prefix and URI of an attribute.} Since there is no default namespace for attributes, prefix and uri must be changed in the same step to rename an attribute with no namespace to an attribute with both namespace prefix and URI. @see{local-name}

ROOT (NODE)

@arg[node]{an instance of @class{node}} @return{a @class{node} or nil} @short{Returns the root of the tree of nodes @code{node} is part of.} In a complete document, this is an instance of @class{document}, but a detached subtree can have any node as its root. In particular, the argument itself is returned if it does not have a @fun{parent}.

STP-ERROR (FMT &REST ARGS)

@unexport{}

TEXT (&REST KEYS)

@unexport{}

Undocumented

SETFATTRIBUTE-VALUE (NEWVAL ELEMENT NAME &OPTIONAL (URI URIP))

SETFDOCUMENT-ELEMENT (NEWVAL DOCUMENT)

SETFDOCUMENT-TYPE (NEWVAL DOCUMENT)

SETFNAMESPACE-PREFIX (NEWVAL ELEMENT)

SETFNAMESPACE-URI (NEWVAL ELEMENT)

MACRO

Public

DO-CHILDREN ((VAR NODE &OPTIONAL RESULT) &BODY BODY)

@arg[var]{symbol, a variable name} @arg[node]{a @class{node}} @arg[result]{a form} @return{the result of evaluating @code{result}} Executes @code{body} with @code{var} bound to successive child nodes.

DO-RECURSIVELY ((VAR NODE &OPTIONAL RESULT) &BODY BODY)

@arg[var]{symbol, a variable name} @arg[node]{a @class{node}} @arg[result]{a form} @return{the result of evaluating @code{result}} Executes @code{bode} with @code{var} bound to successive descendants of @code{node} in pre-order.

WITH-ATTRIBUTES ((&REST ENTRIES) ELEMENT &BODY BODY)

Evaluate body with the specified attributes bound lexically as if they were variables. Each entry in @code{entries} is a list of the form @em{(variable-name attribute-name &optional uri)}, where @code{variable-name} is a symbol and @code{attribute-name} and @code{uri} are strings. The macro with-attributes invokes @fun{attribute-value} to access the attributes. specified by each entry. Both setf and setq can be used to set the value of the attribute.

GENERIC-FUNCTION

Public

BASE-URI (NODE)

@arg[node]{an @class{node}} @return{a string} @short{Returns the node's base URI.}

SETFBASE-URI (NEWVAL NODE)

@arg[newval]{string, the new base URI} @arg[node]{an @class{parent-node}} @return{the new base URI} @short{Sets the node's base URI.}

COPY (NODE)

@arg[node]{a @class{node}} @short{This function copies a node recursively.} The resulting node is of the same class as the argument, and all child nodes and attributes are copied in the same way. Shared structure includes only primitive slot values like strings. (The consequences are undefined if user code mutates such values, whether @code{copy} is used or not.)

DELETE-CHILD-IF (PREDICATE PARENT &REST ARGS &KEY FROM-END START END COUNT KEY)

@arg[predicate]{a designator for a function of one argument that returns a generalized boolean} @arg[parent]{a @class{node}} @arg[from-end]{a generalized boolead} @arg[start, end]{bounding index designators for @code{parent}'s child list} @arg[key]{a designator for a function of one argument, or nil} @arg[test]{a designator for a function of two arguments, or nil} @return{a @class{node} or nil} Searches for an child node of @code{parent} that satisfies @code{predicate} and removes it, if allowed.

DETACH (NODE)

@arg[node]{a @class{node}} @short{This function removes a child node or attribute.} In contrast to functions for child nodes, this function can also remove an attribute from its parent. @see{parent}

INSERT-CHILD (PARENT CHILD POSITION)

@arg[parent]{a @class{parent-node}} @arg[child]{a @class{node}} @arg[position]{a non-negative integer} @short{Adds @code{child} as a child node of @code{parent} at position @code{position} if allowed.} Signals an error if the new child already has a parent. Also signals an error if @code{position} is greater than the number @code{parent}'s child nodes.

MAP-CHILDREN (RESULT-TYPE FUNCTION NODE)

@arg[result-type]{a sequence type specifier, or nil} @arg[function]{a designator for a function of one argument} @arg[node]{a @class{node}} @return{an sequence of @code{result-type}, or nil} @short{Applies @code{function} to successive child nodes.} The @code{result-type} specifies the type of the resulting sequence. @code{map-children} returns nil if @code{result-type} is nil. Otherwise it returns a sequence such that element i is the result of applying @code{function} to child i of @class{node}.

REPLACE-CHILD (PARENT OLD-CHILD NEW-CHILD)

@arg[parent]{a @class{parent-node}} @arg[old-child]{a @class{node}} @arg[new-child]{a @class{node}} @short{Adds @code{new-child} instead of @code{old-child} as a child node of @code{parent}, if allowed.} Signals an error if the new child already has a parent. Also signals an error if @code{old-child} is not a child of @code{parent}.

SERIALIZE (NODE HANDLER)

@arg[node]{a @class{node}} @short{This function generates SAX events representing @code{node}.} Use this function together with a serialization sink to generate a serialized XML document. Examples. Serializing to a stream: @begin{pre}CL-USER> (stp:serialize (stp:make-document (stp:make-element "test")) (cxml:make-character-stream-sink *standard-output*)) <?xml version="1.0" encoding="UTF-8"?> <test/> #<SWANK-BACKEND::SLIME-OUTPUT-STREAM {10037EA611@}> @end{pre} Examples. Serializing to a string: @begin{pre}CL-USER> (stp:serialize (stp:make-document (stp:make-element "test")) (cxml:make-string-sink)) "<?xml version=\"1.0\" encoding=\"UTF-8\"?> <test/>" @end{pre} @see{make-builder}

STRING-VALUE (NODE)

@arg[node]{an instance of @class{node}} @return{a string} @short{Returns the string value of @code{node} as defined by XPath.} For a document, this is the value of its root element. For an element, the concatenation of the values of those child nodes is returned that are elements or text nodes. (Leaving only the PCDATA content.) For a text, comment, and processing instruction nodes, the node's data is returned. For an attribute, the attribute value is returned. The value for document types is not specified.

Undocumented

SETFLOCAL-NAME (NEWVAL NODE)

SLOT-ACCESSOR

Public

DATA (NODE)

The @arg[node]{a @class{comment}, @class{processing-instruction}, or @class{text}} @return{a string of XML characters} @short{Returns the node's data.}

SETFDATA (NEWVAL NODE)

The @arg[newval]{a string of XML characters} @arg[node]{a @class{comment}, @class{processing-instruction}, or @class{text}} @return{the data} @short{Sets the node's data.}

INTERNAL-SUBSET (DOCUMENT-TYPE)

The @arg[document-type]{@class{document-type}} @return{string, a well-formed internal subset} @short{Returns the document-type's internal subset as a string.}

SETFINTERNAL-SUBSET (NEWVAL DOCUMENT-TYPE)

The @arg[newval]{string, a well-formed internal subset} @arg[document-type]{@class{document-type}} @return{the internal-subset} @short{Sets the document-type's internal subset.}

LOCAL-NAME (NODE)

The @arg[node]{an @class{element} or @class{attribute}} @return{string, an NCName} @short{Returns the node's local name.} @see{qualified-name} @see{namespace-uri} @see{namespace-prefix}

NAMESPACE-PREFIX (NODE)

The @arg[node]{an @class{element} or @class{attribute}} @return{string, an NCName} @short{Returns the node's namespace prefix.} @see{qualified-name} @see{local-name} @see{namespace-uri}

NAMESPACE-URI (NODE)

The @arg[node]{an @class{element} or @class{attribute}} @return{string, a URI} @short{Returns the node's namespace URI.} @see{qualified-name} @see{local-name} @see{namespace-prefix}

PARENT (NODE)

The @arg[node]{an @class{node}} @return{the parent node, or nil} @short{Returns the node's parent.}

PUBLIC-ID (DOCUMENT-TYPE)

The @arg[document-type]{@class{document-type}} @return{string suitable as a system ID} @short{Returns the document-type's public-id.}

SETFPUBLIC-ID (NEWVAL DOCUMENT-TYPE)

The @arg[newval]{string, suitable as a system ID} @arg[document-type]{@class{document-type}} @return{the public-id} @short{Sets the document-type's public-id.}

ROOT-ELEMENT-NAME (DOCUMENT-TYPE)

The @arg[document-type]{@class{document-type}} @return{string, a Name} @short{Returns the document-type's root-element-name.}

SETFROOT-ELEMENT-NAME (NEWVAL DOCUMENT-TYPE)

The @arg[newval]{string, a Name} @arg[document-type]{@class{document-type}} @return{the root-element-name} @short{Sets the document-type's root-element-name.}

SYSTEM-ID (DOCUMENT-TYPE)

The @arg[document-type]{@class{document-type}} @return{string suitable as a system ID} @short{Returns the document-type's system-id.}

SETFSYSTEM-ID (NEWVAL DOCUMENT-TYPE)

The @arg[newval]{string, suitable as a system ID} @arg[document-type]{@class{document-type}} @return{the system-id} @short{Sets the document-type's system-id.}

TARGET (PROCESSING-INSTRUCTION)

The @arg[processing-instruction]{@class{processing-instruction}} @return{string, a Name} @short{Returns the processing-instruction's target.}

SETFTARGET (NEWVAL PROCESSING-INSTRUCTION)

The @arg[newval]{string, a Name} @arg[processing-instruction]{@class{processing-instruction}} @return{the target} @short{Sets the processing-instruction's target.}

VALUE (ATTRIBUTE)

The @arg[attribute]{an @class{attribute}} @return{a string of XML characters} @short{Returns the attribute's value.}

SETFVALUE (NEWVAL ATTRIBUTE)

The @arg[newval]{a string of XML characters} @arg[attribute]{an @class{attribute}} @return{the value} @short{Sets the attribute's value.}

Undocumented

DTD (OBJECT)

SETFDTD (NEW-VALUE OBJECT)

VARIABLE

Public

*CHECK-URI-SYNTAX*

If true (the default), a warning is issued if a string specified as a namespace URI does not have URI syntax.

CLASS

Public

ATTRIBUTE (&REST KEYS)

@short{Instances of this class represent attributes of an @class{element}, excluding namespace declarations.} The @fun{parent} of an attribute is always an @class{element} or nil, but the attribute is not a child of that element. @see-slot{local-name} @see-slot{namespace-prefix} @see-slot{namespace-uri} @see-slot{qualified-name} @see-slot{value} @see{list-attributes} @see-constructor{make-attribute}

COMMENT (&REST KEYS)

Instances of this class represent XML comments. @see-slot{data} @see-constructor{make-comment}

DOCUMENT (NODE)

@short{Instances of this class represent an entire XML document.} A document may have at most one document-type, and must have exactly one element as a child (in this order). It may also have comments and processing-instructions anywhere. @see-constructor{make-document} @see-slot{document-element} @see-slot{document-type}

DOCUMENT-TYPE (DOCUMENT)

@short{Instances of this class represent the DOCTYPE declaration at the beginning of a document.} The document type is an optional child of a @class{document}. At most one document type is allowed, and it must precede the document element. Since STP checks well-formedness only, not validity, the document type only declares what DTD the document claims to be conforming to, but does not guarantee that it actually does. @see-constructor{make-document-type} @see-slot{root-element-name} @see-slot{system-id} @see-slot{public-id} @see-slot{internal-subset}

ELEMENT (&REST KEYS)

@short{Instances of this class represent XML elements with their attributes and namespaces.} See @class{node} for functions to query the list of children. See @class{parent-node} for functions to add or remove children. @see-slot{local-name} @see-slot{namespace-prefix} @see-slot{namespace-uri} @see-slot{qualified-name} @see{add-attribute} @see{remove-attribute} @see{find-attribute-named} @see{find-attribute-if} @see{with-attributes} @see{list-attributes} @see{map-attributes} @see{attribute-value} @see{find-namespace} @see{find-attribute-namespace} @see{find-local-namespace} @see{find-extra-namespace} @see{add-extra-namespace} @see{remove-extra-namespace} @see{map-extra-namespaces} @see-constructor{make-element}

NODE

@short{The superclass of all nodes.} Although only @class{document} and @class{element} allow children, read-only functions accessing the list of children are available for all nodes and always return zero children for other classes. @see-slot{parent} @see-slot{base-uri} @see{document} @see{root} @see{detach} @see{copy} @see{serialize} @see{map-children} @see{do-children} @see{list-children} @see{first-child} @see{last-child} @see{nth-child} @see{previous-sibling} @see{next-sibling} @see{count-children} @see{find-child} @see{child-position} @see{count-children-if} @see{find-child-if} @see{child-position-if} @see{filter-children} @see{map-recursively} @see{do-recursively} @see{find-recursively} @see{filter-recursively}

PARENT-NODE (&REST KEYS)

@short{Instances of this class can have children.} See @class{node} for functions to query the list of children without changing it. @see{prepend-child} @see{append-child} @see{delete-nth-child} @see{delete-child} @see{insert-child-before} @see{insert-child-after} @see{replace-child} @see{insert-child} @see{delete-child-if} @see{replace-children}

PROCESSING-INSTRUCTION (&REST KEYS)

Instances of this class represent processing instructions. @see-slot{target} @see-slot{data} @see-constructor{make-processing-instruction}

TEXT (&REST KEYS)

Instances of this class represent text nodes. @see-slot{data} @see-constructor{make-text}

CONDITION

Public

STP-ERROR (FMT &REST ARGS)

The class of all STP errors.