xml/sax-handler.lisp

   1 ;;; -*- Mode: Lisp; Syntax: Common-Lisp; Package: SAX; readtable: runes; Encoding: utf-8; -*-
   2 ;;; ---------------------------------------------------------------------------
   3 ;;;     Title: A SAX2-like API for the xml parser
   4 ;;;   Created: 2003-06-30
   5 ;;;    Author: Henrik Motakef <hmot@henrik-motakef.de>
   6 ;;;    Author: David Lichteblau (DTD-related changes)
   7 ;;;   License: BSD
   8 ;;; ---------------------------------------------------------------------------
   9 ;;;  (c) copyright 2003 by Henrik Motakef
  10 ;;;  (c) copyright 2004 knowledgeTools Int. GmbH
  11
  12 ;;; Redistribution and use  in source and binary   forms, with or  without
  13 ;;; modification, are permitted provided that the following conditions are
  14 ;;; met:
  15 ;;;
  16 ;;; 1. Redistributions  of  source  code  must retain  the above copyright
  17 ;;;    notice, this list of conditions and the following disclaimer.
  18 ;;;
  19 ;;; 2. Redistributions in  binary form must reproduce  the above copyright
  20 ;;;    notice, this list of conditions and the following disclaimer in the
  21 ;;;    documentation and/or other materials provided with the distribution
  22 ;;;
  23 ;;; THIS  SOFTWARE   IS PROVIDED ``AS  IS''   AND ANY  EXPRESS  OR IMPLIED
  24 ;;; WARRANTIES, INCLUDING, BUT NOT LIMITED  TO, THE IMPLIED WARRANTIES  OF
  25 ;;; MERCHANTABILITY  AND FITNESS FOR A  PARTICULAR PURPOSE ARE DISCLAIMED.
  26 ;;; IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
  27 ;;; INDIRECT,  INCIDENTAL,  SPECIAL, EXEMPLARY,  OR CONSEQUENTIAL  DAMAGES
  28 ;;; (INCLUDING, BUT NOT LIMITED TO,   PROCUREMENT OF SUBSTITUTE GOODS   OR
  29 ;;; SERVICES;  LOSS OF  USE,  DATA, OR  PROFITS; OR BUSINESS INTERRUPTION)
  30 ;;; HOWEVER  CAUSED AND ON ANY THEORY  OF LIABILITY,  WHETHER IN CONTRACT,
  31 ;;; STRICT LIABILITY, OR  TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
  32 ;;; IN ANY WAY  OUT OF THE  USE OF THIS SOFTWARE,  EVEN IF ADVISED OF  THE
  33 ;;; POSSIBILITY OF SUCH DAMAGE.
  34
  35 ;;; TODO/ Open Questions:
  36
  37 ;; o Should there be a predefined "handler" class, or even several
  38 ;;   (like Java SAX' ContentHandler, DTDHandler, LexicalHandler etc? I
  39 ;;   don't really see why.
  40 ;; o Missing stuff from Java SAX2:
  41 ;;   * ignorable-whitespace
  42 ;;   * document-locator/(setf document-locator)
  43 ;;     (probably implies a handler class with an appropriate slot)
  44 ;;   * skipped-entity
  45 ;;   * The whole ErrorHandler class, this is better handled using
  46 ;;     conditions (but isn't yet)
  47 ;;   * The LexicalHandler (start-cdata etc) would be nice  [-- partly done]
  48
  49 (defpackage :sax
  50   (:use :common-lisp)
  51   (:export #:*namespace-processing*
  52            #:*include-xmlns-attributes*
  53            #:*use-xmlns-namespace*
  54
  55            #:make-attribute
  56            #:find-attribute
  57            #:find-attribute-ns
  58            #:attribute-namespace-uri
  59            #:attribute-local-name
  60            #:attribute-qname
  61            #:attribute-value
  62            #:attribute-specified-p
  63
  64            #:start-document
  65            #:start-prefix-mapping
  66            #:start-element
  67            #:characters
  68            #:processing-instruction
  69            #:end-element
  70            #:end-prefix-mapping
  71            #:end-document
  72            #:comment
  73            #:start-cdata
  74            #:end-cdata
  75            #:start-dtd
  76            #:end-dtd
  77            #:start-internal-subset
  78            #:end-internal-subset
  79            #:unparsed-entity-declaration
  80            #:external-entity-declaration
  81            #:internal-entity-declaration
  82            #:notation-declaration
  83            #:element-declaration
  84            #:attribute-declaration
  85            #:entity-resolver))
  86
  87 (in-package :sax)
  88
  89 ;; The http://xml.org/sax/features/namespaces property
  90 (defvar *namespace-processing* t
  91   "If non-nil (the default), namespace processing is enabled.
  92
  93 See also `start-element' and `end-element' for a detailed description
  94 of the consequences of modifying this variable, and
  95 `*include-xmlns-attributes*' and `*use-xmlns-namespace*' for further
  96 related options.")
  97
  98 ;; The http://xml.org/sax/features/namespace-prefixes property.
  99 (defvar *include-xmlns-attributes* t
 100   "If non-nil, namespace declarations are reported as normal
 101 attributes.
 102
 103 This variable has no effect unless `*namespace-processing*' is
 104 non-nil.
 105
 106 See also `*use-xmlns-namespace*', and `start-element' for a detailed
 107 description of the consequences of setting this variable.")
 108
 109 (defvar *use-xmlns-namespace* t
 110   "If this variable is nil (the default), attributes with a name like
 111 'xmlns:x' are not considered to be in a namespace, following the
 112 'Namespaces in XML' specification.
 113
 114 If it is non-nil, such attributes are considered to be in a namespace
 115 with the URI 'http://www.w3.org/2000/xmlns/', following an
 116 incompatible change silently introduced in the errata to that spec,
 117 and adopted by some W3C standards.
 118
 119 For example, an attribute like xmlns:ex='http://example.com' would be
 120 reported like this:
 121
 122 *use-xmlns-namespace*: nil
 123 namespace-uri:         nil
 124 local-name:            nil
 125 qname:                 #\"xmlns:ex\"
 126
 127 *use-xmlns-namespace*: t
 128 namespace-uri:         #\"http://www.w3.org/2000/xmlns/\"
 129 local-name:            #\"ex\"
 130 qname:                 #\"xmlns:ex\"
 131
 132 Setting this variable has no effect unless both
 133 `*namespace-processing*' and `*include-xmlns-attributes*' are non-nil.")
 134
 135 (defstruct attribute
 136   namespace-uri
 137   local-name
 138   qname
 139   value
 140   specified-p)
 141
 142 (defun %rod= (x y)
 143   ;; allow rods *and* strings *and* null
 144   (cond
 145     ((zerop (length x)) (zerop (length y)))
 146     ((zerop (length y)) nil)
 147     ((stringp x) (string= x y))
 148     (t (runes:rod= x y))))
 149
 150 (defun find-attribute (qname attrs)
 151   (find qname attrs :key #'attribute-qname :test #'%rod=))
 152
 153 (defun find-attribute-ns (uri lname attrs)
 154   (find-if (lambda (attr)
 155              (and (%rod= uri (sax:attribute-namespace-uri attr))
 156                   (%rod= lname (sax:attribute-local-name attr))))
 157            attrs))
 158
 159 (defgeneric start-document (handler)
 160   (:documentation "Called at the beginning of the parsing process,
 161 before any element, processing instruction or comment is reported.
 162
 163 Handlers that need to maintain internal state may use this to perform
 164 any neccessary initializations.")
 165   (:method ((handler t)) nil))
 166
 167 (defgeneric start-element (handler namespace-uri local-name qname attributes)
 168   (:documentation "Called to report the beginning of an element.
 169
 170 There will always be a corresponding call to end-element, even in the
 171 case of an empty element (i.e. <foo/>).
 172
 173 If the value of *namespaces* is non-nil, namespace-uri, local-name and
 174 qname are rods. If it is nil, namespace-uri and local-name are always
 175 nil, and it is not an error if the qname is not a well-formed
 176 qualified element name (for example, if it contains more than one
 177 colon).
 178
 179 The attributes parameter is a list (in arbitrary order) of instances
 180 of the `attribute' structure class. The for their namespace-uri and
 181 local-name properties, the same rules as for the element name
 182 apply. Additionally, namespace-declaring attributes (those whose name
 183 is \"xmlns\" or starts with \"xmlns:\") are only included if
 184 *namespace-prefixes* is non-nil.")
 185   (:method ((handler t) namespace-uri local-name qname attributes)
 186     (declare (ignore namespace-uri local-name qname attributes))
 187     nil))
 188
 189 (defgeneric start-prefix-mapping (handler prefix uri)
 190   (:documentation "Called when the scope of a new prefix -> namespace-uri mapping begins.
 191
 192 This will always be called immediatly before the `start-element' event
 193 for the element on which the namespaces are declared.
 194
 195 Clients don't usually have to implement this except under special
 196 circumstances, for example when they have to deal with qualified names
 197 in textual content. The parser will handle namespaces of elements and
 198 attributes on its own.")
 199   (:method ((handler t) prefix uri) (declare (ignore prefix uri)) nil))
 200
 201 (defgeneric characters (handler data)
 202   (:documentation "Called for textual element content.
 203
 204 The data is passed as a rod, with all entity references resolved.
 205 It is possible that the character content of an element is reported
 206 via multiple subsequent calls to this generic function.")
 207   (:method ((handler t) data) (declare (ignore data)) nil))
 208
 209 (defgeneric processing-instruction (handler target data)
 210   (:documentation "Called when a processing instruction is read.
 211
 212 Both target and data are rods.")
 213   (:method ((handler t) target data) (declare (ignore target data)) nil))
 214
 215 (defgeneric end-prefix-mapping (handler prefix)
 216   (:documentation "Called when a prefix -> namespace-uri mapping goes out of scope.
 217
 218 This will always be called immediatly after the `end-element' event
 219 for the element on which the namespace is declared. The order of the
 220 end-prefix-mapping events is otherwise not guaranteed.
 221
 222 Clients don't usually have to implement this except under special
 223 circumstances, for example when they have to deal with qualified names
 224 in textual content. The parser will handle namespaces of elements and
 225 attributes on its own.")
 226   (:method ((handler t) prefix) prefix nil))
 227
 228 (defgeneric end-element (handler namespace-uri local-name qname)
 229   (:documentation "Called to report the end of an element.
 230
 231 See the documentation for `start-element' for a description of the
 232 parameters.")
 233   (:method ((handler t) namespace-uri local-name qname)
 234     (declare (ignore namespace-uri local-name qname))
 235     nil))
 236
 237 (defgeneric end-document (handler)
 238   (:documentation "Called at the end of parsing a document.
 239 This is always the last function called in the parsing process.
 240
 241 In contrast to all of the other methods, the return value of this gf
 242 is significant, it will be returned by the parse-file/stream/string function.")
 243   (:method ((handler t)) nil))
 244
 245 ;; LexicalHandler
 246
 247 (defgeneric comment (handler data)
 248   (:method ((handler t) data) data nil))
 249
 250 (defgeneric start-cdata (handler)
 251   (:documentation "Called at the beginning of parsing a CDATA section.
 252
 253 Handlers only have to implement this if they are interested in the
 254 lexical structure of the parsed document. The content of the CDATA
 255 section is reported via the `characters' generic function like all
 256 other textual content.")
 257   (:method ((handler t)) nil))
 258
 259 (defgeneric end-cdata (handler)
 260   (:documentation "Called at the end of parsing a CDATA section.
 261
 262 Handlers only have to implement this if they are interested in the
 263 lexical structure of the parsed document. The content of the CDATA
 264 section is reported via the `characters' generic function like all
 265 other textual content.")
 266   (:method ((handler t)) nil))
 267
 268 (defgeneric start-dtd (handler name public-id system-id)
 269   (:documentation "Called at the beginning of parsing a DTD.")
 270   (:method ((handler t) name public-id system-id)
 271     (declare (ignore name public-id system-id))
 272     nil))
 273
 274 (defgeneric end-dtd (handler)
 275   (:documentation "Called at the end of parsing a DTD.")
 276   (:method ((handler t)) nil))
 277
 278 (defgeneric start-internal-subset (handler)
 279   (:documentation "Reports that an internal subset is present.  Called before
 280 any definition from the internal subset is reported.")
 281   (:method ((handler t)) nil))
 282
 283 (defgeneric end-internal-subset (handler)
 284   (:documentation "Called after processing of the internal subset has
 285 finished, if present.")
 286   (:method ((handler t)) nil))
 287
 288 (defgeneric unparsed-entity-declaration
 289     (handler name public-id system-id notation-name)
 290   (:documentation
 291    "Called when an unparsed entity declaration is seen in a DTD.")
 292   (:method ((handler t) name public-id system-id notation-name)
 293     (declare (ignore name public-id system-id notation-name))
 294     nil))
 295
 296 (defgeneric external-entity-declaration
 297     (handler kind name public-id system-id)
 298   (:documentation
 299    "Called when a parsed external entity declaration is seen in a DTD.")
 300   (:method ((handler t) kind name public-id system-id)
 301     (declare (ignore kind name public-id system-id))
 302     nil))
 303
 304 (defgeneric internal-entity-declaration
 305     (handler kind name value)
 306   (:documentation
 307    "Called when an internal entity declaration is seen in a DTD.")
 308   (:method ((handler t) kind name value)
 309     (declare (ignore kind name value))
 310     nil))
 311
 312 (defgeneric notation-declaration
 313     (handler name public-id system-id)
 314   (:documentation
 315    "Called when a notation declaration is seen while parsing a DTD.")
 316   (:method ((handler t) name public-id system-id)
 317     (declare (ignore name public-id system-id))
 318     nil))
 319
 320 (defgeneric element-declaration (handler name model)
 321   (:documentation
 322    "Called when a element declaration is seen in a DTD.  Model is not a string,
 323     but a nested list, with *, ?, +, OR, and AND being the operators, rods
 324     as names, :EMPTY and :PCDATA as special tokens.  (AND represents
 325     sequences.)")
 326   (:method ((handler t) name model)
 327     (declare (ignore name model))
 328     nil))
 329
 330 (defgeneric attribute-declaration
 331     (handler element-name attribute-name type default)
 332   (:documentation
 333    "Called when an attribute declaration is seen in a DTD.
 334     type        one of :CDATA, :ID, :IDREF, :IDREFS,
 335                 :ENTITY, :ENTITIES, :NMTOKEN, :NMTOKENS,
 336                 (:NOTATION <name>*), or (:ENUMERATION <name>*)
 337     default     :REQUIRED, :IMPLIED, (:FIXED content), or (:DEFAULT content)")
 338   (:method ((handler t) element-name attribute-name type value)
 339     (declare (ignore element-name attribute-name type value))
 340     nil))
 341
 342 (defgeneric entity-resolver
 343     (handler resolver)
 344   (:documentation
 345    "Called between sax:end-dtd and sax:end-document to register an entity
 346     resolver, a function of two arguments: An entity name and SAX handler.
 347     When called, the resolver function will parse the named entity's data.")
 348   (:method ((handler t) resolver)
 349     (declare (ignore resolver))
 350     nil))
 351
 352 ;; internal for now
 353 (defgeneric dtd (handler dtd)
 354   (:method ((handler t) dtd) (declare (ignore dtd)) nil))