Expand description
A bidirectional crosswalk codec.
One crosswalk document describes how to map between a dataset’s native JSON shape and a shared target shape, and
that one document derives both directions: every two-way operation knows its own inverse, so decode undoes
encode over the paths the crosswalk maps. What cannot be undone is declared as one-way rules. Rules are gated
with trilean predicate trees.
Documents are Values, an ordered JSON value whose numbers are doubles read and written as JavaScript reads and
writes them, so a document means here what it means to JavaScript’s JSON.parse. The crate does no input or
output and compiles to wasm32-unknown-unknown.
Modules§
- schema
- The JSON Schema of the crosswalk format, the document the packages publish as
schemas/crossmap.schema.json.
Structs§
- Compiled
- A crosswalk prepared for running any number of times:
Compiled::encodeandCompiled::decodehave exactly the semantics ofencodeanddecodeon the crosswalk. - Crosswalk
- A parsed crosswalk. It is built only by
parse_crosswalkand cannot be changed afterwards, so the prepared form the executor builds the first time it is used stays the crosswalk’s own. - Crosswalk
Issue - One structural defect of a crosswalk that parses: which rule (two-way rules first, then one-way rules, continuing the count; negative when the defect lies between rules) and what is wrong.
- Empty
Site - An existing empty array a wildcard step met: structure the matches cannot show, since it yields none.
wildcardis the ordinal (from zero) of the wildcard step that met it. - Path
Match - One location a path addresses: the trail reaching it and the value there.
- Reading
- Everything a path addresses in a document: the matches in index order, and every empty array a wildcard met.
- Rule
Sides - The paths a two-way rule reads and writes, in the order its operation takes and produces values: encode reads
fromand writesto, decode the reverse. Each list is non-empty. - Single
Path - The paths and gate of a rule with one path on each side.
- Syntax
Issue - One reason a crosswalk document or a path string failed its schema or grammar: a message naming the offending
value, prefixed with the dotted path of the field it concerns (
(root)for the document itself). - When
- A rule’s
when: the predicate tree as trilean reads it, with the JSON it was read from. - When
Element - The element a wildcard rule is visiting, for a gate whose references carry wildcards: the current match’s index
at each wildcard the gate covers, and the governing side’s path through each of the rule’s wildcards. A reference
such as
rows[].kindis written against the rule’sfromside, so its part through its last wildcard is replaced by the governing side’s array at the same depth, and it reads the visited element in whichever document governs.
Enums§
- Aggregate
Function - What an
aggregatecomputes over the elements it reads. - Crossmap
Error - An error crossmap reports.
- Direction
- The direction a crosswalk runs in.
- Format
Kind - The textual forms
formatconverts, each a bijection between its canonical text and a machine value. - OneWay
Rule - A one-way rule: explicitly lossy, applying in one direction.
- Path
Step - One step of a parsed path: a record key, a fixed array index, or a wildcard over every element of an array.
- Trail
Step - One step of a concrete location: a record key or an array index. A trail is a path with every wildcard bound to an
index, so a record key spelled
0is never mistaken for the first element of an array. - TwoWay
Rule - A two-way rule: both directions derive from it.
- Value
- A JSON value.
Traits§
- Gate
- What the executor asks of a rule’s gate.
Functions§
- assert_
round_ trip - Checks that
decode(encode(sample))equals every sample on the paths the crosswalk promises to preserve. The paths one-way rules touch are left out (a dropped path cannot survive; a decode-direction default or aggregate inserts a path the sample never had), then each round trip is compared with its sample, leaves withObject.is. - canonical_
json - The JSON Canonicalization Scheme form of a value (RFC 8785, https://www.rfc-editor.org/rfc/rfc8785): compact, every
record’s keys sorted by their UTF-16 code units, strings escaped and numbers written as
JSON.stringifywrites them, which is what the scheme prescribes for both. - compile_
crosswalk - Validates and prepares a crosswalk for encoding and decoding any number of documents. The prepared form is kept
with the crosswalk, so compiling it again (as
encodeanddecodedo on every call) costs nothing. - decode
- Decodes a shared document back into the native shape: every two-way rule’s paths swapped and each operation’s
inverse applied. A rule’s
whenis evaluated againstdocument, the shared document. - encode
- Encodes a native document into the shared shape. A rule’s
whenis evaluated againstdocument. - format_
path - Prints steps in the path grammar, the inverse of
parse_path: a key the bare class covers prints bare, any other quoted. A key of exactly__proto__prints quoted, for messages, though the grammar refuses it. - format_
trail - Prints a trail in the path grammar.
- is_path
- Whether a string is a well-formed path.
- js_
ordered - The value with every record’s keys in JavaScript order, which is the value a JavaScript program holding it sees.
- parse_
crosswalk - Parses a JSON value as a crosswalk document.
- parse_
path - Parses a path string into its steps.
- read_
path - Reads every location a path addresses in a document, or
Nonewhen the path is absent from it. - rule_
sides - The sides of a two-way rule: a template reads its fields in its
fromrecord’s order, a copy writes several targets, and every other rule has one path on each side. - stringify
- The text
JSON.stringify(value)writes: compact, keys in JavaScript order, numbers as JavaScript writes them. - stringify_
pretty - The text
JSON.stringify(value, undefined, 2)writes: two spaces per level of nesting, one member per line. - validate_
crosswalk - Validates a parsed crosswalk against the structural rules of the format.
- wildcard_
count - The number of wildcard steps of a path.