Documentation
¶
Overview ¶
The bytecode package contains definitions that are used in the communication between the compiler and the virtual machine.
Index ¶
- Constants
- Variables
- func DecodeInt32(bytecode []byte) int
- func DecodeUInt31(bytecode []byte) int
- func EncodeInt32(bytecode []byte, v int)
- func EncodeUInt31(bytecode []byte, v int)
- func ValuesEqual(a, b Value) bool
- type Chunk
- type CompiledStoryworld
- func (csw *CompiledStoryworld) AddConstant(value Value) int
- func (csw *CompiledStoryworld) Deserialize(r io.Reader) error
- func (csw *CompiledStoryworld) DisassembleChunk(chunk *Chunk, out io.Writer, debugInfo *DebugInfo, chunkIndex int)
- func (csw *CompiledStoryworld) DisassembleInstruction(chunk *Chunk, out io.Writer, offset int, debugInfo *DebugInfo, chunkIndex int) int
- func (csw *CompiledStoryworld) SearchConstant(value Value) int
- func (csw *CompiledStoryworld) Serialize(w io.Writer) errs.Error
- type DebugInfo
- type Lecture
- type OpCode
- type Procedure
- type Value
- func (v Value) AsBool() bool
- func (v Value) AsLecture() Lecture
- func (v Value) AsProcedure() Procedure
- func (v Value) AsString() string
- func (v Value) DebugString(debugInfo *DebugInfo) string
- func (v Value) IsBool() bool
- func (v Value) IsLecture() bool
- func (v Value) IsProcedure() bool
- func (v Value) IsString() bool
- func (v Value) Serialize(w io.Writer) errs.Error
- func (v Value) String() string
- type ValueKind
Constants ¶
const ( // MaxConstants is the maximum number of constants we can have on a // CompiledStoryworld. This is equal to 2^31, so that it fits on an int even // on platforms that use 32-bit integers. And this number should be large // enough to ensure we don't run out of space for constants. MaxConstants uint32 = 2_147_483_648 // CSWVersion is the current version of a Romualdo Compiled Storyworld. CSWVersion uint32 = 0 )
const ( // DebugInfoVersion is the current version of a Romualdo DebugInfo. DebugInfoVersion uint32 = 0 )
Variables ¶
var CSWMagic = []byte{0x52, 0x6D, 0x6C, 0x64, 0x43, 0x53, 0x57, 0x1A}
CSWMagic is the "magic number" identifying a Romualdo Compiled Storyworld. It is comprised of the "RmldCSW" string followed by a SUB character (which in times long gone used to represent a "soft end-of-file").
var DebugInfoMagic = []byte{0x52, 0x6D, 0x6C, 0x64, 0x44, 0x62, 0x67, 0x1A}
DebugInfoMagic is the "magic number" identifying a Romualdo DebugInfo. It is comprised of the "RmldDbg" string followed by a SUB character (which in times long gone used to represent a "soft end-of-file").
Functions ¶
func DecodeInt32 ¶
Decodes the first four bytes in bytecode into a signed 32-bit integer.
func DecodeUInt31 ¶
Decodes the first four bytes in bytecode into an unsigned 31-bit integer. Panics if the value read does not fit into 31 bits.
func EncodeInt32 ¶
Encodes a signed 32-bit integer into the four first bytes of bytecode.
func EncodeUInt31 ¶
Encodes an unsigned 31-bit integer into the four first bytes of bytecode. Panics if v does not fit into 31 bits.
func ValuesEqual ¶
ValuesEqual checks if a and b are considered equal.
Types ¶
type Chunk ¶
type Chunk struct {
// The bytecode itself. Includes both OpCodes and immediate arguments needed
// by the opcodes.
Code []uint8
}
A Chunk is a chunk of bytecode. We'll have one Chunk for each procedure in a Storyworld.
TODO: In the future, one chunk for each version of each procedure.
TODO: In the future, probably, chunks for implicitly-defined procedures that initialize globals and stuff.
type CompiledStoryworld ¶
type CompiledStoryworld struct {
// The constant values used in all Chunks.
Constants []Value
// Chunks is a slice with all Chunks of bytecode containing the compiled
// data. There is one Chunk for each procedure in the Storyworld.
//
// TODO: And in the future, one Chunk for every version of every procedure.
Chunks []*Chunk
// InitialChunk indexes the element in Chunks from where the Storyworld
// execution starts. In other words, it points to the latest version of the
// "/main" chunk.
InitialChunk int
}
CompiledStoryworld is a compiled, binary version of a Romualdo Language Storyworld.
TODO: Use a string interner to avoid having duplicate strings in memory. Make some measurements to ensure it's really beneficial.
func (*CompiledStoryworld) AddConstant ¶
func (csw *CompiledStoryworld) AddConstant(value Value) int
AddConstant adds a constant to the CompiledStoryworld and returns the index of the new constant into csw.Constants.
func (*CompiledStoryworld) Deserialize ¶
func (csw *CompiledStoryworld) Deserialize(r io.Reader) error
Deserialize deserializes a CompiledStoryworld from the given io.Reader.
func (*CompiledStoryworld) DisassembleChunk ¶
func (csw *CompiledStoryworld) DisassembleChunk(chunk *Chunk, out io.Writer, debugInfo *DebugInfo, chunkIndex int)
DisassembleChunk disassembles a whole chunk and writes the output to out. debugInfo is optional: if not nil, it will be used for better disassembly.
func (*CompiledStoryworld) DisassembleInstruction ¶
func (csw *CompiledStoryworld) DisassembleInstruction(chunk *Chunk, out io.Writer, offset int, debugInfo *DebugInfo, chunkIndex int) int
DisassembleInstruction disassembles the instruction at a given offset of chunk and returns the offset of the next instruction to disassemble. Output is written to out. chunkIndex is the index of the current chunk. debugInfo is optional: if not nil, it will be used for better disassembly.
func (*CompiledStoryworld) SearchConstant ¶
func (csw *CompiledStoryworld) SearchConstant(value Value) int
SearchConstant searches the constant pool for a constant with the given value. If found, it returns the index of this constant into csw.Constants. If not found, it returns a negative value.
type DebugInfo ¶
type DebugInfo struct {
// ChunksNames contains the names of the procedures on a CompiledStoryworld.
// There is one entry for each entry in the corresponding
// CompiledStoryworld.Chunks.
ChunksNames []string
// ChunksSourceFiles contains the source files every Chunk was compiled
// from. The indices here match those in CompiledStoryworld.Chunks. The file
// names here contain the path from the root of the Storyworld.
ChunksSourceFiles []string
// ChunksLines contains the source code line that generated each instruction
// of each Chunk. This must be interpreted like this:
// ChunksLines[chunkIndex][codeIndex] contains the line that generated the
// bytecode at CompiledStoryworld.Chunks[chunkIndex].Code[codeIndex].
//
// Notice that we have one entry for each entry in Code. Very
// space-inefficient, but very simple.
//
// TODO: Use run-length encoding (RLE) or something like that to spare some
// memory and storage.
ChunksLines [][]int
}
DebugInfo contains debug information matching a CompiledStoryworld. All information that is not strictly necessary to run a Storyworld but is useful for debugging, producing better error reporting, etc, belongs here.
type Lecture ¶
type Lecture struct {
// Text is the text of the Lecture.
Text string
}
Lecture is the runtime representation of a Lecture. Lectures are just strings, but we wrap them in a struct so that we can differentiate between strings and Lectures.
type Procedure ¶
type Procedure struct {
// ChunkIndex points to the Chunk that contains this function's bytecode.
// It's an index into the CompiledStoryworld slice of Chunks.
ChunkIndex int
}
Procedure is the runtime representation of a Procedure (i.e., a Passage or a Function). We don't include any sort of information about return and parameter types because type-checking is all done statically at compile-time.
type Value ¶
type Value struct {
Value interface{}
}
Value is a Romualdo language value.
func DeserializeValue ¶
DeserializeValue deserializes a Value from the given io.Reader.
func NewValueBool ¶
NewValueBool creates a new Value of type bool, representing a Boolean with the given value.
func NewValueLecture ¶
NewValueLecture creates a new Value of type Lecture, representing a Lecture with the given text.
func NewValueProcedure ¶
NewValueProcedure creates a new Value of type Procedure, representing a Procedure that will run the code at the given Chunk index.
func NewValueString ¶
NewValueString creates a new Value of type string, representing a string with the given text.
func (Value) AsProcedure ¶
AsProcedure returns this Value's value, assuming it is a Procedure value.
func (Value) DebugString ¶
DebugString converts the value to a string usable in debug contexts. debugInfo can be nil (but this will result in less information in the resulting strings).
func (Value) IsProcedure ¶
IsProcedure checks if the value contains a Procedure value.
type ValueKind ¶
type ValueKind int
A ValueKind represents one of the types a value in the Romualdo Virtual Machine can have. This is the type from the perspective of the VM (in the sense that user-defined types are obviously not directly represented here). We use "kind" in the name because "type" is a keyword in Go.
Source Files