bytecode

package
v1.11.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jun 28, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Index

Constants

View Source
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.

View Source
const (
	TagVer0 byte = iota << tagVersionShift
	TagVer1
	TagVer2
	TagVer3
)

Tag versions.

View Source
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.

View Source
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.

View Source
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).

View Source
const FormatVersion uint16 = 2

FormatVersion is the current serialization format version.

Variables

View Source
var Magic = [4]byte{'L', 'G', 'B', 0x01}

Magic bytes identifying an LGB file.

Functions

func Encode

func Encode(w io.Writer, m *Module) error

Encode serializes a Module to binary format.

func EncodeBundle

func EncodeBundle(w io.Writer, consts *vm.Consts, nsChunks map[string]*vm.CodeChunk) error

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

func EncodeCompilation(w io.Writer, consts *vm.Consts, mainChunk *vm.CodeChunk) error

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.

func EncodeModule

func EncodeModule(w io.Writer, consts *vm.Consts, chunks []*vm.CodeChunk) error

EncodeModule builds a Module from live VM objects and serializes it.

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

type LocalVarEntry struct {
	Slot int
	Name string
}

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 Decode

func Decode(r io.Reader) (*Module, error)

Decode reads a binary module from r.

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) Build

func (b *ModuleBuilder) Build() *Module

Build creates the Module.

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 NewReader

func NewReader(r io.Reader) *Reader

NewReader creates a Reader wrapping r.

func (*Reader) ReadByte

func (r *Reader) ReadByte() (byte, error)

ReadByte reads a single byte.

func (*Reader) ReadBytes

func (r *Reader) ReadBytes(n int) ([]byte, error)

ReadBytes reads exactly n bytes.

func (*Reader) ReadFloat64

func (r *Reader) ReadFloat64() (float64, error)

ReadFloat64 reads an IEEE 754 little-endian float64.

func (*Reader) ReadInt32

func (r *Reader) ReadInt32() (int32, error)

ReadInt32 reads a little-endian int32.

func (*Reader) ReadSvarint

func (r *Reader) ReadSvarint() (int64, error)

ReadSvarint reads a signed zigzag-encoded varint.

func (*Reader) ReadUint16

func (r *Reader) ReadUint16() (uint16, error)

ReadUint16 reads a little-endian uint16.

func (*Reader) ReadUint32 added in v1.9.0

func (r *Reader) ReadUint32() (uint32, error)

ReadUint32 reads a little-endian uint32.

func (*Reader) ReadVarint

func (r *Reader) ReadVarint() (uint64, error)

ReadVarint reads an unsigned LEB128-encoded integer.

type SourceEntry

type SourceEntry struct {
	StartIP                          int
	File                             string
	Line, Column, EndLine, EndColumn int
}

SourceEntry is a source map entry for serialization.

type VarResolver

type VarResolver func(ns, name string) *vm.Var

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 NewWriter

func NewWriter(w io.Writer) *Writer

NewWriter creates a Writer wrapping w.

func (*Writer) Flush

func (w *Writer) Flush() error

Flush flushes the underlying buffer.

func (*Writer) WriteByte

func (w *Writer) WriteByte(b byte) error

WriteByte writes a single byte.

func (*Writer) WriteBytes

func (w *Writer) WriteBytes(b []byte) error

WriteBytes writes a byte slice.

func (*Writer) WriteFloat64

func (w *Writer) WriteFloat64(v float64) error

WriteFloat64 writes an IEEE 754 little-endian float64.

func (*Writer) WriteInt32

func (w *Writer) WriteInt32(v int32) error

WriteInt32 writes a little-endian int32.

func (*Writer) WriteSvarint

func (w *Writer) WriteSvarint(v int64) error

WriteSvarint writes a signed zigzag-encoded varint.

func (*Writer) WriteUint16

func (w *Writer) WriteUint16(v uint16) error

WriteUint16 writes a little-endian uint16.

func (*Writer) WriteUint32 added in v1.9.0

func (w *Writer) WriteUint32(v uint32) error

WriteUint32 writes a little-endian uint32.

func (*Writer) WriteVarint

func (w *Writer) WriteVarint(v uint64) error

WriteVarint writes an unsigned LEB128-encoded integer.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL