silk.schema.shape.

When to use#

Call silk.schema.schema.Schemas.shape<T>() to get the Shapes of T: what kind of value it is on the wire, its fields with their wire names, doc comments and constraints, and its variants. silk.schema.json_schema.JsonSchemas renders it as JSON Schema; command line help and AI tool definitions read the same description.

Details#

A shape is derived from the type, its Spec and its doc comments, never written by hand. Its parts are nodes of one table, and a part refers to another by ShapeRef, so a recursive type such as a tree whose children are trees is one named node that refers to itself. Every struct and union is one node named by its type, so a type used twice is described once.

The text in a shape (names, docs, expected text) is static: building one only links nodes.

Import as Shapes with import silk.schema.shape { Shapes }.

Public declarations: 10.

Bound#

pub union Bound

One end of a numeric range.

None#

None

No limit.

Signed#

Signed

A signed integer limit.

Field value#

pub value: i64

The limit.

Unsigned#

Unsigned

An unsigned integer limit.

Field value#

pub value: u64

The limit.

Float#

Float

A floating-point limit.

Field value#

pub value: f64

The limit.

Implementation Copy for Bound#

impl Copy for Bound

Constraint#

pub union Constraint

A rule a value must follow beyond its type, declared in a Spec or given by a codec.

Details#

Every limit is inclusive. Lengths count characters, as JSON Schema's minLength and maxLength do, and usize.MAX means no upper limit.

Range#

Range

A number between min and max.

Field min#

pub min: Bound

The smallest value.

Field max#

pub max: Bound

The largest value.

Length#

Length

Text of min to max characters.

Field min#

pub min: usize

The fewest characters.

Field max#

pub max: usize

The most characters.

Items#

Items

A list of min to max elements.

Field min#

pub min: usize

The fewest elements.

Field max#

pub max: usize

The most elements.

Pattern#

Pattern

Text that a regular expression in silk.text.regex syntax matches.

Field source#

pub source: string<'static>

The expression, which JSON Schema shares, since both use JavaScript syntax.

Expected#

Expected

What a person reads when the value fails, instead of the generated text.

Field text#

pub text: string<'static>

The text, such as "at most an hour".

Implementation Copy for Constraint#

impl Copy for Constraint

Literal#

pub union Literal

A value a static Spec can hold, such as a field's default.

Boolean#

Boolean

true or false.

Field value#

pub value: bool

The value.

Integer#

Integer

An integer.

Field value#

pub value: i64

The value.

Number#

Number

A number.

Field value#

pub value: f64

The value.

Text#

Text

Text, or the name of a unit variant.

Field value#

pub value: string<'static>

The value.

Implementation Copy for Literal#

impl Copy for Literal

ShapeRef#

pub struct ShapeRef

A link to one node of a Shapes table.

Field index#

pub index: usize

The node's position in the table.

Implementation Copy for ShapeRef#

impl Copy for ShapeRef

ShapeOf#

pub struct ShapeOf<T>

The node of a type T in a Shapes table, as silk.schema.schema.Schema.shape returns it.

Details#

The type parameter says whose shape it is, so a call of Schema.shape names the type it wants by the result it expects. at is the node itself.

Field at#

pub at: ShapeRef

The node.

Implementation ShapeOf<T>#

impl<T> ShapeOf<T>

Associated function make#

pub fn make(at: ShapeRef) -> ShapeOf<T>

Returns at as the node of T.

TypeInfo#

pub struct TypeInfo

The name and doc comment of a named type.

Field name#

pub name: string<'static>

The type's name with its type arguments, such as Server or Page<String>.

Field doc#

pub doc: string<'static>

The type's /// comment, without slashes, or empty text.

Implementation Copy for TypeInfo#

impl Copy for TypeInfo

FieldShape#

pub struct FieldShape

One field of a struct or of a union variant.

Field name#

pub name: string<'static>

The field's name in Silk.

Field wire#

pub wire: string<'static>

The field's name in the data format.

Field doc#

pub doc: string<'static>

The field's /// comment, without slashes, or empty text.

Field value#

pub value: ShapeRef

The shape of the field's value.

Field required#

pub required: bool

Whether the field must be present: false for an Option field and a field with a default.

Field default#

pub default: Option<Literal>

The value of an absent field, from Spec.defaultValue.

Field constraints#

pub constraints: List<Constraint>

The rules the field's Spec declares.

VariantShape#

pub struct VariantShape

One variant of a union.

Field name#

pub name: string<'static>

The variant's name in Silk.

Field wire#

pub wire: string<'static>

The variant's name in the data format.

Field doc#

pub doc: string<'static>

The variant's /// comment, without slashes, or empty text.

Field fields#

pub fields: List<FieldShape>

The variant's fields; empty for a unit variant.

Shape#

pub union Shape

The wire form of one type.

Boolean#

Boolean

true or false.

Integer#

Integer

An integer between min and max, the limits of its type.

Field min#

pub min: Bound

The smallest value the type holds.

Field max#

pub max: Bound

The largest value the type holds.

Float#

Float

A number.

Text#

Text

Text.

Optional#

Optional

A value that may be absent or null, as Option is.

Field value#

pub value: ShapeRef

The value when present.

List#

List

A list.

Field element#

pub element: ShapeRef

Each element.

Object#

Object

A struct: an object with one member per field.

Field info#

pub info: TypeInfo

The struct's name and doc comment.

Field fields#

pub fields: List<FieldShape>

The fields, in declaration order.

Field strict#

pub strict: bool

Whether keys that no field names are rejected, from Spec.strict.

Choice#

Choice

A union whose variants have no fields: the name of one variant.

Field info#

pub info: TypeInfo

The union's name and doc comment.

Field variants#

pub variants: List<VariantShape>

The variants, in declaration order.

Tagged#

Tagged

A union with fields: an object whose tag member names the variant and whose other members are that variant's fields.

Field info#

pub info: TypeInfo

The union's name and doc comment.

Field tag#

pub tag: string<'static>

The member that names the variant, type unless Spec.tag picks another.

Field variants#

pub variants: List<VariantShape>

The variants, in declaration order.

Custom#

Custom

A type with its own read, such as a port written as text: its wire form wire, plus the rules its codec reports.

Field wire#

pub wire: ShapeRef

The shape of the wire form.

Field constraints#

pub constraints: List<Constraint>

The rules about the wire value itself.

Field notes#

pub notes: List<string<'static>>

What else the codec expects, as text for a person, such as "a port from 1 to 65535".

Pending#

Pending

A node whose type is still being described; only seen while a recursive type is built.

Shapes#

pub struct Shapes

The shape of one type, and of every type it uses, as a table of nodes.

When to use#

Get one from Schemas.shape<T>() and walk it from Shapes.root with Shapes.get.

Implementation Shapes#

impl Shapes

Associated function make#

pub fn make() -> Shapes

Returns an empty table. Schemas.shape fills it.

Method root#

pub fn root(self: &Self) -> ShapeRef

Returns the shape of the type the table was made for.

Method setRoot#

pub fn setRoot(self: &mut Self, root: ShapeRef) -> ()

Sets the node of the type the table describes.

Method get#

pub fn get(self: &Self, at: ShapeRef) -> &Shape

Returns the node at refers to.

Method length#

pub fn length(self: &Self) -> usize

Returns the number of nodes.

Method add#

pub effect fn add(self: &mut Self, shape: Shape) -> ShapeRef ! OutOfMemoryError ? &mut Allocator

Adds an unnamed node and returns its link.

Errors#

• OutOfMemoryError if the Allocator cannot grow the table.

Method named#

pub fn named(self: &Self, name: string<'static>) -> Option<ShapeRef>

Returns the node of the named type name, if the table has one, finished or pending.

Method reserve#

pub effect fn reserve(self: &mut Self, name: string<'static>) -> ShapeRef ! OutOfMemoryError ? &mut Allocator

Adds a pending node for the named type name and returns its link. Fill it with Shapes.set once its parts are described; a part that refers back to name meanwhile finds this node with Shapes.named.

Errors#

• OutOfMemoryError if the Allocator cannot grow the table.

Method set#

pub fn set(self: &mut Self, at: ShapeRef, shape: Shape) -> ()

Replaces the node at with shape.

Method nameOf#

pub fn nameOf(self: &Self, at: ShapeRef) -> string<'static>

Returns the name of the node at: its type's name for a struct or union, else empty text.

Category: Data formats.

Profiles: aarch64-apple-darwin, aarch64-unknown-linux-gnu, aarch64-unknown-linux-gnu-no-libc, x86_64-unknown-linux-gnu, x86_64-unknown-linux-gnu-no-libc, wasm32-unknown-unknown, wasm32-wasip1, wasm32-wasip2, x86_64-pc-windows-msvc, wasm64-unknown-unknown.