Update of /project/cxml/cvsroot/closure-common In directory clnet:/tmp/cvs-serv30482

Modified Files: hax.lisp Log Message: HAX documentation

--- /project/cxml/cvsroot/closure-common/hax.lisp 2007/10/14 17:29:43 1.1 +++ /project/cxml/cvsroot/closure-common/hax.lisp 2007/10/21 14:11:28 1.2 @@ -129,3 +129,268 @@ (:method ((handler default-handler) data) (declare (ignore data)) nil)) + + +;;;; documentation + +(setf (documentation (find-package :hax) t) + "An event protocol for HTML serialization, this package is similar + to the HAX protocol defined by cxml for XML serialization. + + (Technically, this package should have been spelled SAH, but HAX + sounds better.) + + Note that Closure HTML is not a streaming parser yet. Documents + are always parsed in full before the first HAX event is emitted. + In spite of this restriction, the HAX API is useful for HTML + serialization and transformation purposes, and for integration + with SAX. + + @begin[HAX handlers]{section} + @aboutclass{abstract-handler} + @aboutclass{default-handler} + @end{section} + @begin[The attribute protocol]{section} + @aboutclass{standard-attribute} + @aboutfun{make-attribute} + @aboutfun{attribute-name} + @aboutfun{attribute-value} + @aboutfun{attribute-specified-p} + @end{section} + @begin[HAX events]{section} + @aboutfun{start-document} + @aboutfun{start-element} + @aboutfun{end-element} + @aboutfun{characters} + @aboutfun{comment} + @aboutfun{end-document} + @end{section}") + +(setf (documentation 'abstract-handler 'type) + "@short{The superclass of all HAX handlers.} + + Direct subclasses have to implement all event methods, since + no default methods are defined on this class. + + Note that it is permissible to use handlers that are not + instances of this class in some circumstances. + + In particular, + @code{nil} is a valid HAX handler and ignores all events. + + In addition, + @a[http://common-lisp.net/project/cxml/sax.html#sax%5D%7BSAX handlers} + are valid HAX handlers (and vice versa), even though + hax:abstract-handler and sax:abstract-handler do not + share a specific superclass. HAX events sent to SAX handlers are + automatically re-signalled as XHTML SAX events, and SAX events sent + to HAX handlers are re-signalled as namespace-less HAX events. + + However, user code should define subclasses of the documented + superclasses to enable the HAX/SAX bridging described above. + + @see{chtml:parse} + @see{chtml:serialize-lhtml} + @see{chtml:serialize-pt} + @see{start-document} + @see{end-document} + @see{start-element} + @see{end-element} + @see{characters} + @see{comment}") + +(setf (documentation 'default-handler 'type) + "@short{A no-op HAX handler.} + + This class defines methods for all HAX events that do nothing. + It is useful as a superclass when implementing a HAX handler that + is interested in only some events and not others. + + @see{chtml:parse} + @see{chtml:serialize-lhtml} + @see{chtml:serialize-pt} + @see{start-document} + @see{end-document} + @see{start-element} + @see{end-element} + @see{characters} + @see{comment}") + +(setf (documentation 'standard-attribute 'type) + "@short{An implementation of the HAX attribute protocol.} + + A standard class implementing the generic functions for HAX + attributes. Instances of this class can be passed to + @fun{hax:start-element} in the list of attributes. + + @see-slot{attribute-name} + @see-slot{attribute-value} + @see-slot{attribute-specified-p} + @see-constructor{make-instance}") + +(setf (documentation 'make-attribute 'function) + "@arg[name]{a string/rod} + @arg[value]{a string/rod} + @arg[specified-p]{a boolean, default is @code{t}} + @return{an instance of @class{standard-attribute}.} + @short{Creates a HAX attribute.} + + Creates an instance that can be used with the generic functions + for HAX attributes. The result can be passed to + @fun{hax:start-element} in the list of attributes. + + @see{attribute-name} + @see{attribute-value} + @see{attribute-specified-p}") + +(setf (documentation 'find-attribute 'function) + "@arg[name]{a string/rod} + @arg[attrs]{a list of attributes} + @return{an attribute, or nil} + @short{Searches for an attribute by name.} + + Returns the first attribute in @var{attrs} with the specified name, + or @code{nil} if no such attribute was found. + + @see{attribute-name}") + +(setf (documentation 'attribute-name 'function) + "@arg[instance]{any class implementing this function} + @return{a string/rod} + @short{Return an attribute's name.} + + Instances of this classes implementing this function can be passed to + @fun{hax:start-element} in the list of attributes. + + @see{attribute-value} + @see{attribute-specified-p}") + +(setf (documentation 'attribute-value 'function) + "@arg[instance]{any class implementing this function} + @return{a string/rod} + @short{Return an attribute's value.} + + Instances of this classes implementing this function can be passed to + @fun{hax:start-element} in the list of attributes. + + @see{attribute-name} + @see{attribute-specified-p}") + +(setf (documentation 'attribute-specified-p 'function) + "@arg[instance]{any class implementing this function} + @return{a string/rod} + @short{Return whether the attribute was contained the parsed document.} + + Attributes return @code{nil} here if they resulted from a default + value declaration in a DTD. + + Instances of this classes implementing this function can be passed to + @fun{hax:start-element} in the list of attributes. + + @see{attribute-name} + @see{attribute-value}") + +(setf (documentation 'start-document 'function) + "@arg[handler]{a HAX/SAX handler + (see @class{abstract-handler} for details)} + @arg[name]{root element name, a rod/string} + @arg[public-id]{nil or the Public ID, a rod/string} + @arg[system-id]{nil or the System ID/URI, a rod/string} + @return{unspecified} + @short{Signals the beginning on an HTML document.} + + This is the first event sent to any handler. + + If @var{system-id} is non-nil, the document includes a doctype + declaration. + + @see{start-element} + @see{end-element} + @see{characters} + @see{comment} + @see{end-document}") + +(setf (documentation 'start-element 'function) + "@arg[handler]{a HAX/SAX handler + (see @class{abstract-handler} for details)} + @arg[name]{root element name, a rod/string} + @arg[attributes]{a list of attributes} + @return{unspecified} + @short{Signals the beginning of an HTML element.} + + This event corresponds to the opening tag of an element. + + Elements of the attribute list can have any class, but must implement + the generic functions for attributes. See @class{standard-attribute} + for the built-in attribute implementation. + + @see{find-attribute} + @see{start-document} + @see{end-element} + @see{characters} + @see{comment} + @see{end-document}") + +(setf (documentation 'end-element 'function) + "@arg[handler]{a HAX/SAX handler + (see @class{abstract-handler} for details)} + @arg[name]{root element name, a rod/string} + @return{unspecified} + @short{Signals the end of an HTML element.} + + This event corresponds to the closing tag of an element. + + @see{start-document} + @see{start-element} + @see{characters} + @see{comment} + @see{end-document}") + +(setf (documentation 'characters 'function) + "@arg[handler]{a HAX/SAX handler + (see @class{abstract-handler} for details)} + @arg[data]{rod/string} + @return{unspecified} + @short{Signals character data.} + + This event represents character data in a document. + + @see{start-document} + @see{start-element} + @see{end-element} + @see{comment} + @see{end-document}") + +(setf (documentation 'comment 'function) + "@arg[handler]{a HAX/SAX handler + (see @class{abstract-handler} for details)} + @arg[data]{rod/string} + @return{unspecified} + @short{Signals a comment.} + + This event represents a comment. + + @see{start-document} + @see{start-element} + @see{end-element} + @see{characters} + @see{end-document}") + +(setf (documentation 'end-document 'function) + "@arg[handler]{a HAX/SAX handler + (see @class{abstract-handler} for details)} + @return{The return value of this function depends on the handler class.} + @short{Signals the end on an HTML document.} + + This is the last event sent to any handler, and signals the end of + serialization. + + The return value of this function is usually returned to user code + by higher-level serialization functions and can be considered the + result of serialization and "return value" of the handler. + + @see{start-document} + @see{start-element} + @see{end-element} + @see{characters} + @see{comment}")