]> dreyeck.freedombox.rocks Git - topic-maps.git/blob - docs/reading-ctm-templates.md
feat(xtm): support anyURI resource data on name variants
[topic-maps.git] / docs / reading-ctm-templates.md
1 # Reading CTM Templates and Template Invocations
2
3 Slice 18 builds on `963f2a09444100d37e49cccbd6634879bd6742b5`.
4 The upstream corpus remains pinned at
5 `cd165b150176c1d6842b37be9cc9051b40d4996b` (draft 2010-03-31).
6 Its baselines are evidence, not a replacement for the published standard.
7
8 ## Normative basis
9
10 [CTM](https://www.isotopicmaps.org/ctm/ctm.html) §§3.14–3.15,
11 productions 63–70, define the Template name/arity namespace, positional binding,
12 global and Topic-Tail invocation, deferred lookup of nested calls and fresh
13 invocation-local named Wildcards. §3.2 supplies document order, Document IRI,
14 Wildcard IRI and Counter; §§3.3.6–3.3.8 retain ordinary Topic identity.
15 §3.13 distinguishes Role declarations from argument lists using its colon/layout
16 rule. §3.4.1 production 29 requires an IRI reference after `^^`, not a variable.
17 The body grammar admits Topics, Associations and Invocations, not directives,
18 nested definitions, standalone Embedded Topics or a Topic Map Reifier.
19
20 [TMDM](https://www.isotopicmaps.org/sam/sam-model/2006-06-18/) §§5.3–5.8
21 supply the unchanged information items/equality rules; §§6.1–6.7 supply merging.
22 Templates add no TMDM item kind. [CXTM](https://www.isotopicmaps.org/cxtm/cxtm.html)
23 §§3.4–3.19 and 4.6–4.11 apply to the resulting ordinary information items.
24
25 ## Concrete reader representation
26
27 `template-definition` stores name, ordered parameters, definition position and a
28 list of `ctm-statement` objects. Each statement has its parsed statement kind,
29 original character position and grammar-checked token sequence. Tokens retain
30 start/end offsets in the original source, including Unicode character offsets.
31 These are CTM concrete-syntax objects, not Topic Maps information items.
32
33 The definition traversal does not call TMDM constructors or intern identities.
34 It does not execute Wildcards. It checks the entire body even if never invoked.
35 Stored statements are replayed through the existing Topic/Name/Variant/
36 Occurrence/Association readers. There is no generated CTM string, Common Lisp
37 reader, EVAL, second literal-value parser or second Topic identity registry.
38
39 An invocation creates positional bindings and a fresh named-Wildcard table.
40 The same parser retains the shared Counter, Prefixes and Template registry.
41 Callers' arguments are evaluated in the caller environment: Wildcards and
42 Embedded Topics are resolved once and passed as actual canonical Topic handles.
43 IRIs/QNames retain their syntactic token and a locator resolved once in the
44 caller, without interning a Topic. Their Topic/literal use remains contextual;
45 an argument used only as an Occurrence value creates no SI Topic. Even an unused
46 QName requires a bound prefix; bound prefixes are never decoded a second time.
47 Explicit `=`/`^` arguments remain Topic references and cannot become literal
48 values or bare IRIs after an identity marker.
49 Bare and qualified literal values use the existing `read-literal` policy.
50 Qualified quoted lexical values are preserved. Datatype locators are not Topics.
51
52 The continued Topic Tail always retains its own canonical owner, independently
53 of the last Topic visited by a nested template. Retained argument handles are
54 resolved with `canonical-topic` when used after a Merge.
55
56 ## Three equivalent/useful forms
57
58 Global and Tail calls produce equivalent models:
59
60 ```text
61 def has-name($topic, $name)
62 $topic - $name.
63 end
64 has-name(a, "Name")
65 ```
66
67 ```text
68 def has-name($topic, $name)
69 $topic - $name.
70 end
71 a has-name("Name").
72 ```
73
74 A nested callee may be declared after its caller, but before execution:
75
76 ```text
77 def outer($topic)
78 inner($topic)
79 end
80 def inner($topic)
81 $topic - "Nested".
82 end
83 outer(a)
84 ```
85
86 ## Diagnostics and API policy
87
88 The public deserialization signatures and final Counter return value remain
89 unchanged. New exported CTM-REJECTION subclasses are `template-error`,
90 `duplicate-template`, `undefined-template`, `template-arity-error`,
91 `unbound-template-variable`, `invalid-template-argument` and
92 `invalid-template-body`. Existing Prefix conditions remain distinct.
93
94 `error-position`, `error-line`, `error-column` and `error-source` refer to the
95 original source. `error-context` holds an innermost-first list with Template
96 name, definition position and invocation position. These positions do not
97 identify objects outside that execution. Included-source provenance is not
98 implemented because Include is excluded.
99
100 Unbound variables are rejected during definition checking. Distinct parameter
101 names are required by this implementation's positional-binding policy. The
102 internal expansion-depth limit defaults to 256; reaching it reports
103 CTM-UNSUPPORTED / :TEMPLATE-DEPTH-LIMIT, not a normative syntax error.
104 There is no promise of a transaction covering an entire multi-statement
105 invocation. Existing per-operation conflict/preflight policies remain intact.
106
107 ## Seven deliberately open grammar contracts
108
109 CTM §3.3.6 production 17 gives `subject-identifier -> iri-ref`; §3.9
110 production 52 uses that production for an unmarked identity in a Topic Tail.
111 §3.14's substitution prose does not explicitly add a variable there. The corpus
112 assumes `topic $iri.` is allowed with a bare IRI argument, and rejects it with an
113 explicitly marked II/SL argument. This Slice adds no such grammar extension.
114 An unmarked variable Tail identity is rejected with :TEMPLATE-IDENTITY-TAIL;
115 variables as an Occurrence Type before `:` and the explicit `^$iri`/`=$iri`
116 productions remain supported. The following imported contracts remain NOT-RUN:
117
118 - in/template-subject-identifier2.ctm
119 - in/template-ambiguous-parameter5.ctm
120 - in/template-ambiguous-parameter6.ctm
121 - invalid/template-item-identifier3.ctm
122 - invalid/template-item-identifier-2nd-arg.ctm
123 - invalid/template-subject-locator3.ctm
124 - invalid/template-subject-locator-2nd-arg.ctm
125
126 A rejection of an open contract is not recorded as a conformance PASS.
127 Separately, Include/Mergemap dependencies keep in/include-template.ctm,
128 in/include-template-wildcard.ctm, in/mergemap-template.ctm and
129 invalid/mergemap-template.ctm NOT-RUN. The last requires the fact that Mergemap
130 imports data, not template definitions (CTM §3.16.3); Include would import
131 Templates (§3.16.2). Neither directive is implemented here.
132
133 ## Inspect actual Lisp objects in a fresh process
134
135 Run from the repository root. Printed addresses belong only to this process.
136
137 ```lisp
138 (require :asdf)
139 (asdf:initialize-source-registry '(:source-registry :ignore-inherited-configuration))
140 (asdf:load-asd (truename "topic-maps.asd"))
141 (asdf:load-system "topic-maps/ctm")
142 (asdf:load-system "topic-maps/cxtm")
143 (let* ((source "def named($t,$n) $t - $n. end def outer($t) named($t,\"Name\") end a outer().")
144 (iri "https://example.invalid/templates.ctm")
145 (map (topic-maps.ctm:deserialize-string source :document-iri iri))
146 (topic (find-if #'topic-maps.tmdm:topic-names (topic-maps.tmdm:topic-map-topics map)))
147 (name (first (topic-maps.tmdm:topic-names topic))))
148 (assert (eq topic (topic-maps.tmdm:topic-name-parent name)))
149 (assert (member (topic-maps.tmdm:topic-name-type name)
150 (topic-maps.tmdm:topic-map-topics map) :test #'eq))
151 (describe map)
152 (describe topic)
153 (describe name)
154 (describe (topic-maps.tmdm:topic-name-type name))
155 (write-string (topic-maps.cxtm:canonicalize map :base-locator iri)))
156 ```
157
158 ## Executed original contracts
159
160 The tables below list the explicit test selection, not inferred passes.
161 Execution evidence is in `reports/slice-18/`: original bytes, model observations,
162 specific rejection classes/codes/positions, runtime and source/artifact hashes.
163 The independent Python checker relates actual model references to original
164 baseline topics separately from byte equality. `tests/ctm-templates.lisp` also
165 asserts EQ relationships, retained handles and mutation-free serialization.
166
167 | Positive original | Baseline bytes | Principal exercised capability |
168 |---|---:|---|
169 | `association-scope-embedded3.ctm` | 2431 | definition / invocation, binding, Embedded Topics, Scope |
170 | `association-scope-embedded4.ctm` | 3613 | definition / invocation, binding, Embedded Topics, Scope |
171 | `name-scope-embedded3.ctm` | 2105 | definition / invocation, binding, Embedded Topics, Scope |
172 | `name-scope-embedded4.ctm` | 3284 | definition / invocation, binding, Embedded Topics, Scope |
173 | `occurrence-scope-embedded3.ctm` | 2277 | definition / invocation, binding, Embedded Topics, Scope |
174 | `occurrence-scope-embedded4.ctm` | 3457 | definition / invocation, binding, Embedded Topics, Scope |
175 | `prefix-template-scope.ctm` | 263 | definition / invocation |
176 | `template-ambiguous-parameter.ctm` | 376 | definition / invocation, binding |
177 | `template-ambiguous-parameter2.ctm` | 407 | definition / invocation, binding |
178 | `template-ambiguous-parameter3.ctm` | 399 | definition / invocation, binding |
179 | `template-ambiguous-parameter4.ctm` | 1506 | definition / invocation, binding, type relationships |
180 | `template-assoc-embedded-topic.ctm` | 23 | definition / invocation, Embedded Topics |
181 | `template-duplicate-name.ctm` | 438 | definition / invocation, binding |
182 | `template-forward-ref.ctm` | 825 | definition / invocation, binding |
183 | `template-invocation-embedded.ctm` | 401 | definition / invocation, binding, Embedded Topics |
184 | `template-invocation-embedded2.ctm` | 401 | definition / invocation, binding, Embedded Topics |
185 | `template-invocation-noargs-isa.ctm` | 963 | definition / invocation, type relationships |
186 | `template-invocation-noargs2.ctm` | 828 | definition / invocation, binding |
187 | `template-invocation-prefix-notation.ctm` | 328 | definition / invocation, binding |
188 | `template-invocation-twice.ctm` | 402 | definition / invocation, binding |
189 | `template-invocation-wildcard-named.ctm` | 331 | definition / invocation, binding, Wildcards |
190 | `template-invocation-wildcard-named2.ctm` | 331 | definition / invocation, binding, Wildcards |
191 | `template-invocation-wildcard-named3.ctm` | 646 | definition / invocation, binding, Wildcards |
192 | `template-invocation-wildcard-named4.ctm` | 331 | definition / invocation, Wildcards |
193 | `template-invocation-wildcard-named5.ctm` | 577 | definition / invocation, Wildcards |
194 | `template-invocation-wildcard-named6.ctm` | 581 | definition / invocation, binding, Wildcards |
195 | `template-invocation-wildcard.ctm` | 484 | definition / invocation, binding, Wildcards |
196 | `template-item-identifier.ctm` | 131 | definition / invocation, binding |
197 | `template-item-identifier2.ctm` | 131 | definition / invocation, binding |
198 | `template-item-identifier4.ctm` | 157 | definition / invocation, binding |
199 | `template-nested-occtype.ctm` | 576 | definition / invocation, Embedded Topics |
200 | `template-nested-occtype2.ctm` | 737 | definition / invocation, Embedded Topics |
201 | `template-noop.ctm` | 23 | definition / invocation |
202 | `template-noop2.ctm` | 23 | definition / invocation |
203 | `template-noop3.ctm` | 23 | definition / invocation, binding, type relationships |
204 | `template-references.ctm` | 23 | definition / invocation, type relationships |
205 | `template-simple.ctm` | 114 | definition / invocation |
206 | `template-subject-identifier.ctm` | 141 | definition / invocation, binding |
207 | `template-subject-locator.ctm` | 131 | definition / invocation, binding |
208 | `template-subject-locator2.ctm` | 131 | definition / invocation, binding |
209 | `template-subject-locator4.ctm` | 194 | definition / invocation, binding |
210 | `template-topic-nested.ctm` | 678 | definition / invocation, Embedded Topics, Reifier |
211 | `template-topic-nested2.ctm` | 596 | definition / invocation, Embedded Topics, Reifier |
212 | `template-typed-value.ctm` | 351 | definition / invocation, binding |
213 | `template-wildcard-named.ctm` | 211 | definition / invocation, Wildcards |
214 | `template-wildcard-named2.ctm` | 211 | definition / invocation, Wildcards |
215 | `template-wildcard-named3.ctm` | 211 | definition / invocation, Wildcards |
216 | `template-wildcard-named4.ctm` | 919 | definition / invocation, binding, Wildcards |
217 | `template-wildcard.ctm` | 203 | definition / invocation, Wildcards |
218 | `template-wildcard2.ctm` | 293 | definition / invocation, Wildcards |
219 | `tmlab-tmql-issue-48.ctm` | 2358 | definition / invocation, binding, Wildcards, type relationships |
220 | `topic-embedded-template-invocation.ctm` | 1357 | definition / invocation, binding, Embedded Topics, type relationships |
221 | `topic-identifier-eq-template-name.ctm` | 207 | definition / invocation |
222 | `topic-template-invocation-unary.ctm` | 328 | definition / invocation, binding |
223 | `topic-template-invocation.ctm` | 328 | definition / invocation, binding |
224 | `variant-scope-embedded3.ctm` | 2547 | definition / invocation, binding, Embedded Topics, Scope |
225 | `variant-scope-embedded4.ctm` | 3734 | definition / invocation, binding, Embedded Topics, Scope |
226
227 | Negative original | Required specific code |
228 |---|---|
229 | `embedded-topic-template.ctm` | `:INVALID-TEMPLATE-BODY` |
230 | `occurrence-explicit-datatype-as-parameter.ctm` | `:VARIABLE-DATATYPE` |
231 | `prefix-template-scope.ctm` | `:INVALID-TEMPLATE-BODY` |
232 | `template-bad-type.ctm` | `:INVALID-TEMPLATE-ARGUMENT` |
233 | `template-missing-args.ctm` | `:TEMPLATE-ARITY` |
234 | `template-missing-def.ctm` | `:UNDEFINED-TEMPLATE` |
235 | `template-name-collision.ctm` | `:DUPLICATE-TEMPLATE` |
236 | `tm-reifier-in-template.ctm` | `:INVALID-TEMPLATE-BODY` |
237 | `variable-undefined.ctm` | `:VARIABLE-OUTSIDE-TEMPLATE` |
238 | `variable-undefined2.ctm` | `:VARIABLE-OUTSIDE-TEMPLATE` |