Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 5 additions & 1 deletion CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
16 changes: 12 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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;
Expand All @@ -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.

Expand Down
62 changes: 62 additions & 0 deletions USAGE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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
Expand Down
6 changes: 3 additions & 3 deletions convert/interface.go
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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":
Expand Down
Loading