README
¶
WrenGo
WrenGo provides bindings for go to interact with the wren scripting language. Currently Mutex is not used so be careful with Goroutines. There probably should be a lot more tests as well, however there are some tests to ensure that basic functionality works.
Usage
A simple Hello world
package main
import (
wren "github.com/crazyinfin8/WrenGo"
)
func main() {
vm := wren.NewVM()
vm.InterpretString("main", `System.print("Hello world from wren!")`)
}
Adding some configurating
package main
import (
wren "github.com/crazyinfin8/WrenGo"
)
func main() {
cfg := wren.NewConfig()
cfg.LoadModuleFn = func(vm *wren.VM, name string) string {
if name == "WrenGo" {
return `System.print("Hello from imported module")`
}
return ""
}
vm := cfg.NewVM()
vm.InterpretString("main", `import "WrenGo"`)
}
Calling Wren functions from Go
package main
import (
wren "github.com/crazyinfin8/WrenGo"
)
func main() {
vm := wren.NewVM()
vm.InterpretString("main",
`class MyClass {
static sayHello() {
System.print("Hello from MyClass")
}
}
`)
value, _ := vm.GetVariable("main", "MyClass")
MyClass, _ := value.(*wren.Handle)
Fn, _ := MyClass.Func("sayHello()")
Fn.Call()
}
Calling Go functions from Wren
package main
import (
wren "github.com/crazyinfin8/WrenGo"
)
func main() {
vm := wren.NewVM()
vm.SetModule("main", wren.NewModule(wren.ClassMap{
"MyClass": wren.NewClass(nil, nil, wren.MethodMap{
"static sayHello()": func(vm *wren.VM, parameters []interface{}) (interface{}, error) {
println("Hello from MyClass but from Go")
return nil, nil
},
}),
}))
vm.InterpretString("main",
`foreign class MyClass {
foreign static sayHello()
}
MyClass.sayHello()
`)
}
Documentation
¶
Overview ¶
Package wren provides bindings for Go programs to utilize and interact with the wren(https://wren.io/) scripting langues
Index ¶
- Constants
- Variables
- func VersionTuple() [3]int
- type CallHandle
- type ClassMap
- type CompileError
- type Config
- type ErrorFn
- type ForeignClass
- type ForeignFinalizer
- type ForeignHandle
- type ForeignInitializer
- type ForeignMethodFn
- type Handle
- type InvalidKey
- type InvalidValue
- type KeyNotExist
- type ListHandle
- func (h *ListHandle) Copy() (*ListHandle, error)
- func (h *ListHandle) Count() (int, error)
- func (h *ListHandle) Free()
- func (h *ListHandle) Func(signature string) (*CallHandle, error)
- func (h *ListHandle) Get(index int) (interface{}, error)
- func (h *ListHandle) Handle() *Handle
- func (h *ListHandle) Set(index int, value interface{}) error
- func (h *ListHandle) VM() *VM
- type LoadModuleFn
- type MapHandle
- func (h *MapHandle) Copy() (*MapHandle, error)
- func (h *MapHandle) Count() (int, error)
- func (h *MapHandle) Delete(key interface{}) (interface{}, error)
- func (h *MapHandle) Free()
- func (h *MapHandle) Func(signature string) (*CallHandle, error)
- func (h *MapHandle) Get(key interface{}) (interface{}, error)
- func (h *MapHandle) Handle() *Handle
- func (h *MapHandle) Has(key interface{}) (bool, error)
- func (h *MapHandle) Set(key, value interface{}) error
- func (h *MapHandle) VM() *VM
- type MaxBindingsReached
- type MethodMap
- type Module
- type ModuleMap
- type NilHandleError
- type NilVMError
- type NonMatchingVM
- type OutOfBounds
- type ResultCompileError
- type ResultRuntimeError
- type RuntimeError
- type StackTrace
- type UnexpectedValue
- type UnknownForeign
- type VM
- func (vm *VM) Abort(err error)
- func (vm *VM) Free()
- func (vm *VM) FreeAll(items ...interface{})
- func (vm *VM) GetVariable(module, name string) (interface{}, error)
- func (vm *VM) InterpretFile(fileName string) error
- func (vm *VM) InterpretString(module, source string) error
- func (vm *VM) Merge(moduleMap ModuleMap)
- func (vm *VM) NewList() (*ListHandle, error)
- func (vm *VM) NewMap() (*MapHandle, error)
- func (vm *VM) SetModule(name string, module *Module)
- type WriteFn
Constants ¶
const ( // VersionString Wren's version as a string VersionString string = C.WREN_VERSION_STRING // VersionMajor Wren's major version number VersionMajor int = C.WREN_VERSION_MAJOR // VersionMinor Wren's minor version number VersionMinor int = C.WREN_VERSION_MINOR // VersionPatch Wren's patch version number VersionPatch int = C.WREN_VERSION_PATCH )
const MAX_REGISTRATIONS = 128
Variables ¶
var ( // DefaultOutput is where Wren will print to if a VM's config doesn't specify its own output (Set this to nil to disable output) DefaultOutput io.Writer = os.Stdout // DefaultError is where Wren will send error messages to if a VM's config doesn't specify its own place for outputting errors (Set this to nil to disable output) DefaultError io.Writer = os.Stderr // DefaultModuleLoader allows Wren to import modules by loading files relative to the current directory (Set this to nil to disable importing or file access) DefaultModuleLoader LoadModuleFn = func(vm *VM, name string) (source string) { if data, err := ioutil.ReadFile(name); err == nil { source = string(data) } return source } )
Functions ¶
func VersionTuple ¶
func VersionTuple() [3]int
VersionTuple returns Wren's version numbers as an array of 3 numbers
Types ¶
type CallHandle ¶
type CallHandle struct {
// contains filtered or unexported fields
}
CallHandle is a handle to a wren function
func (*CallHandle) Call ¶
func (h *CallHandle) Call(parameters ...interface{}) (interface{}, error)
Call tries to call the function on the handles that created the `CallHandle`. The amount of parameters should coorespond to the signature used to create this function.
func (*CallHandle) Free ¶
func (h *CallHandle) Free()
Free releases the handle tied to it. The handle should be freed when no longer in use. The handle should not be used after it has been freed
type ClassMap ¶
type ClassMap map[string]*ForeignClass
ClassMap is a map containing all foreign classes (or classes where objects are made in Go and not Wren) organized by class name
type CompileError ¶
type CompileError struct {
// contains filtered or unexported fields
}
CompileError is sent by Wren to `ErrorFn` if Wren source code couldn't compile
func (*CompileError) Error ¶
func (err *CompileError) Error() string
type Config ¶
type Config struct {
// Wren calls this function to print text
WriteFn WriteFn
// Wren calls this function to print errors
ErrorFn ErrorFn
// Wren calls this function to import modules (if you want to disable importing, this should be set to nil and the global value `DefaultModuleLoader` should also be set to nil)
LoadModuleFn LoadModuleFn
// If `WriteFn` is not set, wren will print text to here instead (if you want to disable all output, this should be set to nil and the global value `DefaultOutput` should also be set to nil)
DefaultOutput io.Writer
// If `ErrorFn` is not set, wren errors will be written to here instead (if you want to disable all output, this should be set to nil and the global value `DefaultError` should also be set to nil)
DefaultError io.Writer
// Custom data
UserData interface{}
}
Config contains some settings to setup how VM will behave
type ErrorFn ¶
ErrorFn is called by Wren whenever there is a runtime error, compile error, or stack trace. It should be of type `CompileError`, `RuntimeError`, or `StackTrace`
type ForeignClass ¶
type ForeignClass struct {
// Wren will call this function as a constructor. Whatever it returns for `interface{}` will be the the foreign instance of this foreign class
Initializer ForeignInitializer
// Wren will call this function when Wren's garbage collector collects the forign class (not that maintaining handles will prevent the foreign object from being garbage collected)
Finalizer ForeignFinalizer
// A map containing `ForeignMethodFn`s organized by function signatures. see MethodMap for mor information on signatures syntax.
MethodMap MethodMap
}
ForeignClass details a foreign class (or classes where objects are made in Go and not Wren) for Wren to use. Whenever Wren runs a constructor for this class, `Initializer` is called. Whatever the first value `Initializer` returns will be used as the instance for this foreign class.
func NewClass ¶
func NewClass(initializer ForeignInitializer, finalizer ForeignFinalizer, methods MethodMap) *ForeignClass
NewClass creates a new `ForeignClass` with the given `ForeignInitializer` function, `ForeignFinalizer` function, and `MethodMap`
func (*ForeignClass) Clone ¶
func (class *ForeignClass) Clone() *ForeignClass
Clone creates a copy of the current `ForeignMap`
type ForeignFinalizer ¶
type ForeignFinalizer func(vm *VM, data interface{})
ForeignFinalizer is a function called when Wren garbage collects the forign object it is tied to (not that maintaining handles will prevent the foreign object from being garbage collected)
type ForeignHandle ¶
type ForeignHandle struct {
// contains filtered or unexported fields
}
ForeignHandle is a handle to a foriegn object in Wren
func (*ForeignHandle) Copy ¶
func (h *ForeignHandle) Copy() (*ForeignHandle, error)
Copy creates a new `ForeignHandle` tied to this foreign object, if the previous one is freed the new one should still persist
func (*ForeignHandle) Free ¶
func (h *ForeignHandle) Free()
Free releases the handle tied to it. The handle should be freed when no longer in use. The handle should not be used after it has been freed
func (*ForeignHandle) Func ¶
func (h *ForeignHandle) Func(signature string) (*CallHandle, error)
Func creates a callable handle from the Wren object tied to the current handle. There isn't currently a way to check if the function referenced from `signature` exists before calling it
func (*ForeignHandle) Get ¶
func (h *ForeignHandle) Get() (interface{}, error)
Get tries to get the original value that this `ForeignHandle` set to
func (*ForeignHandle) Handle ¶
func (h *ForeignHandle) Handle() *Handle
Handle returns the generic handle it this `MapHandle` is tied to
func (*ForeignHandle) VM ¶
func (h *ForeignHandle) VM() *VM
VM returns the vm that this handle belongs to
type ForeignInitializer ¶
ForeignInitializer is a function used to initialize a foreign class instance. Whatever it returns for `interface{}` will be the the foreign instance of the foreign class
type ForeignMethodFn ¶
ForeignMethodFn is a function that wren can import or call. if it returns an error, then it will call `vm.Abort`
type Handle ¶
type Handle struct {
// contains filtered or unexported fields
}
Handle is a generic handle from wren
func (*Handle) Free ¶
func (h *Handle) Free()
Free releases the handle tied to it. The handle should be freed when no longer in use. The handle should not be used after it has been freed
type InvalidKey ¶
type InvalidKey struct {
Map *MapHandle
Key interface{}
}
InvalidKey is returned if there was an attempt to access a maps value with a key that is not of type number, boolean, string, or nil
func (*InvalidKey) Error ¶
func (err *InvalidKey) Error() string
type InvalidValue ¶
type InvalidValue struct {
Value interface{}
}
InvalidValue is returned if there was an attempt to pass a value to Wren that WrenGo cannot process. Note that Go maps, lists, and slices (other than byte slices), may also send this error. `ListHandle`s and `MapHandle`s should be used instead of list and maps.
func (InvalidValue) Error ¶
func (err InvalidValue) Error() string
type KeyNotExist ¶
type KeyNotExist struct {
Map *MapHandle
Key interface{}
}
KeyNotExist is returned if there was an attempt to access a key value from a map that doesn't exist yet
func (*KeyNotExist) Error ¶
func (err *KeyNotExist) Error() string
type ListHandle ¶
type ListHandle struct {
// contains filtered or unexported fields
}
ListHandle is a handle to a list object in Wren
func (*ListHandle) Copy ¶
func (h *ListHandle) Copy() (*ListHandle, error)
Copy creates a new `ListHandle` tied to this Wren list, if the previous one is freed the new one should still persist
func (*ListHandle) Count ¶
func (h *ListHandle) Count() (int, error)
Count counts how many elements are in the Wren list
func (*ListHandle) Free ¶
func (h *ListHandle) Free()
Free releases the handle tied to it. The handle should be freed when no longer in use. The handle should not be used after it has been freed
func (*ListHandle) Func ¶
func (h *ListHandle) Func(signature string) (*CallHandle, error)
Func creates a callable handle from the Wren object tied to the current handle. There isn't currently a way to check if the function referenced from `signature` exists before calling it
func (*ListHandle) Get ¶
func (h *ListHandle) Get(index int) (interface{}, error)
Get tries to return the value in the Wren list at the index `index`
func (*ListHandle) Handle ¶
func (h *ListHandle) Handle() *Handle
Handle returns the generic handle it this `ListHandle` is tied to
func (*ListHandle) Set ¶
func (h *ListHandle) Set(index int, value interface{}) error
Set tries to set the value in the Wren list at the index `index`
type LoadModuleFn ¶
LoadModuleFn is called by Wren to whenever `import` is called. it can either return a string with wren source code or it can return nil to send an error to the VM
type MapHandle ¶
type MapHandle struct {
// contains filtered or unexported fields
}
MapHandle is a handle to a map object in Wren
func (*MapHandle) Copy ¶
Copy creates a new `MapHandle` tied to this Wren map, if the previous one is freed the new one should still persist
func (*MapHandle) Free ¶
func (h *MapHandle) Free()
Free releases the handle tied to it. The handle should be freed when no longer in use. The handle should not be used after it has been freed
func (*MapHandle) Func ¶
func (h *MapHandle) Func(signature string) (*CallHandle, error)
Func creates a callable handle from the Wren object tied to the current handle. There isn't currently a way to check if the function referenced from `signature` exists before calling it
type MaxBindingsReached ¶
type MaxBindingsReached struct {
VM *VM
}
func (*MaxBindingsReached) Error ¶
func (err *MaxBindingsReached) Error() string
type MethodMap ¶
type MethodMap map[string]ForeignMethodFn
MethodMap is a map containing `ForeignMethodFn`s organized by signatures.
Signatures have specific syntax in order for wren to know which function to use.
- If the function is static then it will begin with the string "static " (note the space after it).
- The name of the function is required to match how it will look in Wren
- Next will be an open paranthesis("(")
- for the amount of expected parameters, add underscores seperated by comma. do not add a trailing comma after the last underscore
- close everything up with a closing parenthesis (")")
For example:
- A static function called "foo" with 3 parameters will look like "static foo(_,_,_)"
- A function that isn't static called "bar" with no parameters will look like "static bar()"
type Module ¶
type Module struct {
ClassMap ClassMap
}
Module contains a `ClassMap` which is a map containing foreign classes (or classes where objects are made in Go and not Wren) organized by class name
type ModuleMap ¶
ModuleMap is a map containing Module organized by module names
type NilHandleError ¶
type NilHandleError struct {
}
NilHandleError is returned if there was an attempt to use a `Handle` that was freed already
func (*NilHandleError) Error ¶
func (err *NilHandleError) Error() string
type NilVMError ¶
type NilVMError struct{}
NilVMError is returned if there was an attempt to use a VM that was freed already
func (*NilVMError) Error ¶
func (err *NilVMError) Error() string
type NonMatchingVM ¶
type NonMatchingVM struct{}
NonMatchingVM is returned if there was an attempt to use a handle in a VM that it did not originate from
func (*NonMatchingVM) Error ¶
func (err *NonMatchingVM) Error() string
type OutOfBounds ¶
type OutOfBounds struct {
List *ListHandle
Index int
}
OutOfBounds is returned if there was an attempt to access a lists value at an index that hasn't been set yet
func (*OutOfBounds) Error ¶
func (err *OutOfBounds) Error() string
type ResultCompileError ¶
type ResultCompileError struct{}
ResultCompileError is returned from `InterpretString` or `InterpretFile` if there were problems compiling the Wren source code
func (*ResultCompileError) Error ¶
func (err *ResultCompileError) Error() string
type ResultRuntimeError ¶
type ResultRuntimeError struct{}
ResultRuntimeError is returned from `InterpretString`, `InterpretFile`, or `Call` if there was a problem during script execution
func (*ResultRuntimeError) Error ¶
func (err *ResultRuntimeError) Error() string
type RuntimeError ¶
type RuntimeError struct {
// contains filtered or unexported fields
}
RuntimeError is sent by Wren to `ErrorFn` if the vm encountered an error during script execution
func (*RuntimeError) Error ¶
func (err *RuntimeError) Error() string
type StackTrace ¶
type StackTrace struct {
// contains filtered or unexported fields
}
StackTrace is sent by Wren to `ErrorFn` after sending `RuntimeError` these help try to pinpoint how and where an error occurred
func (*StackTrace) Error ¶
func (err *StackTrace) Error() string
type UnexpectedValue ¶
type UnexpectedValue struct {
Value interface{}
}
UnexpectedValue is returned if Wren did not create the correct type (probably might panic from being out of memory or something before that but just to be safe)
func (*UnexpectedValue) Error ¶
func (err *UnexpectedValue) Error() string
type UnknownForeign ¶
type UnknownForeign struct {
Handle *ForeignHandle
}
UnknownForeign is returned if a foreign value was not set by WrenGo
func (*UnknownForeign) Error ¶
func (err *UnknownForeign) Error() string
type VM ¶
type VM struct {
Config *Config
// contains filtered or unexported fields
}
VM is an instance of Wren's virtual machine
func NewVM ¶
func NewVM() *VM
NewVM creates a new instance of Wren's virtual machine with blank configurations
func (*VM) Free ¶
func (vm *VM) Free()
Free destroys the wren virtual machine and frees all handles tied to it. The VM should be freed when no longer in use. The VM should not be used after it has been freed
func (*VM) FreeAll ¶
func (vm *VM) FreeAll(items ...interface{})
FreeAll can take any argument type. It filters through and calls free on any handles passed. It does not free anything else
func (*VM) GetVariable ¶
GetVariable tries to get a variable from the Wren vm with the given module name and variable name. There isn't currently a way to check if the variable does not exist yet.
func (*VM) InterpretFile ¶
InterpretFile compiles and runs wren source code from the given file. the module name would be set to the `fileName`
func (*VM) InterpretString ¶
InterpretString compiles and runs wren source code from `source`. the module name of the source can be set with `module`.
func (*VM) Merge ¶
Merge combine all non nil values from `moduleMap` to the vm's own module map (If a vm already imported classes and methods from any module already, changing it again won't set the previously imported values)
func (*VM) NewList ¶
func (vm *VM) NewList() (*ListHandle, error)
NewList creates a new empty list object in wren and returns it's handle
Source Files