sax-handler.lisp 9.8 KB
Newer Older
david's avatar
david committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70
;;; -*- Mode: Lisp; Syntax: Common-Lisp; Package: SAX; readtable: glisp; Encoding: utf-8; -*-
;;; ---------------------------------------------------------------------------
;;;     Title: A SAX2-like API for the xml parser
;;;   Created: 2003-06-30
;;;    Author: Henrik Motakef <hmot@henrik-motakef.de>
;;;   License: BSD
;;; ---------------------------------------------------------------------------
;;;  © copyright 2003 by Henrik Motakef

;;; Redistribution and use  in source and binary   forms, with or  without
;;; modification, are permitted provided that the following conditions are
;;; met:                                                                  
;;; 								      
;;; 1. Redistributions  of  source  code  must retain  the above copyright
;;;    notice, this list of conditions and the following disclaimer.      
;;; 								      
;;; 2. Redistributions in  binary form must reproduce  the above copyright
;;;    notice, this list of conditions and the following disclaimer in the
;;;    documentation and/or other materials provided with the distribution
;;; 								      
;;; THIS  SOFTWARE   IS PROVIDED ``AS  IS''   AND ANY  EXPRESS  OR IMPLIED
;;; WARRANTIES, INCLUDING, BUT NOT LIMITED  TO, THE IMPLIED WARRANTIES  OF
;;; MERCHANTABILITY  AND FITNESS FOR A  PARTICULAR PURPOSE ARE DISCLAIMED.
;;; IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
;;; INDIRECT,  INCIDENTAL,  SPECIAL, EXEMPLARY,  OR CONSEQUENTIAL  DAMAGES
;;; (INCLUDING, BUT NOT LIMITED TO,   PROCUREMENT OF SUBSTITUTE GOODS   OR
;;; SERVICES;  LOSS OF  USE,  DATA, OR  PROFITS; OR BUSINESS INTERRUPTION)
;;; HOWEVER  CAUSED AND ON ANY THEORY  OF LIABILITY,  WHETHER IN CONTRACT,
;;; STRICT LIABILITY, OR  TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
;;; IN ANY WAY  OUT OF THE  USE OF THIS SOFTWARE,  EVEN IF ADVISED OF  THE
;;; POSSIBILITY OF SUCH DAMAGE.

;;; TODO/ Open Questions:

;; o Should there be a predefined "handler" class, or even several
;;   (like Java SAX' ContentHandler, DTDHandler, LexicalHandler etc? I
;;   don't really see why.
;; o Missing stuff from Java SAX2:
;;   * ignorable-whitespace
;;   * document-locator/(setf document-locator)
;;     (probably implies a handler class with an appropriate slot)
;;   * skipped-entity
;;   * notation-declaration
;;   * unparsed-entity-declaration
;;   * The whole ErrorHandler class, this is better handled using
;;     conditions (but isn't yet)
;;   * The LexicalHandler (start-cdata etc) would be nice
;;   * The DeclHandler interface (element-decl, attribute-decl...)
;;     is useful, but the Java interface sucks.
;; o Despite all the namespace-uri etc arguments, namespaces are not
;;   really supported yet, the xml parser always passes nil. This will
;;   hopefully change Real Soon Now, and I didn't want to have to
;;   rewrite the interface then

(defpackage :sax
  (:use :common-lisp)
  (:export #:*namespace-processing*
	   #:*include-xmlns-attributes*
	   #:*use-xmlns-namespace*
	   
	   #:start-document
	   #:start-prefix-mapping
	   #:start-element
	   #:characters
	   #:processing-instruction
	   #:end-element
	   #:end-prefix-mapping
	   #:end-document
	   #:comment
	   #:start-cdata
david's avatar
david committed
71 72 73
	   #:end-cdata
	   #:start-dtd
	   #:end-dtd))
david's avatar
david committed
74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151

(in-package :sax)

;; The http://xml.org/sax/features/namespaces property
(defvar *namespace-processing* t
  "If non-nil (the default), namespace processing is enabled.

See also `start-element' and `end-element' for a detailed description
of the consequences of modifying this variable, and
`*include-xmlns-attributes*' and `*use-xmlns-namespace*' for further
related options.")

;; The http://xml.org/sax/features/namespace-prefixes property.
(defvar *include-xmlns-attributes* nil
  "If non-nil, namespace declarations are reported as normal
attributes.

This variable has no effect unless `*namespace-processing*' is
non-nil.

See also `*use-xmlns-namespace*', and `start-element' for a detailed
description of the consequences of setting this variable.")

(defvar *use-xmlns-namespace* nil
  "If this variable is nil (the default), attributes with a name like
'xmlns:x' are not considered to be in a namespace, following the
'Namespaces in XML' specification.

If it is non-nil, such attributes are considered to be in a namespace
with the URI 'http://www.w3.org/2000/xmlns/', following an
incompatible change silently introduced in the errata to that spec,
and adopted by some W3C standards.

For example, an attribute like xmlns:ex='http://example.com' would be
reported like this:

*use-xmlns-namespace*: nil
namespace-uri:         nil
local-name:            nil
qname:                 #\"xmlns:ex\"

*use-xmlns-namespace*: t
namespace-uri:         #\"http://www.w3.org/2000/xmlns/\"
local-name:            #\"ex\"
qname:                 #\"xmlns:ex\"

Setting this variable has no effect unless both
`*namespace-processing*' and `*include-xmlns-attributes*' are non-nil.")

(defgeneric start-document (handler)
  (:documentation "Called at the beginning of the parsing process,
before any element, processing instruction or comment is reported.

Handlers that need to maintain internal state may use this to perform
any neccessary initializations.")
  (:method ((handler t)) nil))

;; How should attributes be represented?
;; Currently its just a (name . value) alist, but this isn't too
;; useful wrt namespaced attributes. Probably a struct.
(defgeneric start-element (handler namespace-uri local-name qname attributes)
  (:documentation "Called to report the beginning of an element.

There will always be a corresponding call to end-element, even in the
case of an empty element (i.e. <foo/>).

If the value of *namespaces* is non-nil, namespace-uri, local-name and
qname are rods. If it is nil, namespace-uri and local-name are always
nil, and it is not an error if the qname is not a well-formed
qualified element name (for example, if it contains more than one
colon).

The attributes parameter is a list (in arbitrary order) of instances
of the `attribute' structure class. The for their namespace-uri and
local-name properties, the same rules as for the element name
apply. Additionally, namespace-declaring attributes (those whose name
is \"xmlns\" or starts with \"xmlns:\") are only included if
*namespace-prefixes* is non-nil.")
david's avatar
david committed
152 153 154
  (:method ((handler t) namespace-uri local-name qname attributes)
    (declare (ignore namespace-uri local-name qname attributes))
    nil))
david's avatar
david committed
155 156 157 158 159 160 161 162 163 164 165

(defgeneric start-prefix-mapping (handler prefix uri)
  (:documentation "Called when the scope of a new prefix -> namespace-uri mapping begins.

This will always be called immediatly before the `start-element' event
for the element on which the namespaces are declared.

Clients don't usually have to implement this except under special
circumstances, for example when they have to deal with qualified names
in textual content. The parser will handle namespaces of elements and
attributes on its own.")
david's avatar
david committed
166
  (:method ((handler t) prefix uri) (declare (ignore prefix uri)) nil))
david's avatar
david committed
167 168 169 170 171 172 173

(defgeneric characters (handler data)
  (:documentation "Called for textual element content.

The data is passed as a rod, with all entity references resolved.
It is possible that the character content of an element is reported
via multiple subsequent calls to this generic function.")
david's avatar
david committed
174
  (:method ((handler t) data) (declare (ignore data)) nil))
david's avatar
david committed
175 176 177 178 179

(defgeneric processing-instruction (handler target data)
  (:documentation "Called when a processing instruction is read.

Both target and data are rods.")
david's avatar
david committed
180
  (:method ((handler t) target data) (declare (ignore target data)) nil))
david's avatar
david committed
181 182 183 184 185 186 187 188 189 190 191 192

(defgeneric end-prefix-mapping (handler prefix)
  (:documentation "Called when a prefix -> namespace-uri mapping goes out of scope.

This will always be called immediatly after the `end-element' event
for the element on which the namespace is declared. The order of the
end-prefix-mapping events is otherwise not guaranteed.

Clients don't usually have to implement this except under special
circumstances, for example when they have to deal with qualified names
in textual content. The parser will handle namespaces of elements and
attributes on its own.")
david's avatar
david committed
193
  (:method ((handler t) prefix) prefix nil))
david's avatar
david committed
194 195 196 197 198 199

(defgeneric end-element (handler namespace-uri local-name qname)
  (:documentation "Called to report the end of an element.

See the documentation for `start-element' for a description of the
parameters.")
david's avatar
david committed
200 201 202
  (:method ((handler t) namespace-uri local-name qname)
    (declare (ignore namespace-uri local-name qname))
    nil))
david's avatar
david committed
203 204 205 206 207 208 209 210 211 212 213 214

(defgeneric end-document (handler)
  (:documentation "Called at the end of parsing a document.
This is always the last function called in the parsing process.

In contrast to all of the other methods, the return value of this gf
is significant, it will be returned by the parse-file/stream/string function.")
  (:method ((handler t)) nil))

;; LexicalHandler

(defgeneric comment (handler data)
david's avatar
david committed
215
  (:method ((handler t) data) data nil))
david's avatar
david committed
216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232

(defgeneric start-cdata (handler)
  (:documentation "Called at the beginning of parsing a CDATA section.

Handlers only have to implement this if they are interested in the
lexical structure of the parsed document. The content of the CDATA
section is reported via the `characters' generic function like all
other textual content.")
  (:method ((handler t)) nil))

(defgeneric end-cdata (handler)
  (:documentation "Called at the end of parsing a CDATA section.

Handlers only have to implement this if they are interested in the
lexical structure of the parsed document. The content of the CDATA
section is reported via the `characters' generic function like all
other textual content.")
david's avatar
david committed
233
  (:method ((handler t)) nil))
david's avatar
david committed
234 235 236 237 238 239 240 241 242 243

(defgeneric start-dtd (handler name public-id system-id)
  (:documentation "Called at the beginning of parsing a DTD.")
  (:method ((handler t) name public-id system-id)
    (declare (ignore name public-id system-id))
    nil))

(defgeneric end-dtd (handler)
  (:documentation "Called at the end of parsing a DTD.")
  (:method ((handler t)) nil))