Common Lisp Package: DOCUTILS

Document handling and structured text parsing

README:

FUNCTION

Public

IDS (ELEMENT)

Return mapping of ids to nodes in element.

NAMEIDS (ELEMENT &OPTIONAL (IDS (IDS (DOCUMENT ELEMENT))))

Mapping of names to unique id's.

REFIDS (ELEMENT)

Mapping of ids to lists of referencing nodes.

REFNAMES (ELEMENT)

Return mapping of names to lists of referencing nodes.

REPORT (LEVEL MESSAGE &KEY (NODE *SYSTEM-MESSAGE-DESTINATION*) (LINE (IF NODE (LINE NODE) *CURRENT-LINE-NUMBER*)) SOURCE BACKREFS DATA)

Signals a report. Handlers will check settings to either halt processing or issue a report and return. If a system message has been added by handler, it is returned using the system-message restart

SET-ID (NODE &OPTIONAL (DOCUMENT (DOCUMENT NODE)) (IDS (IDS DOCUMENT)))

This will set and return the id for a node.

Undocumented

ADD-BACKREF (ELEMENT ID)

NAMED-NODE (ELEMENT NAME)

NEXT-SIBLING (ELEMENT)

PART-APPEND (&REST VALUES)

PART-PREPEND (&REST VALUES)

PREV-SIBLING (ELEMENT)

READ-RST (INPUT)

REGISTER-SETTINGS-SPEC (NEW-SPEC)

WRITE-HTML (OS DOCUMENT)

WRITE-LATEX (OS DOCUMENT)

Private

ERROR (DATUM &REST ARGUMENTS)

Invoke the signal facility on a condition formed from DATUM and ARGUMENTS. If the condition is not handled, the debugger is invoked.

HANDLE-TRANSFORM-CONDITION (E DOCUMENT)

Deal with transform errors, adding system message to messages node

MOVE-CHILDREN (FROM-ELEMENT TO-ELEMENT)

Move the children from one node to another. Returns the list of children in to-element

SET-DUPLICATE-NAME-ID (IDS NAMEIDS NAMETYPES NODE)

The following state transition table shows how `self.nameids` wand `self.nametypes`change with new input and what actions are performed: ==== ===== ======== ======== ======= ==== ===== ===== Old State Input Action New State Notes ----------- -------- ----------------- ----------- ----- ids types new type sys.msg. dupname ids types ==== ===== ======== ======== ======= ==== ===== ===== -- -- explicit -- -- new True -- -- implicit -- -- new False None False explicit -- -- new True old False explicit implicit old new True None True explicit explicit new None True old True explicit explicit new,old None True [#]_ None False implicit implicit new None False old False implicit implicit new,old None False None True implicit implicit new None True old True implicit implicit new old True ==== ===== ======== ======== ======= ==== ===== ===== .. [#] Do not clear the name-to-id map or invalidate the old target if both old and new targets are external and refer to identical URIs. The new target is invalidated regardless.

TRANSFORM-CMP (A B)

Transforms compared by priority and order in which created

Undocumented

ADD-TRANSFORM (TRANSFORM)

READ-SETTINGS (FNAME &OPTIONAL (SETTINGS (MAKE-HASH-TABLE)))

MACRO

Public

WITH-ATTRIBUTES ((KEY VALUE NODE &KEY (COPY NIL)) &BODY BODY)

Interate body over the attributes of a node setting key and value in turn. If keyword copy is true, the iteration will be over a list of the attribute list may be modified during iteration, otherwise it may not.

WITH-CHILDREN ((NODE PARENT &KEY (COPY NIL)) &BODY BODY)

Exevute body over the children of a node During execution of the body a catch tags is available for :skip-siblings which will terminate the iteration

WITH-NODES ((NODE ROOT &KEY (COPY NIL)) &BODY BODY)

Traverse a node tree depth first executing body for side affects. The body is executed then children are traversed (if an element). During execution of the body catch tags are available for :skip-children and :skip-siblings to finish processing children of current node or children of parent node. Execution is inside a nil block. Returns nil

Undocumented

COLLATE-NODES ((NODE ROOT) TEST)

WITH-PART ((PART-NAME) &BODY BODY)

WITH-REPORTS-TO-NODE ((NODE) &BODY BODY)

GENERIC-FUNCTION

Public

ADD-CHILD (PARENT CHILD &OPTIONAL INDEX)

Add child as a child node of node, either inserting it at position index or appending it to the end if no index is specified (default)

ADD-CLASS (NODE NAME)

Add class to given node

ALLOWED-CHILD-P (PARENT NODE &OPTIONAL INDEX)

Return true if node is allowed as a child of parent

AS-SEXP (ELEMENT)

Return lisp s-exp representation of an element

AS-TEXT (ELEMENT)

Return text representation of an element as a string

SETFAS-TEXT (VALUE ELEMENT)

Set the text value of a node (if allowed)

ATTRIBUTE (NODE LABEL)

Return an attribute of a node corresponding to label

SETFATTRIBUTE (VALUE NODE LABEL)

Set a named attribute of an element

CHILD (PARENT INDEX)

Return a child at position index

COPY-OF-NODE (NODE)

Deep copy a node

ERROR-SEVERITY (ENTITY)

Return the error-severity (0-10) for an entity

EVALUATE (NODE)

Evaluate the node in current dynamic context, returning the result.

FIELD-VALUE (NAME FIELD-LIST)

Return the field text for a specific field name

INDEX (PARENT CHILD)

Return the posiiton of child in element

LANGUAGE (NODE)

Language for this node

MAKE-NODE (NODE-TYPE &REST ATTRIBUTES)

Make a node with given initialisers

NEW-DOCUMENT (SOURCE)

Create and return a new empty document tree (root node).

NUMBER-CHILDREN (NODE)

Reutrn the number of children a node has

READ-DOCUMENT (SOURCE READER)

Create and read a new document using reader from source

READ-LINES (ENTITY)

Read and return a vector of lines from an entity for subsequent parsing

REM-ATTRIBUTE (NODE LABEL)

Remove an attribute from a node

REM-CHILD (PARENT CHILD-REF)

Remove a child element from parent

REMOVE-NODE (NODE &OPTIONAL INDEX)

Remove a node

SETTING (NAME ENTITY)

Return the value of given setting for entity

SETFSETTING (VALUE KEY ELEMENT)

Set a setting value for an entity

SUBSTITUTE-NODE (NEW OLD &OPTIONAL PARENT)

Substitute new node for and old node in document tree

SUPPORTS-FORMAT (WRITER FORMAT)

Returns true if given writer supports a specific format

TRANSFORM (TRANSFORM)

Apply a given transform to its' document node

TRANSFORMS (READER)

Return a list of the default transforms class names to be applied after parsing

VISIT-NODE (WRITER ENTITY)

Process entity for writer where entity is any entity in the document.

WRITE-DOCUMENT (WRITER DOCUMENT DESTINATION)

Write document out to destination using given writer

WRITE-PART (WRITER PART OUTPUT-STREAM)

Write a document part from writer to an output stream.

Undocumented

ERROR-DATA (CONDITION)

ERROR-LEVEL (CONDITION)

ERROR-LINE (CONDITION)

SETFERROR-LINE (NEW-VALUE CONDITION)

ERROR-MESSAGE (CONDITION)

ERROR-NODE (CONDITION)

ERROR-TEXT-BLOCK (CONDITION)

SETFSETTINGS (VALUE DOCUMENT)

Private

ABSTRACT (ENTITY)

Return the abstract of an entity

CHILD-TEXT-SEPARATOR (ELEMENT)

Return separator for child nodes in as-text

CMP (A B)

Comparison function for ordering sequences of entities

DO-TRANSFORMS (TRANSFORMS DOCUMENT)

Apply the transformations to this document in order. Any system messages are added into a dedicated section at the end of the document

IMPLICIT-TARGET-P (NODE)

Return true if an implicit target

RESOLVE-DEPENDANCY (NODE URI)

Return full path corresponding to uri in a node

SETUP-CHILD (NODE CHLD &OPTIONAL INDEX)

Setup up a child after adding to (arent at index

TAGNAME (ELEMENT)

The element generic identifier.

Undocumented

ERROR-BACKREFS (CONDITION)

ERROR-SOURCE (CONDITION)

SLOT-ACCESSOR

Public

DOCUMENT (NODE)

The Return the document root of the tree containing this node

SETFDOCUMENT (DOCUMENT COMPONENT)

The Set the document to be processed and reset the component

LINE (ELEMENT)

The The line number (1-based) of the beginning of this Node in `source`.

NODE (OBJECT)

Current node in document

SETFNODE (NEW-VALUE OBJECT)

Current node in document

OUTPUT-FORMAT (OBJECT)

Specifies what format the output is in (for writers).

PARENT (NODE)

The Back-reference to the Node immediately containing this Node.

SETFPARENT (NEW-VALUE OBJECT)

Set the Back-reference to the Node immediately containing this Node.

PARTS (OBJECT)

List of slot names for component parts in the output. The writer should accumulate strings on each part using push.

SETTINGS (OBJECT)

Overwritten setting affecting document writing

Undocumented

BACKREFS (OBJECT)

EVALUATION-LANGUAGE (OBJECT)

REFERENCED (OBJECT)

SETFREFERENCED (NEW-VALUE OBJECT)

RESOLVED (OBJECT)

SETFRESOLVED (NEW-VALUE OBJECT)

Private

CURRENT-ID (OBJECT)

current id.

SETFCURRENT-ID (NEW-VALUE OBJECT)

current id.

DATE (OBJECT)

Set date

SETFDATE (NEW-VALUE OBJECT)

Set date

EXPRESSION (OBJECT)

Read expression to be evaluated at some later time.

PRIORITY (OBJECT)

Numerical priority of this transform, 0 through 999.

Undocumented

ORDER (OBJECT)

VARIABLE

Public

*CURRENT-LINE-NUMBER*

Current line number - used for line in node creation

*DEFAULT-READER-PACKAGE*

The default package Lisp expressions in the document are to be read into

*DOCUMENT*

Document (root element) currently being operated on

*EVALUATION-ERROR-HOOK*

Hook to call when there is an error in the evaluator

*EVALUATOR*

Function to call when evaluating an evaluateable node

*UNKNOWN-REFERENCE-RESOLVERS*

List of functions to try to resolve unknown references. Unknown references have a 'refname' attribute which doesn't correspond to any target in the document. Called when FinalCheckVisitor is unable to find a correct target. The list should contain functions which will try to resolve unknown references, with the following signature:: (defun reference_resolver(node) "Returns boolean: true if resolved, false if not." )

Private

*CONFIG-FILES-READ*

List of configuration files already read.

*CURRENT-WRITER*

Writer currently processing document

*CURRENT-WRITER-PART*

current destination writer slot

*REVISION*

(major minor micro) version number. The micro number is bumped for API changes, for new functionality, and for interim project releases. The minor number is bumped whenever there is a significant project release. The major number will be bumped when the project is feature-complete, and perhaps if there is a major change in the design.

*SETTINGS-SPEC*

Hash of of configuration parameters

*STANDARD-CONFIG-FILES*

List of standard docutils configuration files

*SYSTEM-MESSAGE-DESTINATION*

Destination node for any system messages

*TRANSFORM-COUNTER*

Used to ensure transforms of the same priority maintain their order

Undocumented

*PENDING-TRANSFORMS*

+ERROR-LEVELS+

CLASS

Public

DOCUMENT (NODE)

The main document root element

NODE (OBJECT)

Abstract base class of nodes in a document tree

READER

Base classes to produce a document from input

TRANSFORM (TRANSFORM)

Docutils transform component abstract base class.

WRITER

Base Class for writing a document

Undocumented

LINE (ELEMENT)

Private

FIXED-TEXT-ELEMENT

An element which directly contains preformatted text.

LABELED

Contains a `label` as its first element.

Undocumented

DATE (OBJECT)

CONDITION

Public

MARKUP-CONDITION

An condition in the structured text markup. level can be used by handlers to determine whether to ignore, print, record or abort parsing

Private

Undocumented

DOCUTILS-CONDITION

ERROR (DATUM &REST ARGUMENTS)

WARNING