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.
import * as Wire from "gizlang/wire";Types
WireError
type WireError = { offset: i64; message: string; }Where the bytes stop being a T.
offset:i64message:string
Reader
type Reader = { data: bytes; at: i64; }Bytes being read, from AT.
data:bytesat:i64
Codec
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
type SchemaField = { name: string; type: string; }One field of a schema's type: its name and its type (SchemaType.fields).
name:stringtype:string
SchemaCase
type SchemaCase = { kind: string; fields: Vec<SchemaField>; }One case of a union, or a record's one case (KIND "").
kind:stringfields:Vec<gizlang_wire.SchemaField>
SchemaType
type SchemaType = { name: string; union: bool; cases: Vec<SchemaCase>; }name:stringunion:boolcases:Vec<gizlang_wire.SchemaCase>
Schema
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
function encode<T>(value: T, codec: Codec = "wire"): bytesVALUE as bytes in CODEC.
decode
function decode<T>(data: bytes, codec: Codec = "wire"): T throws WireErrorDATA as a T, as encode wrote it in CODEC. Bytes that end early, or run past the value, are an error.
schema
function schema<T>(): stringT'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
function schemaOpen(out: mut Schema, key: string, name: string): boolStarts 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
function schemaCase(out: mut Schema, kind: string): boolStarts a union's case KIND; true, so a derived writeSchema writes the case's fields in its own scope.
Effects: fail, alloc.
schemaField
function schemaField<T>(out: mut Schema, name: string, value: T): voidAdds the field NAME of VALUE's type to the open type's last case.
schemaEnd
function schemaEnd(out: mut Schema): voidEnds the open type.
Effects: fail, alloc.
expectReader
function expectReader(input: mut Reader): void throws WireErrorGives a derived readWire its types; reads nothing.
Effects: fail.
writeTag
function writeTag(out: mut bytes, index: i64): voidWrites a union's case INDEX.
Effects: fail, alloc.
writeValue
function writeValue<T>(out: mut bytes, value: T): voidWrites VALUE, an untagged union's case, as its own type does.
readTag
function readTag(input: mut Reader): i64 throws WireErrorReads a union's case index.
Effects: fail.
unknownTag
function unknownTag(tag: i64): void throws WireErrorThe error of a case index TAG that the union does not have.
Effects: fail, alloc.
Methods
f64.writeSchema
function f64.writeSchema(self: f64, out: mut Schema): voidEffects: fail, alloc.
i64.writeSchema
function i64.writeSchema(self: i64, out: mut Schema): voidEffects: fail, alloc.
u64.writeSchema
function u64.writeSchema(self: u64, out: mut Schema): voidEffects: fail, alloc.
bool.writeSchema
function bool.writeSchema(self: bool, out: mut Schema): voidEffects: fail, alloc.
string.writeSchema
function string.writeSchema(self: string, out: mut Schema): voidEffects: fail, alloc.
bytes.writeSchema
function bytes.writeSchema(self: bytes, out: mut Schema): voidEffects: fail, alloc.
Vec.writeSchema
function Vec.writeSchema<T>(self: Vec<T>, out: mut Schema): voidOption.writeSchema
function Option.writeSchema<T>(self: Option<T>, out: mut Schema): voidMap.writeSchema
function Map.writeSchema<K, V>(self: Map<K, V>, out: mut Schema): voidf64.writeWire
function f64.writeWire(self: f64, out: mut bytes): voidWrites the number: 8 bytes, little-endian.
Effects: fail, alloc.
i64.writeWire
function i64.writeWire(self: i64, out: mut bytes): voidWrites the integer: 8 bytes, little-endian.
Effects: fail, alloc.
u64.writeWire
function u64.writeWire(self: u64, out: mut bytes): voidWrites the integer: 8 bytes, little-endian.
Effects: fail, alloc.
bool.writeWire
function bool.writeWire(self: bool, out: mut bytes): voidWrites the boolean: one byte.
Effects: fail, alloc.
string.writeWire
function string.writeWire(self: string, out: mut bytes): voidWrites the string: its UTF-8 length as a u32, then its bytes.
Effects: fail, alloc.
bytes.writeWire
function bytes.writeWire(self: bytes, out: mut bytes): voidWrites the bytes: their length as a u32, then them.
Effects: fail, alloc.
Vec.writeWire
function Vec.writeWire<T>(self: Vec<T>, out: mut bytes): voidWrites the vector: its length as a u32, then each item.
Option.writeWire
function Option.writeWire<T>(self: Option<T>, out: mut bytes): voidWrites 0 for none, else 1 and the value.
Map.writeWire
function Map.writeWire<K, V>(self: Map<K, V>, out: mut bytes): voidWrites the map: its size as a u32, then each key and value.
f64.readWire
function f64.readWire(self: mut f64, input: mut Reader): void throws WireErrorReads a number.
Effects: fail.
i64.readWire
function i64.readWire(self: mut i64, input: mut Reader): void throws WireErrorReads an integer.
Effects: fail.
u64.readWire
function u64.readWire(self: mut u64, input: mut Reader): void throws WireErrorReads an integer.
Effects: fail.
bool.readWire
function bool.readWire(self: mut bool, input: mut Reader): void throws WireErrorReads a boolean; a byte other than 0 or 1 is an error.
Effects: fail.
string.readWire
function string.readWire(self: mut string, input: mut Reader): void throws WireErrorReads a string; bytes that are not UTF-8 are an error.
Effects: fail, alloc.
bytes.readWire
function bytes.readWire(self: mut bytes, input: mut Reader): void throws WireErrorReads bytes.
Effects: fail, alloc.
Vec.readWire
function Vec.readWire<T>(self: mut Vec<T>, input: mut Reader): void throws WireErrorReads a vector, each item as T.
Option.readWire
function Option.readWire<T>(self: mut Option<T>, input: mut Reader): void throws WireErrorReads 0 as none, and 1 and a T as the value.
Map.readWire
function Map.readWire<K, V>(self: mut Map<K, V>, input: mut Reader): void throws WireErrorReads a map, each key as K and each value as V.