dataconv

package
v0.1.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 8, 2024 License: MIT Imports: 18 Imported by: 12

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

Constants

This section is empty.

Variables

This section is empty.

Functions

func CloneDict added in v0.1.2 

func CloneDict(od *starlark.Dict) (*starlark.Dict, error)

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 added in v0.0.7 

func ConvertJSONStruct(v interface{}) starlark.Value

ConvertJSONStruct converts a struct to a Starlark wrapper with JSON tag.

func ConvertStruct added in v0.0.7 

func ConvertStruct(v interface{}, tagName string) starlark.Value

ConvertStruct converts a struct to a Starlark wrapper.

func DecodeStarlarkJSON added in v0.1.2 

func DecodeStarlarkJSON(data []byte) (starlark.Value, error)

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 added in v0.1.2 

func EncodeStarlarkJSON(v starlark.Value) (string, error)

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 added in v0.1.2 

func GetThreadContext(thread *starlark.Thread) context.Context

GetThreadContext returns the context of the given thread, or new context if not found.

func IsEmptyString 

func IsEmptyString(s starlark.String) bool

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 added in v0.0.12 

func MakeModule(name string, data starlark.StringDict) *starlarkstruct.Module

MakeModule creates a Starlark module from the given name and data.

func MakeStruct added in v0.0.12 

func MakeStruct(name string, data starlark.StringDict) *starlarkstruct.Struct

MakeStruct creates a Starlark struct from the given name and data.

func Marshal 

func Marshal(data interface{}) (v starlark.Value, err error)

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 

func MarshalStarlarkJSON(data starlark.Value, indent int) (string, error)

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 added in v0.0.9 

func StarString(x starlark.Value) string

StarString returns the string representation of a starlark.Value.

func TypeConvert added in v0.0.8 

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 

func Unmarshal(x starlark.Value) (val interface{}, err error)

Unmarshal converts a starlark.Value into it's Golang counterpart, like FromValue() of package starlight does. It's the opposite of Marshal().

func UnmarshalStarlarkJSON added in v0.0.11 

func UnmarshalStarlarkJSON(data []byte) (starlark.Value, error)

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 added in v0.0.7 

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 added in v0.0.11 

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 added in v0.0.8 

type SharedDict struct {
	sync.RWMutex
	// 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 added in v0.0.8 

func NewNamedSharedDict(name string) *SharedDict

NewNamedSharedDict creates a new SharedDict instance with the given name.

func NewSharedDict added in v0.0.8 

func NewSharedDict() *SharedDict

NewSharedDict creates a new SharedDict instance.

func NewSharedDictFromDict added in v0.0.10 

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 added in v0.0.8 

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 added in v0.0.8 

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 added in v0.0.10 

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 added in v0.0.8 

func (s *SharedDict) CompareSameType(op syntax.Token, yv starlark.Value, depth int) (bool, error)

CompareSameType compares the SharedDict with another value of the same type. It implements the starlark.Comparable interface.

func (*SharedDict) Freeze added in v0.0.8 

func (s *SharedDict) Freeze()

Freeze prevents the SharedDict from being modified.

func (*SharedDict) Get added in v0.0.8 

func (s *SharedDict) Get(k starlark.Value) (v starlark.Value, found bool, err error)

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 added in v0.0.8 

func (s *SharedDict) Hash() (uint32, error)

Hash returns the hash value of the SharedDict, actually it's not hashable.

func (*SharedDict) Len added in v0.0.10 

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 added in v0.0.15 

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 added in v0.0.8 

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 added in v0.0.10 

func (s *SharedDict) SetTypeName(name string)

SetTypeName sets the type name of the SharedDict.

func (*SharedDict) String added in v0.0.8 

func (s *SharedDict) String() string

func (*SharedDict) ToJSON added in v0.0.15 

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 added in v0.0.8 

func (s *SharedDict) Truth() starlark.Bool

Truth returns the truth value of the SharedDict.

func (*SharedDict) Type added in v0.0.8 

func (s *SharedDict) Type() string

Type returns the type name of the SharedDict.

type StarlarkFunc added in v0.0.12 

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

View all Source files

Directories

Path Synopsis
Package types provides wrappers for Starlark types that can be unpacked by the Unpack helper functions to interpret call arguments.
 Package types provides wrappers for Starlark types that can be unpacked by the Unpack helper functions to interpret call arguments.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.