1 (in-package #:topic-maps.tmdm)
3 (define-condition variant-error (error)
4 ((code :initarg :code :reader variant-error-code)
5 (detail :initarg :detail :reader variant-error-detail))
6 (:report (lambda (c out) (format out "Variant ~A: ~A" (variant-error-code c) (variant-error-detail c)))))
7 (defun variant-problem (code detail) (error 'variant-error :code code :detail detail))
8 (defun variant-scope-valid-p (scope parent-scope)
9 ;; Both operands are sets. TMDM 5.5 requires a *proper* superset.
10 (and (> (length scope) (length parent-scope))
11 (subsetp parent-scope scope :test #'eq)))
13 (defun check-variant-merge-constraints (map &key pair identifier)
14 "Preflight the full prospective Topic identity closure, without model mutation.
15 An explicit PAIR and/or proposed IDENTIFIER (Topic Kind IRI) may add edges.
16 Reject scope collapse atomically; TMDM specifies the invariant, not this API policy."
17 (let ((names (mapcan (lambda (topic) (copy-list (%topic-names topic))) (%topic-map-topics map))))
18 (when (some #'%topic-name-variants names)
19 (let ((parents (make-hash-table :test #'eq)) (topics (%topic-map-topics map)))
20 (dolist (topic topics) (setf (gethash topic parents) topic))
21 (labels ((root (topic)
22 (loop for current = topic then (gethash current parents)
23 when (eq current (gethash current parents)) return current))
24 (join (a b) (setf (gethash (root a) parents) (root b)))
25 (project (scope) (remove-duplicates (mapcar #'root scope) :test #'eq)))
26 (loop for tail on topics do
27 (dolist (other (rest tail))
28 (when (equal-topics-p (first tail) other) (join (first tail) other))))
29 (when pair (join (first pair) (second pair)))
31 (destructuring-bind (topic kind iri) identifier
32 (dolist (other topics)
33 (when (identifier-matches-p other kind iri) (join topic other)))))
35 (let ((parent-scope (project (%topic-name-scope name))))
36 (dolist (item (%topic-name-variants name))
37 (unless (variant-scope-valid-p (project (%variant-scope item)) parent-scope)
38 (variant-problem :variant-scope-collapse
39 "Topic merging would remove the Variant's additional scope; no mutation was performed."))))))))))
41 (defun normalize-variants (map)
42 "TMDM 5.5/6.4: remove equal Variants under each current Parent Name.
43 Reifier remains null; Item Identifiers are unioned, not equality keys."
44 (dolist (topic (%topic-map-topics map))
45 (dolist (name (%topic-names topic))
46 (loop for pair = (equal-pair (%topic-name-variants name)
48 (and (string= (%variant-value a) (%variant-value b))
49 (string= (%variant-datatype a) (%variant-datatype b))
50 (same-scope-p (%variant-scope a) (%variant-scope b)))))
52 (let* ((a (first pair)) (b (second pair))
53 (c (%make-variant (%variant-value a) (%variant-datatype a) name)))
54 (setf (%variant-scope c) (copy-list (%variant-scope a))
55 (%variant-item-identifiers c) (set-union (%variant-item-identifiers a) (%variant-item-identifiers b) #'string=)
56 (%topic-name-variants name) (replace-pair (%topic-name-variants name) a b c)
57 (%variant-forward a) c (%variant-forward b) c)))))
60 (defun add-variant (name value &key (datatype (string-datatype)) scope)
61 "Add an unreified Variant with actual TMDM SCOPE, a proper superset of NAME's.
62 The CTM reader unions explicit themes with the Parent Name scope before calling.
63 Validate before mutation. Quoted lexical values are not rewritten."
64 (check-type value string) (check-type datatype string)
65 (let* ((name (canonical-topic-name name)) (owner (live-topic (%topic-name-parent name)))
66 (map (%topic-parent owner)) (scope (canonical-scope map scope)))
67 (unless (member name (%topic-names owner) :test #'eq)
68 (variant-problem :invalid-parent "Parent must be a live Name in its Topic Map."))
69 (unless (variant-scope-valid-p scope (%topic-name-scope name))
70 (variant-problem :invalid-variant-scope "Variant scope must properly contain its Parent Name scope."))
71 (unless (absolute-locator-p datatype)
72 (variant-problem :invalid-datatype "Datatype must be a resolved absolute locator."))
73 (dolist (rule (list (list (integer-datatype) #'integer-lexical-p :invalid-integer-value)
74 (list (decimal-datatype) #'decimal-lexical-p :invalid-decimal-value)
75 (list (date-datatype) #'date-lexical-p :invalid-date-value)
76 (list (datetime-datatype) #'datetime-lexical-p :invalid-datetime-value)
77 (list (iri-datatype) #'absolute-locator-p :relative-uri-value)))
78 (when (and (string= datatype (first rule)) (not (funcall (second rule) value)))
79 (variant-problem (third rule) "Value is not valid for the specified datatype.")))
80 (let ((item (%make-variant value datatype name)))
81 (setf (%variant-scope item) scope
82 (%topic-name-variants name) (append (%topic-name-variants name) (list item)))
83 (normalize-variants map)
84 (canonical-variant item))))