]> dreyeck.freedombox.rocks Git - topic-maps.git/blob - docs/reading-integer-occurrences.md
test(ctm): register forty original Slice 20A contracts
[topic-maps.git] / docs / reading-integer-occurrences.md
1 # Reading Integer Occurrences
2
3 Slice 7 extends the accepted Slice 6 commit
4 `3924d1eac5a070fe5a6a26683e23ac338793f544`. The original corpus remains pinned to
5 `cd165b150176c1d6842b37be9cc9051b40d4996b`. Its CTM tests target draft 2010-03-31;
6 the published standards remain authoritative.
7
8 ## Representation, equality and canonicalization
9
10 These are three separate operations, not a single numeric-equality rule.
11
12 [CTM §3.4.1](https://www.isotopicmaps.org/ctm/ctm.html) defines the integer form
13 as an optional sign plus digits, assigns xsd:integer, and puts the literal's
14 value into the Occurrence. A quoted string can explicitly name that datatype.
15 This implementation maps an **unquoted numeric literal's value** to its canonical
16 integer string during deserialization: `+001` becomes `"1"`, `-000` becomes
17 `"0"`. This is the reader's documented value-representation policy, not a claim
18 that §3.4.1 explicitly mandates early lexical canonicalization. The lexer retains
19 the original token spelling; the unmodified CTM source remains separate.
20 **Explicitly quoted values retain their escape-decoded strings**, including
21 leading zeros and XML whitespace. The two source forms are not a promise to
22 preserve identical lexical histories in the model.
23
24 [TMDM §§4.3–4.4, 5.6, 6.5](https://www.isotopicmaps.org/sam/sam-model/2006-06-18/)
25 require a string [value], a separate datatype locator, and equality by the
26 Occurrence's value/datatype/type/scope/parent. String equality compares Unicode
27 scalar sequences; mathematical value-space equivalence alone does not make
28 unequal strings equal. The existing model/API **does not normalize stored integer
29 strings**. Identical strings with equal remaining properties merge; differing
30 strings stay distinct. A datatype locator does not synthesize a Topic.
31
32 [CXTM §§3.16, 4.2–4.3, 4.9](https://www.isotopicmaps.org/cxtm/cxtm.html)
33 require integer canonical lexical output and Occurrence ordering by the model's
34 value, datatype, type, scope, parent. The integer's stored value is still a string:
35 comparison uses the stored string under the string rules, rather than a numeric
36 comparison or the reformatted output. Serialization computes the canonical
37 string without modifying the model or removing items that serialize alike.
38
39 [XML Schema Part 2, §§3.3.13.1–3.3.13.2 and 4.3.6](https://www.w3.org/TR/2004/REC-xmlschema-2-20041028/#integer)
40 provide ASCII sign/digits, canonical representation and the XML-whitespace
41 collapse facet. The canonical output has no plus sign or leading zeros, and
42 zero is `0` (also consistent with §3.3.14.2). Internal whitespace is invalid;
43 XML whitespace at the ends of qualified values is accepted for interpreting
44 this datatype. It is retained in TMDM, removed only in canonical output.
45 No fixed-width numeric representation is needed: pure character processing
46 handles arbitrary finite-length integer strings.
47
48 Examples of the resulting contract, with the same Parent and Type:
49
50 | CTM forms | Stored values/datatype | Equality/result |
51 | --- | --- | --- |
52 | `001`, `+1`, `1` | all `"1"`, xsd:integer | duplicate Occurrences merge |
53 | `1`, `"1"^^xsd:integer` | both `"1"`, xsd:integer | merge |
54 | `"001"^^xsd:integer`, `"1"^^xsd:integer` | `"001"`, `"1"` | remain two Occurrences; both output `1` |
55 | `1`, `"1"` | same string, different datatypes | remain two Occurrences |
56
57 A map with one `"001"` integer Occurrence and one with one `"1"` integer
58 Occurrence can have identical canonical XML while their stored values differ.
59 The tests explicitly establish this counterexample; XML equality does not drive
60 TMDM merging.
61
62 The string order for `-2`, `-10`, `2`, `10` is `-10`, `-2`, `10`, `2`.
63 For **explicit** stored strings `+002`, `-10`, `001`, `2`, the string order is
64 `+002`, `-10`, `001`, `2`, while the output values are `2`, `-10`, `1`, `2`.
65 This is intentional: ordering uses §4.9's properties, output uses §3.16.
66
67 ## Original cases and expected information items
68
69 The six original sources and baselines were read before implementation. All use
70 Document IRI `https://ctm-tests.example.invalid/cd165b150176c1d6842b37be9cc9051b40d4996b/`
71 followed by their full `ctm/in/...ctm` ID; CXTM uses the same Base Locator.
72 Their baseline `#topic` and type identifiers follow the existing §3.18 policy.
73 Stored identifiers remain absolute, and datatype output remains a full locator.
74
75 Each input creates one Topic Map. The first four and the explicit-datatype case
76 create two Topics: owner `topic`, Type `occtype`. Each Topic has only its local
77 Item Identifier `DocumentIRI#identifier`. One Occurrence has Parent EQ owner,
78 Type EQ occtype, datatype `http://www.w3.org/2001/XMLSchema#integer`, and NIL
79 Item Identifiers. The actual stored values are `"1"`, `"1"`, `"1"`, `"-1"`, and
80 `"42"`, respectively. SI/SL/Names/Associations are empty. No datatype Topic exists.
81 CXTM numbers type=1, owner=2 and Occurrence=1.
82
83 The leading-zero case creates eight Topics: owner `topic` and seven Type Topics
84 `o1` through `o7`. The seven Occurrences' stored values in source order are
85 `"1"`, `"1"`, `"-1"`, `"100"`, `"0"`, `"0"`, `"0"`. All have Parent EQ owner
86 and distinct corresponding Type references, so they are not duplicates.
87 CXTM numbers o1–o7 as Topics 1–7 and owner as Topic 8. Its Occurrence order is
88 o3, o5, o6, o7, o1, o2, o4: value-string order followed by Type order on ties.
89
90 ### ctm/in/occurrence-integer.ctm
91
92 ```ctm
93 topic
94 occtype: 1;.
95 ```
96
97 Original has no final LF; the display fence adds only a visual line break. Original CXTM: 351 bytes. **Byte-exact PASS**.
98
99 ### ctm/in/occurrence-integer2.ctm
100
101 ```ctm
102
103 # In a previous CTM draft 1. was a valid decimal.
104 # This is not the case anymore, the "1." must be interpreted as
105 # integer "1" followed by the end of the topic block
106
107 topic
108 occtype: 1.
109 ```
110
111 Original has no final LF; the display fence adds only a visual line break. Original CXTM: 351 bytes. **Byte-exact PASS**.
112
113 ### ctm/in/occurrence-integer-plus-sign.ctm
114
115 ```ctm
116 topic
117 occtype: +1;.
118 ```
119
120 Original has no final LF; the display fence adds only a visual line break. Original CXTM: 351 bytes. **Byte-exact PASS**.
121
122 ### ctm/in/occurrence-integer-minus-sign.ctm
123
124 ```ctm
125 topic
126 occtype: -1;.
127 ```
128
129 Original has no final LF; the display fence adds only a visual line break. Original CXTM: 352 bytes. **Byte-exact PASS**.
130
131 ### ctm/in/occurrence-integer-leading-zeros.ctm
132
133 ```ctm
134
135 #
136 # Various integer with leading zeros tests
137 #
138
139 topic
140 o1: 001;
141 o2: +001;
142 o3: -001;
143 o4: 000100;
144 o5: 000000;
145 o6: +000000;
146 o7: -000000.
147 ```
148
149 Original final LF present. Original CXTM: 1741 bytes. **Byte-exact PASS**.
150
151 ### ctm/in/occurrence-explicit-datatype2.ctm
152
153 ```ctm
154 %prefix xsd http://www.w3.org/2001/XMLSchema#
155
156 topic
157 occtype: "42"^^xsd:integer.
158 ```
159
160 Original has no final LF; the display fence adds only a visual line break. Original CXTM: 352 bytes. **Byte-exact PASS**.
161
162 ## Public API and executable inspection
163
164 The existing `deserialize-string`, `deserialize-file`, `add-occurrence`,
165 `occurrence-value`, `occurrence-datatype`, Parent/Type readers,
166 `canonical-occurrence` and CXTM API signatures remain unchanged.
167 New pure helpers in `topic-maps.tmdm`:
168
169 - `(integer-datatype)` returns the exact xsd:integer locator string.
170 - `(integer-lexical-p string)` checks the supported XSD integer lexical space.
171 - `(canonical-integer-lexical-form string)` returns a canonical string, or NIL
172 for invalid input. It performs no model normalization or merging.
173
174 The reader signals `CTM-REJECTION :INVALID-INTEGER-VALUE` for invalid explicitly
175 integer-typed strings, with the quoted token's source position. The model API
176 rejects them atomically via `OCCURRENCE-ERROR :INVALID-INTEGER-VALUE`; CXTM rejects
177 a private invalid model via `CXTM-ERROR :INVALID-INTEGER-VALUE`. These are distinct
178 from undefined-prefix rejection and unsupported Decimal/date/* forms.
179
180 ```lisp
181 (require :asdf)
182 (asdf:initialize-source-registry '(:source-registry :ignore-inherited-configuration))
183 (asdf:load-asd #p"/Users/rgb/workspace/topic-maps/topic-maps.asd")
184 (asdf:load-system "topic-maps/ctm")
185 (asdf:load-system "topic-maps/cxtm")
186 (let* ((doc "https://example.invalid/integers.ctm")
187 (map (topic-maps.ctm:deserialize-string
188 "%prefix xsd <http://www.w3.org/2001/XMLSchema#> topic occtype: +001; occtype: \"001\"^^xsd:integer."
189 :document-iri doc))
190 (owner (first (topic-maps.tmdm:topic-map-topics map)))
191 (items (topic-maps.tmdm:topic-occurrences owner)))
192 (assert (= 2 (length items)))
193 (assert (equal '("1" "001") (mapcar #'topic-maps.tmdm:occurrence-value items)))
194 (assert (eq (topic-maps.tmdm:occurrence-type (first items))
195 (topic-maps.tmdm:occurrence-type (second items))))
196 (describe (second items))
197 (describe (topic-maps.tmdm:occurrence-type (second items)))
198 (write-string (topic-maps.cxtm:canonicalize map :base-locator doc)))
199 ```
200
201 ## Local observations and limits
202
203 `reports/slice-7/integers.json` contains the six original sources, absolute
204 Document IRIs and actual object properties/reference ordinals. Its 143 additional
205 probes record both implicit/explicit model strings and complete canonical XML.
206 An independent Python big-integer oracle checks each output, including positive
207 and negative 10,000-digit values. The tests also permute construction order,
208 check lexical duplicate removal/late merges and verify model/retained-handle
209 purity. All prior 33 positive and three negative contracts retain their results.
210
211 The literal lexer recognizes `1.` as an integer followed by a terminator;
212 `1.5` remains an excluded Decimal. Preserve the QName grammar: `t:1` is a QName,
213 so use `t: 1` (or `t :1`) for a local Occurrence Type followed by an integer.
214 The selected originals already use the unambiguous syntax. Integer source text
215 is handled by the same dedicated CTM lexer/reader, never Common Lisp READ/EVAL.
216
217 Decimal, Date, DateTime, Variants, nonempty Scope, Reification, Templates,
218 cross-document merging and HyperDoc integration remain outside the slice.
219 The `*` literal/ctm-integer counter semantics are not implemented and are not a
220 dependency of any selected case. The existing generic explicit-datatype path
221 can carry an opaque ctm-integer locator; that adds no special semantics.
222 No derived XSD integer subtype coercion is introduced: only the exact xsd:integer
223 locator receives the new treatment. Existing locator-validation, Unicode and
224 root-LF boundaries are unchanged. No selected draft/published-standard conflict
225 was found; the early bare-literal representation policy is explicitly qualified
226 above rather than asserted as a new TMDM equality rule.