package.lisp

   1 (defpackage :cxml-stp
   2   (:use :cl)
   3   (:nicknames :stp)
   4   (:export #:*check-uri-syntax*
   5            #:stp-error
   6
   7            #:node
   8            #:parent
   9            #:root
  10            #:base-uri
  11            #:detach
  12            #:string-value
  13            #:copy
  14            #:serialize
  15            ;; #:query
  16            #:map-children
  17            #:do-children
  18            #:list-children
  19            #:nth-child
  20            #:first-child
  21            #:last-child
  22            #:previous-sibling
  23            #:next-sibling
  24            #:find-child
  25            #:find-child-if
  26            #:child-position
  27            #:child-position-if
  28            #:number-of-children
  29            #:count-children
  30            #:count-children-if
  31            #:filter-children
  32            #:map-recursively
  33            #:do-recursively
  34            #:find-recursively
  35            #:find-recursively-if
  36            #:filter-recursively
  37
  38            #:document
  39            #:make-document
  40            #:document-element
  41
  42            #:parent-node
  43            #:prepend-child
  44            #:append-child
  45            #:delete-child
  46            #:delete-nth-child
  47            #:insert-child
  48            #:insert-child-before
  49            #:insert-child-after
  50            #:delete-child-if
  51            #:delete-children
  52            #:replace-child
  53
  54            ;; #:named-node
  55            #:local-name
  56            #:namespace-prefix
  57            #:namespace-uri
  58            #:of-name
  59            #:qualified-name
  60
  61            #:element
  62            #:make-element
  63            #:add-attribute
  64            #:remove-attribute
  65            #:find-attribute-named
  66            #:find-attribute-if
  67            #:attribute-value
  68            #:list-attributes
  69            #:with-attributes
  70            #:map-attributes
  71            #:find-namespace
  72            #:find-local-namespace
  73            #:find-extra-namespace
  74            #:map-extra-namespaces
  75            #:add-extra-namespace
  76            #:remove-extra-namespace
  77
  78            #:attribute
  79            #:make-attribute
  80            #:value
  81            #:rename-attribute
  82
  83            #:comment
  84            #:make-comment
  85            #:data
  86
  87            #:processing-instruction
  88            #:make-processing-instruction
  89            #:target
  90
  91            #:document-type
  92            #:make-document-type
  93            #:root-element-name
  94            #:system-id
  95            #:public-id
  96            #:internal-subset
  97
  98            #:text
  99            #:make-text
 100
 101            #:make-builder)
 102   (:documentation
 103    "STP is a data structure for well-formed XML documents.
 104
 105     @begin[Parsing and Serializing]{section}
 106     To parse into STP, use an STP builder together with a function
 107     generating SAX events:
 108
 109     @aboutfun{make-builder}
 110     Serialize STP by sending SAX events for the tree to a sink:
 111
 112     @aboutfun{serialize}
 113     @end{section}
 114     @begin[Names and Namespace URIs]{section}
 115     STP represents namespace-well-formed documents only.  All functions
 116     accepting names take a local-name and and a namespace URI as an argument.
 117     Qualified names are accepted where it makes sense, and named nodes have
 118     a namespace prefix that is taken into account for well-formedness checks.
 119
 120     There are two kinds of named nodes: @class{element} and @class{attribute}.
 121     Their slots are:
 122
 123     @aboutfun{local-name}
 124     @aboutfun{namespace-uri}
 125     @aboutfun{namespace-prefix}
 126     For @code{element}, all of the above can be changed using SETF (subject
 127     to well-formedness checks).
 128
 129     For attribute, @fun{local-name} can be changed directly, while URI and
 130     prefix always have to be changed in the same step using
 131     @fun{rename-attribute}.
 132
 133     A node's qualified name can be be queried:
 134
 135     @aboutfun{qualified-name}
 136
 137     @code{of-name} is convenient when searching for elements or attributes:
 138
 139     @aboutfun{of-name}
 140     @end{section}
 141     @begin[Subclasses of Node]{section}
 142     All STP nodes have a common superclass.
 143
 144     @aboutclass{node}
 145     Documents and elements can have children:
 146
 147     @aboutclass{parent-node}
 148     @aboutclass{document}
 149     @aboutclass{element}
 150     Attributes belong to an @code{element}:
 151
 152     @aboutclass{attribute}
 153     Other kinds of nodes:
 154
 155     @aboutclass{comment}
 156     @aboutclass{document-type}
 157     @aboutclass{processing-instruction}
 158     @aboutclass{text}
 159     @end{section}
 160     @begin[Creating nodes]{section}
 161     Nodes are created using the following functions:
 162
 163     @aboutfun{make-attribute}
 164     @aboutfun{make-comment}
 165     @aboutfun{make-document}
 166     @aboutfun{make-document-type}
 167     @aboutfun{make-element}
 168     @aboutfun{make-processing-instruction}
 169     @aboutfun{make-text}
 170     In addition, nodes can be copied including all their children:
 171
 172     @aboutfun{copy}
 173     @end{section}
 174     @begin[Listing Child Nodes]{section}
 175     Nodes have an optional parent node and can have children.
 176
 177     @aboutfun{parent}
 178     If a node has a @class{document} as its ancestor, it can be found using
 179     the @fun{document} function.
 180
 181     @aboutfun{document}
 182     Since the @code{parent} slot needs to be updated when children are added or
 183     removed, the sequence of children is not exposed as a mutable Common
 184     Lisp sequence.
 185
 186     @aboutfun{list-children}
 187     @aboutfun{map-children}
 188     @aboutmacro{do-children}
 189     The following DOM-like functions are also offered:
 190
 191     @aboutfun{nth-child}
 192     @aboutfun{first-child}
 193     @aboutfun{last-child}
 194     @aboutfun{previous-sibling}
 195     @aboutfun{next-sibling}
 196     A wide variety of sequence-related functions is offered that work
 197     like the Common Lisp functions of the same name, but without the need
 198     to call @fun{list-children} first:
 199
 200     @aboutfun{find-child}
 201     @aboutfun{find-child-if}
 202     @aboutfun{child-position}
 203     @aboutfun{child-position-if}
 204     @aboutfun{count-children}
 205     @aboutfun{count-children-if}
 206     @aboutfun{filter-children}
 207     The functions listed above walk only across the direct children of the
 208     parent node.  In addition, the node hierarchy can be mapped recursively
 209     using these functions:
 210
 211     @aboutfun{map-recursively}
 212     @aboutmacro{do-recursively}
 213     @aboutfun{find-recursively}
 214     @aboutfun{filter-recursively}
 215
 216     @end{section}
 217     @begin[Adding and Removing Child Nodes]{section}
 218     While all nodes can be asked for their children, only documents and
 219     elements permit actually adding children.  (For all other nodes, the
 220     sequence of children appears as empty.)
 221
 222     The most flexible function capable of changing the child nodes is
 223     @fun{replace-children}.  Perhaps more common is @fun{insert-child},
 224     a specialized version for only one new child.
 225
 226     @aboutfun{replace-children}
 227     @aboutfun{insert-child}
 228     Various convenience functions are offered in addition:
 229
 230     @aboutfun{prepend-child}
 231     @aboutfun{append-child}
 232     @aboutfun{delete-child}
 233     @aboutfun{delete-child-if}
 234     @aboutfun{delete-nth-child}
 235     @aboutfun{insert-child-before}
 236     @aboutfun{insert-child-after}
 237     @aboutfun{replace-child}
 238     A node can also be deleted from its parent directly using @fun{detach}.
 239
 240     @aboutfun{detach}
 241     @fun{detach} also works for attributes.
 242
 243     @end{section}
 244     @begin[Elements and their Attributes]{section}
 245     In addition to their children, elements have attributes and \"extra
 246     namespaces\".
 247
 248     Attributes themselves are nodes and be accessed using these functions:
 249
 250     @aboutfun{add-attribute}
 251     @aboutfun{remove-attribute}
 252     @aboutfun{find-attribute-named}
 253     @aboutfun{find-attribute-if}
 254     @aboutfun{list-attributes}
 255     @aboutfun{map-attributes}
 256     @aboutmacro{with-attributes}
 257     As a shortcut, the @fun{attribute-value} and its @code{setf} function
 258     allow access to attribute values by name, without having to look up the
 259     attribute node first:
 260
 261     @aboutfun{attribute-value}
 262     There are three ways to declare a namespace: Using the name of the
 263     element, using the name of one of its attributes, or using an \"extra
 264     namespace\".  A prefix can be looked up from any of these local
 265     declarations.  It is also possible to look up a namespace while taking
 266     into account all declarations on parent elements.
 267
 268     @aboutfun{find-local-namespace}
 269     @aboutfun{find-namespace}
 270     Extra namespaces are needed only when a namespace must be declared even
 271     though there is no element or attribute referencing it through its name.
 272     For example, an attribute declared with type @code{QName} using
 273     RelaxNG/XSD must reference a namespace in scope.
 274
 275     @aboutfun{add-extra-namespace}
 276     @aboutfun{remove-extra-namespace}
 277     @aboutfun{find-extra-namespace}
 278     @aboutfun{map-extra-namespaces}
 279     @end{section}"))
 280
 281 (defpackage :cxml-stp-impl
 282   (:use :cl :stp)
 283   (:shadow #:document #:document-type))