[tannevaled]

An embedding API that keeps state

Until now the public API was one function, ruby.Run(src, out), which runs a program on a fresh VM. This adds Interp, for hosts that evaluate Ruby piece by piece, exchange values with it and define Ruby from Go. Its first users are the go-scikit Ruby bindings and the Ruby cells of go-notebook.

• State: New(WithStdout(w), WithStderr(w)) *Interp. Eval(src, file, line) (Value, error) evaluates top-level code. Its top-level locals persist from one call to the next, as one binding, and methods, constants and globals persist in the VM as before. SetStdout/SetStderr switch the two streams, which are kept separate. Close runs the at_exit handlers.

• Errors: a Ruby exception, a SyntaxError included, comes back as an *ruby.Error with Class, Message, Backtrace, File and Line. File and Line are those of the innermost frame in the evaluated file, so an exception raised deep in a method is placed at the line of the source that led to it. exit is an *Error whose ExitStatus() holds the status, and the interpreter stays usable after any error.

• Values: Set/Get/Lookup/Locals/ValueOf convert between Go and Ruby:

  • nil, bool and the integers; a Bignum becomes a *big.Int;
  • float, complex, *big.Rat, string/[]byte, ruby.Symbol;
  • slices to Array and maps to Hash;
  • *ndarray.Array to NDArray, as the same array;
  • any other Go value as an opaque object that comes back as itself, of the class Module.Bind names for its type, or of GoValue.

  Value has Go, Inspect, String, ClassName and Call.

• Defining Ruby from Go:

  • DefineModule and DefineClass take qualified names; DefineMethod, DefineSingletonMethod, SetConst, Bind, Wrap.
  • A Func(*Call) receives Self, Args, Kwargs and a Block. Block.Call returns a Ruby exception as an *Error; returning it re-raises the same exception.
  • break, throw and return in the block unwind through the Go code to where Ruby expects them.
  • The operators of a host class are its methods: binary ones, unary minus, and ==. == keeps its result, so a data frame's == can answer a mask.

• Scope of the change: the VM side is internal/vm/embed.go, reached only through an Interp. On the shared path there are three small changes, none of which changes how existing Ruby code runs:

  • callNative keeps the call site's keyword verdict for a host method to read;
  • classOf gets a case for the host object type;
  • binaryOp and OpNeg dispatch when the operand is a host object, and nothing else can be one.

  The README's "Embedding in a Go program" section is rewritten for it.

Verified locally, every step of ci.yml, before the push

• go vet ./..., go build ./..., GOOS=js and GOOS=wasip1 builds.
• go test -race -coverpkg=./internal/... ./...: all green. The coverage ratchet is OK, with no function newly below 100%.
• rbgo_core: vet, the internal/vm + cmd/wasm suite, the 23.2 MB module and web/smoke.mjs --core; the default module's smoke too.
• RBGO_BUILD_IT=1 go test ./cmd/rbgo: ok.

Found while doing this, not changed here

A user-defined -@ on a plain Ruby class is never called: class A; def -@ = 42; end; p(-A.new) raises NoMethodError. OpNeg goes to negate(), which knows only built-in values. Fixing it changes how existing Ruby programs behave, so it belongs in a conformance PR of its own.

🤖 Generated with Claude Code

[tannevaled]

Rebased on #819, whose classOf cases sit next to this PR's. Added a commit: a panic of go-ruby-parser on a malformed source (go-ruby-parser/parser#54) is now a SyntaxError from Interp.Eval rather than a crash of the host. The full local run of ci.yml is green again on the rebased branch.