Module schema 

Schemas: a format is a Rust type implementing Schema (usually #[derive(Schema)]). One schema reads and writes the format, checks it with the path of every problem, collects its references for the build to check, and describes itself (Shape) for editors (property grids, completion) and the docs.

Modules

with

Field codecs: #[data(with = "…")] reads and writes a field through a type other than its own — like serde’s with. The field keeps the plain type a program uses (String), the format says what it holds (a reference to a file), checked and resolved by the Reader’s Resolve.

Structs

Dictionary

The values references expand to — the words of a vocabulary, the texts of a language, the entries of a table — kept per kind and id, in the order they were added. It is a Resolve: a reference of a kind it holds is checked against its ids and, where a field takes a value (with::Expand), expanded to the value; a reference of a kind it doesn’t hold is left alone.

EnumShape

An enum’s shape: its variants, and the key naming one if it’s tagged.

Field

A field of a struct (or of an enum’s variant).

FieldDoc

A field: its name, doc, shape, whether it must be written, its range.

Found

Where a reference was found.

Id

The id of something of kind K, of K’s id type: written @file:images/logo.png, @user:42.

NamedShape

The shape of a NamedType: its name and its stored shape.

OneOrList

One value or several, read either way and written back the same way (one as itself). Never empty: an empty list is a problem.

Ordered

An object kept in file order, values of one schema.

Read

What reading a document gives: the value and the references in it.

Reader

The state of reading a value: where it is, the problems so far, and the references met (for the build to check against the content there is).

ShapeDoc

A shape as data: written { root, defs }, structs and enums once in defs and referred to by name.

StructShape

A struct’s shape: its fields.

Uid

A 128-bit id (a UUID’s bits, a hash), spelled as 32 lower-case hex digits: @doc:0123456789abcdef0123456789abcdef.

Variant

A variant of an enum.

VariantDoc

A variant: its name, doc, and (in a tagged enum) its fields.

Enums

DefinitionDoc

A struct or an enum, as written once in a description’s defs.

Expansion

What a reference read where a value may stand came to.

Expected

What a field takes, for the “expected …, found …” problem.

Shape

What a format looks like: drives an editor’s property grids and pickers, completion, hover docs and the docs’ field tables.

ShapeNode

One shape as data, tagged by kind; a struct or enum is a def, its definition written once in the description’s defs.

Unresolved

Why a reference doesn’t resolve.

Constants

COMMENT_KEY

A note for whoever edits the file — every object may have one.

MAX_EXPANSION_DEPTH

How many expanded values may be read inside one another: a value that expands to itself (through references that expand to references) stops here with a problem instead of never.

META_PREFIX

What a source-only key starts with: $… (a note on an entry: $<key>), _….

PRIVATE_PREFIX

What a private source-only key starts with: _….

RESULT_ERR

The key of a Result’s failure side.

RESULT_OK

The key of a Result’s success side.

WRAPPED

Where a tagged enum’s variant keeps what it wraps when that isn’t a struct (Id(String) is {type: "id", value: "…"}); a wrapped struct’s fields sit next to the tag instead.

Traits

Fields

A struct with named fields (#[derive(Schema)]): each field’s Rust name and its name in files.

Kind

A kind of thing a reference names: user, doc, file, … — a format declares its own with kind!, each with the type of its ids.

Kinds

One kind or several ((File, Doc), sharing an id type): what a reference field takes.

NamedType

A type of a format’s own, stored as NamedType::Stored in every form (text, binary, frames) and described by NamedType::NAME, so a tool that knows the name shows its own editor (a colour picker, a calendar) and one that doesn’t edits the stored data. crate::named_schema! implements Schema for it.

Numbers

The numbers a value holds — what #[data(range = …)] checks.

RefId

The type of a kind’s ids: how one is spelled in a reference (@user:42), read back, and stored in every other form (a frame packs it as itself — a number as a number).

Resolve

What a tool makes of the references it reads: a build checks each one against what there is (and may rewrite its id), an editor shows them.

Schema

A format: a type that reads, writes, encodes, packs and describes itself.

Functions

field_name

ident’s name in files among fields — a compile error when it’s used in a constant (as field! does) and there’s no such field.

field_names

The field names of a struct’s shape (none for anything else).

from_bytes_with

read_bytes with resolver for the references: the binary form read through a value tree (the straight path has nowhere to ask), so references can be checked, rewritten and expanded (with::Expand).

from_doc

Reads a parsed document as T; text is its source, for positions.

from_doc_with

from_doc, references and texts going through resolver.

from_text

Parses text and reads it as T; problems come with their line and column.

from_value

Reads v as T: the value and its references, or every problem.

from_value_with

from_value, references and texts going through resolver.

is_metadata_key

Source-only keys every object may have: $…, _…, comment.

placed

d (about a value of doc, parsed from text) at its line and column: its key’s for one about the key (an unknown field).

read_both

A and B read from the same object — each allowing the other’s fields, like serde’s flatten: a record’s common fields and its kind’s.

read_bytes

Reads the binary form as T, borrowed all the way: no string is copied but into T itself — content as the runtime takes it.

read_id

v as a reference to one of K’s kinds, its id read as K::Id — as written, or as the crate::Resolve rewrote it.

read_named

Reads a NamedType through its stored form (what crate::named_schema! calls).

read_ref

v as a reference to one of kinds (any kind if empty), written @kind:id — a bare id is an error that says how to write it. The id is read untyped (read_id reads it as a kind’s id type).

read_ref_value

read_value of a borrowed value.

read_value

Reads v as T, nothing else: what a runtime wants of content (the references met aren’t kept).

ref_shape

The shape of a reference to K.

to_bytes

v in the binary form, written straight (Schema::encode).

to_bytes_into

v in the binary form, appended to out (a whole document, header first): a buffer that is kept and reused grows once.

to_text

value as text, indented: written straight, no value tree built.

Type Aliases

ShapeFn

A shape, built on demand — so shapes of recursive types are fine.