mdld-parse 0.9.9 → 1.0.1
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/README.md +263 -326
- package/dist/index.js +1860 -1337
- package/package.json +4 -4
- package/dist/.nojekyll +0 -0
- package/dist/CNAME +0 -1
- package/dist/README.md +0 -500
- package/dist/docs/API.md +0 -435
- package/dist/docs/Architecture.md +0 -190
- package/dist/docs/Guide.md +0 -816
- package/dist/docs/LLM-MDLD-Inducer.md +0 -550
- package/dist/docs/LiterateRDF.md +0 -472
- package/dist/docs/Parser.md +0 -720
- package/dist/docs/Performance.md +0 -238
- package/dist/docs/Spec-render.md +0 -1439
- package/dist/docs/Subject.md +0 -180
- package/dist/docs/Syntax.md +0 -463
- package/dist/docs/TodoList.md +0 -215
- package/dist/docs/Use-Cases.md +0 -354
- package/dist/docs/guide-m.md +0 -56
- package/dist/docs/index.html +0 -108
- package/dist/docs/index.md +0 -56
- package/dist/docs/one-page.md +0 -322
- package/dist/docs/origin.md +0 -460
- package/dist/docs/polarity.md +0 -586
- package/dist/docs/primary-subject.md +0 -326
- package/dist/docs/statements.md +0 -226
- package/dist/docs/tokenization-performance-report.md +0 -164
- package/dist/examples/Cookbook.md +0 -32
- package/dist/examples/Status-SHACL.md +0 -31
- package/dist/examples/demo/index.md +0 -35
- package/dist/examples/demo/journal.md +0 -58
- package/dist/examples/demo/minimal.md +0 -23
- package/dist/examples/demo/project.md +0 -84
- package/dist/examples/demo/prov.md +0 -107
- package/dist/examples/demo/rdf.md +0 -69
- package/dist/examples/demo/recipe.md +0 -50
- package/dist/examples/demo/research.md +0 -84
- package/dist/examples/demo/shacl.md +0 -161
- package/dist/examples/demo/space-mission.md +0 -58
- package/dist/examples/demo/tasks.md +0 -175
- package/dist/examples/demo/xsd.md +0 -91
- package/dist/examples/dogfood.md +0 -288
- package/dist/examples/few-shot.md +0 -309
- package/dist/examples/graph/rdf-graph.html +0 -473
- package/dist/examples/graph/rdf_force_graph_web_component.html +0 -506
- package/dist/examples/index.md +0 -45
- package/dist/examples/llm-time-workflow.md +0 -173
- package/dist/examples/statements.md +0 -43
- package/dist/examples/workflow.md +0 -150
- package/dist/index.html +0 -3049
- package/dist/logo.svg +0 -7
- package/dist/spec/Spec-compact.md +0 -368
- package/dist/spec/Spec-ultra.md +0 -232
- package/dist/spec/Spec.md +0 -1116
- package/dist/spec/index.md +0 -46
package/package.json
CHANGED
|
@@ -1,20 +1,20 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "mdld-parse",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "1.0.1",
|
|
4
4
|
"description": "A standards-compliant parser for **MD-LD (Markdown-Linked Data)** — a human-friendly RDF authoring format that extends Markdown with semantic annotations.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"packageManager": "pnpm@10.33.4+sha512.1c67b3b359b2d408119ba1ed289f34b8fc3c6873412bec6fd264fbdc82489e510fcbecb9ce9d22dae7f3b76269d8441046014bdca53b9979cd7a561ad631b800",
|
|
7
|
-
"main": "index.js",
|
|
7
|
+
"main": "./dist/index.js",
|
|
8
8
|
"exports": {
|
|
9
9
|
".": "./dist/index.js"
|
|
10
10
|
},
|
|
11
11
|
"files": [
|
|
12
|
-
"dist"
|
|
12
|
+
"dist/index.js"
|
|
13
13
|
],
|
|
14
14
|
"scripts": {
|
|
15
15
|
"test": "node tests/index.js",
|
|
16
16
|
"dev": "vite dev",
|
|
17
|
-
"build": "vite build && vite build --config vite.config.lib.js && cp -r docs/ dist/docs/ && cp -r examples/ dist/examples/ && cp -r spec/ dist/spec/ && cp -r README.md dist/README.md"
|
|
17
|
+
"build": "vite build && vite build --config vite.config.lib.js && cp -r docs/ dist/docs/ && cp -r examples/ dist/examples/ && cp -r grammar/ dist/grammar/ && cp -r ontologies/ dist/ontologies/ && cp -r spec/ dist/spec/ && cp -r README.md dist/README.md"
|
|
18
18
|
},
|
|
19
19
|
"keywords": [
|
|
20
20
|
"mdld",
|
package/dist/.nojekyll
DELETED
|
File without changes
|
package/dist/CNAME
DELETED
|
@@ -1 +0,0 @@
|
|
|
1
|
-
mdld.js.org
|
package/dist/README.md
DELETED
|
@@ -1,500 +0,0 @@
|
|
|
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
|
-
- **🏷️ Primary metadata** - Structured primary object with subject, type, and label for document identity
|
|
61
|
-
|
|
62
|
-
## 🌟 What is MD-LD?
|
|
63
|
-
|
|
64
|
-
MD-LD allows you to author RDF graphs directly in Markdown using explicit `{...}` annotations:
|
|
65
|
-
|
|
66
|
-
```markdown
|
|
67
|
-
[my] <tag:alice@example.com,2026:>
|
|
68
|
-
# 2024-07-18 {=my:journal-2024-07-18 .my:Event my:date ^^xsd:date}
|
|
69
|
-
## A good day {label}
|
|
70
|
-
Mood: [Happy] {my:mood}
|
|
71
|
-
Energy level: [8] {my:energyLevel ^^xsd:integer}
|
|
72
|
-
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.
|
|
73
|
-
```
|
|
74
|
-
|
|
75
|
-
Generates valid RDF triples with complete provenance tracking.
|
|
76
|
-
|
|
77
|
-
## 📦 Installation
|
|
78
|
-
|
|
79
|
-
### Node.js
|
|
80
|
-
|
|
81
|
-
```bash
|
|
82
|
-
pnpm install mdld-parse
|
|
83
|
-
```
|
|
84
|
-
|
|
85
|
-
```javascript
|
|
86
|
-
import { parse } from 'mdld-parse';
|
|
87
|
-
|
|
88
|
-
const markdown = `[ex] <tag:alice@example.org,2026:>
|
|
89
|
-
|
|
90
|
-
# Demo document {=ex:example/doc .prov:Entity label}
|
|
91
|
-
|
|
92
|
-
> A demo document for MD-LD {comment}
|
|
93
|
-
[Alice] {+ex:alice ?ex:author .prov:Person label}
|
|
94
|
-
`;
|
|
95
|
-
|
|
96
|
-
const result = parse({ text: markdown });
|
|
97
|
-
|
|
98
|
-
console.log(result.quads);
|
|
99
|
-
// RDF/JS quads ready for n3.js, rdflib, etc.
|
|
100
|
-
```
|
|
101
|
-
|
|
102
|
-
### Browser (ES Modules)
|
|
103
|
-
|
|
104
|
-
```html
|
|
105
|
-
<script type="module">
|
|
106
|
-
import { parse } from 'https://cdn.jsdelivr.net/npm/mdld-parse/+esm';
|
|
107
|
-
|
|
108
|
-
const result = parse('[ex] <tag:alice@example.org,2026:>\n\n# Hello {=ex:hello label}');
|
|
109
|
-
</script>
|
|
110
|
-
```
|
|
111
|
-
|
|
112
|
-
## 🧠 Semantic Model
|
|
113
|
-
|
|
114
|
-
MD-LD encodes a directed labeled multigraph where three nodes may be in scope:
|
|
115
|
-
|
|
116
|
-
- **S** — current subject (IRI)
|
|
117
|
-
- **O** — object resource (IRI from link/image)
|
|
118
|
-
- **L** — literal value (string + optional datatype/language)
|
|
119
|
-
|
|
120
|
-
### Predicate Routing (§8.1)
|
|
121
|
-
|
|
122
|
-
Each predicate form determines the graph edge:
|
|
123
|
-
|
|
124
|
-
| Form | Edge | Example | Meaning |
|
|
125
|
-
|-------|---------|------------------------------|------------------|
|
|
126
|
-
| `p` | S → L | `[Alice] {label}` | literal property |
|
|
127
|
-
| `?p` | S → O | `[NASA] {=ex:nasa ?org}` | object property |
|
|
128
|
-
| `!p` | O → S | `[Parent] {=ex:p !hasPart}` | reverse object |
|
|
129
|
-
|
|
130
|
-
## 📍 Elevated Statements
|
|
131
|
-
|
|
132
|
-
MD-LD automatically detects `rdf:Statement` patterns during parsing and extracts elevated SPO quads for convenient consumption by applications.
|
|
133
|
-
|
|
134
|
-
### Pattern Detection
|
|
135
|
-
|
|
136
|
-
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:
|
|
137
|
-
|
|
138
|
-
```markdown
|
|
139
|
-
[ex] <http://example.org/>
|
|
140
|
-
|
|
141
|
-
## Elevated statement {=ex:stmt1 .rdf:Statement}
|
|
142
|
-
**Alice** {+ex:alice ?rdf:subject} *knows* {+ex:knows ?rdf:predicate} **Bob** {+ex:bob ?rdf:object}
|
|
143
|
-
|
|
144
|
-
Direct statement:**Alice** {=ex:alice} knows **Bob** {?ex:knows +ex:bob}
|
|
145
|
-
```
|
|
146
|
-
|
|
147
|
-
## 🎨 Syntax Quick Reference
|
|
148
|
-
|
|
149
|
-
### Subject Declaration
|
|
150
|
-
Set current subject (emits no quads):
|
|
151
|
-
```markdown
|
|
152
|
-
## Apollo 11 {=ex:apollo11}
|
|
153
|
-
```
|
|
154
|
-
|
|
155
|
-
### Fragment Syntax
|
|
156
|
-
Create fragment IRIs relative to current subject:
|
|
157
|
-
```markdown
|
|
158
|
-
# Document {=ex:document}
|
|
159
|
-
{=#summary}
|
|
160
|
-
[Content] {label}
|
|
161
|
-
```
|
|
162
|
-
Fragments replace any existing fragment and require a current subject.
|
|
163
|
-
|
|
164
|
-
### Type Declaration
|
|
165
|
-
Emit `rdf:type` triple:
|
|
166
|
-
```markdown
|
|
167
|
-
## Apollo 11 {=ex:apollo11 .ex:SpaceMission .ex:Event}
|
|
168
|
-
```
|
|
169
|
-
|
|
170
|
-
### Literal Properties
|
|
171
|
-
Inline value carriers emit literal properties:
|
|
172
|
-
```markdown
|
|
173
|
-
# Mission {=ex:apollo11}
|
|
174
|
-
[Neil Armstrong] {ex:commander}
|
|
175
|
-
[1969] {ex:year ^^xsd:gYear}
|
|
176
|
-
[Historic mission] {ex:description @en}
|
|
177
|
-
```
|
|
178
|
-
|
|
179
|
-
### Object Properties
|
|
180
|
-
Links create relationships (use `?` prefix):
|
|
181
|
-
```markdown
|
|
182
|
-
# Mission {=ex:apollo11}
|
|
183
|
-
[NASA] {=ex:nasa ?ex:organizer}
|
|
184
|
-
```
|
|
185
|
-
|
|
186
|
-
### Resource Declaration
|
|
187
|
-
Declare resources inline with `{=iri}`:
|
|
188
|
-
```markdown
|
|
189
|
-
# Mission {=ex:apollo11}
|
|
190
|
-
[Neil Armstrong] {=ex:armstrong ?ex:commander .prov:Person}
|
|
191
|
-
```
|
|
192
|
-
|
|
193
|
-
## 🔧 API Reference
|
|
194
|
-
|
|
195
|
-
### `parse({ text, context, dataFactory, graph })`
|
|
196
|
-
|
|
197
|
-
Parse MD-LD markdown and return RDF quads with lean origin tracking.
|
|
198
|
-
|
|
199
|
-
**Parameters (named object):**
|
|
200
|
-
- `text` (string, required) — MD-LD formatted text
|
|
201
|
-
- `context` (object, optional) — Prefix mappings (default: `{ '@vocab': 'http://www.w3.org/2000/01/rdf-schema#', rdf, rdfs, xsd, sh, prov }`)
|
|
202
|
-
- `dataFactory` (object, optional) — Custom RDF/JS DataFactory
|
|
203
|
-
- `graph` (string, optional) — Named graph IRI
|
|
204
|
-
|
|
205
|
-
**Returns:** `{ quads, remove, statements, origin, context, primarySubject, primary, md }`
|
|
206
|
-
|
|
207
|
-
- `quads` — Array of RDF/JS Quads (final resolved graph state)
|
|
208
|
-
- `remove` — Array of RDF/JS Quads (external retractions targeting prior state)
|
|
209
|
-
- `statements` — Array of elevated RDF/JS Quads extracted from rdf:Statement patterns
|
|
210
|
-
- `origin` — Lean origin tracking object with quadIndex for UI navigation
|
|
211
|
-
- `context` — Final context used (includes prefixes)
|
|
212
|
-
- `primarySubject` — String IRI or null (canonical append identity)
|
|
213
|
-
- `primary` — Object containing primary metadata (semantic surface descriptor)
|
|
214
|
-
- `md` — Clean Markdown with all MD-LD annotations stripped (round-trip safe)
|
|
215
|
-
|
|
216
|
-
**Dual-Layer Architecture:**
|
|
217
|
-
|
|
218
|
-
| Layer | Field | Purpose | Use Cases |
|
|
219
|
-
|-------|-------|---------|-----------|
|
|
220
|
-
| **Canonical Identity** | `primarySubject` | Append routing, storage, synchronization | `append()`, file placement, authority validation |
|
|
221
|
-
| **Semantic Surface** | `primary` | UI, indexing, navigation, agent orientation | Dashboards, search, previews, timelines |
|
|
222
|
-
|
|
223
|
-
**Primary Object Structure:**
|
|
224
|
-
```javascript
|
|
225
|
-
primary: {
|
|
226
|
-
subject: string | null, // First non-fragment subject declaration
|
|
227
|
-
type: string | null, // First rdf:type declaration
|
|
228
|
-
label: string | null // First rdfs:label literal
|
|
229
|
-
}
|
|
230
|
-
```
|
|
231
|
-
|
|
232
|
-
### `merge(docs, options)`
|
|
233
|
-
|
|
234
|
-
Merge multiple MDLD documents with diff polarity resolution.
|
|
235
|
-
|
|
236
|
-
**Parameters:**
|
|
237
|
-
- `docs` (array) — Array of markdown strings or ParseResult objects
|
|
238
|
-
- `options` (object, optional):
|
|
239
|
-
- `context` (object) — Prefix mappings (merged with DEFAULT_CONTEXT)
|
|
240
|
-
|
|
241
|
-
**Returns:** `{ quads, remove, origin, context, primarySubjects, primary }`
|
|
242
|
-
|
|
243
|
-
- `quads` — Array of RDF/JS Quads (final resolved graph state)
|
|
244
|
-
- `remove` — Array of RDF/JS Quads (external retractions targeting prior state)
|
|
245
|
-
- `origin` — Merge origin with document tracking
|
|
246
|
-
- `context` — Final context used (includes prefixes)
|
|
247
|
-
- `primarySubjects` — Array of string IRIs (canonical append identities, ordered by merge)
|
|
248
|
-
- `primary` — Array of primary objects (semantic surface descriptors, ordered by merge)
|
|
249
|
-
|
|
250
|
-
**Dual-Layer Architecture:**
|
|
251
|
-
|
|
252
|
-
| Layer | Field | Purpose | Use Cases |
|
|
253
|
-
|-------|-------|---------|-----------|
|
|
254
|
-
| **Canonical Identity** | `primarySubjects` | Append routing, storage, synchronization | Multi-document append, file organization |
|
|
255
|
-
| **Semantic Surface** | `primary` | UI, indexing, navigation, agent orientation | Vault indexing, document discovery, search |
|
|
256
|
-
|
|
257
|
-
**Primary Object Array Structure:**
|
|
258
|
-
```javascript
|
|
259
|
-
primary: [
|
|
260
|
-
{
|
|
261
|
-
subject: string | null, // First non-fragment subject declaration
|
|
262
|
-
type: string | null, // First rdf:type declaration
|
|
263
|
-
label: string | null // First rdfs:label literal
|
|
264
|
-
},
|
|
265
|
-
// ... one object per document
|
|
266
|
-
]
|
|
267
|
-
```
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
### `generate({ quads, context, primarySubject })`
|
|
271
|
-
|
|
272
|
-
Generate deterministic MDLD from RDF quads with visual styling.
|
|
273
|
-
|
|
274
|
-
**Parameters (named object):**
|
|
275
|
-
- `quads` (array, required) — Array of RDF/JS Quads to convert
|
|
276
|
-
- `context` (object, optional) — Prefix mappings (default: `{}`)
|
|
277
|
-
- `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.
|
|
278
|
-
|
|
279
|
-
**Returns:** `{ text, context }`
|
|
280
|
-
|
|
281
|
-
**Features:**
|
|
282
|
-
- Visual carrier styles based on datatype (code spans for numbers, bold booleans, etc.)
|
|
283
|
-
- Label-in-heading: Uses `rdfs:label` in subject headings when available
|
|
284
|
-
- Multiple labels: First label in heading, additional labels rendered as literals
|
|
285
|
-
- Round-trip safe: All data preserved through parse → generate → parse
|
|
286
|
-
- Composable: `generate(parse(text))` extracts semantics; `parse(generate({quads}))` normalizes quads
|
|
287
|
-
|
|
288
|
-
### `generateNode({ quads, focusIRI, context })`
|
|
289
|
-
|
|
290
|
-
Generate node-centric MDLD showing all quads where a specific IRI appears in any position.
|
|
291
|
-
|
|
292
|
-
**Parameters (named object):**
|
|
293
|
-
- `quads` (array, required) — Array of RDF/JS Quads to search
|
|
294
|
-
- `focusIRI` (string, required) — The IRI to center the view on
|
|
295
|
-
- `context` (object, optional) — Prefix mappings (default: `{}`)
|
|
296
|
-
|
|
297
|
-
**Returns:** `{ text, context }`
|
|
298
|
-
|
|
299
|
-
**Behavior (Safety-First):**
|
|
300
|
-
- If `focusIRI` is null/undefined: Returns empty text
|
|
301
|
-
- If `focusIRI` not in graph: Returns empty text (never falls back to all data)
|
|
302
|
-
- If `quads` is empty: Returns empty text
|
|
303
|
-
|
|
304
|
-
**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.
|
|
305
|
-
|
|
306
|
-
**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.
|
|
307
|
-
|
|
308
|
-
### `updateValue()` — Update Quad Carrier Text in Source Text
|
|
309
|
-
|
|
310
|
-
Update the carrier text of a literal quad in MDLD text. Only the carrier content is replaced — datatype (`^^xsd:integer`) and language (`@en`) annotations inside the `{…}` block are preserved as-is, since they are part of the annotation, not the carrier.
|
|
311
|
-
|
|
312
|
-
```javascript
|
|
313
|
-
import { parse, updateValue } from 'mdld-parse';
|
|
314
|
-
|
|
315
|
-
const mdld = `[ex] <http://example.org/>
|
|
316
|
-
|
|
317
|
-
# Article {=ex:article .ex:Article}
|
|
318
|
-
|
|
319
|
-
[Alice Smith] {ex:author}`;
|
|
320
|
-
|
|
321
|
-
const result = parse({ text: mdld });
|
|
322
|
-
const authorQuad = result.quads.find(q =>
|
|
323
|
-
q.subject.value === 'http://example.org/article' &&
|
|
324
|
-
q.predicate.value === 'http://example.org/author'
|
|
325
|
-
);
|
|
326
|
-
|
|
327
|
-
const updatedText = updateValue({
|
|
328
|
-
text: mdld,
|
|
329
|
-
quad: authorQuad,
|
|
330
|
-
value: 'Bob Johnson',
|
|
331
|
-
origin: result.origin // optional (auto-parses if not provided)
|
|
332
|
-
});
|
|
333
|
-
|
|
334
|
-
console.log(updatedText);
|
|
335
|
-
// [ex] <http://example.org/>
|
|
336
|
-
//
|
|
337
|
-
// # Article {=ex:article .ex:Article}
|
|
338
|
-
//
|
|
339
|
-
// [Bob Johnson] {ex:author}
|
|
340
|
-
```
|
|
341
|
-
|
|
342
|
-
**Annotation annotations are preserved:**
|
|
343
|
-
```javascript
|
|
344
|
-
// Original: > 25 {ex:age ^^xsd:integer}
|
|
345
|
-
updateValue({ text, quad, value: '30' });
|
|
346
|
-
// Result: > 30 {ex:age ^^xsd:integer} ← datatype preserved
|
|
347
|
-
|
|
348
|
-
// Original: > Hello {ex:greeting @en}
|
|
349
|
-
updateValue({ text, quad, value: 'Good morning' });
|
|
350
|
-
// Result: > Good morning {ex:greeting @en} ← language tag preserved
|
|
351
|
-
```
|
|
352
|
-
|
|
353
|
-
**Parameters:**
|
|
354
|
-
- `text` (string) — The original MDLD text
|
|
355
|
-
- `quad` (object) — The quad to update (subject, predicate, object)
|
|
356
|
-
- `value` (string) — The new carrier text to set
|
|
357
|
-
- `origin` (object, optional) — ParseResult.origin (auto-parses if not provided)
|
|
358
|
-
|
|
359
|
-
**Returns:** Updated MDLD text, or original text if update fails (fail-safe)
|
|
360
|
-
|
|
361
|
-
**How it works:**
|
|
362
|
-
- Uses `locate()` to find the quad's position in the source text
|
|
363
|
-
- Uses `valueRange` to replace only the carrier text (excluding carrier markers like `[`, `]`)
|
|
364
|
-
- Annotation block `{…}` with predicate, datatype, language is untouched
|
|
365
|
-
- Auto-parses if result not provided (convenient but less efficient)
|
|
366
|
-
|
|
367
|
-
**Fail-safe behavior:**
|
|
368
|
-
- Returns original text if quad cannot be located
|
|
369
|
-
- Returns original text if valueRange is not available
|
|
370
|
-
- Never corrupts the source text
|
|
371
|
-
|
|
372
|
-
**Use case:** Perfect for editor applications that need to update literal values while preserving carrier syntax, datatype annotations, and language tags.
|
|
373
|
-
|
|
374
|
-
### Composition Patterns
|
|
375
|
-
|
|
376
|
-
With the unified named parameter API, `parse()` and `generate()` compose seamlessly through object spreading:
|
|
377
|
-
|
|
378
|
-
```javascript
|
|
379
|
-
import { parse, generate, generateNode } from 'mdld-parse';
|
|
380
|
-
|
|
381
|
-
// Pattern 1: parse → generate (semantic extraction)
|
|
382
|
-
const canonical = generate({ ...parse({ text, context }) });
|
|
383
|
-
// text → quads → canonical MDLD (deterministic, visual styling applied)
|
|
384
|
-
|
|
385
|
-
// Pattern 2: generate → parse (normalize external RDF)
|
|
386
|
-
const normalized = parse({ ...generate({ quads: externalQuads, context }) });
|
|
387
|
-
// external quads → MDLD → validated quads (DataFactory-safe, no blank nodes)
|
|
388
|
-
|
|
389
|
-
// Pattern 3: parse → generateNode (node-centric exploration)
|
|
390
|
-
const nodeView = generateNode({ ...parse({ text }), focusIRI: 'http://example.org/alice' });
|
|
391
|
-
// full graph → isolated node view (safe: returns empty if IRI not found)
|
|
392
|
-
```
|
|
393
|
-
|
|
394
|
-
**Why this works:**
|
|
395
|
-
- `parse()` returns `{ quads, context, primarySubject, md, ... }`
|
|
396
|
-
- `generate()` accepts `{ quads, context, primarySubject }`
|
|
397
|
-
- `generateNode()` accepts `{ quads, context, focusIRI }` (with focusIRI override)
|
|
398
|
-
- Perfect shape alignment enables elegant `{ ...spread }` composition
|
|
399
|
-
|
|
400
|
-
### The `md` Field — Clean Markdown Extraction
|
|
401
|
-
|
|
402
|
-
Every `parse()` result includes a `md` field containing the original Markdown with all MD-LD annotations stripped:
|
|
403
|
-
|
|
404
|
-
```javascript
|
|
405
|
-
const result = parse({
|
|
406
|
-
text: `# Document {=ex:doc .Article}\n[Content] {ex:content}`,
|
|
407
|
-
context: { ex: 'http://example.org/' }
|
|
408
|
-
});
|
|
409
|
-
|
|
410
|
-
console.log(result.md);
|
|
411
|
-
// # Document\nContent
|
|
412
|
-
|
|
413
|
-
// Round-trip safety: re-parsing clean MD produces zero quads
|
|
414
|
-
const reparsed = parse({ text: result.md });
|
|
415
|
-
console.log(reparsed.quads.length); // 0
|
|
416
|
-
```
|
|
417
|
-
|
|
418
|
-
**Behavior:**
|
|
419
|
-
- Valid MD-LD annotations (`{=...}`, `{+...}`, `{...}`) are completely removed
|
|
420
|
-
- Content from value carriers (`[text]`, `**bold**`, `` `code` ``) is preserved
|
|
421
|
-
- Invalid syntax (annotations not at end-of-line) is preserved as visible markers
|
|
422
|
-
- Headings, lists, blockquotes, code blocks maintain their structure
|
|
423
|
-
- Prefix declarations at start of line are stripped
|
|
424
|
-
- Standalone subject declarations (`{=ex:subject}`) are stripped
|
|
425
|
-
|
|
426
|
-
**Use cases:**
|
|
427
|
-
- **Content extraction** — Get readable Markdown without semantic markup
|
|
428
|
-
- **Syntax validation** — Remaining `{...}` patterns indicate invalid MD-LD syntax
|
|
429
|
-
- **Round-trip testing** — `parse(md).md` should parse to zero quads
|
|
430
|
-
- **Preview generation** — Show clean document before publishing
|
|
431
|
-
|
|
432
|
-
### `locate(quad, origin)`
|
|
433
|
-
|
|
434
|
-
Locate the origin entry for a quad using the lean origin system.
|
|
435
|
-
|
|
436
|
-
**Parameters:**
|
|
437
|
-
- `quad` (object) — The quad to locate (subject, predicate, object)
|
|
438
|
-
- `origin` (object) — Origin object containing quadIndex
|
|
439
|
-
|
|
440
|
-
**Returns:** `{ blockId, range, valueRange, carrierType, subject, predicate, context, value, polarity }` or `null`
|
|
441
|
-
|
|
442
|
-
- `range`: Full character range including carrier markers (e.g., `[`, `]`, `{`, `}`)
|
|
443
|
-
- `valueRange`: Character range excluding carrier markers (null if not available)
|
|
444
|
-
|
|
445
|
-
### `render(quads, options)`
|
|
446
|
-
|
|
447
|
-
Render RDF quads as HTML+RDFa for web display.
|
|
448
|
-
|
|
449
|
-
**Parameters:**
|
|
450
|
-
- `quads` (array) — Array of RDF/JS Quads to render
|
|
451
|
-
- `options` (object, optional):
|
|
452
|
-
- `context` (object) — Prefix mappings for CURIE shortening
|
|
453
|
-
- `baseIRI` (string) — Base IRI for resolving relative references
|
|
454
|
-
|
|
455
|
-
**Returns:** `{ html, context }`
|
|
456
|
-
|
|
457
|
-
### Utility Functions
|
|
458
|
-
|
|
459
|
-
```javascript
|
|
460
|
-
import {
|
|
461
|
-
DEFAULT_CONTEXT, // Default prefix mappings
|
|
462
|
-
DataFactory, // RDF/JS DataFactory instance
|
|
463
|
-
hash, // String hashing function
|
|
464
|
-
expandIRI, // IRI expansion with context
|
|
465
|
-
shortenIRI, // IRI shortening with context
|
|
466
|
-
parseSemanticBlock // Parse semantic block syntax
|
|
467
|
-
} from 'mdld-parse';
|
|
468
|
-
```
|
|
469
|
-
|
|
470
|
-
## 🏗️ Architecture
|
|
471
|
-
|
|
472
|
-
### Design Principles
|
|
473
|
-
- **Zero dependencies** — Pure JavaScript, ~15KB minified
|
|
474
|
-
- **Streaming-first** — Single-pass parsing, O(n) complexity
|
|
475
|
-
- **Standards-compliant** — RDF/JS data model
|
|
476
|
-
- **Origin tracking** — Full round-trip support with source maps
|
|
477
|
-
- **Explicit semantics** — No guessing, inference, or heuristics
|
|
478
|
-
|
|
479
|
-
### RDF/JS Compatibility
|
|
480
|
-
Quads are compatible with:
|
|
481
|
-
- [`n3.js`](https://github.com/rdfjs/N3.js) — Turtle/N-Triples serialization
|
|
482
|
-
- [`rdflib.js`](https://github.com/linkeddata/rdflib.js) — RDF store and reasoning
|
|
483
|
-
- [`sparqljs`](https://github.com/RubenVerborgh/SPARQL.js) — SPARQL queries
|
|
484
|
-
- [`rdf-ext`](https://github.com/rdf-ext/rdf-ext) — Extended RDF utilities
|
|
485
|
-
|
|
486
|
-
## 🧪 Testing
|
|
487
|
-
|
|
488
|
-
The parser includes comprehensive tests covering all spec requirements:
|
|
489
|
-
|
|
490
|
-
```bash
|
|
491
|
-
pnpm test
|
|
492
|
-
```
|
|
493
|
-
|
|
494
|
-
Tests validate:
|
|
495
|
-
- Subject declaration and context
|
|
496
|
-
- All predicate forms (p, ?p, !p)
|
|
497
|
-
- Datatypes and language tags
|
|
498
|
-
- Explicit list item annotations
|
|
499
|
-
- Code blocks and blockquotes
|
|
500
|
-
- Round-trip serialization
|