Crate yog_data 

Yog Data: Substrate Data (one model, text, binary, frames and schemas) with Yog’s domain declared over it — the kinds of content, tags, mod resources, translation keys, texts players read, images and colours. See docs/design/yog-data.md.

Everything of Substrate Data is here as it is (yog_data::Value, yog_data::Schema, yog_data::to_bytes); Yog’s own types are the modules below.

Modules

atom

Atoms: names that repeat across messages (core:open, a live record’s state) kept once a process and sent in frames as their number. An Atom is a u32: copied, compared and packed as one; its text is the table’s, alive as long as the process. A frame carries the number, every other form (text, the tagged binary form, files) the text — the numbers mean nothing outside the process.

binary

The binary form — self-describing, compact: what a build compiles content to, what saves and caches are kept in, what a reader that doesn’t know the schema can still walk. docs/format.md (“Binary form”) has the layout: a header (SDAT, a version byte), then the root value, a tag byte and its payload. A string is written where it’s first used and referred to after that, so repeated keys and ids cost one varint each and the writer never goes back over what it wrote.

diagnostic

What a tool finds wrong — reading a document, building a mod, serving a request — each as one record: what it is (a code), how bad, what’s wrong and where (a file, its line and column, a value’s path in it). The one kind of problem every tool says and every tool reads.

export

The binary form’s constants for the other languages’ readers — the IDE’s TypeScript (yog-data-export), so the tags are written once.

found

What a read met, by what Yog makes of it: content, tags of content, .yres entries. Every one is a reference (substrate_data::Read::refs); these split them.

frame

Frames: data packed for messages — both sides know the schema, so nothing says what a value is or what it’s called. A record’s fields go in the order they’re declared, after the record’s length (so a reader that knows fewer fields skips the rest; one that knows more takes their defaults: fields are only ever appended). Strings go in a table at the end, each once; the body refers to them by index. docs/format.md (“Frames”) has the layout of every value.

io

Messages over a byte stream — a socket, a pipe: each message a frame, its length (a little-endian u32) and then its binary form. What programs say to each other (a program and its editor, a tool’s service).

kinds

The kinds every Yog format knows.

names

The words the formats share, defined once: the typed value grammar’s mark and the keys a format’s own structure uses. Problem codes are crate::diagnostic::Problem; the words a shape is described by are crate::schema::ShapeNode’s variants.

patch

Editing text in place: patch changes a document to hold a new value and keeps everything that didn’t change as it was — comments, key order, number spelling, layout. What changed is written by format(), the way editors write a value.

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.

source

A source file as it’s kept and as it’s read: on disk the binary form (what an editor may save), to people its text — formatted as editors write it, so a line in an error is the line the editor shows. A file still in text is read as it is.

text

The text syntax: JSON, plus // and /* */ comments, trailing commas and unquoted keys (the part of JSON5 editors already understand).

typed

The typed values’ string forms — one grammar for every format:

Macros

field

Field ident of struct T as files write it: field!(UserProfile, display_name) → "display_name". A field T hasn’t got doesn’t compile.

kind

Declares kinds, each with its id type (String when none is said). A kind’s name is a string literal or a path to a &'static str constant (Mesh = ids::MESH, for names a format keeps in one place), or a { block } of one; either way it is checked when the kind compiles.

named_schema

Implements Schema for a NamedType: every form is its stored form’s, so a reader that only knows the shape reads it as stored.

Structs

Atom

A name kept once a process; see the module.

Bump

An arena to bump allocate into.

Diagnostic

One thing found.

Doc

A parsed document: the value and where each of its parts is.

Errors

Every problem found reading a document, in its order.

Id

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

KindName

A reference’s kind: lower case ASCII letters, digits and _, starting with a letter (user, doc, file). Checked when it’s made, then a number: copied and compared as one.

LineCol

A 1-based line and column (in characters).

Map

Keys are shared: a decoded document allocates each distinct key once, however many maps have it.

MapRef

A borrowed map: entries in file order.

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.

Path

Where a value is in a document: tasks[2].parts[0].owner.

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).

Ref

A reference: its kind (user, doc, file, or any other the format names) and id (images/logo.png, team:alice). The id is opaque here; what it names and whether it exists is the format’s business (a crate::Resolve checks it), and a typed field reads it as its kind’s id type (crate::Id).

RefKey

A reference’s id as written, untyped: anything but empty, whitespace or control characters. What it names is the format’s business; a typed field reads it as its kind’s id type (crate::RefId).

Res

An entry of a .yres set: the set (upper case, Strings) and its key (screen.title), written @res:Strings.screen.title.

ShapeDoc

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

Span

A byte range of the source.

Spans

Where each value of a parsed document is: the value’s span, its key’s (map entries), and its children’s, in the same order as the value’s.

Stream

A list of T kept written: its body in the binary form, its strings its own.

StreamWriter

Writes a Stream’s items as they come.

SyntaxError

A syntax error.

TagId

A tag of content of kind K: @tag:item:minecraft:planks.

TextOf

A field that is a text, kept resolved (Text::resolve): #[data(with = "yog_data::TextOf")].

Uid

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

Enums

AnyRefOrTag

Content of any kind or a tag of it: @entity:minecraft:pig, @tag:entity:c:bosses — what a tag names is its first part.

Code

A diagnostic’s kind: one of this crate’s Problems, or a tool’s own code (E0308, a lint’s name), kept as an Atom. Written as its code in every form.

Color

A colour: ARGB, or a .yres colour.

Expected

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

Image

An image: a source (@image:sprite:button, @image:mymod:gui/logo, @image:item:minecraft:stick) or a .yres image (@res:Images.logo).

Meaning

What a reference is to Yog: content, a tag of content, a .yres entry, an image source or a translation key.

OneOrTag

Content of kind K or a tag of it — a recipe ingredient.

Problem

What’s wrong with a value, as this crate finds it: each a stable code (SD…) tools can match on.

Seg

One step of a Path.

Severity

How bad it is.

Shape

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

Text

A text a player reads: Yog text as written ({b|bold}), a .yres text (@res:Strings.title), the name of some content (@item:minecraft:stick shows “Stick”), or a translation key (@lang:gui.done).

Unresolved

Why a reference doesn’t resolve.

Value

The text form has no syntax of its own for the typed values (Ref, Bytes): they’re written as strings ("@file:images/logo.png"), so every file stays JSON, and the schema of a field says what its string means. The binary form keeps the type.

ValueKind

Which of a Value’s cases a value is — what messages name ("a string", "a list") when they say what was found.

ValueRef

A borrowed Value: the same cases, strings &'a str, lists and maps slices.

Traits

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.

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

built_in

A table a crate ships (include_str! of its .ydata), read: what it says, or — when it won’t read, which its crate’s tests catch — the error logged (what: which table) and its default.

expected

“expected what, found …”: for a form substrate_data::Expected has no word for ("auto", "full" or six numbers).

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_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_res_key

A key as .yres files have them: letters, digits, _, dotted.

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_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_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).

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.

Type Aliases

BlockId

A block: @block:minecraft:furnace[facing=north].

EntityId

An entity: @entity:minecraft:pig.

ItemId

An item: @item:minecraft:stick.

ItemIdOrTag

An item or an item tag: "@item:minecraft:stick", "@tag:item:minecraft:planks".

Lang

A translation key of the game’s or a mod’s lang files: @lang:gui.done.

RecipeId

A recipe: @recipe:minecraft:furnace.

Derive Macros

Schema

#[derive(Schema)]: see the crate’s docs.