mdld-parse 0.9.8 → 0.9.9

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 CHANGED
@@ -305,6 +305,72 @@ Generate node-centric MDLD showing all quads where a specific IRI appears in any
305
305
 
306
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
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
+
308
374
  ### Composition Patterns
309
375
 
310
376
  With the unified named parameter API, `parse()` and `generate()` compose seamlessly through object spreading:
@@ -371,7 +437,10 @@ Locate the origin entry for a quad using the lean origin system.
371
437
  - `quad` (object) — The quad to locate (subject, predicate, object)
372
438
  - `origin` (object) — Origin object containing quadIndex
373
439
 
374
- **Returns:** `{ blockId, range, carrierType, subject, predicate, context, value, polarity }` or `null`
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)
375
444
 
376
445
  ### `render(quads, options)`
377
446
 
package/dist/README.md CHANGED
@@ -305,6 +305,72 @@ Generate node-centric MDLD showing all quads where a specific IRI appears in any
305
305
 
306
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
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
+
308
374
  ### Composition Patterns
309
375
 
310
376
  With the unified named parameter API, `parse()` and `generate()` compose seamlessly through object spreading:
@@ -371,7 +437,10 @@ Locate the origin entry for a quad using the lean origin system.
371
437
  - `quad` (object) — The quad to locate (subject, predicate, object)
372
438
  - `origin` (object) — Origin object containing quadIndex
373
439
 
374
- **Returns:** `{ blockId, range, carrierType, subject, predicate, context, value, polarity }` or `null`
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)
375
444
 
376
445
  ### `render(quads, options)`
377
446
 
@@ -25,7 +25,8 @@ Each `OriginEntry` contains:
25
25
  ```javascript
26
26
  {
27
27
  blockId: string, // Unique identifier for the containing block
28
- range: { start: number, end: number }, // Character range in source text
28
+ range: { start: number, end: number }, // Character range including carrier markers
29
+ valueRange: { start: number, end: number } | null, // Character range excluding carrier markers
29
30
  carrierType: string, // 'heading', 'blockquote', 'span'
30
31
  subject: string, // Subject IRI of the quad
31
32
  predicate: string, // Predicate IRI of the quad
@@ -2,59 +2,57 @@
2
2
 
3
3
  # Personal Journal {=j:index .prov:Collection label}
4
4
 
5
- Alice's daily journal, structured as a hierarchy of collections. The top-level index contains [2026] {+j:2026/index ?prov:hadMember label}.
5
+ Everything I write ends up here. Started keeping this in [2026] {+j:2026/index ?prov:hadMember label}.
6
6
 
7
7
  ## Year 2026 {=j:2026/index .prov:Collection label}
8
8
 
9
- 2026 is organised into monthly collections: [January] {+j:2026/01/index ?prov:hadMember label}, [February] {+j:2026/02/index ?prov:hadMember label}, [March] {+j:2026/03/index ?prov:hadMember label}, [April] {+j:2026/04/index ?prov:hadMember label}, and [May] {+j:2026/05/index ?prov:hadMember label}.
9
+ Quite a year so far. I've been writing through [January] {+j:2026/01/index ?prov:hadMember label}, [February] {+j:2026/02/index ?prov:hadMember label}, [March] {+j:2026/03/index ?prov:hadMember label}, [April] {+j:2026/04/index ?prov:hadMember label}, and now [May] {+j:2026/05/index ?prov:hadMember label}.
10
10
 
11
11
  ## May 2026 {=j:2026/05/index .prov:Collection label}
12
12
 
13
- May started on [2026-05-01] {prov:startedAtTime ^^xsd:date} and is divided into five weekly collections: days [1–3] {+j:2026/05/week-1/index ?prov:hadMember label}, [4–10] {+j:2026/05/week-2/index ?prov:hadMember label}, [11–17] {+j:2026/05/week-3/index ?prov:hadMember label}, [18–24] {+j:2026/05/week-4/index ?prov:hadMember label}, and [25–31] {+j:2026/05/week-5/index ?prov:hadMember label}.
13
+ May kicked off on [2026-05-01] {prov:startedAtTime ^^xsd:date}. I'm splitting it into weeks: [1–3] {+j:2026/05/week-1/index ?prov:hadMember label}, [4–10] {+j:2026/05/week-2/index ?prov:hadMember label}, [11–17] {+j:2026/05/week-3/index ?prov:hadMember label}, [18–24] {+j:2026/05/week-4/index ?prov:hadMember label}, [25–31] {+j:2026/05/week-5/index ?prov:hadMember label}.
14
14
 
15
15
  ## Week 2, May 2026 {=j:2026/05/week-2/index .prov:Collection label}
16
16
 
17
- The second week of May ran from [2026-05-04] {prov:startedAtTime ^^xsd:date} through [2026-05-10] {prov:endedAtTime ^^xsd:date}. It contained [6] {j:totalActivities ^^xsd:integer} logged activities across [5] {j:readingHours ^^xsd:integer} hours of reading, [8] {j:workHours ^^xsd:integer} hours of work, and [3] {j:exerciseHours ^^xsd:integer} hours of exercise. Of [5] {j:goalsTotal ^^xsd:integer} weekly goals set on Monday, [4] {j:goalsCompleted ^^xsd:integer} were completed and [1] {j:goalsCarryOver ^^xsd:integer} carried over.
18
-
19
- The week's daily entries are members of this collection:
17
+ Week ran [2026-05-04] {prov:startedAtTime ^^xsd:date} to [2026-05-10] {prov:endedAtTime ^^xsd:date}. Decent week overall — [6] {j:totalActivities ^^xsd:integer} things logged, [5] {j:readingHours ^^xsd:integer} hrs reading, [8] {j:workHours ^^xsd:integer} hrs work, [3] {j:exerciseHours ^^xsd:integer} hrs moving. Set [5] {j:goalsTotal ^^xsd:integer} goals Monday, hit [4] {j:goalsCompleted ^^xsd:integer}, rolled [1] {j:goalsCarryOver ^^xsd:integer} over.
20
18
 
21
19
  ======
22
20
 
23
21
  ### 06 May 2026 {=j:2026/05/06/index .prov:Activity label}
24
22
 
25
- A productive Wednesday. The day ran from [2026-05-06T08:00:00+04:00] {prov:startedAtTime ^^xsd:dateTime} to [2026-05-06T23:30:00+04:00] {prov:endedAtTime ^^xsd:dateTime} and is a [member] {+j:2026/05/week-2/index ?prov:hadMember} of week 2. It produced a [daily summary] {+j:2026/05/06/summary .prov:Entity ?prov:generated label} capturing mood and locations visited.
23
+ Good day. Up at [2026-05-06T08:00:00+04:00] {prov:startedAtTime ^^xsd:dateTime}, lights out [2026-05-06T23:30:00+04:00] {prov:endedAtTime ^^xsd:dateTime}. This is [week 2] {+j:2026/05/week-2/index ?prov:hadMember}. By end of day I had a [daily wrap-up] {+j:2026/05/06/summary .prov:Entity ?prov:generated label} written.
26
24
 
27
- The day flowed through three phases, each informing the next: [morning] {+#morning ?prov:wasInformedBy}, then [afternoon] {+#afternoon ?prov:wasInformedBy}, then [social] {+#social ?prov:wasInformedBy}.
25
+ Morning led into afternoon which led into [evening out] {+#morning ?prov:wasInformedBy} → [#afternoon] {+#afternoon ?prov:wasInformedBy} → [#social] {+#social ?prov:wasInformedBy}.
28
26
 
29
27
  #### Morning {=#morning .prov:Activity label}
30
28
 
31
- The morning started with a [walk] {+#walk ?prov:wasInformedBy} and then [coffee] {+#coffee-prep ?prov:wasInformedBy}.
29
+ Started slow, which was the point. [Run first] {+#walk ?prov:wasInformedBy}, then [coffee] {+#coffee-prep ?prov:wasInformedBy}.
32
30
 
33
- ##### Morning Walk {=#walk .prov:Activity label}
31
+ ##### Morning Run {=#walk .prov:Activity label}
34
32
 
35
- A [45] {j:durationMin ^^xsd:integer}-minute run covering [2.5] {j:distanceMiles ^^xsd:decimal} miles through [Central Park] {+j:place/central-park .prov:Location ?prov:atLocation label}, wearing [running shoes] {+j:shoes/running .prov:Entity ?prov:used label}. The watch generated [heart rate data] {+j:2026/05/06/hr-data .prov:Entity ?prov:generated label} for the session.
33
+ [45] {j:durationMin ^^xsd:integer} minutes, [2.5] {j:distanceMiles ^^xsd:decimal} miles around [Central Park] {+j:place/central-park .prov:Location ?prov:atLocation label}. Wore my [running shoes] {+j:shoes/running .prov:Entity ?prov:used label} — watch logged [heart rate data] {+j:2026/05/06/hr-data .prov:Entity ?prov:generated label} the whole time.
36
34
 
37
- ##### Coffee Preparation {=#coffee-prep .prov:Activity label}
35
+ ##### Coffee {=#coffee-prep .prov:Activity label}
38
36
 
39
- Back [home] {+j:place/home .prov:Location ?prov:atLocation label}, ground [coffee beans] {+j:coffee/beans .prov:Entity ?prov:used label} with [water] {+j:coffee/water .prov:Entity ?prov:used label} and produced a [morning coffee] {+#morning-coffee .prov:Entity ?prov:generated label}.
37
+ Back [home] {+j:place/home .prov:Location ?prov:atLocation label}. Ground the [beans] {+j:coffee/beans .prov:Entity ?prov:used label}, boiled [water] {+j:coffee/water .prov:Entity ?prov:used label}, got a proper [cup] {+#morning-coffee .prov:Entity ?prov:generated label}.
40
38
 
41
39
  #### Afternoon {=#afternoon .prov:Activity ?prov:wasInformedBy label}
42
40
 
43
- The afternoon split between reading and a work session.
41
+ Split between reading and grinding through docs.
44
42
 
45
- ##### Reading Session {=#reading .prov:Activity label}
43
+ ##### Reading {=#reading .prov:Activity label}
46
44
 
47
- Read [42] {j:pages ^^xsd:integer} pages of [Dune] {+j:dune-book .prov:Entity ?prov:used label} over [2] {j:durationHours ^^xsd:integer} hours, producing [reading notes] {+j:reading-notes .prov:Entity ?prov:generated label}.
45
+ [2] {j:durationHours ^^xsd:integer} hours with [Dune] {+j:dune-book .prov:Entity ?prov:used label} — got through [42] {j:pages ^^xsd:integer} pages. Wrote up [some notes] {+j:reading-notes .prov:Entity ?prov:generated label} while it was fresh.
48
46
 
49
- ##### Work Session {=#work .prov:Activity ?prov:wasInformedBy label}
47
+ ##### Work {=#work .prov:Activity ?prov:wasInformedBy label}
50
48
 
51
- Spent [3] {j:durationHours ^^xsd:integer} hours on [API documentation] {+j:api-docs .prov:Entity ?prov:used label}, generating [documentation updates] {+j:doc-updates .prov:Entity ?prov:generated label}.
49
+ [3] {j:durationHours ^^xsd:integer} hours on [API docs] {+j:api-docs .prov:Entity ?prov:used label}. Pushed [a round of updates] {+j:doc-updates .prov:Entity ?prov:generated label}.
52
50
 
53
- #### Social {=#social .prov:Activity ?prov:wasInformedBy label}
51
+ #### Evening — coffee with Sam {=#social .prov:Activity ?prov:wasInformedBy label}
54
52
 
55
- Met [Sam] {+j:sam .prov:Person ?prov:wasAssociatedWith label} at the [local café] {+j:place/cafe .prov:Location ?prov:atLocation label} for [30] {j:durationMin ^^xsd:integer} minutes to talk through [career changes] {j:topic}.
53
+ Met [Sam] {+j:sam .prov:Person ?prov:wasAssociatedWith label} at [our usual spot] {+j:place/cafe .prov:Location ?prov:atLocation label}. [30] {j:durationMin ^^xsd:integer} minutes turned into a real conversation about [career changes] {j:topic}.
56
54
 
57
- ### Daily Summary {=j:2026/05/06/summary .prov:Entity label}
55
+ ### Wrap-up {=j:2026/05/06/summary .prov:Entity label}
58
56
 
59
- End-of-day reflection, generated by the day's activity. Mood: [happy] {j:mood}, energy [8] {j:energy ^^xsd:integer}/10, stress [2] {j:stress ^^xsd:integer}/10. Places visited today: [Central Park] {+j:place/central-park ?j:visited}, [home] {+j:place/home ?j:visited}, and [local café] {+j:place/cafe ?j:visited}.
57
+ Mood: [happy] {j:mood}. Energy [8] {j:energy ^^xsd:integer}/10, stress [2] {j:stress ^^xsd:integer}/10 — good ratio. Was out at [Central Park] {+j:place/central-park ?j:visited}, [home] {+j:place/home ?j:visited}, and [the café] {+j:place/cafe ?j:visited}.
60
58