Documentation
¶
Index ¶
- Constants
- Variables
- func Encode(w io.Writer, m *Module) error
- func EncodeBundle(w io.Writer, consts *vm.Consts, nsChunks map[string]*vm.CodeChunk) error
- func EncodeBundleOrdered(w io.Writer, consts *vm.Consts, nsChunks map[string]*vm.CodeChunk, ...) error
- func EncodeCompilation(w io.Writer, consts *vm.Consts, mainChunk *vm.CodeChunk) error
- func EncodeModule(w io.Writer, consts *vm.Consts, chunks []*vm.CodeChunk) error
- type ChunkData
- type ExecUnit
- type LocalVarEntry
- type Module
- type ModuleBuilder
- type Reader
- func (r *Reader) ReadByte() (byte, error)
- func (r *Reader) ReadBytes(n int) ([]byte, error)
- func (r *Reader) ReadFloat64() (float64, error)
- func (r *Reader) ReadInt32() (int32, error)
- func (r *Reader) ReadSvarint() (int64, error)
- func (r *Reader) ReadUint16() (uint16, error)
- func (r *Reader) ReadUint32() (uint32, error)
- func (r *Reader) ReadVarint() (uint64, error)
- type SourceEntry
- type VarResolver
- type Writer
- func (w *Writer) Flush() error
- func (w *Writer) WriteByte(b byte) error
- func (w *Writer) WriteBytes(b []byte) error
- func (w *Writer) WriteFloat64(v float64) error
- func (w *Writer) WriteInt32(v int32) error
- func (w *Writer) WriteSvarint(v int64) error
- func (w *Writer) WriteUint16(v uint16) error
- func (w *Writer) WriteUint32(v uint32) error
- func (w *Writer) WriteVarint(v uint64) error
Constants ¶
const ( FlagConstsBase uint16 = 1 << 0 // ConstsBase field is present in consts section FlagCapabilities uint16 = 1 << 1 // Capability mask follows the header FlagLocalVars uint16 = 1 << 2 // per-chunk local-variable debug tables follow the NS table (v2+) )
Module flags.
const ( TagVer0 byte = iota << tagVersionShift TagVer1 TagVer2 TagVer3 )
Tag versions.
const ( TagIDNil byte = 0x00 TagIDTrue byte = 0x01 TagIDFalse byte = 0x02 TagIDInt byte = 0x03 TagIDFloat byte = 0x04 TagIDString byte = 0x05 TagIDKeyword byte = 0x06 TagIDSymbol byte = 0x07 TagIDChar byte = 0x08 TagIDBigInt byte = 0x09 TagIDVoid byte = 0x0A TagIDUUID byte = 0x0B TagIDInstant byte = 0x0C TagIDFunc byte = 0x10 TagIDVarRef byte = 0x11 TagIDEmptyList byte = 0x20 TagIDList byte = 0x21 TagIDVector byte = 0x22 TagIDMap byte = 0x23 TagIDSet byte = 0x24 TagIDRecordType byte = 0x30 TagIDRecord byte = 0x31 TagIDRegex byte = 0x32 TagIDAtom byte = 0x33 )
Tag IDs (6-bit). These are the semantic tag identifiers.
const ( TagNil byte = TagIDNil | TagVer0 TagTrue byte = TagIDTrue | TagVer0 TagFalse byte = TagIDFalse | TagVer0 TagInt byte = TagIDInt | TagVer0 TagFloat byte = TagIDFloat | TagVer0 TagString byte = TagIDString | TagVer0 TagKeyword byte = TagIDKeyword | TagVer0 TagSymbol byte = TagIDSymbol | TagVer0 TagChar byte = TagIDChar | TagVer0 TagBigInt byte = TagIDBigInt | TagVer0 TagVoid byte = TagIDVoid | TagVer0 TagUUID byte = TagIDUUID | TagVer0 TagInstant byte = TagIDInstant | TagVer0 TagFunc byte = TagIDFunc | TagVer0 TagVarRef byte = TagIDVarRef | TagVer0 TagEmptyList byte = TagIDEmptyList | TagVer0 TagList byte = TagIDList | TagVer0 TagVector byte = TagIDVector | TagVer0 TagMap byte = TagIDMap | TagVer0 TagSet byte = TagIDSet | TagVer0 TagRecordType byte = TagIDRecordType | TagVer0 TagRecord byte = TagIDRecord | TagVer0 TagRegex byte = TagIDRegex | TagVer0 TagAtom byte = TagIDAtom | TagVer0 )
Tag byte values (version 0). These are the actual bytes on the wire for the initial v2 release. They are byte-identical to v1 tags.
const ( TagIDReserved0 byte = 0x34 TagIDReserved1 byte = 0x35 TagIDReserved2 byte = 0x36 TagIDReserved3 byte = 0x37 TagIDReserved4 byte = 0x38 TagIDReserved5 byte = 0x39 TagIDReserved6 byte = 0x3A TagIDReserved7 byte = 0x3B TagIDReserved8 byte = 0x3C TagIDReserved9 byte = 0x3D TagIDReserved10 byte = 0x3E TagIDReserved11 byte = 0x3F )
Reserved tag IDs for future standard tags (0x34–0x3F).
const FormatVersion uint16 = 2
FormatVersion is the current serialization format version.
Variables ¶
var Magic = [4]byte{'L', 'G', 'B', 0x01}
Magic bytes identifying an LGB file.
Functions ¶
func EncodeBundle ¶
EncodeBundle serializes a multi-namespace compilation bundle. Namespaces are registered in sorted name order so output is deterministic across runs; callers that need a specific load order should use EncodeBundleOrdered instead.
func EncodeBundleOrdered ¶ added in v1.3.5
func EncodeBundleOrdered(w io.Writer, consts *vm.Consts, nsChunks map[string]*vm.CodeChunk, nsOrder []string) error
EncodeBundleOrdered serializes a multi-namespace bundle with explicit ordering. nsOrder determines the chunk index assignment (lower index = earlier dependency).
func EncodeCompilation ¶
EncodeCompilation serializes a compilation result (main chunk + const pool). The main chunk is always chunk index 0. All CodeChunks referenced by Funcs in the const pool are collected automatically. If consts is a child pool, only the child's entries are serialized with the base offset stored so the decoder can reconstruct the layering.
Types ¶
type ChunkData ¶
type ChunkData struct {
MaxStack int
Code []int32
SourceMap []SourceEntry
// LocalVars is the chunk's local-variable debug table (slot -> name),
// serialized in an optional section under FlagLocalVars.
LocalVars []LocalVarEntry
}
ChunkData holds the data for a single code chunk.
type ExecUnit ¶
type ExecUnit struct {
Consts *vm.Consts
MainChunk *vm.CodeChunk
// NSChunks maps namespace names to their main chunks (for bundles).
NSChunks map[string]*vm.CodeChunk
// NSOrder lists namespace names in chunk index order (load/dependency order).
NSOrder []string
}
ExecUnit is a decoded compilation unit ready for execution.
func DecodeToExecUnit ¶
func DecodeToExecUnit(r io.Reader, resolve VarResolver) (*ExecUnit, error)
DecodeToExecUnit decodes an LGB module and returns a ready-to-execute unit. The main chunk is chunk index 0. All decoded consts are populated into a shared Consts pool that all chunks reference.
func DecodeToExecUnitWithParent ¶
func DecodeToExecUnitWithParent(r io.Reader, resolve VarResolver, parent *vm.Consts) (*ExecUnit, error)
DecodeToExecUnitWithParent decodes an LGB module with an optional parent const pool. If parent is non-nil and the module has a ConstsBase, the decoded consts are layered on top of the parent pool — indices < base resolve from the parent.
type LocalVarEntry ¶ added in v1.10.0
LocalVarEntry is a local-variable debug entry for serialization.
type Module ¶
type Module struct {
Version uint16
Flags uint16
// Capabilities is an optional feature mask. If FlagCapabilities is set in Flags,
// a uint32 capability mask follows the header. Bits indicate optional features
// the decoder must support. Currently no capability bits are defined (all reserved).
Capabilities uint32
Strings []string
Chunks []*ChunkData
Consts []vm.Value
// ConstsBase is the starting global index for the consts in this module.
// For layered pools, indices 0..ConstsBase-1 are in a parent pool.
ConstsBase int
// NSTable maps namespace names to their main chunk indices (for bundles).
NSTable map[string]int
}
Module is the serializable unit — a complete compilation result.
func DecodeWithResolver ¶
func DecodeWithResolver(r io.Reader, resolve VarResolver) (*Module, error)
DecodeWithResolver reads a binary module, resolving var references with the given function.
type ModuleBuilder ¶
type ModuleBuilder struct {
// contains filtered or unexported fields
}
ModuleBuilder collects strings, chunks, and consts for serialization.
func NewModuleBuilder ¶
func NewModuleBuilder() *ModuleBuilder
NewModuleBuilder creates a new builder.
func (*ModuleBuilder) AddChunk ¶
func (b *ModuleBuilder) AddChunk(c *vm.CodeChunk) int
AddChunk registers a CodeChunk and interns its strings.
func (*ModuleBuilder) AddConst ¶
func (b *ModuleBuilder) AddConst(v vm.Value)
AddConst registers a const value and interns related strings/chunks.
func (*ModuleBuilder) ChunkIndex ¶
func (b *ModuleBuilder) ChunkIndex(c *vm.CodeChunk) (int, bool)
ChunkIndex returns the index for a given CodeChunk pointer.
func (*ModuleBuilder) SetNSEntry ¶
func (b *ModuleBuilder) SetNSEntry(name string, chunk *vm.CodeChunk)
SetNSEntry records a namespace name → main chunk mapping for bundle modules.
type Reader ¶
type Reader struct {
// contains filtered or unexported fields
}
Reader wraps a buffered reader with binary decoding helpers.
func (*Reader) ReadFloat64 ¶
ReadFloat64 reads an IEEE 754 little-endian float64.
func (*Reader) ReadSvarint ¶
ReadSvarint reads a signed zigzag-encoded varint.
func (*Reader) ReadUint16 ¶
ReadUint16 reads a little-endian uint16.
func (*Reader) ReadUint32 ¶ added in v1.9.0
ReadUint32 reads a little-endian uint32.
func (*Reader) ReadVarint ¶
ReadVarint reads an unsigned LEB128-encoded integer.
type SourceEntry ¶
SourceEntry is a source map entry for serialization.
type VarResolver ¶
VarResolver resolves a var reference by namespace and name.
type Writer ¶
type Writer struct {
// contains filtered or unexported fields
}
Writer wraps a buffered writer with binary encoding helpers.
func (*Writer) WriteBytes ¶
WriteBytes writes a byte slice.
func (*Writer) WriteFloat64 ¶
WriteFloat64 writes an IEEE 754 little-endian float64.
func (*Writer) WriteInt32 ¶
WriteInt32 writes a little-endian int32.
func (*Writer) WriteSvarint ¶
WriteSvarint writes a signed zigzag-encoded varint.
func (*Writer) WriteUint16 ¶
WriteUint16 writes a little-endian uint16.
func (*Writer) WriteUint32 ¶ added in v1.9.0
WriteUint32 writes a little-endian uint32.
func (*Writer) WriteVarint ¶
WriteVarint writes an unsigned LEB128-encoded integer.