GizStackGizStack
View .mdOpen in ChatGPTOpen in Claude

gizlang/wire

Typed values as bytes on a wire: the one format that programs, hosts and peers built from the same source use to talk. The type is the schema. A record is its fields in order, with no names; a number is 8 bytes little-endian; a bool one byte; a string, bytes, Vec or Map a u32 count and then its items; an Option a byte (0 none, 1 some) and its value; a union's case its index as one byte and then its fields. Each type writes and reads itself: here the scalars and the containers, and the compiler gives each record and union its own (checker derivedMethod), from the helpers below. Json, a union, is written so too.

A program that reads the bytes in another language (a page's JavaScript: app/components/src/wire.js) takes the type's schema: schema<T>() is its fields and cases as JSON text, which the compiler writes for each record and union too.

JSON stays the codec for what a person or an outside API reads: encode(value, "json") writes gizlang/json's text of the same value, and decode reads it back.

gizlang
import * as Wire from "gizlang/wire";

Types

WireError

gizlang
type WireError = { offset: i64; message: string; }

Where the bytes stop being a T.

  • offset: i64
  • message: string

Reader

gizlang
type Reader = { data: bytes; at: i64; }

Bytes being read, from AT.

  • data: bytes
  • at: i64

Codec

gizlang
type Codec = "wire" | "json"

How a value is written: "wire", the compact binary form (the default and the fastest), or "json", text that a person or an outside API reads.

SchemaField

gizlang
type SchemaField = { name: string; type: string; }

One field of a schema's type: its name and its type (SchemaType.fields).

  • name: string
  • type: string

SchemaCase

gizlang
type SchemaCase = { kind: string; fields: Vec<SchemaField>; }

One case of a union, or a record's one case (KIND "").

  • kind: string
  • fields: Vec<gizlang_wire.SchemaField>

SchemaType

gizlang
type SchemaType = { name: string; union: bool; cases: Vec<SchemaCase>; }
  • name: string
  • union: bool
  • cases: Vec<gizlang_wire.SchemaCase>

Schema

gizlang
type Schema = { keys: Map<string, i64>; types: Vec<SchemaType>; open: Vec<i64>; refs: Vec<string>; }

A schema being written (schema). A type is a name ("f64", "i64", "u64", "bool", "string", "bytes"), {"vec": T}, {"option": T}, {"map": [K, V]}, or the index of a record or union in TYPES.

  • keys: _gizlang_sdk_collections.Map<string, i64>
  • types: Vec<gizlang_wire.SchemaType>
  • open: Vec<i64>
  • refs: Vec<string>

Functions

encode

gizlang
function encode<T>(value: T, codec: Codec = "wire"): bytes

VALUE as bytes in CODEC.

decode

gizlang
function decode<T>(data: bytes, codec: Codec = "wire"): T throws WireError

DATA as a T, as encode wrote it in CODEC. Bytes that end early, or run past the value, are an error.

schema

gizlang
function schema<T>(): string

T's wire schema as JSON: {"root": type, "types": [{"name", "fields": [[name, type], ...]} or {"name", "cases": [[kind, [[name, type], ...]], ...]}, ...]}. An untagged union's cases have the kind "" and one unnamed field.

schemaOpen

gizlang
function schemaOpen(out: mut Schema, key: string, name: string): bool

Starts the type KEY, named NAME, and whether it is new: a type met before (or being written) is its index alone.

Effects: fail, alloc.

schemaCase

gizlang
function schemaCase(out: mut Schema, kind: string): bool

Starts a union's case KIND; true, so a derived writeSchema writes the case's fields in its own scope.

Effects: fail, alloc.

schemaField

gizlang
function schemaField<T>(out: mut Schema, name: string, value: T): void

Adds the field NAME of VALUE's type to the open type's last case.

schemaEnd

gizlang
function schemaEnd(out: mut Schema): void

Ends the open type.

Effects: fail, alloc.

expectReader

gizlang
function expectReader(input: mut Reader): void throws WireError

Gives a derived readWire its types; reads nothing.

Effects: fail.

writeTag

gizlang
function writeTag(out: mut bytes, index: i64): void

Writes a union's case INDEX.

Effects: fail, alloc.

writeValue

gizlang
function writeValue<T>(out: mut bytes, value: T): void

Writes VALUE, an untagged union's case, as its own type does.

readTag

gizlang
function readTag(input: mut Reader): i64 throws WireError

Reads a union's case index.

Effects: fail.

unknownTag

gizlang
function unknownTag(tag: i64): void throws WireError

The error of a case index TAG that the union does not have.

Effects: fail, alloc.

Methods

f64.writeSchema

gizlang
function f64.writeSchema(self: f64, out: mut Schema): void

Effects: fail, alloc.

i64.writeSchema

gizlang
function i64.writeSchema(self: i64, out: mut Schema): void

Effects: fail, alloc.

u64.writeSchema

gizlang
function u64.writeSchema(self: u64, out: mut Schema): void

Effects: fail, alloc.

bool.writeSchema

gizlang
function bool.writeSchema(self: bool, out: mut Schema): void

Effects: fail, alloc.

string.writeSchema

gizlang
function string.writeSchema(self: string, out: mut Schema): void

Effects: fail, alloc.

bytes.writeSchema

gizlang
function bytes.writeSchema(self: bytes, out: mut Schema): void

Effects: fail, alloc.

Vec.writeSchema

gizlang
function Vec.writeSchema<T>(self: Vec<T>, out: mut Schema): void

Option.writeSchema

gizlang
function Option.writeSchema<T>(self: Option<T>, out: mut Schema): void

Map.writeSchema

gizlang
function Map.writeSchema<K, V>(self: Map<K, V>, out: mut Schema): void

f64.writeWire

gizlang
function f64.writeWire(self: f64, out: mut bytes): void

Writes the number: 8 bytes, little-endian.

Effects: fail, alloc.

i64.writeWire

gizlang
function i64.writeWire(self: i64, out: mut bytes): void

Writes the integer: 8 bytes, little-endian.

Effects: fail, alloc.

u64.writeWire

gizlang
function u64.writeWire(self: u64, out: mut bytes): void

Writes the integer: 8 bytes, little-endian.

Effects: fail, alloc.

bool.writeWire

gizlang
function bool.writeWire(self: bool, out: mut bytes): void

Writes the boolean: one byte.

Effects: fail, alloc.

string.writeWire

gizlang
function string.writeWire(self: string, out: mut bytes): void

Writes the string: its UTF-8 length as a u32, then its bytes.

Effects: fail, alloc.

bytes.writeWire

gizlang
function bytes.writeWire(self: bytes, out: mut bytes): void

Writes the bytes: their length as a u32, then them.

Effects: fail, alloc.

Vec.writeWire

gizlang
function Vec.writeWire<T>(self: Vec<T>, out: mut bytes): void

Writes the vector: its length as a u32, then each item.

Option.writeWire

gizlang
function Option.writeWire<T>(self: Option<T>, out: mut bytes): void

Writes 0 for none, else 1 and the value.

Map.writeWire

gizlang
function Map.writeWire<K, V>(self: Map<K, V>, out: mut bytes): void

Writes the map: its size as a u32, then each key and value.

f64.readWire

gizlang
function f64.readWire(self: mut f64, input: mut Reader): void throws WireError

Reads a number.

Effects: fail.

i64.readWire

gizlang
function i64.readWire(self: mut i64, input: mut Reader): void throws WireError

Reads an integer.

Effects: fail.

u64.readWire

gizlang
function u64.readWire(self: mut u64, input: mut Reader): void throws WireError

Reads an integer.

Effects: fail.

bool.readWire

gizlang
function bool.readWire(self: mut bool, input: mut Reader): void throws WireError

Reads a boolean; a byte other than 0 or 1 is an error.

Effects: fail.

string.readWire

gizlang
function string.readWire(self: mut string, input: mut Reader): void throws WireError

Reads a string; bytes that are not UTF-8 are an error.

Effects: fail, alloc.

bytes.readWire

gizlang
function bytes.readWire(self: mut bytes, input: mut Reader): void throws WireError

Reads bytes.

Effects: fail, alloc.

Vec.readWire

gizlang
function Vec.readWire<T>(self: mut Vec<T>, input: mut Reader): void throws WireError

Reads a vector, each item as T.

Option.readWire

gizlang
function Option.readWire<T>(self: mut Option<T>, input: mut Reader): void throws WireError

Reads 0 as none, and 1 and a T as the value.

Map.readWire

gizlang
function Map.readWire<K, V>(self: mut Map<K, V>, input: mut Reader): void throws WireError

Reads a map, each key as K and each value as V.