Documentation
¶
Overview ¶
Package convert provides functions for converting data and functions between Go and Starlark.
Index ¶
- Variables
- func FromDict(m *starlark.Dict) map[interface{}]interface{}
- func FromList(l *starlark.List) []interface{}
- func FromSet(s *starlark.Set) map[interface{}]bool
- func FromSetToSlice(s *starlark.Set) []interface{}
- func FromStringDict(m starlark.StringDict) map[string]interface{}
- func FromTuple(v starlark.Tuple) []interface{}
- func FromValue(v starlark.Value) interface{}
- func MakeDict(v interface{}) (starlark.Value, error)
- func MakeDictWithTag(v interface{}, tagName string) (starlark.Value, error)
- func MakeList(v []interface{}) (*starlark.List, error)
- func MakeSet(s map[interface{}]bool) (*starlark.Set, error)
- func MakeSetFromSlice(s []interface{}) (*starlark.Set, error)
- func MakeStarFn(name string, gofn interface{}) *starlark.Builtin
- func MakeStringDict(m map[string]interface{}) (starlark.StringDict, error)
- func MakeStringDictWithTag(m map[string]interface{}, tagName string) (starlark.StringDict, error)
- func MakeTuple(v []interface{}) (starlark.Tuple, error)
- func ToValue(v interface{}) (starlark.Value, error)
- func ToValueWithTag(v interface{}, tagName string) (starlark.Value, error)
- func TryFromDict(m *starlark.Dict) (map[interface{}]interface{}, error)
- func TryFromSet(s *starlark.Set) (map[interface{}]bool, error)
- type DoNotCompare
- type GoInterface
- func (g *GoInterface) Attr(name string) (starlark.Value, error)
- func (g *GoInterface) AttrNames() []string
- func (g *GoInterface) Freeze()
- func (g *GoInterface) Hash() (uint32, error)
- func (g *GoInterface) String() string
- func (g *GoInterface) ToBool() (bool, error)
- func (g *GoInterface) ToFloat() (float64, error)
- func (g *GoInterface) ToInt() (int64, error)
- func (g *GoInterface) ToString() (string, error)
- func (g *GoInterface) ToUint() (uint64, error)
- func (g *GoInterface) Truth() starlark.Bool
- func (g *GoInterface) Type() string
- func (g *GoInterface) Value() reflect.Value
- type GoMap
- func (g *GoMap) Attr(name string) (starlark.Value, error)
- func (g *GoMap) AttrNames() []string
- func (g *GoMap) Clear() error
- func (g *GoMap) Delete(k starlark.Value) (v starlark.Value, found bool, err error)
- func (g *GoMap) Freeze()
- func (g *GoMap) Get(in starlark.Value) (out starlark.Value, found bool, err error)
- func (g *GoMap) Hash() (uint32, error)
- func (g *GoMap) Items() []starlark.Tuple
- func (g *GoMap) Iterate() starlark.Iterator
- func (g *GoMap) Keys() []starlark.Value
- func (g *GoMap) Len() int
- func (g *GoMap) SetKey(k, v starlark.Value) (err error)
- func (g *GoMap) String() string
- func (g *GoMap) Truth() starlark.Bool
- func (g *GoMap) Type() string
- func (g *GoMap) Value() reflect.Value
- type GoSlice
- func (g *GoSlice) Attr(name string) (starlark.Value, error)
- func (g *GoSlice) AttrNames() []string
- func (g *GoSlice) Clear() error
- func (g *GoSlice) Freeze()
- func (g *GoSlice) Hash() (uint32, error)
- func (g *GoSlice) Index(i int) starlark.Value
- func (g *GoSlice) Iterate() starlark.Iterator
- func (g *GoSlice) Len() int
- func (g *GoSlice) SetIndex(index int, v starlark.Value) error
- func (g *GoSlice) Slice(start, end, step int) starlark.Value
- func (g *GoSlice) String() string
- func (g *GoSlice) Truth() starlark.Bool
- func (g *GoSlice) Type() string
- func (g *GoSlice) Value() reflect.Value
- type GoStruct
- func (g *GoStruct) Attr(name string) (starlark.Value, error)
- func (g *GoStruct) AttrNames() []string
- func (g *GoStruct) Freeze()
- func (g *GoStruct) Get(in starlark.Value) (v starlark.Value, found bool, err error)
- func (g *GoStruct) Hash() (uint32, error)
- func (g *GoStruct) SetField(name string, val starlark.Value) error
- func (g *GoStruct) SetKey(k, v starlark.Value) error
- func (g *GoStruct) String() string
- func (g *GoStruct) Truth() starlark.Bool
- func (g *GoStruct) Type() string
- func (g *GoStruct) Value() reflect.Value
- type Kwarg
- type PanicError
Constants ¶
This section is empty.
Variables ¶
var (
// DefaultPropertyTag is the default struct tag to use when converting
DefaultPropertyTag = "starlark"
)
Functions ¶
func FromDict ¶
FromDict converts a starlark.Dict to a map[interface{}]interface{}. Keys are converted with the same rules as TryFromDict; a key with no comparable Go form falls back to its printed form (k.String()) so the entry is preserved instead of panicking. Use TryFromDict to detect such keys instead of silently accepting the fallback.
func FromList ¶
FromList creates a go slice from the given starlark list. A list that reaches itself converts its cyclic reference to nil.
func FromSet ¶
FromSet converts a starlark.Set to a map[interface{}]bool. Elements are converted with the same rules as TryFromSet; an element with no comparable Go form falls back to its printed form (v.String()) so the member is preserved instead of panicking. Use TryFromSet to detect such elements instead of silently accepting the fallback.
func FromSetToSlice ¶ added in v0.2.0
FromSetToSlice converts a starlark.Set into a []interface{}, preserving the set's iteration (insertion) order. Use it instead of FromSet when the order of members matters: FromSet returns a Go map, which has no defined iteration order.
func FromStringDict ¶
func FromStringDict(m starlark.StringDict) map[string]interface{}
FromStringDict makes a map[string]interface{} from the given arg. Any inconvertible values are ignored.
func FromValue ¶
FromValue converts a starlark value to a go value.
Integer contract: a starlark.Int converts down a fixed ladder — int64 if the value fits, else uint64 if it fits, else *math/big.Int. The Go type of a round-tripped integer therefore depends on its magnitude and is not guaranteed to be identical to what was originally converted in.
func MakeDict ¶
MakeDict makes a Dict from the given map. The acceptable keys and values are the same as ToValue. For nil input, it returns an empty Dict. It panics if the input is not a map.
func MakeDictWithTag ¶ added in v0.0.8
MakeDictWithTag makes a Dict from the given map with custom tag. The acceptable keys and values are the same as ToValueWithTag. For nil input, it returns an empty Dict. It panics if the input is not a map.
func MakeList ¶ added in v0.0.5
MakeList makes a Starlark List from the given Go slice. The types supported are the same as ToValue. It returns an empty list for nil input.
func MakeSet ¶
MakeSet makes a Set from the given map. The acceptable keys the same as ToValue. For nil input, it returns an empty Set.
func MakeSetFromSlice ¶ added in v0.0.5
MakeSetFromSlice makes a Set from the given slice. The acceptable keys the same as ToValue. For nil input, it returns an empty Set.
func MakeStarFn ¶
MakeStarFn creates a wrapper around the given function that can be called from a starlark script. Argument support is the same as ToValue. If the last value the function returns is an error, it will cause an error to be returned from the starlark function. If there are no other errors, the function will return None. If there's exactly one other value, the function will return the starlark equivalent of that value. If there is more than one return value, they'll be returned as a tuple. MakeStarFn will panic if you pass it something other than a function, like nil or a non-function.
func MakeStringDict ¶
func MakeStringDict(m map[string]interface{}) (starlark.StringDict, error)
MakeStringDict makes a StringDict from the given arg. The types supported are the same as ToValue. It returns an empty dict for nil input.
func MakeStringDictWithTag ¶ added in v0.0.8
func MakeStringDictWithTag(m map[string]interface{}, tagName string) (starlark.StringDict, error)
MakeStringDictWithTag makes a StringDict from the given arg with custom tag. The types supported are the same as ToValueWithTag. It returns an empty dict for nil input.
func MakeTuple ¶ added in v0.0.5
MakeTuple makes a Starlark Tuple from the given Go slice. The types supported are the same as ToValue. It returns an empty tuple for nil input.
func ToValue ¶
ToValue attempts to convert the given value to a starlark.Value. It supports all int, uint, and float numeric types, plus strings and booleans. It supports structs, maps, slices, and functions that use the aforementioned. Any starlark.Value is passed through as-is.
func ToValueWithTag ¶ added in v0.0.8
ToValueWithTag attempts to convert the given value to a starlark.Value. It works like ToValue, but also accepts a tag name to use for all nested struct fields.
func TryFromDict ¶ added in v0.2.0
TryFromDict converts a starlark.Dict to a map[interface{}]interface{}. It works like FromDict, but returns an error if any key has no comparable Go form (e.g. a custom value that converts to a non-comparable Go type) instead of falling back to the key's printed form.
func TryFromSet ¶ added in v0.2.0
TryFromSet converts a starlark.Set to a map[interface{}]bool. It works like FromSet, but returns an error if any element has no comparable Go form (e.g. a custom value that converts to a non-comparable Go type) instead of falling back to the element's printed form.
Types ¶
type DoNotCompare ¶ added in v0.1.2
type DoNotCompare [0]func()
DoNotCompare is an embedded zero-sized struct used to disallow comparison operations (== and !=) on the containing struct.
type GoInterface ¶
type GoInterface struct {
// contains filtered or unexported fields
}
GoInterface wraps a go value to expose its methods to starlark scripts. Basic types will not behave as their base type (you can't add 2 to an ID, even if it is an int underneath).
func MakeGoInterface ¶
func MakeGoInterface(v interface{}) *GoInterface
MakeGoInterface converts the given value into a GoInterface. This will panic if the value is nil or the type is not a bool, string, float kind, int kind, or uint kind.
func (*GoInterface) Attr ¶
func (g *GoInterface) Attr(name string) (starlark.Value, error)
Attr returns a starlark value that wraps the method or field with the given name.
func (*GoInterface) AttrNames ¶
func (g *GoInterface) AttrNames() []string
AttrNames returns the names Attr resolves for this value: the wrapped value's methods plus the synthetic to* conversion attributes, sorted and without duplicates.
func (*GoInterface) Freeze ¶
func (g *GoInterface) Freeze()
Freeze is a no-op: GoInterface exposes no write path, so there is nothing to freeze. The wrapped Go value itself is not protected — the host can still mutate it.
func (*GoInterface) Hash ¶
func (g *GoInterface) Hash() (uint32, error)
Hash returns a function of x such that Equals(x, y) => Hash(x) == Hash(y). Hash may fail if the value's type is not hashable, or if the value contains a non-hashable value.
func (*GoInterface) String ¶
func (g *GoInterface) String() string
String returns the string representation of the value. Cyclic or overly deep values are elided as "<cyclic TYPE>" instead of overflowing the stack; see safeGoString.
func (*GoInterface) ToBool ¶
func (g *GoInterface) ToBool() (bool, error)
ToBool converts the interface value into a starlark bool. This will fail if the underlying type is not a bool type or pointer to a bool type.
func (*GoInterface) ToFloat ¶
func (g *GoInterface) ToFloat() (float64, error)
ToFloat converts the interface value into a starlark float. This will fail if the underlying type is not a float type (including if the underlying type is a pointer to a float).
func (*GoInterface) ToInt ¶
func (g *GoInterface) ToInt() (int64, error)
ToInt converts the interface value into a starlark int. This will fail if the underlying type is not an int type or pointer to an int type.
func (*GoInterface) ToString ¶
func (g *GoInterface) ToString() (string, error)
ToString converts the interface value into a starlark string. This will fail if the underlying type is not a string (including if the underlying type is a pointer to a string).
func (*GoInterface) ToUint ¶
func (g *GoInterface) ToUint() (uint64, error)
ToUint converts the interface value into a starlark int. This will fail if the underlying type is not an uint type or pointer to an uint type.
func (*GoInterface) Truth ¶
func (g *GoInterface) Truth() starlark.Bool
Truth returns the truth value of an object.
func (*GoInterface) Type ¶
func (g *GoInterface) Type() string
Type returns a short string describing the value's type.
func (*GoInterface) Value ¶ added in v0.0.3
func (g *GoInterface) Value() reflect.Value
Value returns reflect.Value of the underlying value.
type GoMap ¶
type GoMap struct {
// contains filtered or unexported fields
}
GoMap is a wrapper around a Go map that makes it satisfy starlark's expectations of a starlark dict.
func NewGoMap ¶
func NewGoMap(m interface{}) *GoMap
NewGoMap wraps the given map m in a new GoMap. This function will panic if m is nil or not a map.
func (*GoMap) Freeze ¶
func (g *GoMap) Freeze()
Freeze marks this wrapper as frozen: mutations through this GoMap fail afterwards. The freeze is shallow — it does not propagate to the wrapped Go map, which the host (or other wrappers around the same value) can still mutate.
func (*GoMap) Hash ¶
Hash returns a function of x such that Equals(x, y) => Hash(x) == Hash(y). Hash may fail if the value's type is not hashable, or if the value contains a non-hashable value.
func (*GoMap) String ¶
String returns the string representation of the value. Cyclic or overly deep values are elided as "<cyclic TYPE>" instead of overflowing the stack; see safeGoString.
type GoSlice ¶
type GoSlice struct {
// contains filtered or unexported fields
}
GoSlice is a wrapper around a Go slice or array to adapt it for use with starlark. Arrays are copied into a slice at wrap time: they arrive by value (unaddressable) through interface{}, so in-place mutation could never reach the host's array anyway — mutations affect the copy only.
func NewGoSlice ¶
func NewGoSlice(slice interface{}) *GoSlice
NewGoSlice wraps the given slice or array in a new GoSlice; arrays are copied into a slice (see the GoSlice doc). This function will panic if the argument is not a slice nor an array.
func (*GoSlice) Freeze ¶
func (g *GoSlice) Freeze()
Freeze marks this wrapper as frozen: mutations through this GoSlice fail afterwards. The freeze is shallow — it does not propagate to the wrapped Go slice, which the host (or other wrappers around the same value) can still mutate.
func (*GoSlice) Hash ¶
Hash returns a function of x such that Equals(x, y) => Hash(x) == Hash(y). Hash may fail if the value's type is not hashable, or if the value contains a non-hashable value.
func (*GoSlice) String ¶
String returns the string representation of the value. Cyclic or overly deep values are elided as "<cyclic TYPE>" instead of overflowing the stack; see safeGoString.
type GoStruct ¶
type GoStruct struct {
// contains filtered or unexported fields
}
GoStruct is a wrapper around a Go struct to let it be manipulated by Starlark scripts.
func NewStruct ¶
func NewStruct(strct interface{}) *GoStruct
NewStruct makes a new Starlark-compatible Struct from the given struct or pointer to struct. This will panic if you pass it nil or anything else.
func NewStructWithTag ¶
NewStructWithTag makes a new Starlark-compatible Struct from the given struct or pointer to struct, using the given struct tag to determine which fields to expose. This will panic if you pass it anything else.
func (*GoStruct) Attr ¶
Attr returns a Starlark value that wraps the method or field with the given name.
func (*GoStruct) Freeze ¶
func (g *GoStruct) Freeze()
Freeze marks this wrapper as frozen: writes through this GoStruct (attribute or index assignment) fail afterwards. The freeze is shallow — it does not propagate to the wrapped Go struct, which the host (or other wrappers around the same value) can still mutate.
func (*GoStruct) Get ¶ added in v0.1.1
Get returns the value of the field with the given name, allowing the struct to be accessed like a dictionary.
func (*GoStruct) Hash ¶
Hash returns a function of x such that Equals(x, y) => Hash(x) == Hash(y). Hash may fail if the value's type is not hashable, or if the value contains a non-hashable value.
func (*GoStruct) SetField ¶
SetField sets the struct field with the given name with the given value.
func (*GoStruct) SetKey ¶ added in v0.1.1
SetKey implements the starlark.HasSetKey interface, allowing the struct to be used like a dictionary.
func (*GoStruct) String ¶
String returns the string representation of the value. Cyclic or overly deep values are elided as "<cyclic TYPE>" instead of overflowing the stack; see safeGoString.
type Kwarg ¶
type Kwarg struct {
Name string
Value interface{}
}
Kwarg is a single instance of a python foo=bar style named argument.
type PanicError ¶ added in v0.2.0
type PanicError struct {
Value interface{} // the recovered panic value
Stack []byte // the goroutine stack captured at recovery
}
PanicError reports a panic recovered at the conversion boundary. The conversion entry points are not supposed to panic; if this error surfaces, it indicates a bug in starlight (or a misbehaving custom type), and the captured stack identifies where the panic started.
func (*PanicError) Error ¶ added in v0.2.0
func (e *PanicError) Error() string
Error implements the error interface. The message keeps the historic "panic recovered" prefix and appends the captured stack.
Source Files