## What is Plump?

Plump is a parser for HTML/XML like documents, focusing on being lenient towards invalid markup. It can handle things like invalid attributes, bad closing tag order, unencoded entities, inexistent tag types, self-closing tags and so on. It parses documents to a class representation and offers a small set of DOM functions to manipulate it. You are free to change it to parse to your own classes though.

## How To

Load Plump through Quicklisp or ASDF:

    (ql:quickload :plump)

Using the `PARSE` function, plump will transform a string, pathname or stream into a document:

    (plump:parse "<foo><bar this is=\"a thing\">baz</bar><span id=\"test\">oh my")

This returns a root node. If you want to append a document to a root node (or any other node that accepts children) that you've made, you can pass it into the parse function. To return the document into a readable form, you can call `SERIALIZE`:

    (plump:serialize *)

Using the DOM you can easily traverse the document and change it:

    (plump:remove-child (plump:get-element-by-id ** "test"))
    (plump:serialize ***)

By default plump includes a few special tag dispatchers to catch HTML oddities like self-closing tags and fulltext-nodes. Especially the self-closing tags can lead to problems in XML documents. In order to parse without any HTML "tricks", you can simply do:

    (let ((plump:*tag-dispatchers* plump:*xml-tags*)) (plump:parse "<link>foo</link>"))

This will also influence the serialization. By default self-closing tags will be printed in "HTML-fashion," but if you require full XML support, the above should be the way to go. This behaviour is new in Plump2, as previously everything was always serialized in XML mode.

## Extending Plump

If you want to handle a certain tag in a special way, you can write your own tag-dispatcher. For example comments, the doctype and self-closing tags are handled in this fashion. In order to properly hook in, you will have to learn to use Plump's lexer (see next section).

    (plump:define-tag-dispatcher (my-dispatcher *tag-dispatchers*) (name)
      (string-equal name "my-tag"))

    (plump:define-tag-parser my-dispatcher (name)
      (let ((attrs (plump:read-attributes)))
        (when (char= (plump:consume) #\/)
          (plump:consume)) ;; Consume closing
        (make-instance 'my-tag :parent plump:*root* :attributes attrs)))

If you don't want to disturb the standard Plump tag dispatchers list, you can define your own special variable to contain the dispatchers and bind `*tag-dispatchers*` to that during parsing, as shown for the XML example above. Shorthand macros exist to define self-closing or full-text tags:

    (plump:define-self-closing-element img *tag-dispatchers* *html-tags*)
    (plump:define-fulltext-element style *tag-dispatchers* *html-tags*)

XML allows for script tags (like `<?php ?>`). By default Plump does not specify any special reading for any script tag. If an unhandled script tag is encountered, a warning is emitted and Plump will try to just read anything until `?>` is encountered. For most script tags this probably will not suffice, as they might contain some form of escaped `?>`. If you do want to use Plump to process script tags properly as well, you will have to define your own reader with `define-processing-parser`. You can also use that macro to define a reader that outputs a more suitable format than a text tag.

During parsing, all elements are created through `MAKE-*` functions like `MAKE-ROOT`, `MAKE-ELEMENT`, `MAKE-TEXT-NODE`, and so on. By overriding these functions you can instead delegate the parsing to your own DOM.

If you subclass the DOM classes, you might want to define a method on `SERIALIZE-OBJECT` to produce the right output.

## Plump's Lexer

Since parser generators are good for strict grammars and Plump needed to be fast and lenient, it comes with its own primitive reading/lexing mechanisms. All the lexer primitives are defined in `lexer.lisp` and you can leverage them for your own projects as well, if you so desire.

In order to allow the lexing to work, you'll have to wrap your processing code in `with-lexer-environment`. You can then use functions like `consume`, `advance`, `unread`, `peek` and `consume-until` to process the input.

`make-matcher` allows you to use a very simple language to define matching operations. This will evaluate to a function with no arguments that should return `T` if it matches and `NIL` otherwise. Combining matchers with `consume-until` allows you to easily make sequence readers:

    (plump:with-lexer-environment ("<foo>")
      (when (char= #\< (plump:consume))
        (plump:consume-until (plump:make-matcher (is #\>)))))

Available matcher constructs are `not`, `and`, `or`, `is`, `in`, `next`, `prev`, `any`, and `find`. `define-matcher` allows you to associate keywords to matchers, which you can then use as a matcher rule in `make-matcher`. Regular symbols act as variables:

    (let ((find "baz"))
      (plump:with-lexer-environment ("foo bar baz")
         (plump:consume-until (plump:make-matcher (is find)))))

## Speed

If you know of other native-lisp libraries that beat Plump, please do let me know, I would be very interested!

## See Also

- lQuery Dissect and manipulate the DOM with jQuery-like commands.
- CLSS Traverse the DOM by CSS selectors.
- plump-tex Serialize between TeX and the Plump DOM.
- plump-sexp Serialize between SEXPrs and the Plump DOM.

## Copyright

plump is licensed under the Artistic license. © Nicolas Hafner <shinmera@tymoon.eu> . This library can be obtained on https://github.com/Shinmera/plump.

## Package Index

- ### PLUMP-LEXER (ORG.SHIRAKUMO.PLUMP.LEXER)

  - special

    #### `*INDEX*`

        Set to the current reading index.

  - special

    #### `*LENGTH*`

        Set to the length of the string for bounds checking.

  - special

    #### `*STRING*`

        Contains the current string to lex.

  - function `(`

    #### `ADVANCE`

    `` ```)`

        Skips a chracter if possible.
        Returns the new index or NIL.

  - function `(`

    #### `ADVANCE-N`

    `` `N``)`

        Advances by N characters if possible.
        Returns the new *INDEX*.

  - function `(`

    #### `CONSUME`

    `` ```)`

        Consumes a single character if possible and returns it.
        Otherwise returns NIL.

  - function `(`

    #### `CONSUME-UNTIL`

    `` `MATCHER``)`

        Consumes until the provided matcher function returns positively.
        Returns the substring that was consumed.

  - function `(`

    #### `MATCHER-AND`

    `` `&REST MATCHERS``)`

        Creates a matcher function that returns if all of the sub-expressions
        return successfully. The last match is returned, if all.

  - function `(`

    #### `MATCHER-CHARACTER`

    `` `CHARACTER``)`

        Creates a matcher function that attempts to match the given character.

  - function `(`

    #### `MATCHER-FIND`

    `` `LIST``)`

        Creates a matcher function that returns T if the character is found in the given list.

  - function `(`

    #### `MATCHER-NEXT`

    `` `MATCHER``)`

        Creates a matcher environment that peeks ahead one farther.

  - function `(`

    #### `MATCHER-NOT`

    `` `MATCHER``)`

        Creates a matcher function that inverts the result of the sub-expression.

  - function `(`

    #### `MATCHER-OR`

    `` `&REST MATCHERS``)`

        Creates a matcher function that returns successfully if any of the
        sub-expressions return successfully. The first match is returned, if any.

  - function `(`

    #### `MATCHER-PREV`

    `` `MATCHER``)`

        Creates a matcher environment that peeks behind.

  - function `(`

    #### `MATCHER-RANGE`

    `` `FROM TO``)`

        Creates a matcher that checks a range according to the next character's CHAR-CODE.

  - function `(`

    #### `MATCHER-STRING`

    `` `STRING``)`

        Creates a matcher function that attempts to match the given string.

  - function `(`

    #### `PEEK`

    `` ```)`

        Returns the next character, if any.

  - function `(`

    #### `UNREAD`

    `` ```)`

        Steps back a single character if possible.
        Returns the new *INDEX*.

  - function `(`

    #### `UNREAD-N`

    `` `N``)`

        Steps back by N characters if possible.
        Returns the new *INDEX*.

  - macro `(`

    #### `DEFINE-MATCHER`

    `` `NAME FORM``)`

        Associates NAME as a keyword to the matcher form. You can then use the keyword in further matcher rules.

  - macro `(`

    #### `MAKE-MATCHER`

    `` `FORM``)`

        Macro to create a matcher chain.

  - macro `(`

    #### `MATCHER-ANY`

    `` `&REST IS``)`

        Shorthand for (or (is a) (is b)..)

  - macro `(`

    #### `WITH-LEXER-ENVIRONMENT`

    `` `(STRING) &BODY BODY``)`

        Sets up the required lexing environment for the given string.

- ### PLUMP-DOM (ORG.SHIRAKUMO.PLUMP.DOM)

  - special

    #### `*ENTITY-MAP*`

        String hash-table containing the entity names and mapping them to their respective characters.

  - special

    #### `*STREAM*`

        The stream to serialize to during SERIALIZE-OBJECT.

  - class

    #### `CDATA`

        XML CDATA section node.

  - class

    #### `CHILD-NODE`

        Node class that is a child and thus has a parent.

  - class

    #### `COMMENT`

        Comment node that can only contain a single comment string.

  - class

    #### `DOCTYPE`

        Special DOM node for the doctype declaration.

  - class

    #### `ELEMENT`

        Standard DOM element/block including attributes, tag-name, parent and children.

  - class

    #### `FULLTEXT-ELEMENT`

        Special DOM element that contains full, un-entitied text like SCRIPT and STYLE.

  - class

    #### `NESTING-NODE`

        Node class that can contain child nodes.

  - class

    #### `NODE`

        Base DOM node class.

  - class

    #### `PROCESSING-INSTRUCTION`

        XML processing instruction node.

  - class

    #### `ROOT`

        Root DOM node, practically equivalent to a "document".

  - class

    #### `TEXT-NODE`

        Text node that can only contain a single text string.

  - class

    #### `TEXTUAL-NODE`

        Node class that represents a textual node and thus contains a TEXT field.

  - class

    #### `XML-HEADER`

        XML header element

  - condition

    #### `DISCOURAGED-XML-CHARACTER`

        Warning signalled when a discouraged XML character is encountered during WRITE-ENCODE-CHAR.

  - condition

    #### `INVALID-XML-CHARACTER`

        Error signalled when an invalid XML character is encountered during WRITE-ENCODE-CHAR.

  - accessor `(`

    #### `ATTRIBUTE`

    `` `ELEMENT ATTRIBUTE``)`

        Returns the asked attribute from the element
        or NIL. If the attribute could not be found, the
        second return value is set to NIL.

  - accessor `(`

    #### `ATTRIBUTES`

    `` `OBJECT``)`

        Returns an EQUALP hash-table of the element's attributes.

  - accessor `(`

    #### `CHILDREN`

    `` `OBJECT``)`

        Returns a vector of child-nodes that are contained within the node.

  - accessor `(`

    #### `DOCTYPE`

    `` `OBJECT``)`

        Returns the doctype node's actual doctype string.

  - accessor `(`

    #### `FAULTY-CHAR`

    `` `CONDITION``)`

        Returns the faulty char that caused the signal.

  - accessor `(`

    #### `PARENT`

    `` `OBJECT``)`

        Returns the node's parent that should contain this element as a child.

  - accessor `(`

    #### `TAG-NAME`

    `` `OBJECT``)`

        Returns the element's tag name.

  - accessor `(`

    #### `TEXT`

    `` `OBJECT``)`

        Returns the node's textual content.

  - function `(`

    #### `ALLOWED-CHAR-P`

    `` `CHAR``)`

        Returns T if the character is a permitted XML character.

  - function `(`

    #### `APPEND-CHILD`

    `` `PARENT CHILD``)`

        Appends the given child onto the parent's child list.
        Returns the child.

  - function `(`

    #### `CDATA-P`

    `` `OBJECT``)`

        Returns T if the given OBJECT is of type CDATA

  - function `(`

    #### `CHILD-ELEMENTS`

    `` `NESTING-NODE``)`

        Returns a new vector of children of the given node, filtered to elements.

  - function `(`

    #### `CHILD-NODE-P`

    `` `OBJECT``)`

        Returns T if the given OBJECT is of type CHILD-NODE

  - function `(`

    #### `CHILD-POSITION`

    `` `CHILD``)`

        Returns the index of the child within its parent.

  - function `(`

    #### `CLEAR`

    `` `NESTING-NODE``)`

        Clears all children from the node.

        Noe that the PARENT of all child elements is set to NIL.

  - function `(`

    #### `CLONE-ATTRIBUTES`

    `` `NODE``)`

        Clone the attribute map.
        Note that keys and values are NOT copied/cloned.

  - function `(`

    #### `CLONE-CHILDREN`

    `` `NODE &OPTIONAL DEEP NEW-PARENT``)`

        Clone the array of children.
        If DEEP is non-NIL, each child is cloned as per (CLONE-NODE NODE T).
        When copying deeply, you can also pass a NEW-PARENT to set on each child.

  - function `(`

    #### `COMMENT-P`

    `` `OBJECT``)`

        Returns T if the given OBJECT is of type COMMENT

  - function `(`

    #### `DECODE-ENTITIES`

    `` `TEXT &OPTIONAL REMOVE-INVALID``)`

        Translates all entities in the text into their character counterparts if possible.
        If an entity does not match, it is left in place unless REMOVE-INVALID is non-NIL.

  - function `(`

    #### `DISCOURAGED-CHAR-P`

    `` `CHAR``)`

        Returns T if the character is a discouraged XML character.

  - function `(`

    #### `DOCTYPE-P`

    `` `OBJECT``)`

        Returns T if the given OBJECT is of type DOCTYPE

  - function `(`

    #### `ELEMENT-P`

    `` `OBJECT``)`

        Returns T if the given OBJECT is of type ELEMENT

  - function `(`

    #### `ELEMENT-POSITION`

    `` `CHILD``)`

        Returns the index of the child within its parent, counting only elements.
        This excludes comments, text-nodes and the like.

  - function `(`

    #### `ENCODE-ENTITIES`

    `` `TEXT &OPTIONAL STREAM``)`

        Encodes the characters < > & " with their XML entity equivalents.

        If no STREAM is given, it encodes to a new string.

  - function `(`

    #### `ENSURE-ATTRIBUTE-MAP`

    `` `TABLE``)`

        Ensures that the TABLE is suitable as an attribute-map.
        If it is not, the table is copied into a proper attribute-map.

  - function `(`

    #### `ENSURE-CHILD-ARRAY`

    `` `ARRAY``)`

        If the ARRAY is suitable as a child-array, it is returned.
        Otherwise the array's elements are copied over into a proper
        child-array.

  - function `(`

    #### `FAMILY`

    `` `CHILD``)`

        Returns the direct array of children of the parent of the given child.
        Note that modifying this array directly modifies that of the parent.

  - function `(`

    #### `FAMILY-ELEMENTS`

    `` `CHILD``)`

        Returns the direct array of children elements of the parent of the given child.
        Note that this is a copy of the array, modifying it is safe.
        This excludes comments, text-nodes and the like.

  - function `(`

    #### `FIRST-CHILD`

    `` `ELEMENT``)`

        Returns the first child within the parent or NIL
        if the parent is empty.

  - function `(`

    #### `FIRST-ELEMENT`

    `` `ELEMENT``)`

        Returns the first child element within the parent or NIL
        if the parent is empty. This excludes comments, text-nodes and the like.

  - function `(`

    #### `FULLTEXT-ELEMENT-P`

    `` `OBJECT``)`

        Returns T if the given OBJECT is of type FULLTEXT-ELEMENT

  - function `(`

    #### `GET-ATTRIBUTE`

    `` `ELEMENT ATTRIBUTE``)`

        Synonymous to ATTRIBUTE.

  - function `(`

    #### `GET-ELEMENT-BY-ID`

    `` `NODE ID``)`

        Searches the given node and returns the first
        node at arbitrary depth that matches the given ID
        attribute.

  - function `(`

    #### `GET-ELEMENTS-BY-TAG-NAME`

    `` `NODE TAG``)`

        Searches the given node and returns an unordered
        list of child nodes at arbitrary depth that match
        the given tag.

  - function `(`

    #### `HAS-ATTRIBUTE`

    `` `ELEMENT ATTRIBUTE``)`

        Returns T if the provided attribute exists.

  - function `(`

    #### `HAS-CHILD-NODES`

    `` `NODE``)`

        Returns T if the node can contain children and
        the child array is not empty.

  - function `(`

    #### `INSERT-AFTER`

    `` `ELEMENT NEW-CHILD``)`

        Inserts the new-child after the given element in the parent's list.
        Returns the new child.

        Note that this operation is potentially very costly.
        See VECTOR-PUSH-EXTEND-POSITION

  - function `(`

    #### `INSERT-BEFORE`

    `` `ELEMENT NEW-CHILD``)`

        Inserts the new-child before the given element in the parent's list.
        Returns the new child.

        Note that this operation is potentially very costly.
        See VECTOR-PUSH-EXTEND-POSITION

  - function `(`

    #### `LAST-CHILD`

    `` `ELEMENT``)`

        Returns the last child within the parent or NIL
        if the parent is empty.

  - function `(`

    #### `LAST-ELEMENT`

    `` `ELEMENT``)`

        Returns the last child element within the parent or NIL
        if the parent is empty. This excludes comments, text-nodes and the like.

  - function `(`

    #### `MAKE-ATTRIBUTE-MAP`

    `` `&OPTIONAL (SIZE 0)``)`

        Creates a map to contain attributes.

  - function `(`

    #### `MAKE-CDATA`

    `` `PARENT &KEY (TEXT "")``)`

        Creates an XML CDATA section under the parent.

        Note that the element is automatically appended to the parent's child list.

  - function `(`

    #### `MAKE-CHILD-ARRAY`

    `` `&OPTIONAL (SIZE 0)``)`

        Creates an array to contain child elements

  - function `(`

    #### `MAKE-COMMENT`

    `` `PARENT &OPTIONAL (TEXT "")``)`

        Creates a new comment node under the parent.

        Note that the node is automatically appended to the parent's child list.

  - function `(`

    #### `MAKE-DOCTYPE`

    `` `PARENT DOCTYPE``)`

        Creates a new doctype node under the parent.

        Note that the node is automatically appended to the parent's child list.

  - function `(`

    #### `MAKE-ELEMENT`

    `` `PARENT TAG &KEY (CHILDREN (MAKE-CHILD-ARRAY)) (ATTRIBUTES (MAKE-ATTRIBUTE-MAP))``)`

        Creates a standard DOM element with the given tag name and parent.
        Optionally a vector (with fill-pointer) containing children and an
        attribute-map (a hash-table with equalp test) can be supplied.

        Note that the element is automatically appended to the parent's child list.

  - function `(`

    #### `MAKE-FULLTEXT-ELEMENT`

    `` `PARENT TAG &KEY TEXT (ATTRIBUTES (MAKE-ATTRIBUTE-MAP))``)`

        Creates a fulltext element under the parent.
        Optionally a text and an attribute-map (a hash-table with equalp test)
        can be supplied.

        Note that the element is automatically appended to the parent's child list.

  - function `(`

    #### `MAKE-PROCESSING-INSTRUCTION`

    `` `PARENT &KEY NAME (TEXT "")``)`

        Creates an XML processing instruction under the parent.

        Note that the element is automatically appended to the parent's child list.

  - function `(`

    #### `MAKE-ROOT`

    `` `&OPTIONAL (CHILDREN (MAKE-CHILD-ARRAY))``)`

        Creates a root node with the given children.
        Children should be a vector with fill-pointer.

  - function `(`

    #### `MAKE-TEXT-NODE`

    `` `PARENT &OPTIONAL (TEXT "")``)`

        Creates a new text node under the parent.

        Note that the node is automatically appended to the parent's child list.

  - function `(`

    #### `MAKE-XML-HEADER`

    `` `PARENT &KEY (ATTRIBUTES (MAKE-ATTRIBUTE-MAP))``)`

        Creates an XML header object under the parent.

        Note that the element is automatically appended to the parent's child list.

  - function `(`

    #### `NESTING-NODE-P`

    `` `OBJECT``)`

        Returns T if the given OBJECT is of type NESTING-NODE

  - function `(`

    #### `NEXT-ELEMENT`

    `` `CHILD``)`

        Returns the sibling element next to this one or NIL if
        it is already last. This excludes comments, text-nodes and the like.

  - function `(`

    #### `NEXT-SIBLING`

    `` `CHILD``)`

        Returns the sibling next to this one or NIL if
        it is already the last.

  - function `(`

    #### `NODE-P`

    `` `OBJECT``)`

        Returns T if the given OBJECT is of type NODE

  - function `(`

    #### `PREPEND-CHILD`

    `` `PARENT CHILD``)`

        Prepends the given child onto the parent's child list.
        Returns the child.

        Note that this operation is costly, see VECTOR-PUSH-EXTEND-FRONT

  - function `(`

    #### `PREVIOUS-ELEMENT`

    `` `CHILD``)`

        Returns the sibling element next to this one or NIL if
        it is already last. This excludes comments, text-nodes and the like.

  - function `(`

    #### `PREVIOUS-SIBLING`

    `` `CHILD``)`

        Returns the sibling before this one or NIL if
        it is already the first.

  - function `(`

    #### `PROCESSING-INSTRUCTION-P`

    `` `OBJECT``)`

        Returns T if the given OBJECT is of type PROCESSING-INSTRUCTION

  - function `(`

    #### `REMOVE-ATTRIBUTE`

    `` `ELEMENT ATTRIBUTE``)`

        Remove the specified attribute if it exists.
        Returns NIL.

  - function `(`

    #### `REMOVE-CHILD`

    `` `CHILD``)`

        Removes the child from its parent.
        Returns the child.

        Note that this operation is potentially very costly.
        See VECTOR-POP-POSITION

  - function `(`

    #### `RENDER-TEXT`

    `` `NODE``)`

        "Renders" the text of this element and its children.

        In effect the text is gathered from the component and all of
        its children, but transforming the text in such a way that:
        - All ASCII white space (Space, Tab, CR, LF) is converted into spaces.
        - There are no consecutive spaces.
        - There are no spaces at the beginning or end.

        This is somewhat analogous to how the text will be shown to
        the user when rendered by a browser. Hence, render-text.

  - function `(`

    #### `REPLACE-CHILD`

    `` `OLD-CHILD NEW-CHILD``)`

        Replace the old child with a new one.
        Returns the old child.

  - function `(`

    #### `ROOT-P`

    `` `OBJECT``)`

        Returns T if the given OBJECT is of type ROOT

  - function `(`

    #### `SERIALIZE`

    `` `NODE &OPTIONAL (STREAM T)``)`

        Serializes NODE to STREAM.
        STREAM can be a stream, T for *standard-output* or NIL to serialize to string.

  - function `(`

    #### `SET-ATTRIBUTE`

    `` `ELEMENT ATTRIBUTE VALUE``)`

        Synonymous to (SETF (ATTIBUTE ..) ..)

  - function `(`

    #### `SIBLING-ELEMENTS`

    `` `CHILD``)`

        Returns the array of sibling elements of the given child.
        Note that this is a copy of the array, modifying it is safe.
        This excludes comments, text-nodes and the like.

  - function `(`

    #### `SIBLINGS`

    `` `CHILD``)`

        Returns the array of siblings of the given child.
        Note that this is a copy of the array, modifying it is safe.

  - function `(`

    #### `SPLICE`

    `` `ELEMENT``)`

        Splices the contents of element into the position of the element in its parent.
        Returns the parent.

        Note that this operation is potentially very costly.
        See ARRAY-SHIFT

  - function `(`

    #### `STRIP`

    `` `NODE``)`

        Trim all text-nodes within NODE (at any depth) of leading and trailing whitespace.
        If their TEXT should be an empty string after trimming, remove them.

  - function `(`

    #### `TEXT-NODE-P`

    `` `OBJECT``)`

        Returns T if the given OBJECT is of type TEXT-NODE

  - function `(`

    #### `TEXTUAL-NODE-P`

    `` `OBJECT``)`

        Returns T if the given OBJECT is of type TEXTUAL-NODE

  - function `(`

    #### `TRANSLATE-ENTITY`

    `` `TEXT &KEY (START 0) (END (LENGTH TEXT))``)`

        Translates the given entity identifier (a name, #Dec or #xHex) into their respective strings if possible.
        Otherwise returns NIL.

  - function `(`

    #### `TRIM`

    `` `NODE``)`

        Trim all text-nodes within NODE (at any depth) of leading and trailing whitespace.

  - function `(`

    #### `WRITE-ENCODE-CHAR`

    `` `CHAR STREAM``)`

        Write and possibly encode the CHAR to STREAM.
        This also properly handles detection of invalid or discouraged XML characters.

        The following restarts are available in the case of a faulty character:
          ABORT              Do not output the faulty character at all.
          USE-NEW-CHARACTER  Output a replacement character instead.
          CONTINUE           Continue and output the faulty character anyway.

        See INVALID-XML-CHARACTER
        See DISCOURAGED-XML-CHARACTER

  - function `(`

    #### `XML-HEADER-P`

    `` `OBJECT``)`

        Returns T if the given OBJECT is of type XML-HEADER

  - generic `(`

    #### `CLONE-NODE`

    `` `NODE &OPTIONAL DEEP``)`

        Clone the given node, creating a new instance with the same contents.
        If DEEP is non-NIL, the following applies:
        The text of COMMENT and TEXT-NODEs is copied as per COPY-SEQ.
        The children of NESTING-NODEs are copied as per (CLONE-CHILDREN CHILD T)

  - generic `(`

    #### `SERIALIZE-OBJECT`

    `` `NODE``)`

        Serialize the given node and print it to *stream*.

  - generic `(`

    #### `TRAVERSE`

    `` `NODE FUNCTION &KEY TEST``)`

        Traverse the NODE and all its children recursively,
        calling FUNCTION on the current node if calling TEST on the current node
        returns a non-NIL value. It is safe to modify the child array of the
        parent of each node passed to FUNCTION.

        NODE is returned.

- ### PLUMP-PARSER (ORG.SHIRAKUMO.PLUMP.PARSER)

  - special

    #### `*ALL-TAG-DISPATCHERS*`

        All defined tag dispatchers

  - special

    #### `*HTML-TAGS*`

        List of HTML tag dispatchers

  - special

    #### `*ROOT*`

        Object containing the current node to set as parent.

  - special

    #### `*TAG-DISPATCHERS*`

        Active tag dispatcher functions

  - special

    #### `*XML-TAGS*`

        List of XML tag dispatchers

  - class

    #### `TAG-DISPATCHER`

        Encapsulates the processing for a given tag.

        See TAG-DISPATCHER-NAME
        See TAG-DISPATCHER-TEST
        See TAG-DISPATCHER-PARSER
        See TAG-DISPATCHER-PRINTER

  - accessor `(`

    #### `PROCESSING-PARSER`

    `` `PROCESS-NAME``)`

        Return the processing-parser function for PROCESS-NAME. SETF-able.

  - function `(`

    #### `READ-ATTRIBUTE`

    `` ```)`

        Reads an attribute and returns it as a key value cons.

  - function `(`

    #### `READ-ATTRIBUTE-NAME`

    `` ```)`

        Reads an attribute name.

  - function `(`

    #### `READ-ATTRIBUTE-VALUE`

    `` ```)`

        Reads an attribute value, either enclosed in quotation marks or until a space or tag end.

  - function `(`

    #### `READ-ATTRIBUTES`

    `` ```)`

        Reads as many attributes as possible from a tag and returns them as an attribute map.

  - function `(`

    #### `READ-CHILDREN`

    `` ```)`

        Read all children of the current *root* until the closing tag for *root* is encountered.

  - function `(`

    #### `READ-NAME`

    `` ```)`

        Reads and returns a tag name.

  - function `(`

    #### `READ-ROOT`

    `` `&OPTIONAL (ROOT (MAKE-ROOT))``)`

        Creates a root element and reads nodes into it.
        Optionally uses the specified root to append child nodes to.
        Returns the root.

  - function `(`

    #### `READ-STANDARD-TAG`

    `` `NAME``)`

        Reads an arbitrary tag and returns it.
        This recurses with READ-CHILDREN.

  - function `(`

    #### `READ-TAG`

    `` ```)`

        Attempts to read a tag and dispatches or defaults to READ-STANDARD-TAG.
        Returns the completed node if one can be read.

  - function `(`

    #### `READ-TAG-CONTENTS`

    `` ```)`

        Reads and returns all tag contents.
        E.g. <foo bar baz> => bar baz

  - function `(`

    #### `READ-TEXT`

    `` ```)`

        Reads and returns a text-node.

  - function `(`

    #### `REMOVE-PROCESSING-PARSER`

    `` `PROCESS-NAME``)`

        Remove the processing-parser for PROCESS-NAME.

  - function `(`

    #### `REMOVE-TAG-DISPATCHER`

    `` `NAME &OPTIONAL (LIST '*ALL-TAG-DISPATCHERS*)``)`

        Removes the tag-dispatcher of the given name from the list.

  - function `(`

    #### `SLURP-STREAM`

    `` `STREAM``)`

        Quickly slurps the stream's contents into an array with fill pointer.

  - function `(`

    #### `TAG-DISPATCHER`

    `` `NAME &OPTIONAL (LIST *ALL-TAG-DISPATCHERS*)``)`

        Accessor to the tag-dispatcher of the given name.

  - generic `(`

    #### `PARSE`

    `` `INPUT &KEY ROOT``)`

        Parses the given input into a DOM representation.
        By default, methods for STRING, PATHNAME and STREAM are defined.
        If supplied, the given root is used to append children to as per READ-ROOT.
        Returns the root.

  - macro `(`

    #### `DEFINE-FULLTEXT-ELEMENT`

    `` `TAG &REST LISTS``)`

        Defines an element to be read as a full-text element.
        This means that it cannot contain any child-nodes and everything up until its closing
        tag is used as its text.

  - macro `(`

    #### `DEFINE-PROCESSING-PARSER`

    `` `PROCESS-NAME NIL &BODY BODY``)`

        Defines a new processing-instruction parser.
        It is invoked if a processing-instruction (<?) with PROCESS-NAME is encountered.
        The lexer will be at the point straight after reading in the PROCESS-NAME.
        Expected return value is a string to use as the processing-instructions' TEXT.
        The closing tag (?>) should NOT be consumed by a processing-parser.

  - macro `(`

    #### `DEFINE-SELF-CLOSING-ELEMENT`

    `` `TAG &REST LISTS``)`

        Defines an element that does not need to be closed with /> and cannot contain child nodes.

  - macro `(`

    #### `DEFINE-TAG-DISPATCHER`

    `` `(NAME &REST LISTS) (TAGVAR) &BODY BODY``)`

        Defines a new tag dispatcher. It is invoked if TEST-FORM passes.

        NAME      --- Name to discern the dispatcher with.
        LISTS     --- Symbols of lists to which the dispatcher should be added.
        TAGVAR    --- Symbol bound to the tag name.
        BODY      --- Body forms describing the test to match the tag.

  - macro `(`

    #### `DEFINE-TAG-PARSER`

    `` `NAME (TAGVAR) &BODY BODY``)`

        Defines the parser function for a tag dispatcher.

        NAME    --- The name of the tag dispatcher. If one with this name
                    cannot be found, an error is signalled.
        TAGVAR  --- Symbol bound to the tag name.
        BODY    --- Body forms describing the tag parsing behaviour.

  - macro `(`

    #### `DEFINE-TAG-PRINTER`

    `` `NAME (NODEVAR) &BODY BODY``)`

        Defines the printer function for a tag dispatcher.

        NAME    --- The name of the tag dispatcher. If one with this name
                    cannot be found, an error is signalled.
        TAGVAR  --- Symbol bound to the tag name.
        BODY    --- Body forms describing the printing behaviour. Write to
                    the stream bound to PLUMP-DOM:*STREAM*.

  - macro `(`

    #### `DO-TAG-PARSERS`

    `` `(TEST PARSER &OPTIONAL RESULT-FORM) &BODY BODY``)`

        Iterates over the current *TAG-DISPATCHERS*, binding the TEST and PARSER functions.
        Returns RESULT-FORM's evaluated value.

  - macro `(`

    #### `DO-TAG-PRINTERS`

    `` `(TEST PRINTER &OPTIONAL RESULT-FORM) &BODY BODY``)`

        Iterates over the current *TAG-DISPATCHERS*, binding the TEST and PRINTER functions.
        Returns RESULT-FORM's evaluated value.

- ### PLUMP (ORG.SHIRAKUMO.PLUMP)

  - special

    #### `*ALL-TAG-DISPATCHERS*`

        All defined tag dispatchers

  - special

    #### `*ENTITY-MAP*`

        String hash-table containing the entity names and mapping them to their respective characters.

  - special

    #### `*HTML-TAGS*`

        List of HTML tag dispatchers

  - special

    #### `*INDEX*`

        Set to the current reading index.

  - special

    #### `*LENGTH*`

        Set to the length of the string for bounds checking.

  - special

    #### `*ROOT*`

        Object containing the current node to set as parent.

  - special

    #### `*STREAM*`

        The stream to serialize to during SERIALIZE-OBJECT.

  - special

    #### `*STRING*`

        Contains the current string to lex.

  - special

    #### `*TAG-DISPATCHERS*`

        Active tag dispatcher functions

  - special

    #### `*XML-TAGS*`

        List of XML tag dispatchers

  - class

    #### `CDATA`

        XML CDATA section node.

  - class

    #### `CHILD-NODE`

        Node class that is a child and thus has a parent.

  - class

    #### `COMMENT`

        Comment node that can only contain a single comment string.

  - class

    #### `DOCTYPE`

        Special DOM node for the doctype declaration.

  - class

    #### `ELEMENT`

        Standard DOM element/block including attributes, tag-name, parent and children.

  - class

    #### `FULLTEXT-ELEMENT`

        Special DOM element that contains full, un-entitied text like SCRIPT and STYLE.

  - class

    #### `NESTING-NODE`

        Node class that can contain child nodes.

  - class

    #### `NODE`

        Base DOM node class.

  - class

    #### `PROCESSING-INSTRUCTION`

        XML processing instruction node.

  - class

    #### `ROOT`

        Root DOM node, practically equivalent to a "document".

  - class

    #### `TAG-DISPATCHER`

        Encapsulates the processing for a given tag.

        See TAG-DISPATCHER-NAME
        See TAG-DISPATCHER-TEST
        See TAG-DISPATCHER-PARSER
        See TAG-DISPATCHER-PRINTER

  - class

    #### `TEXT-NODE`

        Text node that can only contain a single text string.

  - class

    #### `TEXTUAL-NODE`

        Node class that represents a textual node and thus contains a TEXT field.

  - class

    #### `XML-HEADER`

        XML header element

  - condition

    #### `DISCOURAGED-XML-CHARACTER`

        Warning signalled when a discouraged XML character is encountered during WRITE-ENCODE-CHAR.

  - condition

    #### `INVALID-XML-CHARACTER`

        Error signalled when an invalid XML character is encountered during WRITE-ENCODE-CHAR.

  - accessor `(`

    #### `ATTRIBUTE`

    `` `ELEMENT ATTRIBUTE``)`

        Returns the asked attribute from the element
        or NIL. If the attribute could not be found, the
        second return value is set to NIL.

  - accessor `(`

    #### `ATTRIBUTES`

    `` `OBJECT``)`

        Returns an EQUALP hash-table of the element's attributes.

  - accessor `(`

    #### `CHILDREN`

    `` `OBJECT``)`

        Returns a vector of child-nodes that are contained within the node.

  - accessor `(`

    #### `DOCTYPE`

    `` `OBJECT``)`

        Returns the doctype node's actual doctype string.

  - accessor `(`

    #### `FAULTY-CHAR`

    `` `CONDITION``)`

        Returns the faulty char that caused the signal.

  - accessor `(`

    #### `PARENT`

    `` `OBJECT``)`

        Returns the node's parent that should contain this element as a child.

  - accessor `(`

    #### `PROCESSING-PARSER`

    `` `PROCESS-NAME``)`

        Return the processing-parser function for PROCESS-NAME. SETF-able.

  - accessor `(`

    #### `TAG-NAME`

    `` `OBJECT``)`

        Returns the element's tag name.

  - accessor `(`

    #### `TEXT`

    `` `OBJECT``)`

        Returns the node's textual content.

  - function `(`

    #### `ADVANCE`

    `` ```)`

        Skips a chracter if possible.
        Returns the new index or NIL.

  - function `(`

    #### `ADVANCE-N`

    `` `N``)`

        Advances by N characters if possible.
        Returns the new *INDEX*.

  - function `(`

    #### `ALLOWED-CHAR-P`

    `` `CHAR``)`

        Returns T if the character is a permitted XML character.

  - function `(`

    #### `APPEND-CHILD`

    `` `PARENT CHILD``)`

        Appends the given child onto the parent's child list.
        Returns the child.

  - function `(`

    #### `CDATA-P`

    `` `OBJECT``)`

        Returns T if the given OBJECT is of type CDATA

  - function `(`

    #### `CHILD-ELEMENTS`

    `` `NESTING-NODE``)`

        Returns a new vector of children of the given node, filtered to elements.

  - function `(`

    #### `CHILD-NODE-P`

    `` `OBJECT``)`

        Returns T if the given OBJECT is of type CHILD-NODE

  - function `(`

    #### `CHILD-POSITION`

    `` `CHILD``)`

        Returns the index of the child within its parent.

  - function `(`

    #### `CLEAR`

    `` `NESTING-NODE``)`

        Clears all children from the node.

        Noe that the PARENT of all child elements is set to NIL.

  - function `(`

    #### `CLONE-ATTRIBUTES`

    `` `NODE``)`

        Clone the attribute map.
        Note that keys and values are NOT copied/cloned.

  - function `(`

    #### `CLONE-CHILDREN`

    `` `NODE &OPTIONAL DEEP NEW-PARENT``)`

        Clone the array of children.
        If DEEP is non-NIL, each child is cloned as per (CLONE-NODE NODE T).
        When copying deeply, you can also pass a NEW-PARENT to set on each child.

  - function `(`

    #### `COMMENT-P`

    `` `OBJECT``)`

        Returns T if the given OBJECT is of type COMMENT

  - function `(`

    #### `CONSUME`

    `` ```)`

        Consumes a single character if possible and returns it.
        Otherwise returns NIL.

  - function `(`

    #### `CONSUME-UNTIL`

    `` `MATCHER``)`

        Consumes until the provided matcher function returns positively.
        Returns the substring that was consumed.

  - function `(`

    #### `DECODE-ENTITIES`

    `` `TEXT &OPTIONAL REMOVE-INVALID``)`

        Translates all entities in the text into their character counterparts if possible.
        If an entity does not match, it is left in place unless REMOVE-INVALID is non-NIL.

  - function `(`

    #### `DISCOURAGED-CHAR-P`

    `` `CHAR``)`

        Returns T if the character is a discouraged XML character.

  - function `(`

    #### `DOCTYPE-P`

    `` `OBJECT``)`

        Returns T if the given OBJECT is of type DOCTYPE

  - function `(`

    #### `ELEMENT-P`

    `` `OBJECT``)`

        Returns T if the given OBJECT is of type ELEMENT

  - function `(`

    #### `ELEMENT-POSITION`

    `` `CHILD``)`

        Returns the index of the child within its parent, counting only elements.
        This excludes comments, text-nodes and the like.

  - function `(`

    #### `ENCODE-ENTITIES`

    `` `TEXT &OPTIONAL STREAM``)`

        Encodes the characters < > & " with their XML entity equivalents.

        If no STREAM is given, it encodes to a new string.

  - function `(`

    #### `ENSURE-ATTRIBUTE-MAP`

    `` `TABLE``)`

        Ensures that the TABLE is suitable as an attribute-map.
        If it is not, the table is copied into a proper attribute-map.

  - function `(`

    #### `ENSURE-CHILD-ARRAY`

    `` `ARRAY``)`

        If the ARRAY is suitable as a child-array, it is returned.
        Otherwise the array's elements are copied over into a proper
        child-array.

  - function `(`

    #### `FAMILY`

    `` `CHILD``)`

        Returns the direct array of children of the parent of the given child.
        Note that modifying this array directly modifies that of the parent.

  - function `(`

    #### `FAMILY-ELEMENTS`

    `` `CHILD``)`

        Returns the direct array of children elements of the parent of the given child.
        Note that this is a copy of the array, modifying it is safe.
        This excludes comments, text-nodes and the like.

  - function `(`

    #### `FIRST-CHILD`

    `` `ELEMENT``)`

        Returns the first child within the parent or NIL
        if the parent is empty.

  - function `(`

    #### `FIRST-ELEMENT`

    `` `ELEMENT``)`

        Returns the first child element within the parent or NIL
        if the parent is empty. This excludes comments, text-nodes and the like.

  - function `(`

    #### `FULLTEXT-ELEMENT-P`

    `` `OBJECT``)`

        Returns T if the given OBJECT is of type FULLTEXT-ELEMENT

  - function `(`

    #### `GET-ATTRIBUTE`

    `` `ELEMENT ATTRIBUTE``)`

        Synonymous to ATTRIBUTE.

  - function `(`

    #### `GET-ELEMENT-BY-ID`

    `` `NODE ID``)`

        Searches the given node and returns the first
        node at arbitrary depth that matches the given ID
        attribute.

  - function `(`

    #### `GET-ELEMENTS-BY-TAG-NAME`

    `` `NODE TAG``)`

        Searches the given node and returns an unordered
        list of child nodes at arbitrary depth that match
        the given tag.

  - function `(`

    #### `HAS-ATTRIBUTE`

    `` `ELEMENT ATTRIBUTE``)`

        Returns T if the provided attribute exists.

  - function `(`

    #### `HAS-CHILD-NODES`

    `` `NODE``)`

        Returns T if the node can contain children and
        the child array is not empty.

  - function `(`

    #### `INSERT-AFTER`

    `` `ELEMENT NEW-CHILD``)`

        Inserts the new-child after the given element in the parent's list.
        Returns the new child.

        Note that this operation is potentially very costly.
        See VECTOR-PUSH-EXTEND-POSITION

  - function `(`

    #### `INSERT-BEFORE`

    `` `ELEMENT NEW-CHILD``)`

        Inserts the new-child before the given element in the parent's list.
        Returns the new child.

        Note that this operation is potentially very costly.
        See VECTOR-PUSH-EXTEND-POSITION

  - function `(`

    #### `LAST-CHILD`

    `` `ELEMENT``)`

        Returns the last child within the parent or NIL
        if the parent is empty.

  - function `(`

    #### `LAST-ELEMENT`

    `` `ELEMENT``)`

        Returns the last child element within the parent or NIL
        if the parent is empty. This excludes comments, text-nodes and the like.

  - function `(`

    #### `MAKE-ATTRIBUTE-MAP`

    `` `&OPTIONAL (SIZE 0)``)`

        Creates a map to contain attributes.

  - function `(`

    #### `MAKE-CDATA`

    `` `PARENT &KEY (TEXT "")``)`

        Creates an XML CDATA section under the parent.

        Note that the element is automatically appended to the parent's child list.

  - function `(`

    #### `MAKE-CHILD-ARRAY`

    `` `&OPTIONAL (SIZE 0)``)`

        Creates an array to contain child elements

  - function `(`

    #### `MAKE-COMMENT`

    `` `PARENT &OPTIONAL (TEXT "")``)`

        Creates a new comment node under the parent.

        Note that the node is automatically appended to the parent's child list.

  - function `(`

    #### `MAKE-DOCTYPE`

    `` `PARENT DOCTYPE``)`

        Creates a new doctype node under the parent.

        Note that the node is automatically appended to the parent's child list.

  - function `(`

    #### `MAKE-ELEMENT`

    `` `PARENT TAG &KEY (CHILDREN (MAKE-CHILD-ARRAY)) (ATTRIBUTES (MAKE-ATTRIBUTE-MAP))``)`

        Creates a standard DOM element with the given tag name and parent.
        Optionally a vector (with fill-pointer) containing children and an
        attribute-map (a hash-table with equalp test) can be supplied.

        Note that the element is automatically appended to the parent's child list.

  - function `(`

    #### `MAKE-FULLTEXT-ELEMENT`

    `` `PARENT TAG &KEY TEXT (ATTRIBUTES (MAKE-ATTRIBUTE-MAP))``)`

        Creates a fulltext element under the parent.
        Optionally a text and an attribute-map (a hash-table with equalp test)
        can be supplied.

        Note that the element is automatically appended to the parent's child list.

  - function `(`

    #### `MAKE-PROCESSING-INSTRUCTION`

    `` `PARENT &KEY NAME (TEXT "")``)`

        Creates an XML processing instruction under the parent.

        Note that the element is automatically appended to the parent's child list.

  - function `(`

    #### `MAKE-ROOT`

    `` `&OPTIONAL (CHILDREN (MAKE-CHILD-ARRAY))``)`

        Creates a root node with the given children.
        Children should be a vector with fill-pointer.

  - function `(`

    #### `MAKE-TEXT-NODE`

    `` `PARENT &OPTIONAL (TEXT "")``)`

        Creates a new text node under the parent.

        Note that the node is automatically appended to the parent's child list.

  - function `(`

    #### `MAKE-XML-HEADER`

    `` `PARENT &KEY (ATTRIBUTES (MAKE-ATTRIBUTE-MAP))``)`

        Creates an XML header object under the parent.

        Note that the element is automatically appended to the parent's child list.

  - function `(`

    #### `MATCHER-AND`

    `` `&REST MATCHERS``)`

        Creates a matcher function that returns if all of the sub-expressions
        return successfully. The last match is returned, if all.

  - function `(`

    #### `MATCHER-CHARACTER`

    `` `CHARACTER``)`

        Creates a matcher function that attempts to match the given character.

  - function `(`

    #### `MATCHER-FIND`

    `` `LIST``)`

        Creates a matcher function that returns T if the character is found in the given list.

  - function `(`

    #### `MATCHER-NEXT`

    `` `MATCHER``)`

        Creates a matcher environment that peeks ahead one farther.

  - function `(`

    #### `MATCHER-NOT`

    `` `MATCHER``)`

        Creates a matcher function that inverts the result of the sub-expression.

  - function `(`

    #### `MATCHER-OR`

    `` `&REST MATCHERS``)`

        Creates a matcher function that returns successfully if any of the
        sub-expressions return successfully. The first match is returned, if any.

  - function `(`

    #### `MATCHER-PREV`

    `` `MATCHER``)`

        Creates a matcher environment that peeks behind.

  - function `(`

    #### `MATCHER-RANGE`

    `` `FROM TO``)`

        Creates a matcher that checks a range according to the next character's CHAR-CODE.

  - function `(`

    #### `MATCHER-STRING`

    `` `STRING``)`

        Creates a matcher function that attempts to match the given string.

  - function `(`

    #### `NESTING-NODE-P`

    `` `OBJECT``)`

        Returns T if the given OBJECT is of type NESTING-NODE

  - function `(`

    #### `NEXT-ELEMENT`

    `` `CHILD``)`

        Returns the sibling element next to this one or NIL if
        it is already last. This excludes comments, text-nodes and the like.

  - function `(`

    #### `NEXT-SIBLING`

    `` `CHILD``)`

        Returns the sibling next to this one or NIL if
        it is already the last.

  - function `(`

    #### `NODE-P`

    `` `OBJECT``)`

        Returns T if the given OBJECT is of type NODE

  - function `(`

    #### `PEEK`

    `` ```)`

        Returns the next character, if any.

  - function `(`

    #### `PREPEND-CHILD`

    `` `PARENT CHILD``)`

        Prepends the given child onto the parent's child list.
        Returns the child.

        Note that this operation is costly, see VECTOR-PUSH-EXTEND-FRONT

  - function `(`

    #### `PREVIOUS-ELEMENT`

    `` `CHILD``)`

        Returns the sibling element next to this one or NIL if
        it is already last. This excludes comments, text-nodes and the like.

  - function `(`

    #### `PREVIOUS-SIBLING`

    `` `CHILD``)`

        Returns the sibling before this one or NIL if
        it is already the first.

  - function `(`

    #### `PROCESSING-INSTRUCTION-P`

    `` `OBJECT``)`

        Returns T if the given OBJECT is of type PROCESSING-INSTRUCTION

  - function `(`

    #### `READ-ATTRIBUTE`

    `` ```)`

        Reads an attribute and returns it as a key value cons.

  - function `(`

    #### `READ-ATTRIBUTE-NAME`

    `` ```)`

        Reads an attribute name.

  - function `(`

    #### `READ-ATTRIBUTE-VALUE`

    `` ```)`

        Reads an attribute value, either enclosed in quotation marks or until a space or tag end.

  - function `(`

    #### `READ-ATTRIBUTES`

    `` ```)`

        Reads as many attributes as possible from a tag and returns them as an attribute map.

  - function `(`

    #### `READ-CHILDREN`

    `` ```)`

        Read all children of the current *root* until the closing tag for *root* is encountered.

  - function `(`

    #### `READ-NAME`

    `` ```)`

        Reads and returns a tag name.

  - function `(`

    #### `READ-ROOT`

    `` `&OPTIONAL (ROOT (MAKE-ROOT))``)`

        Creates a root element and reads nodes into it.
        Optionally uses the specified root to append child nodes to.
        Returns the root.

  - function `(`

    #### `READ-STANDARD-TAG`

    `` `NAME``)`

        Reads an arbitrary tag and returns it.
        This recurses with READ-CHILDREN.

  - function `(`

    #### `READ-TAG`

    `` ```)`

        Attempts to read a tag and dispatches or defaults to READ-STANDARD-TAG.
        Returns the completed node if one can be read.

  - function `(`

    #### `READ-TAG-CONTENTS`

    `` ```)`

        Reads and returns all tag contents.
        E.g. <foo bar baz> => bar baz

  - function `(`

    #### `READ-TEXT`

    `` ```)`

        Reads and returns a text-node.

  - function `(`

    #### `REMOVE-ATTRIBUTE`

    `` `ELEMENT ATTRIBUTE``)`

        Remove the specified attribute if it exists.
        Returns NIL.

  - function `(`

    #### `REMOVE-CHILD`

    `` `CHILD``)`

        Removes the child from its parent.
        Returns the child.

        Note that this operation is potentially very costly.
        See VECTOR-POP-POSITION

  - function `(`

    #### `REMOVE-PROCESSING-PARSER`

    `` `PROCESS-NAME``)`

        Remove the processing-parser for PROCESS-NAME.

  - function `(`

    #### `REMOVE-TAG-DISPATCHER`

    `` `NAME &OPTIONAL (LIST '*ALL-TAG-DISPATCHERS*)``)`

        Removes the tag-dispatcher of the given name from the list.

  - function `(`

    #### `RENDER-TEXT`

    `` `NODE``)`

        "Renders" the text of this element and its children.

        In effect the text is gathered from the component and all of
        its children, but transforming the text in such a way that:
        - All ASCII white space (Space, Tab, CR, LF) is converted into spaces.
        - There are no consecutive spaces.
        - There are no spaces at the beginning or end.

        This is somewhat analogous to how the text will be shown to
        the user when rendered by a browser. Hence, render-text.

  - function `(`

    #### `REPLACE-CHILD`

    `` `OLD-CHILD NEW-CHILD``)`

        Replace the old child with a new one.
        Returns the old child.

  - function `(`

    #### `ROOT-P`

    `` `OBJECT``)`

        Returns T if the given OBJECT is of type ROOT

  - function `(`

    #### `SERIALIZE`

    `` `NODE &OPTIONAL (STREAM T)``)`

        Serializes NODE to STREAM.
        STREAM can be a stream, T for *standard-output* or NIL to serialize to string.

  - function `(`

    #### `SET-ATTRIBUTE`

    `` `ELEMENT ATTRIBUTE VALUE``)`

        Synonymous to (SETF (ATTIBUTE ..) ..)

  - function `(`

    #### `SIBLING-ELEMENTS`

    `` `CHILD``)`

        Returns the array of sibling elements of the given child.
        Note that this is a copy of the array, modifying it is safe.
        This excludes comments, text-nodes and the like.

  - function `(`

    #### `SIBLINGS`

    `` `CHILD``)`

        Returns the array of siblings of the given child.
        Note that this is a copy of the array, modifying it is safe.

  - function `(`

    #### `SLURP-STREAM`

    `` `STREAM``)`

        Quickly slurps the stream's contents into an array with fill pointer.

  - function `(`

    #### `SPLICE`

    `` `ELEMENT``)`

        Splices the contents of element into the position of the element in its parent.
        Returns the parent.

        Note that this operation is potentially very costly.
        See ARRAY-SHIFT

  - function `(`

    #### `STRIP`

    `` `NODE``)`

        Trim all text-nodes within NODE (at any depth) of leading and trailing whitespace.
        If their TEXT should be an empty string after trimming, remove them.

  - function `(`

    #### `TAG-DISPATCHER`

    `` `NAME &OPTIONAL (LIST *ALL-TAG-DISPATCHERS*)``)`

        Accessor to the tag-dispatcher of the given name.

  - function `(`

    #### `TEXT-NODE-P`

    `` `OBJECT``)`

        Returns T if the given OBJECT is of type TEXT-NODE

  - function `(`

    #### `TEXTUAL-NODE-P`

    `` `OBJECT``)`

        Returns T if the given OBJECT is of type TEXTUAL-NODE

  - function `(`

    #### `TRANSLATE-ENTITY`

    `` `TEXT &KEY (START 0) (END (LENGTH TEXT))``)`

        Translates the given entity identifier (a name, #Dec or #xHex) into their respective strings if possible.
        Otherwise returns NIL.

  - function `(`

    #### `TRIM`

    `` `NODE``)`

        Trim all text-nodes within NODE (at any depth) of leading and trailing whitespace.

  - function `(`

    #### `UNREAD`

    `` ```)`

        Steps back a single character if possible.
        Returns the new *INDEX*.

  - function `(`

    #### `UNREAD-N`

    `` `N``)`

        Steps back by N characters if possible.
        Returns the new *INDEX*.

  - function `(`

    #### `WRITE-ENCODE-CHAR`

    `` `CHAR STREAM``)`

        Write and possibly encode the CHAR to STREAM.
        This also properly handles detection of invalid or discouraged XML characters.

        The following restarts are available in the case of a faulty character:
          ABORT              Do not output the faulty character at all.
          USE-NEW-CHARACTER  Output a replacement character instead.
          CONTINUE           Continue and output the faulty character anyway.

        See INVALID-XML-CHARACTER
        See DISCOURAGED-XML-CHARACTER

  - function `(`

    #### `XML-HEADER-P`

    `` `OBJECT``)`

        Returns T if the given OBJECT is of type XML-HEADER

  - generic `(`

    #### `CLONE-NODE`

    `` `NODE &OPTIONAL DEEP``)`

        Clone the given node, creating a new instance with the same contents.
        If DEEP is non-NIL, the following applies:
        The text of COMMENT and TEXT-NODEs is copied as per COPY-SEQ.
        The children of NESTING-NODEs are copied as per (CLONE-CHILDREN CHILD T)

  - generic `(`

    #### `PARSE`

    `` `INPUT &KEY ROOT``)`

        Parses the given input into a DOM representation.
        By default, methods for STRING, PATHNAME and STREAM are defined.
        If supplied, the given root is used to append children to as per READ-ROOT.
        Returns the root.

  - generic `(`

    #### `SERIALIZE-OBJECT`

    `` `NODE``)`

        Serialize the given node and print it to *stream*.

  - generic `(`

    #### `TRAVERSE`

    `` `NODE FUNCTION &KEY TEST``)`

        Traverse the NODE and all its children recursively,
        calling FUNCTION on the current node if calling TEST on the current node
        returns a non-NIL value. It is safe to modify the child array of the
        parent of each node passed to FUNCTION.

        NODE is returned.

  - macro `(`

    #### `DEFINE-FULLTEXT-ELEMENT`

    `` `TAG &REST LISTS``)`

        Defines an element to be read as a full-text element.
        This means that it cannot contain any child-nodes and everything up until its closing
        tag is used as its text.

  - macro `(`

    #### `DEFINE-MATCHER`

    `` `NAME FORM``)`

        Associates NAME as a keyword to the matcher form. You can then use the keyword in further matcher rules.

  - macro `(`

    #### `DEFINE-PROCESSING-PARSER`

    `` `PROCESS-NAME NIL &BODY BODY``)`

        Defines a new processing-instruction parser.
        It is invoked if a processing-instruction (<?) with PROCESS-NAME is encountered.
        The lexer will be at the point straight after reading in the PROCESS-NAME.
        Expected return value is a string to use as the processing-instructions' TEXT.
        The closing tag (?>) should NOT be consumed by a processing-parser.

  - macro `(`

    #### `DEFINE-SELF-CLOSING-ELEMENT`

    `` `TAG &REST LISTS``)`

        Defines an element that does not need to be closed with /> and cannot contain child nodes.

  - macro `(`

    #### `DEFINE-TAG-DISPATCHER`

    `` `(NAME &REST LISTS) (TAGVAR) &BODY BODY``)`

        Defines a new tag dispatcher. It is invoked if TEST-FORM passes.

        NAME      --- Name to discern the dispatcher with.
        LISTS     --- Symbols of lists to which the dispatcher should be added.
        TAGVAR    --- Symbol bound to the tag name.
        BODY      --- Body forms describing the test to match the tag.

  - macro `(`

    #### `DEFINE-TAG-PARSER`

    `` `NAME (TAGVAR) &BODY BODY``)`

        Defines the parser function for a tag dispatcher.

        NAME    --- The name of the tag dispatcher. If one with this name
                    cannot be found, an error is signalled.
        TAGVAR  --- Symbol bound to the tag name.
        BODY    --- Body forms describing the tag parsing behaviour.

  - macro `(`

    #### `DEFINE-TAG-PRINTER`

    `` `NAME (NODEVAR) &BODY BODY``)`

        Defines the printer function for a tag dispatcher.

        NAME    --- The name of the tag dispatcher. If one with this name
                    cannot be found, an error is signalled.
        TAGVAR  --- Symbol bound to the tag name.
        BODY    --- Body forms describing the printing behaviour. Write to
                    the stream bound to PLUMP-DOM:*STREAM*.

  - macro `(`

    #### `DO-TAG-PARSERS`

    `` `(TEST PARSER &OPTIONAL RESULT-FORM) &BODY BODY``)`

        Iterates over the current *TAG-DISPATCHERS*, binding the TEST and PARSER functions.
        Returns RESULT-FORM's evaluated value.

  - macro `(`

    #### `DO-TAG-PRINTERS`

    `` `(TEST PRINTER &OPTIONAL RESULT-FORM) &BODY BODY``)`

        Iterates over the current *TAG-DISPATCHERS*, binding the TEST and PRINTER functions.
        Returns RESULT-FORM's evaluated value.

  - macro `(`

    #### `MAKE-MATCHER`

    `` `FORM``)`

        Macro to create a matcher chain.

  - macro `(`

    #### `MATCHER-ANY`

    `` `&REST IS``)`

        Shorthand for (or (is a) (is b)..)

  - macro `(`

    #### `WITH-LEXER-ENVIRONMENT`

    `` `(STRING) &BODY BODY``)`

        Sets up the required lexing environment for the given string.