Documentation
¶
Overview ¶
Package dataconv provides helper functions to convert between Starlark and Go types.
It works like package starlight, but only supports common Starlark and Go types, and won't wrap any custom types or functions.
For data type conversion, it provides functions to convert between Starlark and Go types:
+---------+ Marshal +------------+ MarshalStarlarkJSON +----------+ | | ----------> | | ----------------------> | | | Go | | Starlark | | JSON | | Value | <---------- | Value | <---------------------- | String | | | Unmarshal | | UnmarshalStarlarkJSON | | +---------+ +------------+ +----------+
Index ¶
- func CloneDict(od *starlark.Dict) (*starlark.Dict, error)
- func ConvertJSONStruct(v interface{}) starlark.Value
- func ConvertStruct(v interface{}, tagName string) starlark.Value
- func DecodeStarlarkJSON(data []byte) (starlark.Value, error)
- func EncodeStarlarkJSON(v starlark.Value) (string, error)
- func GetThreadContext(thread *starlark.Thread) context.Context
- func GoToStarlarkViaJSON(v interface{}) (starlark.Value, error)
- func IsEmptyString(s starlark.String) bool
- func IsInterfaceNil(i interface{}) bool
- func MakeModule(name string, data starlark.StringDict) *starlarkstruct.Module
- func MakeStruct(name string, data starlark.StringDict) *starlarkstruct.Struct
- func Marshal(data interface{}) (v starlark.Value, err error)
- func MarshalStarlarkJSON(data starlark.Value, indent int) (string, error)
- func StarString(x starlark.Value) string
- func TypeConvert(data interface{}) interface{}
- func Unmarshal(x starlark.Value) (val interface{}, err error)
- func UnmarshalStarlarkJSON(data []byte) (starlark.Value, error)
- func WrapModuleData(name string, data starlark.StringDict) func() (starlark.StringDict, error)
- func WrapStructData(name string, data starlark.StringDict) func() (starlark.StringDict, error)
- type Marshaler
- type SharedDict
- func (s *SharedDict) Attr(name string) (starlark.Value, error)
- func (s *SharedDict) AttrNames() []string
- func (s *SharedDict) CloneDict() (*starlark.Dict, error)
- func (s *SharedDict) CompareSameType(op syntax.Token, yv starlark.Value, depth int) (bool, error)
- func (s *SharedDict) Freeze()
- func (s *SharedDict) Get(k starlark.Value) (v starlark.Value, found bool, err error)
- func (s *SharedDict) Hash() (uint32, error)
- func (s *SharedDict) Len() int
- func (s *SharedDict) LoadJSON(jsonStr string) error
- func (s *SharedDict) SetKey(k, v starlark.Value) error
- func (s *SharedDict) SetTypeName(name string)
- func (s *SharedDict) String() string
- func (s *SharedDict) ToJSON() (string, error)
- func (s *SharedDict) Truth() starlark.Bool
- func (s *SharedDict) Type() string
- type StarlarkFunc
- type Unmarshaler
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CloneDict ¶
CloneDict returns a shadow-clone of the given dictionary. It's safe to call it with a nil dictionary, it will return a new empty dictionary.
func ConvertJSONStruct ¶
ConvertJSONStruct converts a struct to a Starlark wrapper with JSON tag.
func ConvertStruct ¶
ConvertStruct converts a struct to a Starlark wrapper.
func DecodeStarlarkJSON ¶
DecodeStarlarkJSON decodes JSON bytes into a starlark.Value using the official JSON module of Starlark Go. It retrieves the "json.decode" function from the Starlark standard library and calls it to perform the decoding. It handles certain Starlark-specific structures better but less control over Go-specific types. Compared to the Marshal/Unmarshal* pair, which is more feature-rich and flexible, the Encode/Decode* pair is more focused on core Starlark types.
func EncodeStarlarkJSON ¶
EncodeStarlarkJSON encodes a starlark.Value into a JSON string using the official JSON module of Starlark Go. It retrieves the "json.encode" function from the Starlark standard library and calls it to perform the encoding. It's less flexible but more straightforward for pure Starlark values. Compared to the Marshal/Unmarshal* pair, which is more feature-rich and flexible, the Encode/Decode* pair is more focused on core Starlark types.
func GetThreadContext ¶
GetThreadContext returns the context of the given thread, or new context if not found.
func GoToStarlarkViaJSON ¶
GoToStarlarkViaJSON converts any Go value that can be marshaled into JSON into a corresponding Starlark value. It first marshals the Go value into a JSON string with the standard Go JSON package, then decodes this JSON string into a Starlark value with the official Starlark JSON module.
func IsEmptyString ¶
IsEmptyString checks is a starlark string is empty ("" for a go string) starlark.String.String performs repr-style quotation, which is necessary for the starlark.Value contract but a frequent source of errors in API clients. This helper method makes sure it'll work properly
func IsInterfaceNil ¶
func IsInterfaceNil(i interface{}) bool
IsInterfaceNil returns true if the given interface is nil.
func MakeModule ¶
func MakeModule(name string, data starlark.StringDict) *starlarkstruct.Module
MakeModule creates a Starlark module from the given name and data.
func MakeStruct ¶
func MakeStruct(name string, data starlark.StringDict) *starlarkstruct.Struct
MakeStruct creates a Starlark struct from the given name and data.
func Marshal ¶
Marshal converts Go values into Starlark types, like ToValue() of package starlight does. It only supports common Go types, won't wrap any custom types like Starlight does.
func MarshalStarlarkJSON ¶
MarshalStarlarkJSON marshals a starlark.Value into a JSON string. It first converts the starlark.Value into a Go value using the Unmarshal function, then marshals the Go value into a JSON string. It handles Go-specific types (supports more types like Go slices, maps, structs, interfaces, time) better than EncodeStarlarkJSON but may be slower due to intermediate conversion.
func StarString ¶
StarString returns the string representation of a starlark.Value, i.e. converts Starlark values to Go strings.
func TypeConvert ¶
func TypeConvert(data interface{}) interface{}
TypeConvert converts JSON decoded values to their appropriate types. Usually it's used after JSON Unmarshal, Starlark Unmarshal, or similar.
func Unmarshal ¶
Unmarshal converts a starlark.Value into it's Golang counterpart, like FromValue() of package starlight does. It's the opposite of Marshal().
func UnmarshalStarlarkJSON ¶
UnmarshalStarlarkJSON unmarshals JSON bytes into a starlark.Value. It first unmarshals the JSON bytes into a Go value using the standard JSON Unmarshal function, then converts the Go value into a starlark.Value using the Marshal function. Time strings are parsed as starlark Time objects. In comparison with DecodeStarlarkJSON, it gives you more control over type conversion but may be less efficient due to intermediate steps.
func WrapModuleData ¶
func WrapModuleData(name string, data starlark.StringDict) func() (starlark.StringDict, error)
WrapModuleData wraps data from the given starlark.StringDict into a Starlark module loader, which can be used to load the module into a Starlark interpreter and accessed via `load("name", "data_key")`.
func WrapStructData ¶
func WrapStructData(name string, data starlark.StringDict) func() (starlark.StringDict, error)
WrapStructData wraps data from the given starlark.StringDict into a Starlark struct loader, which can be used to load the struct into a Starlark interpreter and accessed via `load("name", "data_key")`.
Types ¶
type Marshaler ¶
type Marshaler interface {
// MarshalStarlark marshal a custom type to Starlark object.
MarshalStarlark() (starlark.Value, error)
}
Marshaler is the interface use to marshal Starlark from custom types, i.e. Go to Starlark.
type SharedDict ¶
type SharedDict struct {
// contains filtered or unexported fields
}
SharedDict represents a thread-safe dictionary that can be concurrently accessed and modified by multiple Starlark threads. This synchronization is crucial in concurrent environments where Starlark scripts are executed in parallel, ensuring data consistency and preventing race conditions.
The internal state of a SharedDict includes a standard Starlark dictionary (`*starlark.Dict`), a mutex (`sync.RWMutex`) to manage concurrent access, and a boolean flag indicating whether the dictionary is frozen. A frozen SharedDict cannot be modified, aligning with Starlark's immutability rules for frozen values. Additionally, SharedDict supports custom naming through the 'name' field, allowing for more descriptive representations and debugging.
Constructors: - NewSharedDict: Initializes a new SharedDict with default settings. - NewNamedSharedDict: Creates a new SharedDict with a specified name, providing clarity when multiple SharedDicts are used. - NewSharedDictFromDict: Generates a new SharedDict based on an existing Starlark dictionary. It attempts to clone the original dictionary to preserve immutability.
Methods like Len, CloneDict, ToJSON, LoadJSON provide additional functionalities like determining the dictionary's length, cloning, JSON serialization, and deserialization, enhancing the utility of SharedDict in various use cases.
SharedDict integrates tightly with Starlark's concurrency model, offering a robust solution for managing shared state across threads. By encapsulating thread safety mechanisms and providing a familiar dictionary interface, SharedDict facilitates the development of concurrent Starlark scripts with shared mutable state.
func NewNamedSharedDict ¶
func NewNamedSharedDict(name string) *SharedDict
NewNamedSharedDict creates a new SharedDict instance with the given name.
func NewSharedDict ¶
func NewSharedDict() *SharedDict
NewSharedDict creates a new SharedDict instance.
func NewSharedDictFromDict ¶
func NewSharedDictFromDict(d *starlark.Dict) *SharedDict
NewSharedDictFromDict creates a new SharedDict instance from the given starlark.Dict. It attempts to clone the dictionary, and returns the original dictionary if failed.
func (*SharedDict) Attr ¶
func (s *SharedDict) Attr(name string) (starlark.Value, error)
Attr returns the value of the specified attribute, or (nil, nil) if the attribute is not found. It implements the starlark.HasAttrs interface.
func (*SharedDict) AttrNames ¶
func (s *SharedDict) AttrNames() []string
AttrNames returns a new slice containing the names of all the attributes of the SharedDict. It implements the starlark.HasAttrs interface.
func (*SharedDict) CloneDict ¶
func (s *SharedDict) CloneDict() (*starlark.Dict, error)
CloneDict creates a shallow copy of the underlying Starlark dictionary contained within the SharedDict instance. This method is particularly valuable when a snapshot of the current state of the dictionary is needed without affecting the original dictionary. It ensures that modifications to the returned dictionary do not impact the source SharedDict, providing a mechanism for safe, concurrent read operations.
func (*SharedDict) CompareSameType ¶
CompareSameType compares the SharedDict with another value of the same type. It implements the starlark.Comparable interface.
func (*SharedDict) Freeze ¶
func (s *SharedDict) Freeze()
Freeze prevents the SharedDict from being modified.
func (*SharedDict) Get ¶
Get returns the value corresponding to the specified key, or not found if the mapping does not contain the key. It implements the starlark.Mapping interface.
func (*SharedDict) Hash ¶
func (s *SharedDict) Hash() (uint32, error)
Hash returns the hash value of the SharedDict, actually it's not hashable.
func (*SharedDict) Len ¶
func (s *SharedDict) Len() int
Len returns the length of the underlying dictionary. Notice that this method is not a must for the starlark.Value interface, but it's useful for Go code.
func (*SharedDict) LoadJSON ¶
func (s *SharedDict) LoadJSON(jsonStr string) error
LoadJSON updates the SharedDict instance with key-value pairs decoded from a given JSON string. This method provides a convenient way to populate or update the contents of a SharedDict with data received in JSON format, such as from a configuration file, a network request, or any external data source.
The method attempts to merge the contents of the JSON string into the existing SharedDict. In cases where keys overlap, the values specified in the JSON string will overwrite those in the SharedDict.
It's important to ensure that the JSON string represents a dictionary/object structure; otherwise, `LoadJSON` will return an error. Also, the SharedDict must not be frozen; attempting to modify a frozen SharedDict will result in an error.
func (*SharedDict) SetKey ¶
func (s *SharedDict) SetKey(k, v starlark.Value) error
SetKey sets the value for the specified key, supports update using x[k]=v syntax, like a dictionary. It implements the starlark.HasSetKey interface.
func (*SharedDict) SetTypeName ¶
func (s *SharedDict) SetTypeName(name string)
SetTypeName sets the type name of the SharedDict.
func (*SharedDict) String ¶
func (s *SharedDict) String() string
func (*SharedDict) ToJSON ¶
func (s *SharedDict) ToJSON() (string, error)
ToJSON serializes the SharedDict instance into a JSON string representation. This method facilitates the conversion of complex, nested data structures stored within a SharedDict into a universally recognizable format (JSON), making it easier to export or log the data contained within the SharedDict.
It is important to note that the serialization process adheres to JSON's limitations, such as not supporting circular references. If the SharedDict contains circular references or types not supported by JSON (e.g., functions), `ToJSON` will return an error.
func (*SharedDict) Truth ¶
func (s *SharedDict) Truth() starlark.Bool
Truth returns the truth value of the SharedDict.
func (*SharedDict) Type ¶
func (s *SharedDict) Type() string
Type returns the type name of the SharedDict.
type StarlarkFunc ¶
type StarlarkFunc func(thread *starlark.Thread, fn *starlark.Builtin, args starlark.Tuple, kwargs []starlark.Tuple) (starlark.Value, error)
StarlarkFunc is a function that can be called from Starlark.
type Unmarshaler ¶
type Unmarshaler interface {
// UnmarshalStarlark unmarshal a Starlark object to custom type.
UnmarshalStarlark(starlark.Value) error
}
Unmarshaler is the interface use to unmarshal Starlark values to custom types, i.e. Starlark to Go.
Source Files
Directories