# gizlang:protobuf the Protocol Buffers wire format. A message is a list of fields; a field has a number, a wire type and its value: a varint, a fixed 32 or 64 bit word (both in `value`), or length-delimited bytes (a string, bytes, a nested message or a packed list, in `data`). The schema is the caller's: it reads the numbers it knows and skips the rest, as the format asks. ```gizlang import * as Protobuf from "gizlang:protobuf"; ``` ## Types ### `Field` ```gizlang type Field = { number: i64; wire: i64; value: i64; data: bytes; } ``` One field of a message. - `number`: `i64` - `wire`: `i64` - `value`: `i64` - `data`: `bytes` ### `Wire` ```gizlang type Wire = { data: bytes; at: i64; end: i64; } ``` A message read in place: its bytes and the range [at, end) still to read. Nothing is copied until a caller slices. - `data`: `bytes` - `at`: `i64` - `end`: `i64` ### `Span` ```gizlang type Span = { number: i64; wire: i64; value: u64; start: i64; end: i64; } ``` A field read in place: its number, its wire type, the bits of a varint or a fixed word, and the range [start, end) of its bytes (of length-delimited bytes, their content). - `number`: `i64` - `wire`: `i64` - `value`: `u64` - `start`: `i64` - `end`: `i64` ## Functions ### `varintField` ```gizlang function varintField(number: i64, value: i64): Field ``` A varint field (int32, int64, uint32, uint64, bool, enum); use zigzag for sint32 and sint64. ### `bytesField` ```gizlang function bytesField(number: i64, data: bytes): Field ``` A bytes field. ### `stringField` ```gizlang function stringField(number: i64, text: string): Field ``` A string field. ### `messageField` ```gizlang function messageField(number: i64, fields: Vec): Field ``` A nested message field. Effects: fail. ### `fixed32Field` ```gizlang function fixed32Field(number: i64, value: i64): Field ``` A fixed32 field (fixed32, sfixed32, float bits). ### `fixed64Field` ```gizlang function fixed64Field(number: i64, value: i64): Field ``` A fixed64 field (fixed64, sfixed64, double bits). ### `packedField` ```gizlang function packedField(number: i64, values: Vec): Field ``` A packed list of varints in one field. Effects: fail. ### `zigzag` ```gizlang function zigzag(value: i64): i64 ``` The sint32 or sint64 encoding of a signed value. Effects: fail. ### `unzigzag` ```gizlang function unzigzag(value: i64): i64 ``` The signed value of a zigzag encoding. Effects: fail. ### `encode` ```gizlang function encode(fields: Vec): bytes ``` The wire form of a message. Effects: fail. ### `reader` ```gizlang function reader(data: bytes): Wire ``` A reader of all of `data`. ### `decode` ```gizlang function decode(data: bytes): Vec throws string ``` The fields of a message, in order; an error for a field that is cut, a number of 0 or a group (wire type 3 or 4). Effects: fail. ### `last` ```gizlang function last(fields: Vec, number: i64): Option ``` The last field with `number`: a repeated scalar keeps its last value. Effects: fail. ### `all` ```gizlang function all(fields: Vec, number: i64): Vec ``` Every field with `number`, in order (a repeated field). Effects: fail. ### `unpacked` ```gizlang function unpacked(field: Field): Vec throws string ``` The varints of a packed field (or of one field that was not packed). Effects: fail. ## Methods ### `Wire.varint` ```gizlang function Wire.varint(self: mut Wire): u64 throws string ``` The next varint. Effects: fail. ### `Wire.take` ```gizlang function Wire.take(self: mut Wire, n: i64): Wire throws string ``` The next `n` bytes, as a reader of their own. Effects: fail. ### `Wire.block` ```gizlang function Wire.block(self: mut Wire): Wire throws string ``` The next length-delimited bytes, as a reader of their own. Effects: fail. ### `Wire.next` ```gizlang function Wire.next(self: mut Wire): Span throws string ``` The next field. Effects: fail. ### `Wire.skip` ```gizlang function Wire.skip(self: mut Wire, wire: i64): bool throws string ``` Passes the value of a field of wire type `wire`, after its tag. Effects: fail. ### `Wire.inner` ```gizlang function Wire.inner(self: Wire, f: Span): Wire ``` A reader of a length-delimited field's bytes. ## Constants ### `VARINT` ```gizlang const VARINT = 0 ``` The wire types of a field. ### `FIXED64` ```gizlang const FIXED64 = 1 ``` The wire type of a fixed 64-bit word. ### `BYTES` ```gizlang const BYTES = 2 ``` The wire type of length-delimited bytes. ### `FIXED32` ```gizlang const FIXED32 = 5 ``` The wire type of a fixed 32-bit word.