diff --git a/CLAUDE.md b/CLAUDE.md index 505207a..929c7ba 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -25,7 +25,7 @@ CI (`.github/workflows/build.yml`): Go `1.19.x`/`1.27.x` × ubuntu-22.04 / macos ## Downstream compatibility — a release gate -starlight is the L1 foundation; `starlet` (via `dataconv`), `starbox`, and the `starpkg/*` modules all depend on it. A change can be locally green yet break a consumer. **Before tagging a release, run the two-leg matrix** — for each downstream (at least `starlet`, then `starbox` / `starpkg/base` / `starpkg/sqlite`): +starlight is the L1 foundation. `starlet` uses it in its default bridge and `dataconv` struct helpers; `starbox` and `starpkg/*` also depend on it. A change can be locally green yet break a consumer. **Before tagging a release, run the two-leg matrix** — for each downstream (at least `starlet`, then `starbox` / `starpkg/base` / `starpkg/sqlite`): Use each downstream module's declared Go floor; do not assume all consumers share this library's Go 1.19 floor. In the following commands, substitute @@ -118,6 +118,10 @@ Note the asymmetry: Go `[]byte` is a `uint8` slice → `*GoSlice`, **not** Starl **Map keys** (`hashableGoValue`) must be **comparable by value**, which is stricter than `reflect.Type.Comparable()` (pointers pass that but compare by identity): `Tuple`→`[N]interface{}`, `Bytes`→`[N]byte`, large `Int`→`bigIntKey`; other hashable values use their `FromValue` form if comparable-by-value, else **error**. `dict`/`list`/`set` keys are unhashable → error. +Public `FromDict`/`FromSet` use printed-string fallback for unsupported key/member +forms; `TryFromDict`/`TryFromSet` report immediate key/member errors instead. +See [result-conversion policies](USAGE.md#results-and-conversion-errors). + When you add or edit any type switch: walk it against **both tables above plus the full `reflect.Kind` set**, and for every unhandled type decide its behavior — error, correct fall-through, or the bug: **silently wrong / panic**. ## Contribution standard diff --git a/README.md b/README.md index 711faf5..3611220 100644 --- a/README.md +++ b/README.md @@ -96,9 +96,11 @@ executes a whole script, including statements and function definitions. The returned `map[string]interface{}` contains bindings defined by the script, converted through `convert.FromValue`. Input names are not automatically copied into the result. Functions and custom values without a native Go conversion -remain `starlark.Value` objects. Conversion, parsing, loading and execution +remain `starlark.Value` objects. Input conversion, parsing, loading and execution failures return an `error`; host changes made before an error are not rolled back. `Eval` compiles on every call and does not use `Cache` automatically. +See [result-conversion policies](USAGE.md#results-and-conversion-errors) for +conversions that have no error return. ## Files, modules and caching @@ -149,10 +151,14 @@ data where it is writable. Pass a struct pointer to allow exported-field writes; Go arrays are copied to slices. A Go `[]byte` is a slice wrapper, not native Starlark `bytes`. Wrapper `Freeze` is shallow; it neither copies host data nor synchronizes host access. The host must coordinate concurrent access. +See the [slice update example](USAGE.md#slice-updates) for explicit write-back +when the host needs the new length. -Exported Go methods are callable from scripts. Field tags rename or hide fields; -they do not hide methods. Neither tags nor wrapper `Freeze` restrict the effects -of a Go method, which may still change host state. +`GoStruct` and `GoInterface` expose the Go methods available on the wrapped +value; `GoMap` and `GoSlice` expose their mapping/sequence builtins instead. +Field tags rename or hide fields; they do not hide methods. Neither tags nor +wrapper `Freeze` restrict the effects of a Go method, which may still change +host state. Channels, complex numbers, `unsafe.Pointer` and `uintptr` have no direct conversion. Statically unsupported collection element types are rejected; @@ -161,6 +167,8 @@ wrappers. Existing `starlark.Value` objects pass through, except typed-nil pointers become `None`. Wrapped Go functions accept **positional arguments only**, including variadics. +Arguments and collection writes use checked conversions: overflow, fractional +float-to-integer conversion and `None` for a non-nullable target are errors. A non-nil final `error` becomes a script error; after removing that error result, zero, one or multiple return values become `None`, one value or a tuple. diff --git a/USAGE.md b/USAGE.md index d8bc318..ecdfe3c 100644 --- a/USAGE.md +++ b/USAGE.md @@ -63,6 +63,66 @@ Tags affect fields, while exported methods such as `Greet` remain callable. A method can have host effects even when its wrapper has been frozen. Pass only host data and methods that the script is allowed to use. +## Slice updates + +Element writes can change the shared backing array, but length-changing +operations update the wrapper's slice header, not the original Go variable. +Return the updated wrapper under a script-defined name and assign the result +back when the host needs the new slice: + +```go +package main + +import ( + "fmt" + "log" + + "github.com/1set/starlight" +) + +func main() { + items := []int{1, 2} + result, err := starlight.Eval([]byte(` +items[0] = 10 +items.append(3) +updated = items +`), map[string]interface{}{"items": items}, nil) + if err != nil { + log.Fatal(err) + } + fmt.Println(items) + items = result["updated"].([]int) + fmt.Println(items) +} +``` + +Output: + +```text +[10 2] +[10 2 3] +``` + +The returned wrapper retains its Go `[]int` type. A native Starlark list instead +converts to `[]interface{}`. Slicing a wrapped slice, such as `items[:]`, copies +its elements; nested values can still be shared. + +## Results and conversion errors + +`Eval` and `Cache.Run` automatically use `convert.FromValue` for each returned +binding. `FromValue` has no error return and is not a lossless graph copy. During +native list/dictionary conversion, a reference back to a list/dictionary already +on that conversion path becomes a nil slice/map. + +Native dictionary keys and set members need comparable Go forms: tuples become +fixed-size arrays, bytes become byte arrays, and integers outside the +`int64`/`uint64` ranges use an internal comparable key type. A key/member without +a stable comparable form falls back to its printed string, which can collide +with another converted key/member. +For direct conversion of a native `*starlark.Dict` or `*starlark.Set`, use +`convert.TryFromDict` or `convert.TryFromSet` to return an error instead of this +fallback. These check the immediate keys/members, not every nested value. + ## Files and modules Create these three files in the example directory: @@ -121,6 +181,8 @@ Hello, Lin! `WithGlobals`; `name` is a per-call input to `main.star` from `Run`. A `Run` input is not automatically available inside a loaded module. Both calls reuse the compiled main script and initialized module but use the current `name` value. +A load name is searched from the configured directories, not from the importing +file's directory. After editing script files, call `cache.Reset()` before the next `Run` to reload all scripts and modules. `cache.Forget("greetings.star")` only removes that diff --git a/convert/interface.go b/convert/interface.go index 337f479..c33237e 100644 --- a/convert/interface.go +++ b/convert/interface.go @@ -9,8 +9,8 @@ import ( "go.starlark.net/starlark" ) -// 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. +// MakeGoInterface wraps a supported scalar or pointer as a GoInterface. +// It panics for unsupported input; use ToValue for error-returning conversion. func MakeGoInterface(v interface{}) *GoInterface { val := reflect.ValueOf(v) ifc, ok := makeGoInterface(val, emptyStr) @@ -51,7 +51,7 @@ type GoInterface struct { tag string } -// Attr returns a starlark value that wraps the method or field with the given name. +// Attr resolves an exported Go method or a synthetic to* conversion method. func (g *GoInterface) Attr(name string) (starlark.Value, error) { switch name { case "toInt":