Documentation
¶
Overview ¶
Package luacty is an adapter library that wraps values from cty -- a configuration-oriented dynamic type system in Go -- so that they can be used in Lua programs executed by GopherLua.
cty and Lua are both, in different ways, tailored for configuration use-cases. This bridge allows applications that are using cty for other reasons, such as more declarative configuration formats that produce cty results, to interchange those same results with Lua programs in situations where a scripting language is more appropriate.
luacty is a two-way bridge: it allows cty values to be wrapped in Lua's "userdata" type for direct use in Lua, and it also allows many of Lua's native types to be converted to cty values so that script results can be consumed.
Conversion of cty values to Lua values is via wrapping: Lua features are used to implement normal Lua operators against the real underlying cty values, via the cty API. This causes operations on cty values to behave like they would within the Go API, but also means that certain cty semantics "leak in" to Lua: the list vs. map vs. object vs. tuple distinction is retained, for example, rather than converting to a generic Lua table, and cty lists and tuples retain their zero-indexing rather than adopting the one-indexing that Lua uses for its own indexed tables.
Conversion of Lua values out to cty is done by actual conversion rather than wrapping, producing new cty values that start with equivalent content to the given Lua value but using cty semantics rather than Lua semantics. Not all Lua values can convert to cty values, and conversions may be "lossy" in the sense that the original Lua value cannot be easily recovered. The available automatic conversions are:
LNilType cty.NullVal(cty.DynamicPseudoType) LBool cty.Bool LNumber cty.Number LString cty.String LTable cty.Object LUserData cty.Value (when userdata was created by this package)
When cty type information can be provided for conversion, additional conversions are possible for LTable, allowing conversions to cty.List, cty.Map and cty.Tuple where the table content meets the constraints of these types.
No value conversions are available for Lua functions or userdata that was created by other packages. A wrapper is provided to allow Lua functions to be used as cty functions within applications that make use of the cty function extension, but cty functions are not cty values.
Index ¶
- type Converter
- func (c *Converter) ImpliedCtyType(val lua.LValue) (cty.Type, error)
- func (c *Converter) ToCtyFunction(f *lua.LFunction) function.Function
- func (c *Converter) ToCtyValue(val lua.LValue, ty cty.Type) (cty.Value, error)
- func (c *Converter) WrapCtyFunction(f function.Function) *lua.LFunction
- func (c *Converter) WrapCtyValue(val cty.Value) lua.LValue
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Converter ¶
type Converter struct {
// contains filtered or unexported fields
}
Converter is the main type in this package, providing the conversion functionality in both directions.
A converter is specific to a givan lua.LState because it uses that state to create new values and to interact with the Lua stack during operations.
func NewConverter ¶
NewConverter creates and returns a new Converter for the given Lua state.
func (*Converter) ImpliedCtyType ¶
ImpliedCtyType attempts to produce a cty Type that is suitable to recieve the given Lua value, or returns an error if no mapping is possible.
Error messages are written with a Lua developer as the audience, and so will not include Go-specific implementation details. Where possible, the result is a cty.PathError describing the location of the error within the given data structure.
func (*Converter) ToCtyFunction ¶
ToCtyFunction wraps a Lua function so that it can be used as a cty function.
Since Lua functions do not have statically-defined argument types, all of the parameters in the returned function are typed as cty.DynamicPseudoType, and the return type is also cty.DynamicPseudoType.
func (*Converter) ToCtyValue ¶
ToCtyValue attempts to convert the given Lua value to a cty Value of the given type.
If the given type is cty.DynamicPseudoType then this method will select a cty type automatically based on the Lua value type, which is an obvious mapping for most types but note that Lua tables are always converted to object types unless specifically typed other wise.
If the requested conversion is not possible -- because the given Lua value is not of a suitable type for the target type -- the result is cty.DynamicVal and an error is returned.
Not all Lua types have corresponding cty types; those that don't will produce an error regardless of the target type.
Error messages are written with a Lua developer as the audience, and so will not include Go-specific implementation details. Where possible, the result is a cty.PathError describing the location of the error within the given data structure.
func (*Converter) WrapCtyFunction ¶
WrapCtyFunction wraps a cty function so that it can be called from Lua as a Lua function.
Arguments to the produced Lua function are converted to the cty types required by the function. The return value is always a cty Value wrapped in a Lua userdata, as would be returned from WrapCtyValue.
func (*Converter) WrapCtyValue ¶
WrapCtyValue takes a cty Value and returns a Lua value (of type UserData) that represents the same value, with its metatable configured such that many Lua operations will delegate to the cty API.
WrapCtyValue produces a result that stays as close as possible to cty semantics when used with other such wrapped values, but the result may not integrate well with native Lua values. For example, a wrapped cty.String value will not compare equal to any native Lua string.
Source Files