engine

type CallParams struct {
	Fn Value
}

type DebugReader interface {
	// Frames walks the active call stack from innermost to outermost,
	// skipping host (Go/C) frames. The slice is fresh on every call.
	Frames() []Frame

	// Locals returns the named locals at the frame indicated by level
	// (0 = innermost). Returns an empty map if the level is out of range.
	Locals(level int) map[string]Value

	// Upvalues returns the captured upvalues at the frame indicated by level.
	// Returns an empty map if the function has no upvalues or the level is
	// out of range.
	Upvalues(level int) map[string]Value

	// CallDepth reports the number of active call frames. Used by step-over
	// to know when a frame boundary is crossed.
	CallDepth() int
}

type DriversProvider interface {
	Drivers() []ReplDriver
}

type Engine interface {
	// NewSession returns a fresh session with standard libraries loaded
	// and ctx bound for cancellation. Pass context.Background() for no cancellation.
	NewSession(ctx context.Context) (Session, error)
}

type Frame struct {
	Source      string
	ShortSrc    string
	CurrentLine int
	Name        string // function name when discoverable
	What        string // engine-reported frame kind (e.g. "main", "tail")
}

type ReplDriver interface {
	// Language returns the driver's name (e.g. "buzz").
	Language() string

	// EvalLine evaluates snippet. Implementations should first try
	// "return "+snippet so that bare expressions print a result; if that
	// fails with a syntax error they should fall back to running snippet
	// as a statement. Returns (nil, nil) if execution succeeded with no
	// printable value. Multiple return values are supported.
	EvalLine(snippet string) ([]Value, error)

	// IsIncomplete returns true when err indicates that snippet is a partial
	// statement that needs more input (e.g. an unexpected end-of-input error).
	// The REPL accumulates additional lines when this returns true.
	IsIncomplete(err error) bool

	// LineDelta returns the net open-block delta for this line of source (e.g.
	// bracket-depth counting for JS). Engines that rely on error-based
	// continuation instead return 0 always. The REPL buffers more input while
	// the cumulative delta is positive.
	LineDelta(line string) int

	// HostBindingNames returns the names injected by the host runtime so the
	// REPL can omit them from .globals output.
	HostBindingNames() []string

	// UserGlobals returns the current user-defined globals with host bindings
	// filtered out. Returns nil when the engine does not support listing globals.
	UserGlobals() map[string]Value
}

type Session interface {
	Close() error

	SetGlobal(name string, v Value)
	GetGlobal(name string) Value

	NewTable() Table
	LoadString(code string) (Value, error)
	DoString(code string) error
	Call(p CallParams) error
}

type StepEvent int

type StepMask int

type Stepper interface {
	SetStepHook(mask StepMask, cb func(StepEvent, Frame))
	ClearStepHook()
}

type Table interface {
	Value
	RawSetString(key string, v Value)
	RawGetString(key string) Value
	RawSetInt(key int, v Value)
	RawGetInt(key int) Value
	ForEach(fn func(k, v Value))
	Len() int
}

type Value interface {
	IsNil() bool
	String() string
	AsString() (string, bool)
	AsNumber() (float64, bool)
	AsBool() bool
	AsTable() (Table, bool)
	AsFunction() (Value, bool)
}