Skip to main content

Crate crossmap

Crate crossmap 

Source
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::encode and Compiled::decode have exactly the semantics of encode and decode on the crosswalk.
Crosswalk
A parsed crosswalk. It is built only by parse_crosswalk and cannot be changed afterwards, so the prepared form the executor builds the first time it is used stays the crosswalk’s own.
CrosswalkIssue
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.
EmptySite
An existing empty array a wildcard step met: structure the matches cannot show, since it yields none. wildcard is the ordinal (from zero) of the wildcard step that met it.
PathMatch
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.
RuleSides
The paths a two-way rule reads and writes, in the order its operation takes and produces values: encode reads from and writes to, decode the reverse. Each list is non-empty.
SinglePath
The paths and gate of a rule with one path on each side.
SyntaxIssue
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.
WhenElement
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[].kind is written against the rule’s from side, 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§

AggregateFunction
What an aggregate computes over the elements it reads.
CrossmapError
An error crossmap reports.
Direction
The direction a crosswalk runs in.
FormatKind
The textual forms format converts, each a bijection between its canonical text and a machine value.
OneWayRule
A one-way rule: explicitly lossy, applying in one direction.
PathStep
One step of a parsed path: a record key, a fixed array index, or a wildcard over every element of an array.
TrailStep
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 0 is never mistaken for the first element of an array.
TwoWayRule
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 with Object.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.stringify writes 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 encode and decode do 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 when is evaluated against document, the shared document.
encode
Encodes a native document into the shared shape. A rule’s when is evaluated against document.
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 None when the path is absent from it.
rule_sides
The sides of a two-way rule: a template reads its fields in its from record’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.