@domorium/validator 2.0.1 → 2.1.0

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to `@domorium/validator` are documented here.
 
+## 2.1.0
+
+- **`readDate(payload)` answers what a date says, not only whether it is
+  valid.** A consumer wanting the year of a birth had to parse the payload
+  again, and a regular expression that finds `1401` in `1401 BCE` or a year in
+  `ABT HEBREW 5761` hands on a wrong year as a fact. The document now returns
+  the parse its diagnostics apply: the modifier, each date with its calendar,
+  day, month, year and epoch, a 5.5.1 phrase and dual year, and the text. It
+  reads in the document's dialect, resolves a `SCHMA` alias of a month or a
+  calendar, and answers `null` for whatever the diagnostics reject as a date
+  value, including a day its month does not have (#378).
+
 ## 2.0.1
 
 - **A 5.5.1 date names its calendar where the specification puts it.** 5.5.1

package/README.md

@@ -59,8 +59,58 @@ interface GedcomError {
 }
 ```
 
-`data` carries the facts a quick fix is built from — which xref failed to
-resolve, and what record tag it needed.
+| Field     | Type                             | What it holds                                                                                                     |
+| --------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `code`    | `string`, a `GedcomErrorCode`    | What kind of problem this is. Match on this.                                                                      |
+| `message` | `string`                         | Written for a person to read, and rewritten when a clearer wording is found. Do not match on it.                  |
+| `hint`    | `string?`                        | Declared for advice alongside the message. Nothing in this package sets it yet, so treat it as absent.            |
+| `data`    | object?                          | The structured facts a quick fix is built from, where the diagnostic has any.                                     |
+| `range`   | `Range`                          | Zero-based line and character, `end` exclusive, over the smallest text that is wrong — the payload, not the line. |
+| `level`   | `"error" \| "warning" \| "info"` | How much it matters.                                                                                              |
+
+`data` is what makes a fix offerable rather than merely reportable: an
+unresolved pointer reports the xref that failed and the record tag it needed, so
+a host can offer to create that record.
+
+For this file, where `SEX` carries a value its schema does not permit and `FAMC`
+points at a record that is not there:
+
+```gedcom
+0 HEAD
+1 GEDC
+2 VERS 7.0
+0 @I1@ INDI
+1 NAME Lisa /Simpson/
+1 SEX Q
+1 FAMC @F9@
+0 TRLR
+```
+
+`getErrors()` answers:
+
+```json
+[
+  {
+    "code": "VAL005",
+    "message": "Value for SEX should be in set [F, M, U, X]",
+    "range": {
+      "start": { "line": 5, "character": 6 },
+      "end": { "line": 5, "character": 7 }
+    },
+    "level": "error"
+  },
+  {
+    "code": "unresolved-xref",
+    "message": "No FAM record carries @F9@",
+    "data": { "xref": "@F9@", "requiredRecordTag": "FAM" },
+    "range": {
+      "start": { "line": 6, "character": 7 },
+      "end": { "line": 6, "character": 11 }
+    },
+    "level": "error"
+  }
+]
+```
 
 Match on `code` rather than on `message`; messages are written for people and
 change. `GedcomErrorCode` is exported for this:
@@ -95,6 +145,73 @@ const unresolved = errors.filter(
 | `LEXER`           | `Lexer`                 | the text could not be tokenized                                                |
 | `PARSER`          | `Parser`                | the tokens could not be assembled into a tree                                  |
 
+## Reading the tree
+
+`getNodes()` returns the records — the level-0 nodes — each holding its
+substructures in `children`. A node carries its line's tokens in a `tokens` map
+keyed by `TokenNames`, and which key holds the text is the thing to get right:
+
+| Token     | Written as    | Holds                                  |
+| --------- | ------------- | -------------------------------------- |
+| `LEVEL`   | `1`           | The level, as it was written.          |
+| `POINTER` | `0 @I1@ INDI` | The xref a record declares for itself. |
+| `TAG`     | `1 NAME`      | The tag.                               |
+| `XREF`    | `1 FAMC @F1@` | An xref a line points at.              |
+| `VALUE`   | `1 NAME Lisa` | A payload that is not a pointer.       |
+
+`POINTER` and `XREF` are the pair worth reading twice: a record's own xref is
+never in `XREF`, and a pointer payload is never in `VALUE`.
+
+Pulling every person's name out of a file:
+
+```typescript
+import { GedcomDocument, TokenNames } from "@domorium/validator";
+import type { ASTNode } from "@domorium/validator";
+
+const document = new GedcomDocument().createDocument(gedcomString);
+
+const payload = (node: ASTNode, tag: string): string | undefined =>
+  node.children.find((child) => child.tokens[TokenNames.TAG]?.value === tag)
+    ?.tokens[TokenNames.VALUE]?.value;
+
+for (const record of document.getNodes()) {
+  if (record.tokens[TokenNames.TAG]?.value !== "INDI") continue;
+  console.log({
+    xref: record.tokens[TokenNames.POINTER]?.value,
+    name: payload(record, "NAME"),
+    line: record.range.start.line,
+  });
+}
+```
+
+```text
+{ xref: '@I1@', name: 'Lisa /Simpson/', line: 3 }
+```
+
+`range` on a node or a token is computed from the offsets on every access, not
+stored: a large file has millions of tokens and a stored range costs three
+objects apiece. Read it freely at the edges, and use `startOffset` and
+`endOffset` inside a loop over the whole document.
+
+## What a document answers
+
+Every method reads the document last given to `createDocument`, which returns
+the same instance so the two can be chained.
+
+| Method                               | Answers                                                                                                                                                        |
+| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `createDocument(text, options?)`     | Parses and validates, and returns the document itself.                                                                                                         |
+| `getErrors()`                        | Every diagnostic, in the order found.                                                                                                                          |
+| `getNodes()`                         | The records, each with its substructures.                                                                                                                      |
+| `getVersion()`                       | The version read from `HEAD`.`GEDC`.`VERS`, as written.                                                                                                        |
+| `getDialect()`                       | Which rules were applied: `"5.5.1"` or `"7.0"`.                                                                                                                |
+| `getVersionResolution()`             | How that was decided — `supported`, `substituted`, `unsupported`, `undetermined`, or `paf` for a file whose header names a writing program before its version. |
+| `getLabel(node)`                     | The specification's name for a structure, for a UI to show instead of the tag: `HEAD` answers `Header`.                                                        |
+| `getPointerTargetTag(node)`          | The record tag a pointer line must name: `FAMC` answers `FAM`.                                                                                                 |
+| `isRecordDeclaration(node)`          | Whether the node declares a record other lines can point at.                                                                                                   |
+| `getCompletions(position, lineText)` | What may be written at a position — `{ label, kind: "tag" \| "enum" \| "pointer", detail? }`.                                                                  |
+| `readDate(payload)`                  | What a date payload says, read in the document's dialect — or `null` where the diagnostics would reject it as a date value. See `GedcomDateValue`.             |
+
 ## Scripts
 
 | Command             | Description                                              |

package/dist/document/gedcomDocument.d.ts

@@ -3,6 +3,7 @@ import { ASTNode } from "../parser";
 import { type GedcomDialect, type VersionResolution } from "../validator/versionRegistry";
 import { type GedcomCompletion } from "../completion/completion";
 import type { Position } from "../types/position";
+import type { GedcomDateValue } from "../types/date";
 export interface CreateDocumentOptions {
     /** Text that is part of a document rather than one of its own. */
     fragment?: boolean;
@@ -14,6 +15,7 @@ export declare class GedcomDocument {
     private pointers;
     private errors;
     private scheme;
+    private validatedAs;
     private resolution;
     private requiresSchmaDeclaration;
     private extensions;
@@ -28,6 +30,13 @@ export declare class GedcomDocument {
     getVersionResolution(): VersionResolution | undefined;
     getDialect(): GedcomDialect | undefined;
     getCompletions(position: Position, lineText: string): GedcomCompletion[];
+    /**
+     * Null wherever the document's own diagnostics would not call the payload a
+     * valid date value, and for one with nothing to read: an empty payload, a
+     * 5.5.1 date in a calendar the schema gives no months, or a document not
+     * checked against any dialect.
+     */
+    readDate(value: string): GedcomDateValue | null;
     getErrors(): GedcomError[];
     getNodes(): ASTNode[];
 }