go-mruby: github.com/mitchellh/go-mruby Index | Files

package mruby

import "github.com/mitchellh/go-mruby"


Package Files

args.go array.go class.go context.go decode.go func.go hash.go mruby.go parser.go value.go value_type.go

func Decode Uses

func Decode(out interface{}, v *MrbValue) error

Decode converts the Ruby value to a Go value.

The Decode process may call Ruby code and may generate Ruby garbage, but it collects all of its own garbage. You don't need to GC around this.

See the tests (decode_test.go) for detailed and specific examples of how this function decodes. Basic examples are also available here and in the README.

For primitives, the decoding process is likely what you expect. For Ruby, this is booleans, strings, fixnums, and floats. These map directly to effectively equivalent Go types: bool, string, int, float64. Hash and Arrays can map directly to maps and slices in Go, and Decode will handle this as you expect.

The only remaining data type in Go is a struct. A struct in Go can map to any object in Ruby. If the data in Ruby is a hash, then the struct keys will map directly to the hash keys. If the data in Ruby is an object, then one of two things will be done. First: if the object responds to the `to_gomruby` function, then this will be called and the resulting value is expected to be a Hash and will be used to decode into the struct. If the object does NOT respond to that function, then any struct fields will invoke the corresponding Ruby method to attain the value.

Note that with structs you can use the `mruby` tag to specify the Hash key or method name to call. Example:

type Foo struct {
    Field string `mruby:"read_field"`

type ArenaIndex Uses

type ArenaIndex int

ArenaIndex represents the index into the arena portion of the GC.

See ArenaSave for more information.

type ArgSpec Uses

type ArgSpec C.mrb_aspec

ArgSpec defines how many arguments a function should take and what kind. Multiple ArgSpecs can be combined using the "|" operator.

func ArgsAny Uses

func ArgsAny() ArgSpec

ArgsAny allows any number of arguments.

func ArgsArg Uses

func ArgsArg(r, o int) ArgSpec

ArgsArg says the given number of arguments are required and the second number is optional.

func ArgsBlock Uses

func ArgsBlock() ArgSpec

ArgsBlock says it takes a block argument.

func ArgsNone Uses

func ArgsNone() ArgSpec

ArgsNone says it takes no arguments.

func ArgsOpt Uses

func ArgsOpt(n int) ArgSpec

ArgsOpt says that the given number of arguments are optional.

func ArgsReq Uses

func ArgsReq(n int) ArgSpec

ArgsReq says that the given number of arguments are required.

type Array Uses

type Array struct {

Array represents an MrbValue that is a Array in Ruby.

A Array can be obtained by calling the Array function on MrbValue.

func (*Array) Get Uses

func (v *Array) Get(idx int) (*MrbValue, error)

Get gets an element form the Array by index.

This does not copy the element. This is a pointer/reference directly to the element in the array.

func (*Array) Len Uses

func (v *Array) Len() int

Len returns the length of the array.

type Class Uses

type Class struct {
    // contains filtered or unexported fields

Class is a class in mruby. To obtain a Class, use DefineClass or one of the variants on the Mrb structure.

func (*Class) DefineClassMethod Uses

func (c *Class) DefineClassMethod(name string, cb Func, as ArgSpec)

DefineClassMethod defines a class-level method on the given class.

func (*Class) DefineConst Uses

func (c *Class) DefineConst(name string, value Value)

DefineConst defines a constant within this class.

func (*Class) DefineMethod Uses

func (c *Class) DefineMethod(name string, cb Func, as ArgSpec)

DefineMethod defines an instance method on the class.

func (*Class) MrbValue Uses

func (c *Class) MrbValue(m *Mrb) *MrbValue

MrbValue returns a *Value for this Class. *Values are sometimes required as arguments where classes should be valid.

func (*Class) New Uses

func (c *Class) New(args ...Value) (*MrbValue, error)

New instantiates the class with the given args.

type CompileContext Uses

type CompileContext struct {
    // contains filtered or unexported fields

CompileContext represents a context for code compilation.

CompileContexts keep track of things such as filenames, line numbers, as well as some settings for how to parse and execute code.

func NewCompileContext Uses

func NewCompileContext(m *Mrb) *CompileContext

NewCompileContext constructs a *CompileContext from a *Mrb.

func (*CompileContext) CaptureErrors Uses

func (c *CompileContext) CaptureErrors(yes bool)

CaptureErrors toggles the capture errors feature of the parser, which swallows errors. This allows repls and other partial parsing tools (formatters, f.e.) to function.

func (*CompileContext) Close Uses

func (c *CompileContext) Close()

Close the context, freeing any resources associated with it.

This is safe to call once the context has been used for parsing/loading any Ruby code.

func (*CompileContext) Filename Uses

func (c *CompileContext) Filename() string

Filename returns the filename associated with this context.

func (*CompileContext) SetFilename Uses

func (c *CompileContext) SetFilename(f string)

SetFilename sets the filename associated with this compilation context.

Code parsed under this context will be from this file.

type Exception Uses

type Exception struct {
    File      string
    Line      int
    Message   string
    Backtrace []string

Exception is a special type of value that represents an error and implements the Error interface.

func (*Exception) Error Uses

func (e *Exception) Error() string

func (*Exception) String Uses

func (e *Exception) String() string

type Func Uses

type Func func(m *Mrb, self *MrbValue) (Value, Value)

Func is the signature of a function in Go that you use to expose to Ruby code.

The first return value is the actual return value for the code.

The second return value is an exception, if any. This will be raised.

type Hash Uses

type Hash struct {

Hash represents an MrbValue that is a Hash in Ruby.

A Hash can be obtained by calling the Hash function on MrbValue.

func (*Hash) Delete Uses

func (h *Hash) Delete(key Value) (*MrbValue, error)

Delete deletes a key from the hash, returning its existing value, or nil if there wasn't a value.

func (*Hash) Get Uses

func (h *Hash) Get(key Value) (*MrbValue, error)

Get reads a value from the hash.

func (*Hash) Keys Uses

func (h *Hash) Keys() (*MrbValue, error)

Keys returns the array of keys that the Hash has. This is returned as an *MrbValue since this is a Ruby array. You can iterate over it as you see fit.

func (*Hash) Set Uses

func (h *Hash) Set(key, val Value) error

Set sets a value on the hash

type Int Uses

type Int int

Int is the basic ruby Integer type.

func (Int) MrbValue Uses

func (i Int) MrbValue(m *Mrb) *MrbValue

MrbValue returns the native MRB value

type Mrb Uses

type Mrb struct {
    // contains filtered or unexported fields

Mrb represents a single instance of mruby.

func NewMrb Uses

func NewMrb() *Mrb

NewMrb creates a new instance of Mrb, representing the state of a single Ruby VM.

When you're finished with the VM, clean up all resources it is using by calling the Close method.

func (*Mrb) ArenaRestore Uses

func (m *Mrb) ArenaRestore(idx ArenaIndex)

ArenaRestore restores the arena index so the objects between the save and this point can be garbage collected in the future.

See ArenaSave for more documentation.

func (*Mrb) ArenaSave Uses

func (m *Mrb) ArenaSave() ArenaIndex

ArenaSave saves the index into the arena.

Restore the arena index later by calling ArenaRestore.

The arena is where objects returned by functions such as LoadString are stored. By saving the index and then later restoring it with ArenaRestore, these objects can be garbage collected. Otherwise, the objects will never be garbage collected.

The recommended usage pattern for memory management is to save the arena index prior to any Ruby execution, to turn the resulting Ruby value into Go values as you see fit, then to restore the arena index so that GC can collect any values.

Of course, when Close() is called, all objects in the arena are garbage collected anyways, so if you're only calling mruby for a short period of time, you might not have to worry about saving/restoring the arena.

func (*Mrb) Class Uses

func (m *Mrb) Class(name string, super *Class) *Class

Class returns the class with the kgiven name and superclass. Note that if you call this with a class that doesn't exist, mruby will abort the application (like a panic, but not a Go panic).

super can be nil, in which case the Object class will be used.

func (*Mrb) Close Uses

func (m *Mrb) Close()

Close a Mrb, this must be called to properly free resources, and should only be called once.

func (*Mrb) ConstDefined Uses

func (m *Mrb) ConstDefined(name string, scope Value) bool

ConstDefined checks if the given constant is defined in the scope.

This should be used, for example, before a call to Class, because a failure in Class will crash your program (by design). You can retrieve the Value of a Class by calling Value().

func (*Mrb) DefineClass Uses

func (m *Mrb) DefineClass(name string, super *Class) *Class

DefineClass defines a new top-level class.

If super is nil, the class will be defined under Object.

func (*Mrb) DefineClassUnder Uses

func (m *Mrb) DefineClassUnder(name string, super *Class, outer *Class) *Class

DefineClassUnder defines a new class under another class.

This is, for example, how you would define the World class in `Hello::World` where Hello is the "outer" class.

func (*Mrb) DefineModule Uses

func (m *Mrb) DefineModule(name string) *Class

DefineModule defines a top-level module.

func (*Mrb) DefineModuleUnder Uses

func (m *Mrb) DefineModuleUnder(name string, outer *Class) *Class

DefineModuleUnder defines a module under another class/module.

func (*Mrb) DisableGC Uses

func (m *Mrb) DisableGC()

DisableGC disables the garbage collector for this mruby instance. It returns true if it was previously disabled.

func (*Mrb) EnableGC Uses

func (m *Mrb) EnableGC()

EnableGC enables the garbage collector for this mruby instance. It returns true if garbage collection was previously disabled.

func (*Mrb) FalseValue Uses

func (m *Mrb) FalseValue() *MrbValue

FalseValue returns a Value for "false"

func (*Mrb) FixnumValue Uses

func (m *Mrb) FixnumValue(v int) *MrbValue

FixnumValue returns a Value for a fixed number.

func (*Mrb) FullGC Uses

func (m *Mrb) FullGC()

FullGC executes a complete GC cycle on the VM.

func (*Mrb) GetArgs Uses

func (m *Mrb) GetArgs() []*MrbValue

GetArgs returns all the arguments that were given to the currnetly called function (currently on the stack).

func (*Mrb) GetGlobalVariable Uses

func (m *Mrb) GetGlobalVariable(name string) *MrbValue

GetGlobalVariable returns the value of the global variable by the given name.

func (*Mrb) IncrementalGC Uses

func (m *Mrb) IncrementalGC()

IncrementalGC runs an incremental GC step. It is much less expensive than a FullGC, but must be called multiple times for GC to actually happen.

This function is best called periodically when executing Ruby in the VM many times (thousands of times).

func (*Mrb) KernelModule Uses

func (m *Mrb) KernelModule() *Class

KernelModule returns the Kernel top-level module.

func (*Mrb) LiveObjectCount Uses

func (m *Mrb) LiveObjectCount() int

LiveObjectCount returns the number of objects that have not been collected (aka, alive).

func (*Mrb) LoadString Uses

func (m *Mrb) LoadString(code string) (*MrbValue, error)

LoadString loads the given code, executes it, and returns its final value that it might return.

func (*Mrb) Module Uses

func (m *Mrb) Module(name string) *Class

Module returns the named module as a *Class. If the module is invalid, NameError is triggered within your program and SIGABRT is sent to the application.

func (*Mrb) NilValue Uses

func (m *Mrb) NilValue() *MrbValue

NilValue returns "nil"

func (*Mrb) ObjectClass Uses

func (m *Mrb) ObjectClass() *Class

ObjectClass returns the Object top-level class.

func (*Mrb) Run Uses

func (m *Mrb) Run(v Value, self Value) (*MrbValue, error)

Run executes the given value, which should be a proc type.

If you're looking to execute code directly a string, look at LoadString.

If self is nil, it is set to the top-level self.

func (*Mrb) RunWithContext Uses

func (m *Mrb) RunWithContext(v Value, self Value, stackKeep int) (int, *MrbValue, error)

RunWithContext is a context-aware parser (aka, it does not discard state between runs). It returns a magic integer that describes the stack in place, so that it can be re-used on the next call. This is how local variables can traverse ruby parse invocations.

Otherwise, it is very similar in function to Run()

func (*Mrb) SetGlobalVariable Uses

func (m *Mrb) SetGlobalVariable(name string, value Value)

SetGlobalVariable sets the value of the global variable by the given name.

func (*Mrb) StringValue Uses

func (m *Mrb) StringValue(s string) *MrbValue

StringValue returns a Value for a string.

func (*Mrb) TopSelf Uses

func (m *Mrb) TopSelf() *MrbValue

TopSelf returns the top-level `self` value.

func (*Mrb) TrueValue Uses

func (m *Mrb) TrueValue() *MrbValue

TrueValue returns a Value for "true"

func (*Mrb) Yield Uses

func (m *Mrb) Yield(block Value, args ...Value) (*MrbValue, error)

Yield yields to a block with the given arguments.

This should be called within the context of a Func.

type MrbValue Uses

type MrbValue struct {
    // contains filtered or unexported fields

MrbValue is a "value" internally in mruby. A "value" is what mruby calls basically anything in Ruby: a class, an object (instance), a variable, etc.

func (*MrbValue) Array Uses

func (v *MrbValue) Array() *Array

Array returns the Array value of this value. If the Type of the MrbValue is not a TypeArray, then this will panic. If the MrbValue has a `to_a` function, you must call that manually prior to calling this method.

func (*MrbValue) Call Uses

func (v *MrbValue) Call(method string, args ...Value) (*MrbValue, error)

Call calls a method with the given name and arguments on this value.

func (*MrbValue) CallBlock Uses

func (v *MrbValue) CallBlock(method string, args ...Value) (*MrbValue, error)

CallBlock is the same as call except that it expects the last argument to be a Proc that will be passed into the function call. It is an error if args is empty or if there is no block on the end.

func (*MrbValue) Class Uses

func (v *MrbValue) Class() *Class

Class returns the *Class of a value.

func (*MrbValue) Fixnum Uses

func (v *MrbValue) Fixnum() int

Fixnum returns the numeric value of this object if the Type() is TypeFixnum. Calling this with any other type will result in undefined behavior.

func (*MrbValue) Float Uses

func (v *MrbValue) Float() float64

Float returns the numeric value of this object if the Type() is TypeFloat. Calling this with any other type will result in undefined behavior.

func (*MrbValue) GCProtect Uses

func (v *MrbValue) GCProtect()

GCProtect protects this value from being garbage collected.

func (*MrbValue) GetInstanceVariable Uses

func (v *MrbValue) GetInstanceVariable(variable string) *MrbValue

GetInstanceVariable gets an instance variable on this value.

func (*MrbValue) Hash Uses

func (v *MrbValue) Hash() *Hash

Hash returns the Hash value of this value. If the Type of the MrbValue is not a ValueTypeHash, then this will panic. If the MrbValue has a `to_h` function, you must call that manually prior to calling this method.

func (*MrbValue) IsDead Uses

func (v *MrbValue) IsDead() bool

IsDead tells you if an object has been collected by the GC or not.

func (*MrbValue) Mrb Uses

func (v *MrbValue) Mrb() *Mrb

Mrb returns the Mrb state for this value.

func (*MrbValue) MrbValue Uses

func (v *MrbValue) MrbValue(*Mrb) *MrbValue

MrbValue so that *MrbValue implements the "Value" interface.

func (*MrbValue) SetInstanceVariable Uses

func (v *MrbValue) SetInstanceVariable(variable string, value *MrbValue)

SetInstanceVariable sets an instance variable on this value.

func (*MrbValue) SetProcTargetClass Uses

func (v *MrbValue) SetProcTargetClass(c *Class)

SetProcTargetClass sets the target class where a proc will be executed when this value is a proc.

func (*MrbValue) SingletonClass Uses

func (v *MrbValue) SingletonClass() *Class

SingletonClass returns the singleton class (a class isolated just for the scope of the object) for the given value.

func (*MrbValue) String Uses

func (v *MrbValue) String() string

String returns the "to_s" result of this value.

func (*MrbValue) Type Uses

func (v *MrbValue) Type() ValueType

Type returns the ValueType of the MrbValue. See the constants table.

type NilType Uses

type NilType [0]byte

NilType is the object representation of NilClass

var Nil NilType

Nil is a constant that can be used as a Nil Value

func (NilType) MrbValue Uses

func (NilType) MrbValue(m *Mrb) *MrbValue

MrbValue returns the native MRB value

type Parser Uses

type Parser struct {
    // contains filtered or unexported fields

Parser is a parser for Ruby code.

func NewParser Uses

func NewParser(m *Mrb) *Parser

NewParser initializes the resources for a parser.

Make sure to Close the parser when you're done with it.

func (*Parser) Close Uses

func (p *Parser) Close()

Close releases any resources associated with the parser.

func (*Parser) GenerateCode Uses

func (p *Parser) GenerateCode() *MrbValue

GenerateCode takes all the internal parser state and generates executable Ruby code, returning the callable proc.

func (*Parser) Parse Uses

func (p *Parser) Parse(code string, c *CompileContext) ([]*ParserMessage, error)

Parse parses the code in the given context, and returns any warnings or errors from parsing.

The CompileContext can be nil to not set a context.

type ParserError Uses

type ParserError struct {
    Errors []*ParserMessage

ParserError is an error from the parser.

func (ParserError) Error Uses

func (p ParserError) Error() string

func (ParserError) String Uses

func (p ParserError) String() string

type ParserMessage Uses

type ParserMessage struct {
    Col     int
    Line    int
    Message string

ParserMessage represents a message from parsing code: a warning or error.

type String Uses

type String string

String is objects of the type String.

func (String) MrbValue Uses

func (s String) MrbValue(m *Mrb) *MrbValue

MrbValue returns the native MRB value

type Value Uses

type Value interface {
    MrbValue(*Mrb) *MrbValue

Value is an interface that should be implemented by anything that can be represents as an mruby value.

type ValueType Uses

type ValueType uint32

ValueType is an enum of types that a Value can be and is returned by Value.Type().

const (
    // TypeFalse is `false`
    TypeFalse ValueType = iota
    // TypeFree is ?
    // TypeTrue is `true`
    // TypeFixnum is fixnums, or integers for this case.
    // TypeSymbol is for entities in ruby that look like `:this`
    // TypeUndef is a value internal to ruby for uninstantiated vars.
    // TypeFloat is any floating point number such as 1.2, etc.
    // TypeCptr is a void*
    // TypeObject is a standard ruby object, base class of most instantiated objects.
    // TypeClass is the base class of all classes.
    // TypeModule is the base class of all Modules.
    // TypeIClass is ?
    // TypeSClass is ?
    // TypeProc are procs (concrete block definitons)
    // TypeArray is []
    // TypeHash is { }
    // TypeString is ""
    // TypeRange is (0..x)
    // TypeException is raised when using the raise keyword
    // TypeFile is for objects of the File class
    // TypeEnv is for getenv/setenv etc
    // TypeData is ?
    // TypeFiber is for members of the Fiber class
    // TypeMaxDefine is ?
    // TypeNil is nil
    TypeNil ValueType = 0xffffffff

Package mruby imports 10 packages (graph) and is imported by 11 packages. Updated 2018-10-21. Refresh now. Tools for package owners.