vm

Documentation

Overview

Package vm implements the virtual machine used to run the bytecode generated by http://github.com/lestrrat-go/xslate/compiler

The virtual machine is an extremely simple one: each opcode in the bytecode sequence returns the next opcode to execute. The virtual machine just keeps on calling the opcode until we reach the "end" opcode.

The virtual machine accepts the bytecode, and input variables:

vm.Run(bytecode, variables)

Index

• type ByteCode
  • func NewByteCode() *ByteCode
  • func (b *ByteCode) Append(op Op)
  • func (b *ByteCode) AppendOp(o OpType, args ...interface{}) Op
  • func (b *ByteCode) Get(i int) Op
  • func (b *ByteCode) Len() int
  • func (b *ByteCode) String() string
• type LoopVar
  • func NewLoopVar(idx int, array reflect.Value) *LoopVar
• type Op
  • func NewOp(o OpType, args ...interface{}) Op
• type OpHandler
• type OpType
  • func (o OpType) String() string
  • func (o OpType) Type() OpType
• type State
  • func NewState() *State
  • func (st *State) Advance()
  • func (st *State) AdvanceBy(i int)
  • func (st *State) AdvanceTo(i int)
  • func (st *State) AppendOutput(b []byte)
  • func (st *State) AppendOutputString(o string)
  • func (st *State) CurrentFrame() *frame.Frame
  • func (st *State) CurrentMark() int
  • func (st *State) CurrentOp() Op
  • func (st *State) CurrentPos() int
  • func (st *State) LoadByteCode(key string) (*ByteCode, error)
  • func (st *State) PopFrame() *frame.Frame
  • func (st *State) Popmark() int
  • func (st *State) PushFrame() *frame.Frame
  • func (st *State) Pushmark()
  • func (st *State) Reset()
  • func (st *State) StackPop() interface{}
  • func (st *State) StackPush(v interface{})
  • func (st *State) StackTip() int
  • func (st *State) Vars() Vars
  • func (st *State) Warnf(format string, args ...interface{})
• type VM
  • func NewVM() *VM
  • func (vm *VM) CurrentOp() Op
  • func (vm *VM) IsSupportedByteCodeVersion(bc *ByteCode) bool
  • func (vm *VM) Run(bc *ByteCode, vars Vars, output io.Writer)
  • func (vm *VM) SetFunctions(vars Vars)
• type Vars
  • func (v Vars) Get(k interface{}) (interface{}, bool)
  • func (v *Vars) Reset()
  • func (v Vars) Set(k string, x interface{})

Types

type ByteCode

type ByteCode struct {
	OpList      []Op
	GeneratedOn time.Time
	Name        string
	Version     float32
}

ByteCode is the collection of op codes that the Xslate Virtual Machine should run. It is created from a compiler.Compiler

func NewByteCode

func NewByteCode() *ByteCode

NewByteCode creates an empty ByteCode instance.

func (*ByteCode) Append

func (b *ByteCode) Append(op Op)

Append appends an op code to the current list of op codes.

func (*ByteCode) AppendOp

func (b *ByteCode) AppendOp(o OpType, args ...interface{}) Op

AppendOp is an utility method to create AND append a new op code to the current list of op codes

func (*ByteCode) Get

func (b *ByteCode) Get(i int) Op

Get returns an vm.Op struct at location i. No check is performed to see if this index is valid

func (*ByteCode) Len

func (b *ByteCode) Len() int

Len returns the number of op codes in this ByteCode instance

func (*ByteCode) String

func (b *ByteCode) String() string

String returns the textual representation of this ByteCode

type LoopVar

type LoopVar struct {
	Index    int           // 0 origin, current index
	Count    int           // loop.Index + 1
	Body     reflect.Value // alias to array
	Size     int           // len(loop.Body)
	MaxIndex int           // loop.Size - 1
	PeekNext interface{}   // previous item. nil if not available
	PeekPrev interface{}   // next item. nil if not available
	IsFirst  bool          // true only if Index == 0
	IsLast   bool          // true only if Index == MaxIndex
}

LoopVar is the variable available within FOREACH loops

func NewLoopVar

func NewLoopVar(idx int, array reflect.Value) *LoopVar

NewLoopVar creates the loop variable

type Op

type Op interface {
	Arg() interface{}
	ArgString() string
	ArgInt() int
	Call(*State)
	Comment() string
	Handler() OpHandler
	SetArg(interface{})
	SetComment(string)
	String() string
	Type() OpType
}

Op represents a single op. It has an OpType, OpHandler, and an optional parameter to be used

func NewOp

func NewOp(o OpType, args ...interface{}) Op

NewOp creates a new Op.

type OpHandler

type OpHandler func(*State)

OpHandler describes an op's actual code

type OpType

type OpType int

OpType is an integer identifying the type of op code

const (
	TXOPNoop OpType = iota
	TXOPNil
	TXOPMoveToSb
	TXOPMoveFromSb
	TXOPLiteral
	TXOPFetchSymbol
	TXOPFetchFieldSymbol
	TXOPFetchArrayElement
	TXOPMarkRaw
	TXOPUnmarkRaw
	TXOPPrint
	TXOPPrintRaw
	TXOPPrintRawConst
	TXOPSaveToLvar
	TXOPLoadLvar
	TXOPAdd
	TXOPSub
	TXOPMul
	TXOPDiv
	TXOPAnd
	TXOPGoto
	TXOPForStart
	TXOPForIter
	TXOPHTMLEscape
	TXOPUriEscape
	TXOPEquals
	TXOPNotEquals
	TXOPLessThan
	TXOPGreaterThan
	TXOPPopmark
	TXOPPushmark
	TXOPPopFrame
	TXOPPushFrame
	TXOPPush
	TXOPPop
	TXOPFunCall
	TXOPFunCallSymbol
	TXOPFunCallOmni
	TXOPMethodCall
	TXOPRange
	TXOPMakeArray
	TXOPMakeHash
	TXOPInclude
	TXOPWrapper
	TXOPFilter
	TXOPSaveWriter
	TXOPRestoreWriter
	TXOPEnd
	TXOPMax
)

These TXOP... constants are identifiers for each op

func (OpType) String

func (o OpType) String() string

String returns the textual representation of an OpType

func (OpType) Type

func (o OpType) Type() OpType

Type returns the ... OpType. This seems redundunt, but having this method allows us to embed OpType in Op and have the ability to call Typ() without having to re-declare it

type State

type State struct {
	Loader       byteCodeLoader
	MaxLoopCount int
	// contains filtered or unexported fields
}

State keeps track of Xslate Virtual Machine state

func NewState

func NewState() *State

NewState creates a new State struct

func (*State) Advance

func (st *State) Advance()

Advance advances the op code position by 1

func (*State) AdvanceBy

func (st *State) AdvanceBy(i int)

AdvanceBy advances the op code position by `i`

func (*State) AdvanceTo

func (st *State) AdvanceTo(i int)

AdvanceTo advances the op code to exactly position `i`

func (*State) AppendOutput

func (st *State) AppendOutput(b []byte)

AppendOutput appends the specified bytes to the output

func (*State) AppendOutputString

func (st *State) AppendOutputString(o string)

AppendOutputString is the same as AppendOutput, but uses a string

func (*State) CurrentFrame

func (st *State) CurrentFrame() *frame.Frame

CurrentFrame returns the frame currently at the top of the frame stack

func (*State) CurrentMark

func (st *State) CurrentMark() int

CurrentMark returns the mark stored at the top of the mark stack

func (*State) CurrentOp

func (st *State) CurrentOp() Op

CurrentOp returns the current op code

func (*State) CurrentPos

func (st *State) CurrentPos() int

CurrentPos returns the position of the current executing op

func (*State) LoadByteCode

func (st *State) LoadByteCode(key string) (*ByteCode, error)

LoadByteCode loads a new ByteCode. This is used for op codes that call to external templates such as `include`

func (*State) PopFrame

func (st *State) PopFrame() *frame.Frame

PopFrame pops the frame from the top of the frame stack

func (*State) Popmark

func (st *State) Popmark() int

Popmark pops the mark stored at the top of the mark stack

func (*State) PushFrame

func (st *State) PushFrame() *frame.Frame

PushFrame pushes a new frame to the frame stack

func (*State) Pushmark

func (st *State) Pushmark()

Pushmark records the current stack tip so we can remember where the current context started

func (*State) Reset

func (st *State) Reset()

Reset resets the whole State object

func (*State) StackPop

func (st *State) StackPop() interface{}

StackPop pops from the stack

func (*State) StackPush

func (st *State) StackPush(v interface{})

StackPush pushes to the stack

func (*State) StackTip

func (st *State) StackTip() int

StackTip returns the index of the top of the stack

func (*State) Vars

func (st *State) Vars() Vars

Vars returns the current set of variables

func (*State) Warnf

func (st *State) Warnf(format string, args ...interface{})

Warnf is used to generate warnings during virtual machine execution

type VM

type VM struct {
	Loader byteCodeLoader
	// contains filtered or unexported fields
}

VM represents the Xslate Virtual Machine

func NewVM

func NewVM() *VM

NewVM creates a new VM

func (*VM) CurrentOp

func (vm *VM) CurrentOp() Op

CurrentOp returns the current Op to be executed

func (*VM) IsSupportedByteCodeVersion

func (vm *VM) IsSupportedByteCodeVersion(bc *ByteCode) bool

IsSupportedByteCodeVersion returns true if this VM can handle the provided bytecode version

func (*VM) Run

func (vm *VM) Run(bc *ByteCode, vars Vars, output io.Writer)

Run executes the given vm.ByteCode using the given variables. For historical reasons, it also allows re-executing the previous bytecode instructions given to a virtual machine, but this will probably be removed in the future

func (*VM) SetFunctions

func (vm *VM) SetFunctions(vars Vars)

type Vars

type Vars map[string]interface{}

Vars represents the variables passed into the Virtual Machine

func (Vars) Get

func (v Vars) Get(k interface{}) (interface{}, bool)

Get returns the variable stored in slot `x`

func (*Vars) Reset

func (v *Vars) Reset()

func (Vars) Set

func (v Vars) Set(k string, x interface{})

Set sets the variable stored in slot `x`