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            #:dtd
  98
  99            #:text
 100            #:make-text
 101
 102            #:make-builder)
 103   (:documentation
 104    "STP is a data structure for well-formed XML documents.
 105
 106     @begin[Parsing and Serializing]{section}
 107     To parse into STP, use an STP builder together with a function
 108     generating SAX events:
 109
 110     @aboutfun{make-builder}
 111     Serialize STP by sending SAX events for the tree to a sink:
 112
 113     @aboutfun{serialize}
 114     @end{section}
 115     @begin[Names and Namespace URIs]{section}
 116     STP represents namespace-well-formed documents only.  All functions
 117     accepting names take a local-name and and a namespace URI as an argument.
 118     Qualified names are accepted where it makes sense, and named nodes have
 119     a namespace prefix that is taken into account for well-formedness checks.
 120
 121     There are two kinds of named nodes: @class{element} and @class{attribute}.
 122     Their slots are:
 123
 124     @aboutfun{local-name}
 125     @aboutfun{namespace-uri}
 126     @aboutfun{namespace-prefix}
 127     For @code{element}, all of the above can be changed using SETF (subject
 128     to well-formedness checks).
 129
 130     For attribute, @fun{local-name} can be changed directly, while URI and
 131     prefix always have to be changed in the same step using
 132     @fun{rename-attribute}.
 133
 134     A node's qualified name can be be queried:
 135
 136     @aboutfun{qualified-name}
 137
 138     @code{of-name} is convenient when searching for elements or attributes:
 139
 140     @aboutfun{of-name}
 141     @end{section}
 142     @begin[Subclasses of Node]{section}
 143     All STP nodes have a common superclass.
 144
 145     @aboutclass{node}
 146     Documents and elements can have children:
 147
 148     @aboutclass{parent-node}
 149     @aboutclass{document}
 150     @aboutclass{element}
 151     Attributes belong to an @code{element}:
 152
 153     @aboutclass{attribute}
 154     Other kinds of nodes:
 155
 156     @aboutclass{comment}
 157     @aboutclass{document-type}
 158     @aboutclass{processing-instruction}
 159     @aboutclass{text}
 160     @end{section}
 161     @begin[Creating nodes]{section}
 162     Nodes are created using the following functions:
 163
 164     @aboutfun{make-attribute}
 165     @aboutfun{make-comment}
 166     @aboutfun{make-document}
 167     @aboutfun{make-document-type}
 168     @aboutfun{make-element}
 169     @aboutfun{make-processing-instruction}
 170     @aboutfun{make-text}
 171     In addition, nodes can be copied including all their children:
 172
 173     @aboutfun{copy}
 174     @end{section}
 175     @begin[Listing Child Nodes]{section}
 176     Nodes have an optional parent node and can have children.
 177
 178     @aboutfun{parent}
 179     If a node has a @class{document} as its ancestor, it can be found using
 180     the @fun{document} function.
 181
 182     @aboutfun{document}
 183     Since the @code{parent} slot needs to be updated when children are added or
 184     removed, the sequence of children is not exposed as a mutable Common
 185     Lisp sequence.
 186
 187     @aboutfun{list-children}
 188     @aboutfun{map-children}
 189     @aboutmacro{do-children}
 190     The following DOM-like functions are also offered:
 191
 192     @aboutfun{nth-child}
 193     @aboutfun{first-child}
 194     @aboutfun{last-child}
 195     @aboutfun{previous-sibling}
 196     @aboutfun{next-sibling}
 197     A wide variety of sequence-related functions is offered that work
 198     like the Common Lisp functions of the same name, but without the need
 199     to call @fun{list-children} first:
 200
 201     @aboutfun{find-child}
 202     @aboutfun{find-child-if}
 203     @aboutfun{child-position}
 204     @aboutfun{child-position-if}
 205     @aboutfun{count-children}
 206     @aboutfun{count-children-if}
 207     @aboutfun{filter-children}
 208     The functions listed above walk only across the direct children of the
 209     parent node.  In addition, the node hierarchy can be mapped recursively
 210     using these functions:
 211
 212     @aboutfun{map-recursively}
 213     @aboutmacro{do-recursively}
 214     @aboutfun{find-recursively}
 215     @aboutfun{filter-recursively}
 216
 217     @end{section}
 218     @begin[Adding and Removing Child Nodes]{section}
 219     While all nodes can be asked for their children, only documents and
 220     elements permit actually adding children.  (For all other nodes, the
 221     sequence of children appears as empty.)
 222
 223     The most flexible function capable of changing the child nodes is
 224     @fun{replace-children}.  Perhaps more common is @fun{insert-child},
 225     a specialized version for only one new child.
 226
 227     @aboutfun{replace-children}
 228     @aboutfun{insert-child}
 229     Various convenience functions are offered in addition:
 230
 231     @aboutfun{prepend-child}
 232     @aboutfun{append-child}
 233     @aboutfun{delete-child}
 234     @aboutfun{delete-child-if}
 235     @aboutfun{delete-nth-child}
 236     @aboutfun{insert-child-before}
 237     @aboutfun{insert-child-after}
 238     @aboutfun{replace-child}
 239     A node can also be deleted from its parent directly using @fun{detach}.
 240
 241     @aboutfun{detach}
 242     @fun{detach} also works for attributes.
 243
 244     @end{section}
 245     @begin[Elements and their Attributes]{section}
 246     In addition to their children, elements have attributes and \"extra
 247     namespaces\".
 248
 249     Attributes themselves are nodes and be accessed using these functions:
 250
 251     @aboutfun{add-attribute}
 252     @aboutfun{remove-attribute}
 253     @aboutfun{find-attribute-named}
 254     @aboutfun{find-attribute-if}
 255     @aboutfun{list-attributes}
 256     @aboutfun{map-attributes}
 257     @aboutmacro{with-attributes}
 258     As a shortcut, the @fun{attribute-value} and its @code{setf} function
 259     allow access to attribute values by name, without having to look up the
 260     attribute node first:
 261
 262     @aboutfun{attribute-value}
 263     There are three ways to declare a namespace: Using the name of the
 264     element, using the name of one of its attributes, or using an \"extra
 265     namespace\".  A prefix can be looked up from any of these local
 266     declarations.  It is also possible to look up a namespace while taking
 267     into account all declarations on parent elements.
 268
 269     @aboutfun{find-local-namespace}
 270     @aboutfun{find-namespace}
 271     Extra namespaces are needed only when a namespace must be declared even
 272     though there is no element or attribute referencing it through its name.
 273     For example, an attribute declared with type @code{QName} using
 274     RelaxNG/XSD must reference a namespace in scope.
 275
 276     @aboutfun{add-extra-namespace}
 277     @aboutfun{remove-extra-namespace}
 278     @aboutfun{find-extra-namespace}
 279     @aboutfun{map-extra-namespaces}
 280     @end{section}"))
 281
 282 (defpackage :cxml-stp-impl
 283   (:use :cl :stp)
 284   (:shadow #:document #:document-type)
 285   (:import-from :xpath-protocol #:define-default-method))