Documentation
¶
Overview ¶
Package starlarkconv converts between decoded-JSON Go values and Starlark values, in both directions, with a depth bound and a deterministic key order.
It is the seam between a managed script's language and everything the platform hands it: a tool result going in, a script's own value coming out. It knows nothing about runs, hosts or tools, which is what lets a test exercise the conversion rules directly -- and what makes it a package rather than a file in the engine.
Index ¶
- func Arguments(args *starlark.Dict) (map[string]any, error)
- func ColumnNames(columns any) []string
- func ColumnOrder(rows starlark.Value) []string
- func DictFromStarlark(d *starlark.Dict, depth int) (any, error)
- func FromStarlark(v starlark.Value) (any, error)
- func ResultToStarlark(out map[string]any) (starlark.Value, error)
- func RowsToStarlark(rows []any, columns []string) (starlark.Value, error)
- func SortedKeys(m map[string]any) []string
- func SortedSet(m map[string]bool) []string
- func ToStarlark(v any) (starlark.Value, error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Arguments ¶ added in v1.148.0
Arguments converts the argument dict a script passed into the plain Go map a tool call takes. A missing dict is an empty argument set, which is what a tool taking no arguments wants.
func ColumnNames ¶ added in v1.135.0
ColumnNames reads the column names out of a result's "columns" field: a list of {"name": ...} objects, or of plain names. It returns nil when the field is absent or any entry names nothing, and the caller then falls back to sorted keys rather than to a partial order.
func ColumnOrder ¶
ColumnOrder reads the column order out of a Starlark list of row dicts: the keys of the first row in the order the script wrote them, then any key a later row introduces, in its own order.
It exists because the Go value a row converts to is a map, and a map has no order. A tabular output written from map iteration would put its columns in a different place on every run, which is both unreadable and a break of the determinism contract. Reading the order here — from the Starlark dict, which preserves insertion — gives the author the column order they wrote and gives every run of that script the same one.
Non-dict entries contribute no columns; the exporter reports them.
func DictFromStarlark ¶
DictFromStarlark converts a Starlark dict, refusing non-string keys: the result is destined for JSON, where an object key is a string.
func FromStarlark ¶
FromStarlark converts a Starlark value back to a Go value the platform can serialize. Dict iteration keeps the script's own insertion order, which is deterministic in Starlark and is the order the author wrote.
func ResultToStarlark ¶ added in v1.135.0
ResultToStarlark converts a tool result as ToStarlark does, except that a tabular result -- a "rows" list beside a "columns" list naming them, which is what trino_query and trino_execute answer -- has each row built in column order (#1852). A row is a JSON object and carries no order of its own, so without the columns it would reach the script alphabetized, and an export written straight from it would move the query's columns.
func RowsToStarlark ¶ added in v1.135.0
RowsToStarlark converts a list of rows, setting each object row's keys in the order columns names them. A key the columns do not name follows in sorted order, so nothing a row carries is dropped and every run of a script sees the same order.
func SortedKeys ¶
SortedKeys returns a map's keys in sorted order.
func SortedSet ¶
SortedSet renders a set's members in sorted order, for error messages that must read the same every time.
func ToStarlark ¶
ToStarlark converts a decoded-JSON Go value into a Starlark value.
Map keys are visited in SORTED order, which is load-bearing rather than cosmetic: Go map iteration is randomized, Starlark dicts preserve insertion order, and json.encode follows that order — so unsorted conversion would make a script's own output vary run to run, breaking the determinism contract at the one place the platform fully controls.
Types ¶
This section is empty.
Source Files