silk.schema.path.

When to use#

Read a SchemaPath from a silk.schema.issue.SchemaError to say where a value failed, as settings.ports[2] for a person with SchemaPath.text, or as the JSON Pointer /settings/ports/2 for a tool with SchemaPath.pointer.

Details#

A path keeps its steps, not text, so one error renders in every form. A field step holds both the field's Silk name and its name on the wire, and a variant step names the variant a tagged union chose, so auth.Basic.user says which variant user belongs to.

Import as SchemaPath with import silk.schema.path { SchemaPath }.

Public declarations: 2.

PathSegment#

pub union PathSegment

One step of a SchemaPath: a struct field, the variant a union chose, or a list element.

Field#

Field

A struct or variant field.

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, which Spec.rename may change.

Variant#

Variant

The variant a tagged union chose. Its fields follow it in the path.

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.

Index#

Index

A list element.

Field at#

pub at: usize

The position of the element, from 0.

Implementation Copy for PathSegment#

impl Copy for PathSegment

SchemaPath#

pub struct SchemaPath

The path from the root value to the part a reader is reading, such as settings.ports[2].

When to use#

A format's SchemaReader keeps one and returns it from SchemaReader.path. The derived read operations push a segment before they read a part and pop it after, so when a read fails the path still names the part that failed.

Implementation SchemaPath#

impl SchemaPath

Associated function make#

pub fn make() -> SchemaPath

Returns an empty path, which names the root value.

Method copy#

pub effect fn copy(self: &Self) -> SchemaPath ! OutOfMemoryError ? &mut Allocator

Returns a path with the same segments as self.

Errors#

• OutOfMemoryError if the Allocator cannot supply the copy.

Method push#

pub effect fn push(self: &mut Self, segment: PathSegment) -> () ! OutOfMemoryError ? &mut Allocator

Adds segment at the end of the path.

Errors#

• OutOfMemoryError if the Allocator cannot grow the path.

Method pop#

pub fn pop(self: &mut Self) -> ()

Removes the last segment. It does nothing to an empty path.

Method truncate#

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

Removes segments from the end until length remain.

Method length#

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

Returns the number of segments.

Method segments#

pub fn segments(self: &Self) -> &[PathSegment]

Returns the segments, from the root value outward.

Method matchesText#

pub fn matchesText(self: &Self, text: string) -> bool

Returns whether text is the path as SchemaPath.text writes it, without allocating.

Method text#

pub effect fn text(self: &Self) -> String ! OutOfMemoryError ? &mut Allocator

Returns the path for a person, with wire names, such as auth.Basic.user or ports[2]. The root value is empty text.

Errors#

• OutOfMemoryError if the Allocator cannot supply the text.

Method names#

pub effect fn names(self: &Self) -> String ! OutOfMemoryError ? &mut Allocator

Returns the path with Silk names, such as auth.Basic.user or idleSeconds, for code that matches on a type's own field names.

Errors#

• OutOfMemoryError if the Allocator cannot supply the text.

Method pointer#

pub effect fn pointer(self: &Self) -> String ! OutOfMemoryError ? &mut Allocator

Returns the path as a JSON Pointer (RFC 6901) into the input, such as /auth/user or /ports/2. A variant step is left out, because the input has no member for it. The root value is empty text.

Errors#

• OutOfMemoryError if the Allocator cannot supply the text.

Implementation Debug for SchemaPath#

impl Debug for SchemaPath

Operation debug#

effect fn debug(self: &Self, formatter: &mut Formatter) -> () ! WriterError ? &mut Writer

Writes the path as text returns it, in quotes, such as "ports[2]".

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.