]> dreyeck.freedombox.rocks Git - topic-maps.git/blob - src/xtm/reader.lisp
Integrate qualified XML anyType values into the XTM reader
[topic-maps.git] / src / xtm / reader.lisp
1 (in-package #:topic-maps.xtm)
2
3 (defparameter +any-type+ "http://www.w3.org/2001/XMLSchema#anyType")
4
5 (defparameter +namespace+ "http://www.topicmaps.org/xtm/")
6 ;; This is a source tree of XML events, not a second Topic Maps object model.
7 ;; Positions are SAX approximations at the end of a start tag, never byte spans.
8 (defstruct node uri name attributes children line column)
9 (defclass source-handler (sax:default-handler)
10 ((stack :initform nil :accessor handler-stack)
11 (root :initform nil :accessor handler-root)))
12 (defmethod sax:start-element ((h source-handler) uri local qname attributes)
13 (declare (ignore qname))
14 (let ((node (make-node :uri uri :name local :line (sax:line-number h)
15 :column (sax:column-number h)
16 :attributes (mapcar (lambda (a)
17 (list (sax:attribute-namespace-uri a)
18 (sax:attribute-local-name a)
19 (sax:attribute-value a))) attributes))))
20 (if (handler-stack h) (push node (node-children (first (handler-stack h))))
21 (setf (handler-root h) node))
22 (push node (handler-stack h))))
23 (defmethod sax:characters ((h source-handler) data)
24 (when (handler-stack h) (push (copy-seq data) (node-children (first (handler-stack h))))))
25 (defmethod sax:end-element ((h source-handler) uri local qname)
26 (declare (ignore uri local qname))
27 (let ((node (pop (handler-stack h)))) (setf (node-children node) (nreverse (node-children node)))))
28 (defmethod sax:end-document ((h source-handler)) (handler-root h))
29
30 ;;; Document-local association, not a second XML or Topic Maps model. The
31 ;;; opaque context is NEVER supplied by callers or reused between documents.
32 (defstruct xml-resource-binding document-iri source-key original snapshot nodes indices values)
33 (defvar *xml-resource-binding* nil)
34 (defun source-resource-nodes (node)
35 ;; Same expanded-name predicate and complete preorder as XML's documented
36 ;; RESOURCE-DATA-COUNT / CANONICALIZE-RESOURCE-DATA. Do not count only anyType
37 ;; or skip foreign subtrees: every resourceData slot affects the ordinal.
38 (append (when (and (equal (node-uri node) +namespace+) (equal (node-name node) "resourceData")) (list node))
39 (loop for child in (node-children node) unless (stringp child) append (source-resource-nodes child))))
40 (defun resource-association-error (detail)
41 ;; Internal association failure, not a claim that valid XTM is syntactically
42 ;; invalid. There is no native source span for this invariant; use NIL.
43 (error 'xtm-xml-error :code :resource-data-association :detail detail :cause nil
44 :document-iri *document-iri* :source-key *source-key* :line nil :column nil))
45 (defun prepare-xml-resources (root original snapshot)
46 (let* ((nodes (coerce (source-resource-nodes root) 'vector))
47 (any (find +any-type+ nodes :test #'equal :key (lambda (n) (attr n "datatype")))))
48 (when any
49 (unless (equalp original snapshot) (resource-association-error "Original XML octets changed after source parsing."))
50 ;; Provenance is established by construction: this private call uses only
51 ;; the octet snapshot taken BEFORE parsing this source tree. No DOM/private
52 ;; XML API or reconstructed XML is used for association or canonicalization.
53 (let* ((context (topic-maps.xml:parse-canonical-context snapshot))
54 (indices (make-hash-table :test #'eq))
55 (values (make-array (length nodes) :initial-element nil)))
56 (unless (= (length nodes) (topic-maps.xml:resource-data-count context))
57 (resource-association-error "Source/context resourceData inventories disagree."))
58 (loop for n across nodes for i from 0 do
59 (when (nth-value 1 (gethash n indices)) (resource-association-error "Source resourceData node occurs twice."))
60 (setf (gethash n indices) i)
61 (when (equal (attr n "datatype") +any-type+)
62 (setf (aref values i)
63 (handler-case (topic-maps.xml:canonicalize-resource-data context :index i)
64 (topic-maps.xml:canonicalization-error (c)
65 (error 'xtm-xml-error :code (topic-maps.xml:canonicalization-error-code c)
66 :detail (princ-to-string c) :cause c :document-iri *document-iri* :source-key *source-key*
67 :line nil :column nil))))))
68 (unless (equalp original snapshot) (resource-association-error "Original XML octets changed during context preparation."))
69 (make-xml-resource-binding :document-iri (copy-seq *document-iri*) :source-key (if (stringp *source-key*) (copy-seq *source-key*) *source-key*)
70 :original original :snapshot snapshot :nodes nodes :indices indices :values values)))))
71 (defun bound-xml-value (node)
72 (let ((b *xml-resource-binding*))
73 (unless (and b (equal *document-iri* (xml-resource-binding-document-iri b))
74 (equal *source-key* (xml-resource-binding-source-key b))
75 (equalp (xml-resource-binding-original b) (xml-resource-binding-snapshot b)))
76 (resource-association-error "No matching immutable XML document frame."))
77 (multiple-value-bind (index found) (gethash node (xml-resource-binding-indices b))
78 (unless (and found (typep index '(integer 0 *)) (< index (length (xml-resource-binding-nodes b)))
79 (eq node (aref (xml-resource-binding-nodes b) index))
80 (stringp (aref (xml-resource-binding-values b) index)))
81 (resource-association-error "resourceData is not owned by this document/ordinal."))
82 (aref (xml-resource-binding-values b) index))))
83 (defun validate-embedded-markup (node)
84 ;; XTM 4.3.1 any-markup excludes elements in the XTM namespace at EVERY
85 ;; depth; arbitrary foreign elements/attributes remain XML, not XTM syntax.
86 (when (equal (node-uri node) +namespace+)
87 (reject :embedded-xtm-element "XTM elements cannot occur inside embedded XML." node))
88 (dolist (child (node-children node))
89 (unless (stringp child) (validate-embedded-markup child))))
90
91 (defun xml-space-p (c) (find c '(#\Space #\Tab #\Newline #\Return)))
92 (defun collapse-space (text)
93 ;; xsd:ID has whiteSpace=collapse, even with a non-validating XML processor.
94 (with-output-to-string (out)
95 (let ((written nil) (pending nil))
96 (loop for c across text do
97 (if (xml-space-p c) (when written (setf pending t))
98 (progn (when pending (write-char #\Space out))
99 (write-char c out) (setf written t pending nil)))))))
100 (defun ncname-p (text)
101 ;; Use the pinned XML processor's XML 1.0 name character tables; exclude ':'
102 ;; for XML Schema ID/NCName and XPointer shorthand pointers (XTM 4.5/4.20).
103 (and (plusp (length text)) (not (find #\: text))
104 (cxml::valid-name-p (runes:string-rod text))))
105 (defun attributes (node allowed required)
106 (dolist (attr (node-attributes node))
107 (unless (and (or (null (first attr)) (equal (first attr) ""))
108 (member (second attr) allowed :test #'string=))
109 (reject :unexpected-attribute (format nil "Attribute ~S on ~A." (second attr) (node-name node)) node)))
110 (dolist (name required)
111 (unless (find name (node-attributes node) :key #'second :test #'string=)
112 (reject (if (string= name "id") :missing-id :missing-attribute)
113 (format nil "Required ~A attribute is absent." name) node))))
114 (defun attr (node name)
115 (third (find name (node-attributes node) :key #'second :test #'string=)))
116 (defun elements (node)
117 (loop for child in (node-children node)
118 if (stringp child) do
119 (unless (every #'xml-space-p child)
120 (reject :unexpected-text "Only XML whitespace is allowed here." node))
121 else collect child))
122 (defun check-namespace (node)
123 (unless (equal (node-uri node) +namespace+)
124 (reject :invalid-namespace "Expected the XTM 2.0 namespace." node)))
125 (defun unsupported (node)
126 (reject :unsupported-construct (format nil "XTM ~A is not implemented in this subset." (node-name node))
127 node 'xtm-unsupported))
128 (defun leaf-href (node)
129 (attributes node '("href") '("href"))
130 (when (elements node) (reject :unexpected-child "A locator element must be empty." node))
131 (resolve-iri (attr node "href") *document-iri* node))
132 (defun reference-iri (node)
133 (let* ((iri (leaf-href node)) (fragment (iri-parts-fragment (split-iri iri))))
134 (unless (and fragment (ncname-p fragment))
135 (reject :invalid-topic-ref "topicRef requires an XPointer shorthand fragment." node))
136 iri))
137
138 (defun validate-source (root)
139 "Check the supported XTM schema before model construction; keep event order.
140 Unsupported legal extension points are explicit; no claim to validate excluded
141 constructs' complete subgrammars is made. XML errors have already been checked."
142 (let ((ids (make-hash-table :test #'equal))) ; XML ID uniqueness only, no Topics.
143 (labels ((validate (node context)
144 (check-namespace node)
145 (let ((name (node-name node)))
146 (unless (member name context :test #'string=)
147 (reject :unexpected-element (format nil "Unexpected ~A element." name) node))
148 (cond
149 ((string= name "topicMap")
150 (attributes node '("version" "reifier") '("version"))
151 (unless (equal (attr node "version") "2.0")
152 (reject :invalid-version "This reader accepts XTM version 2.0 only." node))
153 (when (attr node "reifier")
154 (resolve-iri (attr node "reifier") *document-iri* node))
155 (let ((phase 0))
156 (dolist (child (elements node))
157 (let* ((name (node-name child))
158 (next (cond ((string= name "itemIdentity") 0)
159 ((string= name "mergeMap") 1) (t 2))))
160 (when (< next phase) (reject :element-order "topicMap child order is invalid." child))
161 (setf phase next)
162 (validate child '("itemIdentity" "mergeMap" "topic" "association"))))))
163 ((string= name "mergeMap") (mergemap-iri node))
164 ((string= name "topic")
165 (attributes node '("id") '("id"))
166 (let ((id (collapse-space (attr node "id"))))
167 (unless (ncname-p id) (reject :invalid-id "topic/@id must be an XML Schema ID." node))
168 (when (gethash id ids) (reject :duplicate-id "Duplicate XML ID in this document." node))
169 (setf (gethash id ids) t))
170 (let ((phase 0) (instance-seen nil))
171 (dolist (child (elements node))
172 (let* ((name (node-name child))
173 (next (cond ((member name '("itemIdentity" "subjectLocator" "subjectIdentifier")
174 :test #'string=) 0)
175 ((string= name "instanceOf") 1) (t 2))))
176 (when (< next phase) (reject :element-order "topic child order is invalid." child))
177 (when (= next 1)
178 (when instance-seen (reject :duplicate-instance-of "Only one instanceOf element is allowed." child))
179 (setf instance-seen t))
180 (setf phase next)
181 (validate child '("itemIdentity" "subjectLocator" "subjectIdentifier" "instanceOf" "name" "occurrence"))))))
182 ((string= name "instanceOf")
183 (attributes node nil nil)
184 (unless (elements node) (reject :empty-instance-of "instanceOf needs at least one topicRef." node))
185 (dolist (child (elements node)) (validate child '("topicRef"))))
186 ((string= name "name")
187 (attributes node '("reifier") nil)
188 (when (attr node "reifier")
189 (resolve-iri (attr node "reifier") *document-iri* node))
190 (let ((phase 0) (type-seen nil) (scope-seen nil) (value-seen nil))
191 (dolist (child (elements node))
192 (check-namespace child)
193 (let* ((kind (node-name child))
194 (next (position kind '("itemIdentity" "type" "scope" "value" "variant") :test #'string=)))
195 (unless next (reject :unexpected-element (format nil "Unexpected ~A element." kind) child))
196 (when (or (< next phase) (and (string= kind "variant") (not value-seen)))
197 (reject :element-order "name child order is invalid." child))
198 (setf phase next)
199 (cond
200 ((member kind '("itemIdentity" "variant") :test #'string=) nil)
201 ((string= kind "type")
202 (when type-seen (reject :duplicate-name-type "Only one name type is allowed." child))
203 (setf type-seen t))
204 ((string= kind "scope")
205 (when scope-seen (reject :duplicate-name-scope "Only one name scope is allowed." child))
206 (setf scope-seen t))
207 ((string= kind "value")
208 (when value-seen (reject :duplicate-name-value "Only one name value is allowed." child))
209 (setf value-seen t))
210 ;; Valid extension points remain explicitly unsupported.
211 ;; Their complete subgrammars are outside this subset.
212 (t (unsupported child)))
213 (validate child '("itemIdentity" "type" "scope" "value" "variant"))))
214 (unless value-seen (reject :missing-name-value "name requires a value element." node))))
215 ((string= name "variant")
216 (attributes node '("reifier") nil)
217 (when (attr node "reifier") (resolve-iri (attr node "reifier") *document-iri* node))
218 (let ((phase 0) (scope-seen nil) (resource-seen nil))
219 (dolist (child (elements node))
220 (check-namespace child)
221 (let* ((kind (node-name child))
222 (next (cond ((string= kind "itemIdentity") 0)
223 ((string= kind "scope") 1)
224 ((member kind '("resourceData" "resourceRef") :test #'string=) 2))))
225 (unless next (reject :unexpected-element (format nil "Unexpected ~A element." kind) child))
226 (when (< next phase) (reject :element-order "variant child order is invalid." child))
227 (setf phase next)
228 (cond
229 ((string= kind "itemIdentity") nil)
230 ((string= kind "scope")
231 (when scope-seen (reject :duplicate-variant-scope "Only one variant scope is allowed." child))
232 (setf scope-seen t))
233 (t
234 (unless scope-seen (reject :missing-variant-scope "variant requires scope before its resource." child))
235 (when resource-seen (reject :variant-resource-cardinality "variant requires exactly one resource." child))
236 (setf resource-seen t)))
237 (validate child '("itemIdentity" "scope" "resourceData" "resourceRef"))))
238 (unless scope-seen (reject :missing-variant-scope "variant requires a scope element." node))
239 (unless resource-seen (reject :missing-variant-resource "variant requires a resource element." node))))
240 ((string= name "occurrence")
241 (attributes node '("reifier") nil)
242 (when (attr node "reifier")
243 (resolve-iri (attr node "reifier") *document-iri* node))
244 (let ((phase 0) (type-seen nil) (scope-seen nil) (resource-seen nil))
245 (dolist (child (elements node))
246 (check-namespace child)
247 (let* ((kind (node-name child))
248 (next (cond ((string= kind "itemIdentity") 0)
249 ((string= kind "type") 1)
250 ((string= kind "scope") 2)
251 ((member kind '("resourceData" "resourceRef") :test #'string=) 3))))
252 (unless next (reject :unexpected-element (format nil "Unexpected ~A element." kind) child))
253 (when (< next phase) (reject :element-order "occurrence child order is invalid." child))
254 (setf phase next)
255 (cond
256 ((string= kind "itemIdentity") nil)
257 ((string= kind "type")
258 (when type-seen (reject :duplicate-occurrence-type "Only one occurrence type is allowed." child))
259 (setf type-seen t))
260 ((string= kind "scope")
261 (unless type-seen (reject :missing-occurrence-type "occurrence requires type before scope." child))
262 (when scope-seen (reject :duplicate-occurrence-scope "Only one occurrence scope is allowed." child))
263 (setf scope-seen t))
264 (t
265 (unless type-seen (reject :missing-occurrence-type "occurrence requires type before its resource." child))
266 (when resource-seen (reject :occurrence-resource-cardinality "occurrence requires exactly one resource." child))
267 (setf resource-seen t)))
268 (validate child '("itemIdentity" "type" "scope" "resourceData" "resourceRef"))))
269 (unless type-seen (reject :missing-occurrence-type "occurrence requires a type element." node))
270 (unless resource-seen (reject :missing-occurrence-resource "occurrence requires a resource element." node))))
271 ((member name '("association" "role") :test #'string=)
272 (attributes node '("reifier") nil)
273 (when (attr node "reifier")
274 (resolve-iri (attr node "reifier") *document-iri* node))
275 (let ((association-p (string= name "association"))
276 (phase 0) (type-seen nil) (scope-seen nil) (participants 0))
277 (dolist (child (elements node))
278 (check-namespace child)
279 (let* ((kind (node-name child))
280 (next (cond ((string= kind "itemIdentity") 0)
281 ((string= kind "type") 1)
282 ((and association-p (string= kind "scope")) 2)
283 ((string= kind (if association-p "role" "topicRef")) 3))))
284 (unless next (reject :unexpected-element (format nil "Unexpected ~A element." kind) child))
285 (when (< next phase) (reject :element-order (format nil "~A child order is invalid." name) child))
286 (setf phase next)
287 (cond
288 ((string= kind "itemIdentity") nil)
289 ((string= kind "type")
290 (when type-seen (reject :duplicate-type (format nil "Only one ~A type is allowed." name) child))
291 (setf type-seen t))
292 (t
293 (unless type-seen
294 (reject :missing-type (format nil "~A requires type before ~A." name kind) child))
295 (if (string= kind "scope")
296 (progn
297 (when scope-seen (reject :duplicate-scope "Only one association scope is allowed." child))
298 (setf scope-seen t))
299 (progn
300 (incf participants)
301 (when (and (not association-p) (> participants 1))
302 (reject :role-player-cardinality "role requires exactly one topicRef player." child))))))
303 (validate child (if association-p '("itemIdentity" "type" "scope" "role") '("itemIdentity" "type" "topicRef")))))
304 (unless type-seen (reject :missing-type (format nil "~A requires a type element." name) node))
305 (when (zerop participants)
306 (reject (if association-p :missing-roles :missing-role-player)
307 (if association-p "association requires at least one role." "role requires a topicRef player.") node))))
308 ((string= name "resourceRef") (leaf-href node))
309 ((string= name "resourceData")
310 (attributes node '("datatype") nil)
311 (let ((datatype (attr node "datatype")))
312 ;; DATATYPE is already an absolute IRI, not content to
313 ;; resolve against the document or percent-normalize.
314 (when datatype
315 (unless (iri-parts-scheme (split-iri datatype))
316 (reject :invalid-resource-data-datatype "resourceData datatype must be an absolute IRI." node))
317 (validate-decoded-reference (unescape-reference datatype node) node))
318 (dolist (child (node-children node))
319 (unless (stringp child)
320 (if (equal datatype +any-type+) (validate-embedded-markup child)
321 (reject :unexpected-child "Textual resourceData cannot contain child elements." child))))))
322 ((string= name "type")
323 (attributes node nil nil)
324 (let ((refs (elements node)))
325 (unless (= 1 (length refs)) (reject :type-cardinality "type requires exactly one topicRef." node))
326 (validate (first refs) '("topicRef"))))
327 ((string= name "scope")
328 (attributes node nil nil)
329 (unless (elements node) (reject :empty-scope "scope requires at least one topicRef." node))
330 (dolist (child (elements node)) (validate child '("topicRef"))))
331 ((string= name "value")
332 (attributes node nil nil)
333 ;; VALUE accepts all character data, including empty text and
334 ;; whitespace. ELEMENTS would apply the wrong text policy.
335 (dolist (child (node-children node))
336 (unless (stringp child) (reject :unexpected-child "value accepts character data only." child))))
337 ((string= name "topicRef") (reference-iri node))
338 ((member name '("itemIdentity" "subjectIdentifier" "subjectLocator") :test #'string=)
339 (leaf-href node))
340 (t (unsupported node))))))
341 (validate root '("topicMap"))))
342 root)
343
344 (defun find-reference-topic (map iri)
345 ;; XTM 4.20 searches the actual model, not a speculative pre-scan registry.
346 ;; Unlike INTERN-TOPIC, a hit MUST NOT add another identifier category.
347 (let ((topic (find-if (lambda (topic)
348 (or (member iri (topic-maps.tmdm:topic-subject-identifiers topic) :test #'string=)
349 (member iri (topic-maps.tmdm:topic-item-identifiers topic) :test #'string=)))
350 (topic-maps.tmdm:topic-map-topics map))))
351 (if topic (topic-maps.tmdm:canonical-topic topic)
352 (topic-maps.tmdm:intern-topic map :item-identifier iri))))
353 (defun read-item-reifier (node item map)
354 ;; XTM 4.3.2 looks up Item Identifiers only, unlike topicRef (4.20).
355 ;; INTERN-TOPIC adds the II on a miss; any SI/II identity merging then
356 ;; follows the existing TMDM rules, independently of this lookup.
357 (when (attr node "reifier")
358 (let* ((iri (resolve-iri (attr node "reifier") *document-iri* node))
359 (topic (or (find iri (topic-maps.tmdm:topic-map-topics map)
360 :test (lambda (iri topic)
361 (member iri (topic-maps.tmdm:topic-item-identifiers topic) :test #'string=)))
362 (topic-maps.tmdm:intern-topic map :item-identifier iri))))
363 (return-from read-item-reifier (topic-maps.tmdm:set-item-reifier item topic))))
364 item)
365 (defun read-map-reifier (node map)
366 (read-item-reifier node map map))
367 (defun core-topic (map local)
368 (topic-maps.tmdm:intern-topic map :subject-identifier
369 (concatenate 'string "http://psi.topicmaps.org/iso13250/model/" local)))
370 (defun read-instance-of (node owner map)
371 (dolist (ref (elements node))
372 (let ((type (find-reference-topic map (reference-iri ref))))
373 (topic-maps.tmdm:make-association map (core-topic map "type-instance")
374 (list (list (core-topic map "type") type)
375 (list (core-topic map "instance") (topic-maps.tmdm:canonical-topic owner)))))))
376 (defun read-item-identities (node item)
377 ;; XTM 4.6: assign locators to the actual canonical item, never intern Topics.
378 ;; ADD-ITEM-IDENTIFIER owns set semantics and cross-item conflict checks.
379 (dolist (child (elements node) item)
380 (when (string= (node-name child) "itemIdentity")
381 (setf item (topic-maps.tmdm:add-item-identifier item (leaf-href child))))))
382 (defun read-association (node map)
383 ;; Resolve references in source order, then construct the complete native
384 ;; Association. The constructor may already merge Associations AND Roles.
385 (let ((type nil) (scope nil) (roles nil) (role-nodes nil))
386 (labels ((reference (ref) (find-reference-topic map (reference-iri ref)))
387 (type-reference (node) (reference (first (elements node)))))
388 (dolist (child (elements node))
389 (cond ((string= (node-name child) "type") (setf type (type-reference child)))
390 ((string= (node-name child) "scope") (setf scope (mapcar #'reference (elements child))))
391 ((string= (node-name child) "role")
392 (let ((children (elements child)))
393 (push (list (type-reference (find "type" children :key #'node-name :test #'string=))
394 (reference (find "topicRef" children :key #'node-name :test #'string=))) roles)
395 (push child role-nodes)))))
396 (let ((association (read-item-identities node
397 (topic-maps.tmdm:make-association map type (reverse roles) :scope scope))))
398 ;; Match source metadata to the native Role by its complete signature
399 ;; within THIS canonical Parent. Role order/II are not equality keys.
400 (loop for pair in (reverse roles) for source in (reverse role-nodes) do
401 ;; A preceding Role Reifier may have merged Topics and this Parent.
402 (setf association (topic-maps.tmdm:canonical-association association))
403 (let ((role (find-if (lambda (role)
404 (and (eq (topic-maps.tmdm:association-role-type role)
405 (topic-maps.tmdm:canonical-topic (first pair)))
406 (eq (topic-maps.tmdm:association-role-player role)
407 (topic-maps.tmdm:canonical-topic (second pair)))))
408 (topic-maps.tmdm:association-roles association))))
409 (setf role (read-item-identities source role))
410 (read-item-reifier source (topic-maps.tmdm:canonical-association-role role) map)))
411 ;; Role metadata is now on the native canonical Parent. Reifier merging
412 ;; may normalize it again; return the resulting Association handle.
413 (topic-maps.tmdm:canonical-association
414 (read-item-reifier node association map))))))
415 (defun read-resource-value (resource)
416 "Return value and datatype for a validated resource node (XTM 4.16/4.17).
417 This operation neither looks up Topics nor fetches resources. ANYTYPE values
418 come only from the checked document-local XML binding. Preserve datatype IRIs."
419 (if (string= (node-name resource) "resourceRef")
420 (values (leaf-href resource) (topic-maps.tmdm:iri-datatype))
421 (let ((datatype (or (attr resource "datatype") (topic-maps.tmdm:string-datatype))))
422 (if (equal datatype +any-type+) (values (bound-xml-value resource) datatype)
423 (let ((text (with-output-to-string (out)
424 (dolist (part (node-children resource)) (write-string part out)))))
425 (values (if (equal datatype (topic-maps.tmdm:iri-datatype))
426 (resolve-iri text *document-iri* resource) text) datatype))))))
427 (defun read-variant (node name map)
428 (let* ((children (elements node))
429 (scope-node (find "scope" children :key #'node-name :test #'string=))
430 (resource (find-if (lambda (child) (member (node-name child) '("resourceData" "resourceRef") :test #'string=)) children))
431 (explicit (mapcar (lambda (ref) (find-reference-topic map (reference-iri ref))) (elements scope-node))))
432 (multiple-value-bind (value datatype) (read-resource-value resource)
433 ;; ADD-VARIANT owns canonicalization and the proper-superset constraint.
434 (let ((variant (topic-maps.tmdm:add-variant name value :datatype datatype
435 :scope (append (topic-maps.tmdm:topic-name-scope name) explicit))))
436 (setf variant (read-item-identities node variant))
437 ;; Reification may normalize again; retain the native canonical handle.
438 (topic-maps.tmdm:canonical-variant (read-item-reifier node variant map))))))
439 (defun read-name (node owner map)
440 (let* ((children (elements node))
441 (type-node (find "type" children :key #'node-name :test #'string=))
442 (scope-node (find "scope" children :key #'node-name :test #'string=))
443 (type (when type-node (find-reference-topic map (reference-iri (first (elements type-node))))))
444 (scope (when scope-node (mapcar (lambda (ref) (find-reference-topic map (reference-iri ref)))
445 (elements scope-node))))
446 (value-node (find "value" children :key #'node-name :test #'string=))
447 (value (with-output-to-string (out)
448 (dolist (part (node-children value-node)) (write-string part out)))))
449 ;; SAX has already resolved XML character/entity references. Preserve the
450 ;; resulting Unicode sequence without trimming or decoding it again.
451 ;; ADD-NAME owns canonical set semantics and normalization after merging.
452 (let ((name (if type-node
453 (topic-maps.tmdm:add-name owner value :type type :scope scope)
454 (topic-maps.tmdm:add-default-name owner value :scope scope))))
455 ;; Item identifiers belong to the canonical Name, never its owner/type.
456 ;; Use the shared model API for set semantics and global conflicts.
457 (setf name (read-item-identities node name))
458 ;; ADD-NAME may have returned an existing canonical Name. Reifier
459 ;; resolution/merging can normalize it again: retain the native result
460 ;; before processing Variants and return the current Name handle.
461 (setf name (read-item-reifier node name map))
462 (dolist (child children)
463 (when (string= (node-name child) "variant") (read-variant child name map)))
464 (topic-maps.tmdm:canonical-topic-name name))))
465 (defun read-occurrence (node owner map)
466 ;; XTM 4.13-4.17/4.20: reuse native Topics and the qualified resource path.
467 ;; ADD-OCCURRENCE owns live Parent/Type/Scope handles and TMDM 5.6/6.5 merging.
468 (let* ((children (elements node))
469 (type-node (find "type" children :key #'node-name :test #'string=))
470 (type (find-reference-topic map (reference-iri (first (elements type-node)))))
471 (scope-node (find "scope" children :key #'node-name :test #'string=))
472 (scope (when scope-node (mapcar (lambda (ref) (find-reference-topic map (reference-iri ref)))
473 (elements scope-node))))
474 (resource (find-if (lambda (child) (member (node-name child) '("resourceData" "resourceRef") :test #'string=)) children)))
475 (multiple-value-bind (value datatype) (read-resource-value resource)
476 (topic-maps.tmdm:canonical-occurrence
477 ;; Resolve Reifier by II only after native Occurrence normalization and
478 ;; II assignment. Reifier merging can normalize again: return its handle.
479 (read-item-reifier node
480 (read-item-identities node
481 (topic-maps.tmdm:add-occurrence owner type value :datatype datatype :scope scope)) map)))))
482 (defun read-topic (node map)
483 (let ((topic (topic-maps.tmdm:intern-topic map :item-identifier
484 (concatenate 'string *document-iri* "#" (collapse-space (attr node "id"))))))
485 (dolist (child (elements node))
486 (let ((name (node-name child)))
487 (cond
488 ((string= name "instanceOf") (read-instance-of child topic map))
489 ((string= name "name") (read-name child topic map))
490 ((string= name "occurrence") (read-occurrence child topic map))
491 (t (setf topic (topic-maps.tmdm:add-topic-identifier topic
492 (cond ((string= name "itemIdentity") :item-identifier)
493 ((string= name "subjectIdentifier") :subject-identifier)
494 (t :subject-locator))
495 (leaf-href child)))))))
496 (topic-maps.tmdm:canonical-topic topic)))
497 (defun mergemap-iri (node)
498 (let ((iri (leaf-href node)))
499 (when (iri-parts-fragment (split-iri iri))
500 (reject :mergemap-fragment "mergeMap href must not have a fragment identifier." node))
501 iri))
502 (defun resource-failure (code detail node &optional cause)
503 (error 'xtm-resource-error :code code :detail detail :cause cause
504 :document-iri *document-iri* :source-key *source-key*
505 :line (node-line node) :column (node-column node)))
506 (defun resource-octets-p (value)
507 ;; Same resolver value convention as CTM, without a dependency on its Reader.
508 (and (vectorp value) (not (stringp value))
509 (every (lambda (n) (and (integerp n) (<= 0 n 255))) value)))
510 (defun read-mergemap (node map resolver max-depth active-iris)
511 (let ((resource (mergemap-iri node)))
512 (unless resolver
513 (reject :resource-resolver-required "mergeMap requires an explicit resource resolver; no resource was loaded." node 'xtm-unsupported))
514 ;; These are finite resource-policy guards, not normative cycle semantics.
515 ;; Each independent public call starts a new active path; siblings may repeat.
516 (when (member resource active-iris :test #'string=)
517 (reject :cyclic-mergemap "Active recursive XTM resource dependency; cycle processing is not implemented." node 'xtm-unsupported))
518 (when (>= (length active-iris) (1+ max-depth))
519 (reject :resource-depth-limit "Configured nested XTM resource limit reached; this is implementation policy." node 'xtm-unsupported))
520 (multiple-value-bind (bytes source-key)
521 (handler-case
522 (funcall resolver resource :purpose :mergemap :from-document-iri *document-iri*
523 :notation "http://psi.topicmaps.org/iso13250/xtm")
524 (error (c) (resource-failure :resource-resolver-failure (princ-to-string c) node c)))
525 (unless bytes
526 (resource-failure :resource-unavailable "Resolver declined or did not supply the requested XTM resource." node))
527 (unless (and (resource-octets-p bytes) (or (null source-key) (stringp source-key)))
528 (resource-failure :invalid-resource-result "Resolver must return an octet vector and a string source key or NIL." node))
529 (let ((source (deserialize-document
530 (if (typep bytes '(vector (unsigned-byte 8))) bytes
531 (map '(vector (unsigned-byte 8)) #'identity bytes))
532 resource (or source-key resource) resolver max-depth active-iris)))
533 ;; Import only Topics/Associations. The existing operation preflights
534 ;; conflicts, preserves SOURCE, and excludes its Map identifiers/reifier.
535 (handler-case (topic-maps.tmdm:import-map-content map source)
536 (error (c) (resource-failure :mergemap-import-failure (princ-to-string c) node c)))))))
537 (defun deserialize-octets (bytes &key document-iri source-key resource-resolver (max-resource-depth 32))
538 "Deserialize raw XTM 2.0 octets into a fresh TMDM Map.
539 DOCUMENT-IRI is required, absolute and fragment-free. SOURCE-KEY is diagnostic.
540 RESOURCE-RESOLVER is optional: (resolver absolute-iri :purpose :mergemap
541 :from-document-iri parent-iri :notation XTM-notation-IRI)
542 returns raw octets and an optional diagnostic source key. No implicit I/O.
543 Children use their resolved IRI as Document IRI and the same explicit resolver.
544 MAX-RESOURCE-DEPTH bounds nested imports (default 32); active cycles are
545 Unsupported implementation policy, not a normative XTM invalidity decision.
546 Child XML/XTM/model errors retain their original contexts; resolver/import
547 failures use XTM-RESOURCE-ERROR with the original ERROR-CAUSE. No supplied Map
548 is mutated. Each public call has its own resource recursion context."
549 (check-type max-resource-depth (integer 0 *))
550 (deserialize-document bytes document-iri source-key resource-resolver max-resource-depth nil))
551 (defun deserialize-document (bytes document-iri source-key resource-resolver max-resource-depth active-iris)
552 (check-type bytes (vector (unsigned-byte 8)))
553 (let ((*document-iri* document-iri) (*source-key* source-key)
554 (*xml-resource-binding* nil) (snapshot (copy-seq bytes))
555 (handler (make-instance 'source-handler)))
556 (require-document-iri document-iri)
557 (let* ((root
558 (handler-case (topic-maps.xml:parse-octets bytes handler)
559 (cxml:well-formedness-violation (c)
560 (error 'xtm-xml-error :code :xml-not-well-formed :cause c
561 :detail (princ-to-string c) :document-iri document-iri :source-key source-key
562 :line (sax:line-number handler) :column (sax:column-number handler)))
563 (topic-maps.xml:doctype-forbidden (c)
564 (error 'xtm-xml-error :code :doctype-forbidden :cause c
565 :detail "DOCTYPE forbidden by the mandatory XML byte boundary."
566 :document-iri document-iri :source-key source-key
567 :line (sax:line-number handler) :column (sax:column-number handler)))))
568 (map (topic-maps.tmdm:make-topic-map)))
569 (validate-source root)
570 (setf *xml-resource-binding* (prepare-xml-resources root bytes snapshot))
571 ;; The attribute is processed before itemIdentity and later Topic nodes.
572 (read-map-reifier root map)
573 (dolist (child (elements root))
574 (cond ((string= (node-name child) "itemIdentity")
575 (topic-maps.tmdm:add-item-identifier map (leaf-href child)))
576 ((string= (node-name child) "mergeMap")
577 (read-mergemap child map resource-resolver max-resource-depth
578 (cons document-iri active-iris)))
579 ((string= (node-name child) "association") (read-association child map))
580 (t (read-topic child map))))
581 map)))