supermeta

Documentation

Overview

Generic meta-table types and helpers.

This API mostly ignores exact types, relying on "kinds" (reflect.Kind) instead. This means that custom types will work fine.

The following kinds are not supported:

Complex64
Complex128
Chan
Func
UnsafePointer

These are not implemented because they have no corresponding Lua types, some of these may be supported later...

Slices are special in that they allow you to write to the key one passed the end of the slice. This allows you to append now data to an existing slice. If you want anything more complicated than that you should write a custom metatable.

You should be able to assign a table to a value containing a "complex" type (slice, array, map, struct). This does not create a new object (unless the existing object is a nil pointer), instead the data from the table is used to fill as many keys in the object as possible. Slices will be lengthened as needed, arrays will simply ignore extra items. If any key or value in the table cannot be converted to the required type conversion will halt with an error.

Slices an arrays are indexed from 1. Basically I just subtract one from all incoming indexes. This is done to better fit with the rest of Lua, not because I like 1-based indexing (I actually think it is a really stupid idea, and Lua's biggest problem).

I make a fairly good effort at auto-vivification, any assignment to a nil pointer should result in a new object being created. Sadly this cannot be done for nil interfaces (for obvious reasons).

Note that this API is somewhat fragile. Things should "just work", but malformed input is likely to result in lots of errors. Nothing should panic or otherwise crash, but returned errors are entirely possible. Generally I assume you are feeding in good input (from both sides). Rather than trying to detect and handle cases where there is a mix of good and bad, I simply give up at the first issue.

When working with untrusted scripts be very careful what you expose with this API! Some actions have the potential to trash the exposed data! Always use a set of dedicated metatables where possible!

Index

• Variables
• func LValueToRValue(l *lua.State, dest reflect.Value, src int) error
• func New(l *lua.State, obj interface{})
• func RValueToLValue(l *lua.State, src reflect.Value)

Variables

var ErrBadConv = errors.New("Conversion to required type not possible for this value.")

var ErrCantConv = errors.New("Conversion to given type not implemented.")

var ErrCantSet = errors.New("Cannot set given value.")

Possible errors.

Functions

func LValueToRValue

func LValueToRValue(l *lua.State, dest reflect.Value, src int) error

LValueToRValue stores a given Lua value in the given reflect.Value.

If the given reflect.Value cannot hold the requested Lua value you will get an error. Note that the reflect.Value may have been modified! Not all errors happen immediately! For example if you are assigning a table to a map some of the key/value pairs may have been added before the "bad" key was found.

Most of the time you should use the normal API to get values out of the VM!

func New

func New(l *lua.State, obj interface{})

New pushes the given object onto the Lua stack with a generic meta-table applied or otherwise converted to something Lua can use. In the case of simple values the conversion is by-value, slices, arrays, maps, structs, etc are by-reference. For simple values you should probably just use State.Push.

99% of the time you will want to pass the address of the item you want to work with, even if it is a type you would normally pass by value. Unless you pass a pointer the reflection library probably won't be able to modify the item.

In the case of an unconvertible value you will either get a Lua error or a nil value. Invalid conversions from Lua to Go result in script errors, invalid conversions from Go to Lua result in (Lua) nils.

Depending on the exposed value you may or may not be able to set it. Structs in particular may raise script errors when trying to set certain fields. Nil pointers and interfaces may also be a problem. I make an effort to auto-vivify nil pointers, but this may not work for some types.

func RValueToLValue

func RValueToLValue(l *lua.State, src reflect.Value)

RValueToLValue pushes the given reflect.Value onto the stack.

This is basically the same as New, but for use when you have an existing reflect.Value.