Struct Desc

Source

pub struct Desc { /* private fields */ }

Expand description

A canonical description, built by writing and read as bytes.

The bytes are the whole point: they are what gets stored, what gets hashed into the Tag, and what a binding in another language has to produce exactly. Nothing here depends on Rust.

Implementations§

Source §

impl Desc

Source

pub fn new() -> Desc

An empty description.

Source

pub fn of<T>() -> Desc
where T: Shape + ?Sized,

The description of T.

Source

pub fn from_bytes(bytes: impl Into<Vec<u8>>) -> Desc

A description someone else produced, from the catalogue or the wire.

Source

pub fn as_bytes(&self) -> &[u8] ⓘ

The bytes, which are what gets stored.

Source

pub fn as_text(&self) -> String

The description as text, for a message or a log line. It is all ASCII apart from names, which are UTF-8, so this never fails in practice.

Source

pub fn tag(&self) -> Tag

The tag: the first 128 bits of the BLAKE3 hash of these bytes.

Source

pub fn is_empty(&self) -> bool

Whether anything has been written.

Source

pub fn prim(&mut self, p: Prim)

A primitive.

Source

pub fn optional(&mut self, inner: fn(&mut Desc))

An optional value.

Source

pub fn list(&mut self, inner: fn(&mut Desc))

A sequence.

Source

pub fn map(&mut self, key: fn(&mut Desc), value: fn(&mut Desc))

A mapping, key type then value type.

Source

pub fn vector(&mut self, dim: u32, metric: Metric)

A vector of dim dimensions compared with metric.

Source

pub fn reference(&mut self, name: &str)

A named reference, which is what a recursive type writes on the way down. Written for you by Desc::strukt; call it directly only when building a description by hand.

Source

pub fn strukt(&mut self, name: &str, fields: &[(&str, fn(&mut Desc))])

A struct, with its fields in declaration order.

Order is layout, so it is part of the shape and reordering fields is a breaking change (15 section 5). That is why this takes a slice rather than a map.

If name is already being written further up, this writes a reference instead and does not descend, which is what makes a linked list or a tree describable at all.

Source

pub fn enumeration(&mut self, name: &str, variants: &[&str])

An enumeration, with its variants in declaration order.

Variants carry no payload here. A variant that carries data is a struct in a field of its own, which is how it has to be written until the grammar grows a form for it.