eval

package
v0.6.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 6, 2026 License: BSD-3-Clause Imports: 14 Imported by: 0

Documentation

Overview

Package eval is the evaluator of the Go R interpreter: R values, environments, promises, closures and the primitives, written from the R Language Definition and checked against R 4.6.2 (see docs/m2-design.md). Nothing is translated from R's sources.

Index

Constants

View Source
const (
	DefaultMaxDepth = 5000
	DefaultMaxSteps = 30_000_000
	DefaultMaxAlloc = 16 << 30
	DefaultTimeout  = 10 * time.Second
)

The defaults of Options, chosen by measurement (TestMeasureLimits): the golden snippets and the heaviest cells a notebook runs on purpose (a loop of 10^6 iterations: 3 million steps; a list grown by 20 000 assignments: 1.6 GB of copies, 0.63 s) each get about ten times the largest legitimate use.

View Source
const Unbounded = -1

Unbounded, given as MaxSteps, MaxAlloc or Timeout, removes that limit. It is the only way to do so: a zero selects the default, and any other negative value panics in NewSession. Use it only for trusted code.

Variables

This section is empty.

Functions

func Builtins

func Builtins() []string

Builtins returns the names of the primitives and native functions this evaluator provides.

func Length

func Length(v Value) int

Length is length(x) for the types of this slice.

func ToRDS

func ToRDS(v Value) rds.Value

ToRDS converts a value to the serialization tree, so that it can be compared with, or written like, what R serializes.

Types

type Arg

type Arg struct {
	Name    string
	HasName bool
	Value   Value // Missing for an empty argument
}

Arg is one argument of a call.

type Attr

type Attr struct {
	Name  string
	Value Value
}

Attr is one attribute; the slice keeps R's order.

type Builtin

type Builtin struct {
	Name    string
	Special bool
	// contains filtered or unexported fields
}

Builtin is a primitive: Special ones get their arguments unevaluated.

func (*Builtin) Type

func (b *Builtin) Type() Type

type Closure

type Closure struct {
	Formals []Formal
	Body    Value
	Env     *Env
}

Closure is an R function.

func (*Closure) Type

func (*Closure) Type() Type

type Dots

type Dots struct {
	Args []Arg // Value is a *Promise, a constant, or Missing
}

Dots is the value of `...`: the promises of the extra arguments.

func (*Dots) Type

func (*Dots) Type() Type

type Double

type Double struct {
	V    []float64
	Attr []Attr
}

The vectors. Their slices are never modified in place once a value is visible to R code (copy on modify; see docs/m2-design.md).

func (*Double) Type

func (*Double) Type() Type

type Env

type Env struct {
	// contains filtered or unexported fields
}

Env is an environment: a frame of bindings and an enclosure.

func NewEnv

func NewEnv(parent *Env) *Env

NewEnv makes an environment enclosed by parent.

func (*Env) Get

func (e *Env) Get(name string) (Value, bool)

Get returns the value bound to name in this frame only.

func (*Env) Names

func (e *Env) Names() []string

Names lists the bound names in order of creation (ls(sorted = FALSE)).

func (*Env) Parent

func (e *Env) Parent() *Env

Parent is the enclosure.

func (*Env) Set

func (e *Env) Set(name string, v Value)

Set binds name in this frame.

func (*Env) Type

func (e *Env) Type() Type

type Error

type Error struct {
	Message string
	Call    string
	// Condition is the condition object that was signalled (nil for errors
	// that no handler could see: limits and interrupts).
	Condition Value
	// Output and Stderr are what the cell had written before it failed.
	Output, Stderr string
	// Warnings are the warnings raised before the error.
	Warnings []Warning
	// contains filtered or unexported fields
}

Error is an R error that reached the top level. Message is R's conditionMessage and Call the deparsed conditionCall ("" for none).

func (*Error) Error

func (e *Error) Error() string

func (*Error) Unwrap

func (e *Error) Unwrap() error

Unwrap is context.DeadlineExceeded or context.Canceled for an evaluation that was interrupted, and nil otherwise.

type Formal

type Formal struct {
	Name    *Symbol
	Default Value // nil when there is none
}

Formal is one formal argument of a closure.

type Formals

type Formals struct{ F []Formal }

Formals is the formal-argument list of a `function` expression, which sits in the second place of the call to `function`.

func (*Formals) Type

func (*Formals) Type() Type

type Integer

type Integer struct {
	V    []int32
	Attr []Attr
}

The vectors. Their slices are never modified in place once a value is visible to R code (copy on modify; see docs/m2-design.md).

func (*Integer) Type

func (*Integer) Type() Type

type Lang

type Lang struct {
	Fun  Value
	Args []Arg
}

Lang is a call.

func (*Lang) Type

func (*Lang) Type() Type

type List

type List struct {
	V    []Value
	Attr []Attr
}

The vectors. Their slices are never modified in place once a value is visible to R code (copy on modify; see docs/m2-design.md).

func (*List) Type

func (*List) Type() Type

type Logical

type Logical struct {
	V    []int32
	Attr []Attr
}

The vectors. Their slices are never modified in place once a value is visible to R code (copy on modify; see docs/m2-design.md).

func (*Logical) Type

func (*Logical) Type() Type

type Options

type Options struct {
	// MaxDepth bounds the nesting of evaluations: R's option "expressions"
	// (default 5000). Exceeding it is R's error "evaluation nested too deeply".
	MaxDepth int
	// MaxVector bounds the length of any vector the runtime allocates.
	MaxVector int
	// MaxAlloc bounds the bytes of vector storage one Eval allocates, in
	// total over the evaluation, copies included (default DefaultMaxAlloc).
	// Exceeding it ends the evaluation with an error.
	MaxAlloc int
	// MaxSteps bounds the number of calls and loop iterations evaluated by
	// one Eval (default DefaultMaxSteps).
	MaxSteps int
	// Timeout bounds the time one Eval may take (default DefaultTimeout); a
	// context passed to EvalContext bounds it too.
	Timeout time.Duration
	// Parse bounds the source text of an Eval.
	Parse syntax.Limits
}

Options bound a session. A zero field selects its default; Unbounded (MaxSteps, MaxAlloc, Timeout only) removes the limit explicitly.

type Promise

type Promise struct {
	Expr Value
	Env  *Env
	// contains filtered or unexported fields
}

Promise is a delayed argument.

func (*Promise) Type

func (*Promise) Type() Type

type Result

type Result struct {
	// Value is the value of the last expression.
	Value Value
	// Visible says whether R would print it.
	Visible bool
	// Output is what the cell printed on standard output: what print() and
	// cat() wrote, and the auto-printed value of every visible top-level
	// expression, as an R console shows them.
	Output string
	// Stderr is what the cell wrote on standard error: message() output.
	Stderr string
	// Warnings are the warnings raised and not muffled.
	Warnings []Warning
}

Result is what one Eval returns.

type Session

type Session struct {
	Base, Global, Empty *Env
	// contains filtered or unexported fields
}

Session is one interpreter: a global environment that persists from one Eval to the next. It is not safe for concurrent use.

func NewSession

func NewSession(opts Options) *Session

NewSession makes a session whose global environment is empty, enclosed by the base environment holding the primitives.

func (*Session) Eval

func (s *Session) Eval(src string) (*Result, error)

Eval parses src and evaluates its expressions in order in the global environment, as one notebook cell. The result is that of the last one. Errors are *Error (a runtime error: R's message and call, with the output and warnings so far), *syntax.Error or *syntax.LimitError.

func (*Session) EvalContext

func (s *Session) EvalContext(ctx context.Context, src string) (*Result, error)

EvalContext is Eval that ends, with an *Error wrapping the context's error, when ctx is done; Options.Timeout bounds it as well.

func (*Session) EvalIn

func (s *Session) EvalIn(ctx context.Context, src string, env *Env) (res *Result, err error)

EvalIn is EvalContext in the given environment (a child of the global one, for a cell that must not leave names behind).

func (*Session) Get

func (s *Session) Get(name string) (Value, bool)

Get and Set read and write a variable of the global environment.

func (*Session) Set

func (s *Session) Set(name string, v Value)

type Str

type Str struct {
	S  string
	NA bool
}

Str is an element of a character vector.

type String

type String struct {
	V    []Str
	Attr []Attr
}

The vectors. Their slices are never modified in place once a value is visible to R code (copy on modify; see docs/m2-design.md).

func (*String) Type

func (*String) Type() Type

type Symbol

type Symbol struct{ Name string }

Symbol is an interned name.

func Intern

func Intern(name string) *Symbol

Intern returns the one Symbol with this name.

func (*Symbol) Type

func (*Symbol) Type() Type

type Type

type Type = rds.Type

Type is a SEXPTYPE code.

type Value

type Value interface{ Type() Type }

Value is an R object.

var Missing Value = missingT{}

Missing is the empty argument (R_MissingArg).

var Null Value = nullT{}

Null is R's NULL.

func FromSyntax

func FromSyntax(n syntax.Node) Value

FromSyntax converts a parsed expression to a language object.

type Warning

type Warning struct {
	Message string
	Call    string
}

Warning is a warning raised while evaluating.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL