CommonDoc ยป Nodes

A node is a subtree of a document. Nodes range from atomic nodes like text nodes and images to containing nodes like paragraphs, bold text nodes, or section nodes.

Metadata

make-meta(pairs)
Create a metadata table from a list of pairs. If the list is empty, return an empty metadata table.
get-meta(node key)
Find the value corresponding to key in the node's metadata. If not found, return NIL.
do-meta((key value node) &body body)
Iterate over the keys and values of a node's metadata.

Basic Classes

document

A document.

Metadata is mostly based on Dublin Core and the OpenDocument format.

  • children
    The document's children nodes.
  • title
    The document's title.
  • creator
    The creator of the document.
  • publisher
    The document's publisher.
  • subject
    The subject the document deals with.
  • description
    A description of the document.
  • keywords
    A list of strings, each being a keyword for the document.
  • reference
    A reference string to uniquely identify the document within a certain context.
  • language
    An RFC4646 string denoting the language the document is written in.
  • rights
    Information on the document's copyright.
  • version
    The document version.
  • created-on
    The date and time when the document was created. By default, this is the date and time at instance creation.
section
Represents a section in the document. Unlike HTML, where a section is just another element, sections in CommonDoc contain their contents.
  • title
    The section title.
document-node
The base class of all document classes.
  • metadata
    Node metadata.
  • reference
    A unique string identifying the node.
content-node
A node with children. This is the base class of all nodes that have a children slot (Except document, since this class inherits from document-node) and can also be used as a way to represent a generic grouping of elements. This is useful when building a CommonDoc document by parsing some input language.
  • children
    The node's children.
text-node
A node representing a bare string of text.
  • text
    The node's text.
paragraph
A paragraph.

    Inline Nodes

    markup
    The superclass of all inline markup elements.
      bold
      Text in this element is bold.
        italic
        Text in this element is italicized.
          underline
          Text in this element is underlined.
            strikethrough
            Text in this element is striked out.
              code
              Text in this element is monospaced or otherwise marked as code or computer output.
                superscript
                Text in this element is superscripted relative to containing elements.
                  subscript
                  Text in this element is subscripted relative to containing elements.

                    Code

                    code-block
                    A block of code.
                    • language
                      The language of the code block's contents.

                    Quotes

                    base-quote
                    The base class of all quotes.
                      inline-quote
                      A quote that occurs inside a paragraph in the document.
                        block-quote
                        A block quote.

                          Links

                          link
                          The base class for all links, internal and external.
                            document-link
                            A link to a section of this document, to another document and optionally a section within that document. See also the reference slot in the document class.
                            • document-reference
                              A reference ID for the linked document. If NIL, the link is only to a section within the document.
                            • node-reference
                              A reference ID for the linked node.
                            web-link
                            An external link.
                            • uri
                              The URI of the external resource.

                            Lists

                            base-list
                            The base class of all lists.
                              unordered-list
                              A list where the elements are unordered.
                              • children
                                The list of list-item instances.
                              ordered-list
                              A list where the elements are ordered.
                              • children
                                The list of list-item instances.
                              definition-list
                              A list of definitions.
                              • children
                                The list of definition instances.
                              list-item
                              The item in a non-definition list.
                                definition
                                An item in a definition list.
                                • term
                                  The definition term.
                                • definition
                                  Defines the term.

                                Images & Figures

                                image
                                An image.
                                • source
                                  The source where the image is stored.
                                • description
                                  A plain text description of the image.
                                figure
                                A figure, an image plus an annotation.
                                • image
                                  The figure's image.
                                • description
                                  A description of the image.

                                Tables

                                table
                                A table.
                                • rows
                                  The list of rows in a table.
                                row
                                A row in a table.
                                • header
                                  The row header.
                                • footer
                                  The row footer.
                                • cells
                                  The cells in the row.
                                cell
                                A cell in a table.

                                  Constructors

                                  make-content(children &key metadata reference)
                                  Create a content node from its children.
                                  make-text(string &key metadata reference)
                                  Create a text node from the contents of a string.
                                  make-paragraph(children &key metadata reference)
                                  Create a paragraph node from its children.
                                  make-bold(children &key metadata reference)
                                  Create a bold node from its children.
                                  make-italic(children &key metadata reference)
                                  Create an italicized node from its children.
                                  make-underline(children &key metadata reference)
                                  Create an underlined node from its children.
                                  make-strikethrough(children &key metadata reference)
                                  Create an striked out node from its children.
                                  make-code(children &key metadata reference)
                                  Create an inline code node from its children.
                                  make-superscript(children &key metadata reference)
                                  Create a superscripted node from its children.
                                  make-subscript(children &key metadata reference)
                                  Create a subscripted node from its children.
                                  make-code-block(language children &key metadata reference)
                                  Create a code block node from its children and language.
                                  make-inline-quote(children &key metadata reference)
                                  Create an inline quote node from its children.
                                  make-block-quote(children &key metadata reference)
                                  Create a block quote node from its children.
                                  make-document-link(document reference children &key metadata)
                                  Create a document link from document and node references and its children.
                                  make-web-link(uri children &key metadata reference)
                                  Create a web link.
                                  make-list-item(children &key metadata reference)
                                  Create a list item.
                                  make-definition(term definition &key metadata reference)
                                  Create a definition list item.
                                  make-unordered-list(children &key metadata reference)
                                  Create an unordered list.
                                  make-ordered-list(children &key metadata reference)
                                  Create an ordered list.
                                  make-definition-list(children &key metadata reference)
                                  Create a definition list.
                                  make-image(source &key description metadata reference)
                                  Create an image.
                                  make-figure(image description &key metadata reference)
                                  Create a figure.
                                  make-table(rows &key metadata reference)
                                  Create a table from a list of rows.
                                  make-row(cells &key metadata reference)
                                  Create a row from a list of cells.
                                  make-cell(children &key metadata reference)
                                  Create a cell from its children.
                                  make-section(title &key children reference metadata)
                                  Create a section from its title and children.
                                  make-document(title &key children keywords &allow-other-keys)
                                  Create a document.

                                  Examples

                                  We'll create an example document using the constructor functions:

                                  (in-package :common-doc)

(make-document "My Document"
  :children
  (list
    (make-section (list (make-text "Introduction"))
      :children
      (list
        (make-paragraph
          (list (make-text "...")))))))

                                  We can use the dump function to inspect the structure of this document:

                                  COMMON-DOC> (dump my-doc)
document
  section
    paragraph
      text-node
        "..."

                                  Some examples of accessors:

                                  CL-USER> (in-package :common-doc)
#<PACKAGE "COMMON-DOC">

COMMON-DOC> (text (make-text "Hello, world!"))
"Hello, world!"

COMMON-DOC> (children (make-paragraph
                        (list (make-text "This is ")
                              (make-text "a test"))))
(#<TEXT-NODE text: This is > #<TEXT-NODE text: a test>)

COMMON-DOC> (children (make-paragraph (list (make-text "This is ") (make-text "a test"))))
(#<TEXT-NODE text: This is > #<TEXT-NODE text: a test>)

COMMON-DOC> (make-code-block "lisp" (list (make-text "(progn ...)")))
#<CODE-BLOCK children: TEXT-NODE>

COMMON-DOC> (language *)
"lisp"

COMMON-DOC> (children **)
(#<TEXT-NODE text: (progn ...)>)