mdld-parse 0.9.2 β 0.9.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/.nojekyll +0 -0
- package/dist/CNAME +1 -0
- package/dist/README.md +425 -0
- package/dist/docs/API.md +397 -0
- package/dist/docs/Architecture.md +190 -0
- package/dist/docs/Guide.md +322 -0
- package/dist/docs/LLM-MDLD-Inducer.md +550 -0
- package/dist/docs/Parser.md +654 -0
- package/dist/docs/Performance.md +238 -0
- package/dist/docs/Spec-render.md +1439 -0
- package/dist/docs/Subject.md +180 -0
- package/dist/docs/Syntax.md +463 -0
- package/dist/docs/TodoList.md +215 -0
- package/dist/docs/Use-Cases.md +354 -0
- package/dist/docs/index.html +108 -0
- package/dist/docs/index.md +56 -0
- package/dist/docs/origin.md +459 -0
- package/dist/docs/polarity.md +586 -0
- package/dist/docs/primary-subject.md +199 -0
- package/dist/docs/statements.md +226 -0
- package/dist/docs/tokenization-performance-report.md +164 -0
- package/dist/examples/Cookbook.md +32 -0
- package/dist/examples/Status-SHACL.md +33 -0
- package/dist/examples/demo/index.md +35 -0
- package/dist/examples/demo/journal.md +18 -0
- package/dist/examples/demo/minimal.md +11 -0
- package/dist/examples/demo/project.md +15 -0
- package/dist/examples/demo/recipe.md +31 -0
- package/dist/examples/demo/research.md +46 -0
- package/dist/examples/demo/space-mission.md +48 -0
- package/dist/examples/dogfood.md +288 -0
- package/dist/examples/few-shot.md +309 -0
- package/dist/examples/graph/rdf-graph.html +473 -0
- package/dist/examples/graph/rdf_force_graph_web_component.html +506 -0
- package/dist/examples/index.md +45 -0
- package/dist/examples/llm-time-workflow.md +173 -0
- package/dist/examples/prov-o.md +2367 -0
- package/dist/examples/rdf.md +827 -0
- package/dist/examples/shacl.md +3399 -0
- package/dist/examples/statements.md +43 -0
- package/dist/examples/workflow.md +150 -0
- package/dist/index.html +2827 -0
- package/dist/index.js +1548 -0
- package/dist/logo.svg +7 -0
- package/dist/spec/Spec-compact.md +363 -0
- package/dist/spec/Spec-ultra.md +221 -0
- package/dist/spec/Spec.md +1068 -0
- package/dist/spec/index.md +46 -0
- package/package.json +7 -8
- package/src/constants.js +0 -31
- package/src/generate.js +0 -245
- package/src/highlight.js +0 -362
- package/src/index.js +0 -13
- package/src/locate.js +0 -23
- package/src/merge.js +0 -157
- package/src/parse.js +0 -711
- package/src/render.js +0 -576
- package/src/shared.js +0 -577
- package/src/tokenizers.js +0 -594
- package/src/utils.js +0 -430
package/dist/.nojekyll
ADDED
|
File without changes
|
package/dist/CNAME
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
mdld.js.org
|
package/dist/README.md
ADDED
|
@@ -0,0 +1,425 @@
|
|
|
1
|
+
# MD-LD
|
|
2
|
+
|
|
3
|
+
**Markdown-Linked Data (MD-LD)** β a deterministic, streaming-friendly RDF authoring format that extends Markdown with explicit `{...}` annotations.
|
|
4
|
+
|
|
5
|
+
[](https://www.npmjs.com/package/mdld-parse)
|
|
6
|
+
|
|
7
|
+
[Demo](https://mdld.js.org) | [Repository](https://github.com/davay42/mdld-parse)
|
|
8
|
+
|
|
9
|
+
## π Quick Start
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
pnpm install mdld-parse
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
```javascript
|
|
16
|
+
import { parse } from 'mdld-parse';
|
|
17
|
+
|
|
18
|
+
const result = parse(`
|
|
19
|
+
[ex] <http://example.org/>
|
|
20
|
+
|
|
21
|
+
# Document {=ex:doc .ex:Article label}
|
|
22
|
+
|
|
23
|
+
[Alice] {?ex:author =ex:alice .prov:Person ex:firstName label}
|
|
24
|
+
[Smith] {ex:lastName}`);
|
|
25
|
+
|
|
26
|
+
console.log(result.quads);
|
|
27
|
+
// RDF/JS quads ready for n3.js, rdflib, etc.
|
|
28
|
+
// @prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>.
|
|
29
|
+
// @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>.
|
|
30
|
+
// @prefix prov: <http://www.w3.org/ns/prov#>.
|
|
31
|
+
// @prefix ex: <http://example.org/>.
|
|
32
|
+
|
|
33
|
+
// ex:doc a ex:Article;
|
|
34
|
+
// rdfs:label "Document";
|
|
35
|
+
// ex:author ex:alice.
|
|
36
|
+
// ex:alice a prov:Person;
|
|
37
|
+
// rdfs:label "Alice";
|
|
38
|
+
// ex:firstName "Alice";
|
|
39
|
+
// ex:lastName "Smith".
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
## π Documentation Hub
|
|
43
|
+
|
|
44
|
+
- **π [Documentation](./docs/index.md)** - Complete documentation with guides and references
|
|
45
|
+
- **π― [Examples](./examples/index.md)** - Real-world MD-LD examples and use cases
|
|
46
|
+
- **π [Specification](./spec/index.md)** - Formal specification and test suite
|
|
47
|
+
|
|
48
|
+
## β¨ Core Features
|
|
49
|
+
|
|
50
|
+
- **π Prefix folding** - Build hierarchical namespaces with lightweight IRI authoring
|
|
51
|
+
- **π Subject declarations** - `{=IRI}` and `{=#fragment}` for context setting
|
|
52
|
+
- **π― Object IRIs** - `{+IRI}` and `{+#fragment}` for temporary object declarations
|
|
53
|
+
- **π Three predicate forms** - `p` (SβL), `?p` (SβO), `!p` (OβS)
|
|
54
|
+
- **π·οΈ Type declarations** - `.Class` for rdf:type triples
|
|
55
|
+
- **π
Datatypes & language** - `^^xsd:date` and `@en` support
|
|
56
|
+
- **π§© Fragments** - Document structuring with `{=#fragment}`
|
|
57
|
+
- **β‘ Polarity system** - Sophisticated diff authoring with `+` and `-` prefixes
|
|
58
|
+
- **π Origin tracking** - Complete provenance with lean quad-to-source mapping
|
|
59
|
+
- **π― Elevated statements** - Automatic rdf:Statement pattern detection for "golden" graph extraction
|
|
60
|
+
|
|
61
|
+
## π What is MD-LD?
|
|
62
|
+
|
|
63
|
+
MD-LD allows you to author RDF graphs directly in Markdown using explicit `{...}` annotations:
|
|
64
|
+
|
|
65
|
+
## β‘ Performance & Architecture
|
|
66
|
+
|
|
67
|
+
MD-LD v0.10.0 features a **character-based tokenization system** for optimal performance:
|
|
68
|
+
|
|
69
|
+
- **20-28% faster parsing** than regex-based approaches
|
|
70
|
+
- **Memory-efficient** with ~640 bytes per quad retained
|
|
71
|
+
- **Streaming-friendly** with O(n) linear time complexity
|
|
72
|
+
- **Character-based detection** replaces complex regex patterns
|
|
73
|
+
- **Unified tokenizer architecture** in `src/tokenizers.js`
|
|
74
|
+
|
|
75
|
+
### Tokenizer Architecture
|
|
76
|
+
|
|
77
|
+
The parser uses specialized character-based tokenizers:
|
|
78
|
+
|
|
79
|
+
```javascript
|
|
80
|
+
// Block-level tokenizers
|
|
81
|
+
detectFence() // ```code blocks
|
|
82
|
+
detectPrefix() // [prefix] <iri>
|
|
83
|
+
detectHeading() // # Headings
|
|
84
|
+
detectList() // - List items
|
|
85
|
+
detectBlockquote() // > Blockquotes
|
|
86
|
+
detectStandaloneSubject() // {=subject}
|
|
87
|
+
|
|
88
|
+
// Inline carrier scanner
|
|
89
|
+
scanInlineCarriers() // [text], **bold**, `code`, <URL>
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
This design provides:
|
|
93
|
+
- **Better maintainability** - Easier to debug and extend
|
|
94
|
+
- **Improved error handling** - More precise edge case detection
|
|
95
|
+
- **Cleaner code structure** - No complex regex patterns
|
|
96
|
+
- **Full backward compatibility** - All 127 tests passing
|
|
97
|
+
|
|
98
|
+
```markdown
|
|
99
|
+
[my] <tag:alice@example.com,2026:>
|
|
100
|
+
# 2024-07-18 {=my:journal-2024-07-18 .my:Event my:date ^^xsd:date}
|
|
101
|
+
## A good day {label}
|
|
102
|
+
Mood: [Happy] {my:mood}
|
|
103
|
+
Energy level: [8] {my:energyLevel ^^xsd:integer}
|
|
104
|
+
Met [Sam] {+my:sam .my:Person ?my:attendee} on my regular walk at [Central Park] {+my:central-park ?my:location .my:Place label @en} and talked about [Sunny] {my:weather} weather.
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
Generates valid RDF triples with complete provenance tracking.
|
|
108
|
+
|
|
109
|
+
## π¦ Installation
|
|
110
|
+
|
|
111
|
+
### Node.js
|
|
112
|
+
|
|
113
|
+
```bash
|
|
114
|
+
pnpm install mdld-parse
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
```javascript
|
|
118
|
+
import { parse } from 'mdld-parse';
|
|
119
|
+
|
|
120
|
+
const markdown = `# Document {=ex:doc .Article}
|
|
121
|
+
[Alice] {author}`;
|
|
122
|
+
|
|
123
|
+
const result = parse({
|
|
124
|
+
text: markdown,
|
|
125
|
+
context: { ex: 'http://example.org/' }
|
|
126
|
+
});
|
|
127
|
+
|
|
128
|
+
console.log(result.quads);
|
|
129
|
+
// RDF/JS quads ready for n3.js, rdflib, etc.
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
### Browser (ES Modules)
|
|
133
|
+
|
|
134
|
+
```html
|
|
135
|
+
<script type="module">
|
|
136
|
+
import { parse } from 'https://cdn.jsdelivr.net/npm/mdld-parse/+esm';
|
|
137
|
+
|
|
138
|
+
const result = parse('# Hello {=ex:hello label}');
|
|
139
|
+
</script>
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
## π§ Semantic Model
|
|
143
|
+
|
|
144
|
+
MD-LD encodes a directed labeled multigraph where three nodes may be in scope:
|
|
145
|
+
|
|
146
|
+
- **S** β current subject (IRI)
|
|
147
|
+
- **O** β object resource (IRI from link/image)
|
|
148
|
+
- **L** β literal value (string + optional datatype/language)
|
|
149
|
+
|
|
150
|
+
### Predicate Routing (Β§8.1)
|
|
151
|
+
|
|
152
|
+
Each predicate form determines the graph edge:
|
|
153
|
+
|
|
154
|
+
| Form | Edge | Example | Meaning |
|
|
155
|
+
|-------|---------|------------------------------|------------------|
|
|
156
|
+
| `p` | S β L | `[Alice] {name}` | literal property |
|
|
157
|
+
| `?p` | S β O | `[NASA] {=ex:nasa ?org}` | object property |
|
|
158
|
+
| `!p` | O β S | `[Parent] {=ex:p !hasPart}` | reverse object |
|
|
159
|
+
|
|
160
|
+
## π Elevated Statements
|
|
161
|
+
|
|
162
|
+
MD-LD automatically detects `rdf:Statement` patterns during parsing and extracts elevated SPO quads for convenient consumption by applications.
|
|
163
|
+
|
|
164
|
+
### Pattern Detection
|
|
165
|
+
|
|
166
|
+
When the parser encounters a complete `rdf:Statement` pattern with `rdf:subject`, `rdf:predicate`, and `rdf:object`, it automatically adds the corresponding SPO quad to the `statements` array:
|
|
167
|
+
|
|
168
|
+
```markdown
|
|
169
|
+
[ex] <http://example.org/>
|
|
170
|
+
|
|
171
|
+
## Elevated statement {=ex:stmt1 .rdf:Statement}
|
|
172
|
+
**Alice** {+ex:alice ?rdf:subject} *knows* {+ex:knows ?rdf:predicate} **Bob** {+ex:bob ?rdf:object}
|
|
173
|
+
|
|
174
|
+
Direct statement:**Alice** {=ex:alice} knows **Bob** {?ex:knows +ex:bob}
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
## π¨ Syntax Quick Reference
|
|
178
|
+
|
|
179
|
+
### Subject Declaration
|
|
180
|
+
Set current subject (emits no quads):
|
|
181
|
+
```markdown
|
|
182
|
+
## Apollo 11 {=ex:apollo11}
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
### Fragment Syntax
|
|
186
|
+
Create fragment IRIs relative to current subject:
|
|
187
|
+
```markdown
|
|
188
|
+
# Document {=ex:document}
|
|
189
|
+
{=#summary}
|
|
190
|
+
[Content] {label}
|
|
191
|
+
```
|
|
192
|
+
Fragments replace any existing fragment and require a current subject.
|
|
193
|
+
|
|
194
|
+
### Type Declaration
|
|
195
|
+
Emit `rdf:type` triple:
|
|
196
|
+
```markdown
|
|
197
|
+
## Apollo 11 {=ex:apollo11 .ex:SpaceMission .ex:Event}
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
### Literal Properties
|
|
201
|
+
Inline value carriers emit literal properties:
|
|
202
|
+
```markdown
|
|
203
|
+
# Mission {=ex:apollo11}
|
|
204
|
+
[Neil Armstrong] {ex:commander}
|
|
205
|
+
[1969] {ex:year ^^xsd:gYear}
|
|
206
|
+
[Historic mission] {ex:description @en}
|
|
207
|
+
```
|
|
208
|
+
|
|
209
|
+
### Object Properties
|
|
210
|
+
Links create relationships (use `?` prefix):
|
|
211
|
+
```markdown
|
|
212
|
+
# Mission {=ex:apollo11}
|
|
213
|
+
[NASA] {=ex:nasa ?ex:organizer}
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
### Resource Declaration
|
|
217
|
+
Declare resources inline with `{=iri}`:
|
|
218
|
+
```markdown
|
|
219
|
+
# Mission {=ex:apollo11}
|
|
220
|
+
[Neil Armstrong] {=ex:armstrong ?ex:commander .prov:Person}
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
## π§ API Reference
|
|
224
|
+
|
|
225
|
+
### `parse({ text, context, dataFactory, graph })`
|
|
226
|
+
|
|
227
|
+
Parse MD-LD markdown and return RDF quads with lean origin tracking.
|
|
228
|
+
|
|
229
|
+
**Parameters (named object):**
|
|
230
|
+
- `text` (string, required) β MD-LD formatted text
|
|
231
|
+
- `context` (object, optional) β Prefix mappings (default: `{ '@vocab': 'http://www.w3.org/2000/01/rdf-schema#', rdf, rdfs, xsd, sh, prov }`)
|
|
232
|
+
- `dataFactory` (object, optional) β Custom RDF/JS DataFactory
|
|
233
|
+
- `graph` (string, optional) β Named graph IRI
|
|
234
|
+
|
|
235
|
+
**Returns:** `{ quads, remove, statements, origin, context, primarySubject, md }`
|
|
236
|
+
|
|
237
|
+
> **Legacy:** `parse(text, options)` still works for backward compatibility
|
|
238
|
+
|
|
239
|
+
- `quads` β Array of RDF/JS Quads (final resolved graph state)
|
|
240
|
+
- `remove` β Array of RDF/JS Quads (external retractions targeting prior state)
|
|
241
|
+
- `statements` β Array of elevated RDF/JS Quads extracted from rdf:Statement patterns
|
|
242
|
+
- `origin` β Lean origin tracking object with quadIndex for UI navigation
|
|
243
|
+
- `context` β Final context used (includes prefixes)
|
|
244
|
+
- `primarySubject` β String IRI or null (first non-fragment subject declaration)
|
|
245
|
+
- `md` β Clean Markdown with all MD-LD annotations stripped (round-trip safe)
|
|
246
|
+
|
|
247
|
+
### `merge(docs, options)`
|
|
248
|
+
|
|
249
|
+
Merge multiple MDLD documents with diff polarity resolution.
|
|
250
|
+
|
|
251
|
+
**Parameters:**
|
|
252
|
+
- `docs` (array) β Array of markdown strings or ParseResult objects
|
|
253
|
+
- `options` (object, optional):
|
|
254
|
+
- `context` (object) β Prefix mappings (merged with DEFAULT_CONTEXT)
|
|
255
|
+
|
|
256
|
+
**Returns:** `{ quads, remove, origin, context, primarySubjects }`
|
|
257
|
+
|
|
258
|
+
- `quads` β Array of RDF/JS Quads (final resolved graph state)
|
|
259
|
+
- `remove` β Array of RDF/JS Quads (external retractions targeting prior state)
|
|
260
|
+
- `origin` β Merge origin tracking with document index and polarity
|
|
261
|
+
- `context` β Final merged context
|
|
262
|
+
- `primarySubjects` β Array of string IRIs (primary subjects from each document, in merge order)
|
|
263
|
+
|
|
264
|
+
### `generate({ quads, context, primarySubject })`
|
|
265
|
+
|
|
266
|
+
Generate deterministic MDLD from RDF quads with visual styling.
|
|
267
|
+
|
|
268
|
+
**Parameters (named object):**
|
|
269
|
+
- `quads` (array, required) β Array of RDF/JS Quads to convert
|
|
270
|
+
- `context` (object, optional) β Prefix mappings (default: `{}`)
|
|
271
|
+
- `primarySubject` (string, optional) β String IRI to place first in output (ensures round-trip safety). If not provided, falls back to the first subject from quads.
|
|
272
|
+
|
|
273
|
+
**Returns:** `{ text, context }`
|
|
274
|
+
|
|
275
|
+
**Features:**
|
|
276
|
+
- Visual carrier styles based on datatype (code spans for numbers, bold booleans, etc.)
|
|
277
|
+
- Label-in-heading: Uses `rdfs:label` in subject headings when available
|
|
278
|
+
- Multiple labels: First label in heading, additional labels rendered as literals
|
|
279
|
+
- Round-trip safe: All data preserved through parse β generate β parse
|
|
280
|
+
- Composable: `generate(parse(text))` extracts semantics; `parse(generate({quads}))` normalizes quads
|
|
281
|
+
|
|
282
|
+
### `generateNode({ quads, focusIRI, context })`
|
|
283
|
+
|
|
284
|
+
Generate node-centric MDLD showing all quads where a specific IRI appears in any position.
|
|
285
|
+
|
|
286
|
+
**Parameters (named object):**
|
|
287
|
+
- `quads` (array, required) β Array of RDF/JS Quads to search
|
|
288
|
+
- `focusIRI` (string, required) β The IRI to center the view on
|
|
289
|
+
- `context` (object, optional) β Prefix mappings (default: `{}`)
|
|
290
|
+
|
|
291
|
+
**Returns:** `{ text, context }`
|
|
292
|
+
|
|
293
|
+
**Behavior (Safety-First):**
|
|
294
|
+
- If `focusIRI` is null/undefined: Returns empty text
|
|
295
|
+
- If `focusIRI` not in graph: Returns empty text (never falls back to all data)
|
|
296
|
+
- If `quads` is empty: Returns empty text
|
|
297
|
+
|
|
298
|
+
**Safety rationale:** Prevents accidental rendering of entire databases on misspelled IRIsβcritical for production use with LLM cost per token. Explicit emptiness signals "not found" to the caller.
|
|
299
|
+
|
|
300
|
+
**Use case:** Perfect for exploring a specific node and all its relationshipsβwhere it appears as subject, object, predicate, type, or datatype. Creates an exhaustive view of everything related to the focus IRI. Ideal for node-centric knowledge graph explorers.
|
|
301
|
+
|
|
302
|
+
### Composition Patterns
|
|
303
|
+
|
|
304
|
+
With the unified named parameter API, `parse()` and `generate()` compose seamlessly through object spreading:
|
|
305
|
+
|
|
306
|
+
```javascript
|
|
307
|
+
import { parse, generate, generateNode } from 'mdld-parse';
|
|
308
|
+
|
|
309
|
+
// Pattern 1: parse β generate (semantic extraction)
|
|
310
|
+
const canonical = generate({ ...parse({ text, context }) });
|
|
311
|
+
// text β quads β canonical MDLD (deterministic, visual styling applied)
|
|
312
|
+
|
|
313
|
+
// Pattern 2: generate β parse (normalize external RDF)
|
|
314
|
+
const normalized = parse({ ...generate({ quads: externalQuads, context }) });
|
|
315
|
+
// external quads β MDLD β validated quads (DataFactory-safe, no blank nodes)
|
|
316
|
+
|
|
317
|
+
// Pattern 3: parse β generateNode (node-centric exploration)
|
|
318
|
+
const nodeView = generateNode({ ...parse({ text }), focusIRI: 'http://example.org/alice' });
|
|
319
|
+
// full graph β isolated node view (safe: returns empty if IRI not found)
|
|
320
|
+
```
|
|
321
|
+
|
|
322
|
+
**Why this works:**
|
|
323
|
+
- `parse()` returns `{ quads, context, primarySubject, md, ... }`
|
|
324
|
+
- `generate()` accepts `{ quads, context, primarySubject }`
|
|
325
|
+
- `generateNode()` accepts `{ quads, context, focusIRI }` (with focusIRI override)
|
|
326
|
+
- Perfect shape alignment enables elegant `{ ...spread }` composition
|
|
327
|
+
|
|
328
|
+
### The `md` Field β Clean Markdown Extraction
|
|
329
|
+
|
|
330
|
+
Every `parse()` result includes a `md` field containing the original Markdown with all MD-LD annotations stripped:
|
|
331
|
+
|
|
332
|
+
```javascript
|
|
333
|
+
const result = parse({
|
|
334
|
+
text: `# Document {=ex:doc .Article}\n[Content] {ex:content}`,
|
|
335
|
+
context: { ex: 'http://example.org/' }
|
|
336
|
+
});
|
|
337
|
+
|
|
338
|
+
console.log(result.md);
|
|
339
|
+
// # Document\nContent
|
|
340
|
+
|
|
341
|
+
// Round-trip safety: re-parsing clean MD produces zero quads
|
|
342
|
+
const reparsed = parse({ text: result.md });
|
|
343
|
+
console.log(reparsed.quads.length); // 0
|
|
344
|
+
```
|
|
345
|
+
|
|
346
|
+
**Behavior:**
|
|
347
|
+
- Valid MD-LD annotations (`{=...}`, `{+...}`, `{...}`) are completely removed
|
|
348
|
+
- Content from value carriers (`[text]`, `**bold**`, `` `code` ``) is preserved
|
|
349
|
+
- Invalid syntax (annotations not at end-of-line) is preserved as visible markers
|
|
350
|
+
- Headings, lists, blockquotes, code blocks maintain their structure
|
|
351
|
+
- Prefix declarations at start of line are stripped
|
|
352
|
+
- Standalone subject declarations (`{=ex:subject}`) are stripped
|
|
353
|
+
|
|
354
|
+
**Use cases:**
|
|
355
|
+
- **Content extraction** β Get readable Markdown without semantic markup
|
|
356
|
+
- **Syntax validation** β Remaining `{...}` patterns indicate invalid MD-LD syntax
|
|
357
|
+
- **Round-trip testing** β `parse(md).md` should parse to zero quads
|
|
358
|
+
- **Preview generation** β Show clean document before publishing
|
|
359
|
+
|
|
360
|
+
### `locate(quad, origin)`
|
|
361
|
+
|
|
362
|
+
Locate the origin entry for a quad using the lean origin system.
|
|
363
|
+
|
|
364
|
+
**Parameters:**
|
|
365
|
+
- `quad` (object) β The quad to locate (subject, predicate, object)
|
|
366
|
+
- `origin` (object) β Origin object containing quadIndex
|
|
367
|
+
|
|
368
|
+
**Returns:** `{ blockId, range, carrierType, subject, predicate, context, value, polarity }` or `null`
|
|
369
|
+
|
|
370
|
+
### `render(quads, options)`
|
|
371
|
+
|
|
372
|
+
Render RDF quads as HTML+RDFa for web display.
|
|
373
|
+
|
|
374
|
+
**Parameters:**
|
|
375
|
+
- `quads` (array) β Array of RDF/JS Quads to render
|
|
376
|
+
- `options` (object, optional):
|
|
377
|
+
- `context` (object) β Prefix mappings for CURIE shortening
|
|
378
|
+
- `baseIRI` (string) β Base IRI for resolving relative references
|
|
379
|
+
|
|
380
|
+
**Returns:** `{ html, context }`
|
|
381
|
+
|
|
382
|
+
### Utility Functions
|
|
383
|
+
|
|
384
|
+
```javascript
|
|
385
|
+
import {
|
|
386
|
+
DEFAULT_CONTEXT, // Default prefix mappings
|
|
387
|
+
DataFactory, // RDF/JS DataFactory instance
|
|
388
|
+
hash, // String hashing function
|
|
389
|
+
expandIRI, // IRI expansion with context
|
|
390
|
+
shortenIRI, // IRI shortening with context
|
|
391
|
+
parseSemanticBlock // Parse semantic block syntax
|
|
392
|
+
} from 'mdld-parse';
|
|
393
|
+
```
|
|
394
|
+
|
|
395
|
+
## ποΈ Architecture
|
|
396
|
+
|
|
397
|
+
### Design Principles
|
|
398
|
+
- **Zero dependencies** β Pure JavaScript, ~15KB minified
|
|
399
|
+
- **Streaming-first** β Single-pass parsing, O(n) complexity
|
|
400
|
+
- **Standards-compliant** β RDF/JS data model
|
|
401
|
+
- **Origin tracking** β Full round-trip support with source maps
|
|
402
|
+
- **Explicit semantics** β No guessing, inference, or heuristics
|
|
403
|
+
|
|
404
|
+
### RDF/JS Compatibility
|
|
405
|
+
Quads are compatible with:
|
|
406
|
+
- [`n3.js`](https://github.com/rdfjs/N3.js) β Turtle/N-Triples serialization
|
|
407
|
+
- [`rdflib.js`](https://github.com/linkeddata/rdflib.js) β RDF store and reasoning
|
|
408
|
+
- [`sparqljs`](https://github.com/RubenVerborgh/SPARQL.js) β SPARQL queries
|
|
409
|
+
- [`rdf-ext`](https://github.com/rdf-ext/rdf-ext) β Extended RDF utilities
|
|
410
|
+
|
|
411
|
+
## π§ͺ Testing
|
|
412
|
+
|
|
413
|
+
The parser includes comprehensive tests covering all spec requirements:
|
|
414
|
+
|
|
415
|
+
```bash
|
|
416
|
+
pnpm test
|
|
417
|
+
```
|
|
418
|
+
|
|
419
|
+
Tests validate:
|
|
420
|
+
- Subject declaration and context
|
|
421
|
+
- All predicate forms (p, ?p, !p)
|
|
422
|
+
- Datatypes and language tags
|
|
423
|
+
- Explicit list item annotations
|
|
424
|
+
- Code blocks and blockquotes
|
|
425
|
+
- Round-trip serialization
|