]> dreyeck.freedombox.rocks Git - topic-maps.git/blob - src/xtm/reader.lisp
Register final Variant Reification original for Slice 22B
[topic-maps.git] / src / xtm / reader.lisp
1 (in-package #:topic-maps.xtm)
2
3 (defparameter +namespace+ "http://www.topicmaps.org/xtm/")
4 ;; This is a source tree of XML events, not a second Topic Maps object model.
5 ;; Positions are SAX approximations at the end of a start tag, never byte spans.
6 (defstruct node uri name attributes children line column)
7 (defclass source-handler (sax:default-handler)
8 ((stack :initform nil :accessor handler-stack)
9 (root :initform nil :accessor handler-root)))
10 (defmethod sax:start-element ((h source-handler) uri local qname attributes)
11 (declare (ignore qname))
12 (let ((node (make-node :uri uri :name local :line (sax:line-number h)
13 :column (sax:column-number h)
14 :attributes (mapcar (lambda (a)
15 (list (sax:attribute-namespace-uri a)
16 (sax:attribute-local-name a)
17 (sax:attribute-value a))) attributes))))
18 (if (handler-stack h) (push node (node-children (first (handler-stack h))))
19 (setf (handler-root h) node))
20 (push node (handler-stack h))))
21 (defmethod sax:characters ((h source-handler) data)
22 (when (handler-stack h) (push (copy-seq data) (node-children (first (handler-stack h))))))
23 (defmethod sax:end-element ((h source-handler) uri local qname)
24 (declare (ignore uri local qname))
25 (let ((node (pop (handler-stack h)))) (setf (node-children node) (nreverse (node-children node)))))
26 (defmethod sax:end-document ((h source-handler)) (handler-root h))
27
28 (defun xml-space-p (c) (find c '(#\Space #\Tab #\Newline #\Return)))
29 (defun collapse-space (text)
30 ;; xsd:ID has whiteSpace=collapse, even with a non-validating XML processor.
31 (with-output-to-string (out)
32 (let ((written nil) (pending nil))
33 (loop for c across text do
34 (if (xml-space-p c) (when written (setf pending t))
35 (progn (when pending (write-char #\Space out))
36 (write-char c out) (setf written t pending nil)))))))
37 (defun ncname-p (text)
38 ;; Use the pinned XML processor's XML 1.0 name character tables; exclude ':'
39 ;; for XML Schema ID/NCName and XPointer shorthand pointers (XTM 4.5/4.20).
40 (and (plusp (length text)) (not (find #\: text))
41 (cxml::valid-name-p (runes:string-rod text))))
42 (defun attributes (node allowed required)
43 (dolist (attr (node-attributes node))
44 (unless (and (or (null (first attr)) (equal (first attr) ""))
45 (member (second attr) allowed :test #'string=))
46 (reject :unexpected-attribute (format nil "Attribute ~S on ~A." (second attr) (node-name node)) node)))
47 (dolist (name required)
48 (unless (find name (node-attributes node) :key #'second :test #'string=)
49 (reject (if (string= name "id") :missing-id :missing-attribute)
50 (format nil "Required ~A attribute is absent." name) node))))
51 (defun attr (node name)
52 (third (find name (node-attributes node) :key #'second :test #'string=)))
53 (defun elements (node)
54 (loop for child in (node-children node)
55 if (stringp child) do
56 (unless (every #'xml-space-p child)
57 (reject :unexpected-text "Only XML whitespace is allowed here." node))
58 else collect child))
59 (defun check-namespace (node)
60 (unless (equal (node-uri node) +namespace+)
61 (reject :invalid-namespace "Expected the XTM 2.0 namespace." node)))
62 (defun unsupported (node)
63 (reject :unsupported-construct (format nil "XTM ~A is not implemented in this subset." (node-name node))
64 node 'xtm-unsupported))
65 (defun leaf-href (node)
66 (attributes node '("href") '("href"))
67 (when (elements node) (reject :unexpected-child "A locator element must be empty." node))
68 (resolve-iri (attr node "href") *document-iri* node))
69 (defun reference-iri (node)
70 (let* ((iri (leaf-href node)) (fragment (iri-parts-fragment (split-iri iri))))
71 (unless (and fragment (ncname-p fragment))
72 (reject :invalid-topic-ref "topicRef requires an XPointer shorthand fragment." node))
73 iri))
74
75 (defun validate-source (root)
76 "Check the supported XTM schema before model construction; keep event order.
77 Unsupported legal extension points are explicit; no claim to validate excluded
78 constructs' complete subgrammars is made. XML errors have already been checked."
79 (let ((ids (make-hash-table :test #'equal))) ; XML ID uniqueness only, no Topics.
80 (labels ((validate (node context)
81 (check-namespace node)
82 (let ((name (node-name node)))
83 (unless (member name context :test #'string=)
84 (reject :unexpected-element (format nil "Unexpected ~A element." name) node))
85 (cond
86 ((string= name "topicMap")
87 (attributes node '("version" "reifier") '("version"))
88 (unless (equal (attr node "version") "2.0")
89 (reject :invalid-version "This reader accepts XTM version 2.0 only." node))
90 (when (attr node "reifier")
91 (resolve-iri (attr node "reifier") *document-iri* node))
92 (let ((phase 0))
93 (dolist (child (elements node))
94 (let* ((name (node-name child))
95 (next (cond ((string= name "itemIdentity") 0)
96 ((string= name "mergeMap") 1) (t 2))))
97 (when (< next phase) (reject :element-order "topicMap child order is invalid." child))
98 (setf phase next)
99 (validate child '("itemIdentity" "mergeMap" "topic" "association"))))))
100 ((string= name "topic")
101 (attributes node '("id") '("id"))
102 (let ((id (collapse-space (attr node "id"))))
103 (unless (ncname-p id) (reject :invalid-id "topic/@id must be an XML Schema ID." node))
104 (when (gethash id ids) (reject :duplicate-id "Duplicate XML ID in this document." node))
105 (setf (gethash id ids) t))
106 (let ((phase 0) (instance-seen nil))
107 (dolist (child (elements node))
108 (let* ((name (node-name child))
109 (next (cond ((member name '("itemIdentity" "subjectLocator" "subjectIdentifier")
110 :test #'string=) 0)
111 ((string= name "instanceOf") 1) (t 2))))
112 (when (< next phase) (reject :element-order "topic child order is invalid." child))
113 (when (= next 1)
114 (when instance-seen (reject :duplicate-instance-of "Only one instanceOf element is allowed." child))
115 (setf instance-seen t))
116 (setf phase next)
117 (validate child '("itemIdentity" "subjectLocator" "subjectIdentifier" "instanceOf" "name" "occurrence"))))))
118 ((string= name "instanceOf")
119 (attributes node nil nil)
120 (unless (elements node) (reject :empty-instance-of "instanceOf needs at least one topicRef." node))
121 (dolist (child (elements node)) (validate child '("topicRef"))))
122 ((string= name "name")
123 (attributes node '("reifier") nil)
124 (when (attr node "reifier")
125 (resolve-iri (attr node "reifier") *document-iri* node))
126 (let ((phase 0) (type-seen nil) (scope-seen nil) (value-seen nil))
127 (dolist (child (elements node))
128 (check-namespace child)
129 (let* ((kind (node-name child))
130 (next (position kind '("itemIdentity" "type" "scope" "value" "variant") :test #'string=)))
131 (unless next (reject :unexpected-element (format nil "Unexpected ~A element." kind) child))
132 (when (or (< next phase) (and (string= kind "variant") (not value-seen)))
133 (reject :element-order "name child order is invalid." child))
134 (setf phase next)
135 (cond
136 ((member kind '("itemIdentity" "variant") :test #'string=) nil)
137 ((string= kind "type")
138 (when type-seen (reject :duplicate-name-type "Only one name type is allowed." child))
139 (setf type-seen t))
140 ((string= kind "scope")
141 (when scope-seen (reject :duplicate-name-scope "Only one name scope is allowed." child))
142 (setf scope-seen t))
143 ((string= kind "value")
144 (when value-seen (reject :duplicate-name-value "Only one name value is allowed." child))
145 (setf value-seen t))
146 ;; Valid extension points remain explicitly unsupported.
147 ;; Their complete subgrammars are outside this subset.
148 (t (unsupported child)))
149 (validate child '("itemIdentity" "type" "scope" "value" "variant"))))
150 (unless value-seen (reject :missing-name-value "name requires a value element." node))))
151 ((string= name "variant")
152 (attributes node '("reifier") nil)
153 (when (attr node "reifier") (resolve-iri (attr node "reifier") *document-iri* node))
154 (let ((phase 0) (scope-seen nil) (resource-seen nil))
155 (dolist (child (elements node))
156 (check-namespace child)
157 (let* ((kind (node-name child))
158 (next (cond ((string= kind "itemIdentity") 0)
159 ((string= kind "scope") 1)
160 ((member kind '("resourceData" "resourceRef") :test #'string=) 2))))
161 (unless next (reject :unexpected-element (format nil "Unexpected ~A element." kind) child))
162 (when (< next phase) (reject :element-order "variant child order is invalid." child))
163 (setf phase next)
164 (cond
165 ((string= kind "itemIdentity") nil)
166 ((string= kind "scope")
167 (when scope-seen (reject :duplicate-variant-scope "Only one variant scope is allowed." child))
168 (setf scope-seen t))
169 (t
170 (unless scope-seen (reject :missing-variant-scope "variant requires scope before its resource." child))
171 (when resource-seen (reject :variant-resource-cardinality "variant requires exactly one resource." child))
172 (setf resource-seen t)))
173 (validate child '("itemIdentity" "scope" "resourceData" "resourceRef"))))
174 (unless scope-seen (reject :missing-variant-scope "variant requires a scope element." node))
175 (unless resource-seen (reject :missing-variant-resource "variant requires a resource element." node))))
176 ((string= name "resourceRef") (leaf-href node))
177 ((string= name "resourceData")
178 (attributes node '("datatype") nil)
179 (let ((datatype (attr node "datatype")))
180 ;; DATATYPE is already an absolute IRI, not content to
181 ;; resolve against the document or percent-normalize.
182 (when datatype
183 (unless (iri-parts-scheme (split-iri datatype))
184 (reject :invalid-resource-data-datatype "resourceData datatype must be an absolute IRI." node))
185 (validate-decoded-reference (unescape-reference datatype node) node)
186 (unless (member datatype (list (topic-maps.tmdm:string-datatype) (topic-maps.tmdm:iri-datatype)) :test #'equal)
187 (reject :resource-data-datatype "Only textual xsd:string and xsd:anyURI resourceData are implemented." node 'xtm-unsupported)))
188 (dolist (child (node-children node))
189 (unless (stringp child)
190 (if (or (equal datatype (topic-maps.tmdm:iri-datatype)) (equal (node-uri child) +namespace+))
191 (reject :unexpected-child
192 (if (equal datatype (topic-maps.tmdm:iri-datatype))
193 "anyURI resourceData cannot contain child elements."
194 "resourceData cannot contain XTM markup.") child)
195 (reject :resource-data-markup "Embedded XML resourceData is outside this subset." child 'xtm-unsupported))))))
196 ((string= name "type")
197 (attributes node nil nil)
198 (let ((refs (elements node)))
199 (unless (= 1 (length refs)) (reject :type-cardinality "type requires exactly one topicRef." node))
200 (validate (first refs) '("topicRef"))))
201 ((string= name "scope")
202 (attributes node nil nil)
203 (unless (elements node) (reject :empty-scope "scope requires at least one topicRef." node))
204 (dolist (child (elements node)) (validate child '("topicRef"))))
205 ((string= name "value")
206 (attributes node nil nil)
207 ;; VALUE accepts all character data, including empty text and
208 ;; whitespace. ELEMENTS would apply the wrong text policy.
209 (dolist (child (node-children node))
210 (unless (stringp child) (reject :unexpected-child "value accepts character data only." child))))
211 ((string= name "topicRef") (reference-iri node))
212 ((member name '("itemIdentity" "subjectIdentifier" "subjectLocator") :test #'string=)
213 (leaf-href node))
214 (t (unsupported node))))))
215 (validate root '("topicMap"))))
216 root)
217
218 (defun find-reference-topic (map iri)
219 ;; XTM 4.20 searches the actual model, not a speculative pre-scan registry.
220 ;; Unlike INTERN-TOPIC, a hit MUST NOT add another identifier category.
221 (let ((topic (find-if (lambda (topic)
222 (or (member iri (topic-maps.tmdm:topic-subject-identifiers topic) :test #'string=)
223 (member iri (topic-maps.tmdm:topic-item-identifiers topic) :test #'string=)))
224 (topic-maps.tmdm:topic-map-topics map))))
225 (if topic (topic-maps.tmdm:canonical-topic topic)
226 (topic-maps.tmdm:intern-topic map :item-identifier iri))))
227 (defun read-item-reifier (node item map)
228 ;; XTM 4.3.2 looks up Item Identifiers only, unlike topicRef (4.20).
229 ;; INTERN-TOPIC adds the II on a miss; any SI/II identity merging then
230 ;; follows the existing TMDM rules, independently of this lookup.
231 (when (attr node "reifier")
232 (let* ((iri (resolve-iri (attr node "reifier") *document-iri* node))
233 (topic (or (find iri (topic-maps.tmdm:topic-map-topics map)
234 :test (lambda (iri topic)
235 (member iri (topic-maps.tmdm:topic-item-identifiers topic) :test #'string=)))
236 (topic-maps.tmdm:intern-topic map :item-identifier iri))))
237 (return-from read-item-reifier (topic-maps.tmdm:set-item-reifier item topic))))
238 item)
239 (defun read-map-reifier (node map)
240 (read-item-reifier node map map))
241 (defun core-topic (map local)
242 (topic-maps.tmdm:intern-topic map :subject-identifier
243 (concatenate 'string "http://psi.topicmaps.org/iso13250/model/" local)))
244 (defun read-instance-of (node owner map)
245 (dolist (ref (elements node))
246 (let ((type (find-reference-topic map (reference-iri ref))))
247 (topic-maps.tmdm:make-association map (core-topic map "type-instance")
248 (list (list (core-topic map "type") type)
249 (list (core-topic map "instance") (topic-maps.tmdm:canonical-topic owner)))))))
250 (defun read-variant (node name map)
251 (let* ((children (elements node))
252 (scope-node (find "scope" children :key #'node-name :test #'string=))
253 (resource (find-if (lambda (child) (member (node-name child) '("resourceData" "resourceRef") :test #'string=)) children))
254 (reference-p (string= (node-name resource) "resourceRef"))
255 (uri-data-p (and (not reference-p) (equal (attr resource "datatype") (topic-maps.tmdm:iri-datatype))))
256 (explicit (mapcar (lambda (ref) (find-reference-topic map (reference-iri ref))) (elements scope-node)))
257 ;; A resource locator is a value, not a topic reference. LEAF-HREF uses
258 ;; the shared XTM IRI resolver without topic lookup or resource access.
259 (text (unless reference-p (with-output-to-string (out)
260 (dolist (part (node-children resource)) (write-string part out)))))
261 (value (cond (reference-p (leaf-href resource))
262 (uri-data-p (resolve-iri text *document-iri* resource))
263 (t text))))
264 ;; ADD-VARIANT canonicalizes the union and enforces the proper superset.
265 ;; A nonempty explicit scope may still add no theme to the Name scope.
266 (let ((variant (topic-maps.tmdm:add-variant name value
267 :datatype (if (or reference-p uri-data-p) (topic-maps.tmdm:iri-datatype) (topic-maps.tmdm:string-datatype))
268 :scope (append (topic-maps.tmdm:topic-name-scope name) explicit))))
269 ;; Normalize first: an equal Variant may already own this identifier.
270 ;; Keep the native canonical result and its global conflict conditions.
271 (dolist (child children)
272 (when (string= (node-name child) "itemIdentity")
273 (setf variant (topic-maps.tmdm:add-item-identifier variant (leaf-href child)))))
274 ;; Reification may merge Topics and normalize this Variant again.
275 ;; Reuse the II-only resolver and retain its current native result.
276 (topic-maps.tmdm:canonical-variant (read-item-reifier node variant map)))))
277 (defun read-name (node owner map)
278 (let* ((children (elements node))
279 (type-node (find "type" children :key #'node-name :test #'string=))
280 (scope-node (find "scope" children :key #'node-name :test #'string=))
281 (type (when type-node (find-reference-topic map (reference-iri (first (elements type-node))))))
282 (scope (when scope-node (mapcar (lambda (ref) (find-reference-topic map (reference-iri ref)))
283 (elements scope-node))))
284 (value-node (find "value" children :key #'node-name :test #'string=))
285 (value (with-output-to-string (out)
286 (dolist (part (node-children value-node)) (write-string part out)))))
287 ;; SAX has already resolved XML character/entity references. Preserve the
288 ;; resulting Unicode sequence without trimming or decoding it again.
289 ;; ADD-NAME owns canonical set semantics and normalization after merging.
290 (let ((name (if type-node
291 (topic-maps.tmdm:add-name owner value :type type :scope scope)
292 (topic-maps.tmdm:add-default-name owner value :scope scope))))
293 ;; Item identifiers belong to the canonical Name, never its owner/type.
294 ;; Use the shared model API for set semantics and global conflicts.
295 (dolist (child children)
296 (when (string= (node-name child) "itemIdentity")
297 (setf name (topic-maps.tmdm:add-item-identifier name (leaf-href child)))))
298 ;; ADD-NAME may have returned an existing canonical Name. Reifier
299 ;; resolution/merging can normalize it again: retain the native result
300 ;; before processing Variants and return the current Name handle.
301 (setf name (read-item-reifier node name map))
302 (dolist (child children)
303 (when (string= (node-name child) "variant") (read-variant child name map)))
304 (topic-maps.tmdm:canonical-topic-name name))))
305 (defun read-topic (node map)
306 (let ((topic (topic-maps.tmdm:intern-topic map :item-identifier
307 (concatenate 'string *document-iri* "#" (collapse-space (attr node "id"))))))
308 (dolist (child (elements node))
309 (let ((name (node-name child)))
310 (cond
311 ((string= name "instanceOf") (read-instance-of child topic map))
312 ((string= name "name") (read-name child topic map))
313 (t (setf topic (topic-maps.tmdm:add-topic-identifier topic
314 (cond ((string= name "itemIdentity") :item-identifier)
315 ((string= name "subjectIdentifier") :subject-identifier)
316 (t :subject-locator))
317 (leaf-href child)))))))
318 (topic-maps.tmdm:canonical-topic topic)))
319 (defun deserialize-octets (bytes &key document-iri source-key)
320 "Deserialize raw XML octets into a new TMDM Topic Map (XTM 2.0 identity/Name subset).
321 DOCUMENT-IRI is required, absolute and fragment-free. SOURCE-KEY is a diagnostic
322 label only. XML positions are approximate SAX line/column values, not spans.
323 XML-policy errors, XTM rejection/unsupported and original TMDM conflicts remain
324 distinct. No resources are fetched. No externally supplied Map is mutated."
325 (check-type bytes (vector (unsigned-byte 8)))
326 (let ((*document-iri* document-iri) (*source-key* source-key)
327 (handler (make-instance 'source-handler)))
328 (require-document-iri document-iri)
329 (let* ((root
330 (handler-case (topic-maps.xml:parse-octets bytes handler)
331 (cxml:well-formedness-violation (c)
332 (error 'xtm-xml-error :code :xml-not-well-formed :cause c
333 :detail (princ-to-string c) :document-iri document-iri :source-key source-key
334 :line (sax:line-number handler) :column (sax:column-number handler)))
335 (topic-maps.xml:doctype-forbidden (c)
336 (error 'xtm-xml-error :code :doctype-forbidden :cause c
337 :detail "DOCTYPE forbidden by the mandatory XML byte boundary."
338 :document-iri document-iri :source-key source-key
339 :line (sax:line-number handler) :column (sax:column-number handler)))))
340 (map (topic-maps.tmdm:make-topic-map)))
341 (validate-source root)
342 ;; The attribute is processed before itemIdentity and later Topic nodes.
343 (read-map-reifier root map)
344 (dolist (child (elements root))
345 (if (string= (node-name child) "itemIdentity")
346 (topic-maps.tmdm:add-item-identifier map (leaf-href child))
347 (read-topic child map)))
348 map)))