src/xml/sax-handler.lisp

   1 ;;; -*- Mode: Lisp; Syntax: Common-Lisp; Package: SAX; readtable: glisp; 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 ;;;   License: BSD
   7 ;;; ---------------------------------------------------------------------------
   8 ;;;  © copyright 2003 by Henrik Motakef
   9
  10 ;;; Redistribution and use  in source and binary   forms, with or  without
  11 ;;; modification, are permitted provided that the following conditions are
  12 ;;; met:
  13 ;;;
  14 ;;; 1. Redistributions  of  source  code  must retain  the above copyright
  15 ;;;    notice, this list of conditions and the following disclaimer.
  16 ;;;
  17 ;;; 2. Redistributions in  binary form must reproduce  the above copyright
  18 ;;;    notice, this list of conditions and the following disclaimer in the
  19 ;;;    documentation and/or other materials provided with the distribution
  20 ;;;
  21 ;;; THIS  SOFTWARE   IS PROVIDED ``AS  IS''   AND ANY  EXPRESS  OR IMPLIED
  22 ;;; WARRANTIES, INCLUDING, BUT NOT LIMITED  TO, THE IMPLIED WARRANTIES  OF
  23 ;;; MERCHANTABILITY  AND FITNESS FOR A  PARTICULAR PURPOSE ARE DISCLAIMED.
  24 ;;; IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
  25 ;;; INDIRECT,  INCIDENTAL,  SPECIAL, EXEMPLARY,  OR CONSEQUENTIAL  DAMAGES
  26 ;;; (INCLUDING, BUT NOT LIMITED TO,   PROCUREMENT OF SUBSTITUTE GOODS   OR
  27 ;;; SERVICES;  LOSS OF  USE,  DATA, OR  PROFITS; OR BUSINESS INTERRUPTION)
  28 ;;; HOWEVER  CAUSED AND ON ANY THEORY  OF LIABILITY,  WHETHER IN CONTRACT,
  29 ;;; STRICT LIABILITY, OR  TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
  30 ;;; IN ANY WAY  OUT OF THE  USE OF THIS SOFTWARE,  EVEN IF ADVISED OF  THE
  31 ;;; POSSIBILITY OF SUCH DAMAGE.
  32
  33 ;;; TODO/ Open Questions:
  34
  35 ;; o Should there be a predefined "handler" class, or even several
  36 ;;   (like Java SAX' ContentHandler, DTDHandler, LexicalHandler etc? I
  37 ;;   don't really see why.
  38 ;; o Missing stuff from Java SAX2:
  39 ;;   * ignorable-whitespace
  40 ;;   * document-locator/(setf document-locator)
  41 ;;     (probably implies a handler class with an appropriate slot)
  42 ;;   * skipped-entity
  43 ;;   * notation-declaration
  44 ;;   * unparsed-entity-declaration
  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
  48 ;;   * The DeclHandler interface (element-decl, attribute-decl...)
  49 ;;     is useful, but the Java interface sucks.
  50 ;; o Despite all the namespace-uri etc arguments, namespaces are not
  51 ;;   really supported yet, the xml parser always passes nil. This will
  52 ;;   hopefully change Real Soon Now, and I didn't want to have to
  53 ;;   rewrite the interface then
  54
  55 (defpackage :sax
  56   (:use :common-lisp)
  57   (:export #:*namespace-processing*
  58            #:*include-xmlns-attributes*
  59            #:*use-xmlns-namespace*
  60
  61            #:start-document
  62            #:start-prefix-mapping
  63            #:start-element
  64            #:characters
  65            #:processing-instruction
  66            #:end-element
  67            #:end-prefix-mapping
  68            #:end-document
  69            #:comment
  70            #:start-cdata
  71            #:end-cdata))
  72
  73 (in-package :sax)
  74
  75 ;; The http://xml.org/sax/features/namespaces property
  76 (defvar *namespace-processing* t
  77   "If non-nil (the default), namespace processing is enabled.
  78
  79 See also `start-element' and `end-element' for a detailed description
  80 of the consequences of modifying this variable, and
  81 `*include-xmlns-attributes*' and `*use-xmlns-namespace*' for further
  82 related options.")
  83
  84 ;; The http://xml.org/sax/features/namespace-prefixes property.
  85 (defvar *include-xmlns-attributes* nil
  86   "If non-nil, namespace declarations are reported as normal
  87 attributes.
  88
  89 This variable has no effect unless `*namespace-processing*' is
  90 non-nil.
  91
  92 See also `*use-xmlns-namespace*', and `start-element' for a detailed
  93 description of the consequences of setting this variable.")
  94
  95 (defvar *use-xmlns-namespace* nil
  96   "If this variable is nil (the default), attributes with a name like
  97 'xmlns:x' are not considered to be in a namespace, following the
  98 'Namespaces in XML' specification.
  99
 100 If it is non-nil, such attributes are considered to be in a namespace
 101 with the URI 'http://www.w3.org/2000/xmlns/', following an
 102 incompatible change silently introduced in the errata to that spec,
 103 and adopted by some W3C standards.
 104
 105 For example, an attribute like xmlns:ex='http://example.com' would be
 106 reported like this:
 107
 108 *use-xmlns-namespace*: nil
 109 namespace-uri:         nil
 110 local-name:            nil
 111 qname:                 #\"xmlns:ex\"
 112
 113 *use-xmlns-namespace*: t
 114 namespace-uri:         #\"http://www.w3.org/2000/xmlns/\"
 115 local-name:            #\"ex\"
 116 qname:                 #\"xmlns:ex\"
 117
 118 Setting this variable has no effect unless both
 119 `*namespace-processing*' and `*include-xmlns-attributes*' are non-nil.")
 120
 121 (defgeneric start-document (handler)
 122   (:documentation "Called at the beginning of the parsing process,
 123 before any element, processing instruction or comment is reported.
 124
 125 Handlers that need to maintain internal state may use this to perform
 126 any neccessary initializations.")
 127   (:method ((handler t)) nil))
 128
 129 ;; How should attributes be represented?
 130 ;; Currently its just a (name . value) alist, but this isn't too
 131 ;; useful wrt namespaced attributes. Probably a struct.
 132 (defgeneric start-element (handler namespace-uri local-name qname attributes)
 133   (:documentation "Called to report the beginning of an element.
 134
 135 There will always be a corresponding call to end-element, even in the
 136 case of an empty element (i.e. <foo/>).
 137
 138 If the value of *namespaces* is non-nil, namespace-uri, local-name and
 139 qname are rods. If it is nil, namespace-uri and local-name are always
 140 nil, and it is not an error if the qname is not a well-formed
 141 qualified element name (for example, if it contains more than one
 142 colon).
 143
 144 The attributes parameter is a list (in arbitrary order) of instances
 145 of the `attribute' structure class. The for their namespace-uri and
 146 local-name properties, the same rules as for the element name
 147 apply. Additionally, namespace-declaring attributes (those whose name
 148 is \"xmlns\" or starts with \"xmlns:\") are only included if
 149 *namespace-prefixes* is non-nil.")
 150   (:method ((handler t) namespace-uri local-name qname attributes) nil))
 151
 152 (defgeneric start-prefix-mapping (handler prefix uri)
 153   (:documentation "Called when the scope of a new prefix -> namespace-uri mapping begins.
 154
 155 This will always be called immediatly before the `start-element' event
 156 for the element on which the namespaces are declared.
 157
 158 Clients don't usually have to implement this except under special
 159 circumstances, for example when they have to deal with qualified names
 160 in textual content. The parser will handle namespaces of elements and
 161 attributes on its own.")
 162   (:method ((handler t) prefix uri) nil))
 163
 164 (defgeneric characters (handler data)
 165   (:documentation "Called for textual element content.
 166
 167 The data is passed as a rod, with all entity references resolved.
 168 It is possible that the character content of an element is reported
 169 via multiple subsequent calls to this generic function.")
 170   (:method ((handler t) data) nil))
 171
 172 (defgeneric processing-instruction (handler target data)
 173   (:documentation "Called when a processing instruction is read.
 174
 175 Both target and data are rods.")
 176   (:method ((handler t) target data) nil))
 177
 178 (defgeneric end-prefix-mapping (handler prefix)
 179   (:documentation "Called when a prefix -> namespace-uri mapping goes out of scope.
 180
 181 This will always be called immediatly after the `end-element' event
 182 for the element on which the namespace is declared. The order of the
 183 end-prefix-mapping events is otherwise not guaranteed.
 184
 185 Clients don't usually have to implement this except under special
 186 circumstances, for example when they have to deal with qualified names
 187 in textual content. The parser will handle namespaces of elements and
 188 attributes on its own.")
 189   (:method ((handler t) prefix) nil))
 190
 191 (defgeneric end-element (handler namespace-uri local-name qname)
 192   (:documentation "Called to report the end of an element.
 193
 194 See the documentation for `start-element' for a description of the
 195 parameters.")
 196   (:method ((handler t) namespace-uri local-name qname) nil))
 197
 198 (defgeneric end-document (handler)
 199   (:documentation "Called at the end of parsing a document.
 200 This is always the last function called in the parsing process.
 201
 202 In contrast to all of the other methods, the return value of this gf
 203 is significant, it will be returned by the parse-file/stream/string function.")
 204   (:method ((handler t)) nil))
 205
 206 ;; LexicalHandler
 207
 208 (defgeneric comment (handler data)
 209   (:method ((handler t) data) nil))
 210
 211 (defgeneric start-cdata (handler)
 212   (:documentation "Called at the beginning of parsing a CDATA section.
 213
 214 Handlers only have to implement this if they are interested in the
 215 lexical structure of the parsed document. The content of the CDATA
 216 section is reported via the `characters' generic function like all
 217 other textual content.")
 218   (:method ((handler t)) nil))
 219
 220 (defgeneric end-cdata (handler)
 221   (:documentation "Called at the end of parsing a CDATA section.
 222
 223 Handlers only have to implement this if they are interested in the
 224 lexical structure of the parsed document. The content of the CDATA
 225 section is reported via the `characters' generic function like all
 226 other textual content.")
 227   (:method ((handler t)) nil))