package eval

import ""

Package eval handles evaluation of parsed Elvish code and provides runtime facilities.


Package Files

builtin_fn_cmd.go builtin_fn_cmd_unix.go builtin_fn_container.go builtin_fn_debug.go builtin_fn_env.go builtin_fn_flow.go builtin_fn_fs.go builtin_fn_io.go builtin_fn_misc.go builtin_fn_num.go builtin_fn_pred.go builtin_fn_str.go builtin_fn_styled.go builtin_ns.go builtin_special.go callable.go closure.go compile_effect.go compile_lvalue.go compile_value.go compiler.go deprecation.go eval.go exception.go external_cmd.go frame.go glob.go go_fn.go interrupts.go node_utils.go ns.go options.go port.go process_unix.go purely_eval.go pwd.go var_parse.go var_ref.go


const (
    // FnSuffix is the suffix for the variable names of functions. Defining a
    // function "foo" is equivalent to setting a variable named "foo~", and vice
    // versa.
    FnSuffix = "~"
    // NsSuffix is the suffix for the variable names of namespaces. Defining a
    // namespace foo is equivalent to setting a variable named "foo:", and vice
    // versa.
    NsSuffix = ":"


var (
    // NoArgs is an empty argument list. It can be used as an argument to Call.
    NoArgs = []interface{}{}
    // NoOpts is an empty option map. It can be used as an argument to Call.
    NoOpts = map[string]interface{}{}
var (
    ErrBadglobPattern          = errors.New("bad globPattern; elvish bug")
    ErrCannotDetermineUsername = errors.New("cannot determine user name from glob pattern")

Errors thrown when globbing.

var (
    // ErrExternalCmdOpts is thrown when an external command is passed Elvish
    // options.
    // TODO: Catch this kind of errors at compilation time.
    ErrExternalCmdOpts = errors.New("external commands don't accept elvish options")
    // ErrImplicitCdNoArg is thrown when an implicit cd form is passed arguments.
    ErrImplicitCdNoArg = errors.New("implicit cd accepts no arguments")
var (
    ErrMustFollowWildcard    = errors.New("must follow wildcard")
    ErrModifierMustBeString  = errors.New("modifier must be string")
    ErrWildcardNoMatch       = errors.New("wildcard has no match")
    ErrMultipleTypeModifiers = errors.New("only one type modifier allowed")
    ErrUnknownTypeModifier   = errors.New("unknown type modifier")
var (
    // ErrArgs is thrown when a Go function gets erroneous arguments.
    // TODO(xiaq): Replace this single error type with multiple types that carry
    // richer error information.
    ErrArgs = errors.New("args error")
    // ErrNoOptAccepted is thrown when a Go function that does not accept any
    // options gets passed options.
    ErrNoOptAccepted = errors.New("function does not accept any options")
var (
    // ClosedChan is a closed channel, suitable as a placeholder input channel.
    ClosedChan = getClosedChan()
    // BlackholeChan is a channel that absorbs all values written to it,
    // suitable as a placeholder output channel.
    BlackholeChan = getBlackholeChan()
    // DevNull is /dev/null, suitable as a placeholder file for either input or
    // output.
    DevNull = getDevNull()

    // DummyInputPort is a port made up from DevNull and ClosedChan, suitable as
    // a placeholder input port.
    DummyInputPort = &Port{File: DevNull, Chan: ClosedChan}
    // DummyOutputPort is a port made up from DevNull and BlackholeChan,
    // suitable as a placeholder output port.
    DummyOutputPort = &Port{File: DevNull, Chan: BlackholeChan}
var ErrBadBase = errors.New("bad base")

ErrBadBase is thrown by the "base" builtin if the base is smaller than 2 or greater than 36.

var ErrInputOfEawkMustBeString = errors.New("input of eawk must be string")

ErrInputOfEawkMustBeString is thrown when eawk gets a non-string input.

var ErrInterrupted = errors.New("interrupted")

ErrInterrupted is thrown when the execution is interrupted by a signal.

var ErrNonExistentEnvVar = errors.New("non-existent environment variable")

ErrNonExistentEnvVar is raised by the get-env command when the environment variable does not exist.

var ErrNotInSameProcessGroup = errors.New("not in the same process group")

ErrNotInSameProcessGroup is thrown when the process IDs passed to fg are not in the same process group.

var ErrStoreNotConnected = errors.New("store not connected")

ErrStoreNotConnected is thrown by dir-history when the store is not connected.

var ErrUncomparable = errs.BadValue{
    What:  `inputs to "order"`,
    Valid: "comparable values", Actual: "uncomparable values"}

ErrUncomparable is raised by the order command when inputs contain uncomparable values.

var Getwd func() (string, error) = os.Getwd

Getwd allows for unit test error injection.

var IsBuiltinSpecial = map[string]bool{}

IsBuiltinSpecial is the set of all names of builtin special forms. It is intended for external consumption, e.g. the syntax highlighter.

var OK = &exception{}

OK is a pointer to a special value of Exception that represents the absence of exception.

var TimeAfter = func(fm *Frame, d time.Duration) <-chan time.Time {
    return time.After(d)

TimeAfter is used by the sleep command to obtain a channel that is delivered a value after the specified time.

It is a variable to allow for unit tests to efficiently test the behavior of the `sleep` command, both by eliminating an actual sleep and verifying the duration was properly parsed.

func GetCompilationError

func GetCompilationError(e interface{}) *diag.Error

GetCompilationError returns a *diag.Error if the given value is a compilation error. Otherwise it returns nil.

func IsUnqualified

func IsUnqualified(name string) bool

IsUnqualified returns whether name is an unqualified variable name.

func ListenInterrupts

func ListenInterrupts() (<-chan struct{}, func())

ListenInterrupts returns a channel that is closed when SIGINT or SIGQUIT has been received by the process. It also returns a function that should be called when the channel is no longer needed.

func MakePipelineError

func MakePipelineError(excs []Exception) error

MakePipelineError builds an error from the execution results of multiple commands in a pipeline.

If all elements are either nil or OK, it returns nil. If there is exactly non-nil non-OK Exception, it returns it. Otherwise, it return a PipelineError built from the slice, with nil items turned into OK's for easier access from Elvish code.

func MakeVarFromName

func MakeVarFromName(name string) vars.Var

MakeVarFromName creates a Var with a suitable type constraint inferred from the name.

func NewExternalCmdExit

func NewExternalCmdExit(name string, ws syscall.WaitStatus, pid int) error

NewExternalCmdExit constructs an error for representing a non-zero exit from an external command.

func NewPwdVar

func NewPwdVar(ev *Evaler) vars.Var

NewPwdVar returns a variable who value is synchronized with the path of the current working directory.

func NoSuchVariable

func NoSuchVariable(name string) error

NoSuchVariable returns an error representing that a variable can't be found.

func Reason

func Reason(err error) error

Reason returns the Reason field if err is an Exception. Otherwise it returns err itself.

func SplitIncompleteQNameNs

func SplitIncompleteQNameNs(qname string) (ns, name string)

SplitIncompleteQNameNs splits an incomplete qualified variable name into the namespace part and the name part.

func SplitQName

func SplitQName(qname string) (first, rest string)

SplitQName splits a qualified name into the first namespace segment and the rest.

func SplitQNameSegs

func SplitQNameSegs(qname string) []string

SplitQNameSegs splits a qualified name into namespace segments.

func SplitSigil

func SplitSigil(ref string) (sigil string, qname string)

SplitSigil splits any leading sigil from a qualified variable name.

type CallCfg

type CallCfg struct {
    // Arguments to pass to the the function.
    Args []interface{}
    // Options to pass to the function.
    Opts map[string]interface{}
    // The name of the internal source that is calling the function.
    From string

CallCfg keeps configuration for the (*Evaler).Call method.

type Callable

type Callable interface {
    // Call calls the receiver in a Frame with arguments and options.
    Call(fm *Frame, args []interface{}, opts map[string]interface{}) error

Callable wraps the Call method.

func NewExternalCmd

func NewExternalCmd(name string) Callable

NewExternalCmd returns a callable that executes the named external command.

An external command converts all arguments to strings, and does not accept any option.

func NewGoFn

func NewGoFn(name string, impl interface{}) Callable

NewGoFn wraps a Go function into an Elvish function using reflection.

Parameters are passed following these rules:

1. If the first parameter of function has type *Frame, it gets the current call frame.

2. After the potential *Frame argument, the first parameter has type RawOptions, it gets a map of option names to their values.

Alternatively, this parameter may be a (non-pointer) struct whose pointer type implements a SetDefaultOptions method that takes no arguments and has no return value. In this case, a new instance of the struct is constructed, the SetDefaultOptions method is called, and any option passed to the Elvish function is used to populate the fields of the struct. Field names are mapped to option names using strutil.CamelToDashed, unless they have a field tag "name", in which case the tag is preferred.

If the function does not declare that it accepts options via either method described above, it accepts no options.

3. If the last parameter is non-variadic and has type Inputs, it represents an optional parameter that contains the input to this function. If the argument is not supplied, the input channel of the Frame will be used to supply the inputs.

4. Other parameters are converted using vals.ScanToGo.

Return values go to the channel part of the stdout port, after being converted using vals.FromGo. If the last return value has type error and is not nil, it is turned into an exception and no outputting happens. If the last return value is a nil error, it is ignored.

type Editor

type Editor interface {
    Notify(string, ...interface{})

Editor is the interface that the line editor has to satisfy. It is needed so that this package does not depend on the edit package.

type EvalCfg

type EvalCfg struct {
    // Ports to use in evaluation. The first 3 elements, if not specified
    // (either being nil or Ports containing fewer than 3 elements),
    // will be filled with DummyInputPort, DummyOutputPort and
    // DummyOutputPort respectively.
    Ports []*Port
    // Callback to get a channel of interrupt signals and a function to call
    // when the channel is no longer needed.
    Interrupt func() (<-chan struct{}, func())
    // Whether the Eval method should try to put the Elvish in the foreground
    // after the code is executed.
    PutInFg bool
    // If not nil, used the given global namespace, instead of Evaler's own.
    Global *Ns

EvalCfg keeps configuration for the (*Evaler).Eval method.

type Evaler

type Evaler struct {
    // contains filtered or unexported fields

Evaler provides methods for evaluating code, and maintains state that is persisted between evaluation of different pieces of code. An Evaler is safe to use concurrently.

func NewEvaler

func NewEvaler() *Evaler

NewEvaler creates a new Evaler.

func (*Evaler) AddAfterChdir

func (ev *Evaler) AddAfterChdir(f func(string))

AddAfterChdir adds a function to run after changing directory.

func (*Evaler) AddBeforeChdir

func (ev *Evaler) AddBeforeChdir(f func(string))

AddBeforeChdir adds a function to run before changing directory.

func (*Evaler) AddBuiltin

func (ev *Evaler) AddBuiltin(ns *Ns)

AddBuiltin merges the given *Ns into the builtin namespace.

func (*Evaler) AddGlobal

func (ev *Evaler) AddGlobal(ns *Ns)

AddGlobal merges the given *Ns into the global namespace.

func (*Evaler) AddModule

func (ev *Evaler) AddModule(name string, mod *Ns)

AddModule add an internal module so that it can be used with "use $name" from script.

func (*Evaler) Builtin

func (ev *Evaler) Builtin() *Ns

Builtin returns the builtin Ns.

func (*Evaler) Call

func (ev *Evaler) Call(f Callable, callCfg CallCfg, evalCfg EvalCfg) error

Call calls a given function.

func (*Evaler) Chdir

func (ev *Evaler) Chdir(path string) error

Chdir changes the current directory. On success it also updates the PWD environment variable and records the new directory in the directory history. It runs the functions in beforeChdir immediately before changing the directory, and the functions in afterChdir immediately after (if chdir was successful). It returns nil as long as the directory changing part succeeds.

func (*Evaler) Check

func (ev *Evaler) Check(src parse.Source, w io.Writer) (*parse.Error, *diag.Error)

Check checks the given source code for any parse error and compilation error. It always tries to compile the code even if there is a parse error; both return values may be non-nil. If w is not nil, deprecation messages are written to it.

func (*Evaler) CheckTree

func (ev *Evaler) CheckTree(tree parse.Tree, w io.Writer) *diag.Error

CheckTree checks the given parsed source tree for compilation errors. If w is not nil, deprecation messages are written to it.

func (*Evaler) DaemonClient

func (ev *Evaler) DaemonClient() daemon.Client

DaemonClient returns the daemon client associated with the Evaler.

func (*Evaler) Editor

func (ev *Evaler) Editor() Editor

DaemonClient returns the editor associated with the Evaler.

func (*Evaler) Eval

func (ev *Evaler) Eval(src parse.Source, cfg EvalCfg) error

Eval evaluates a piece of source code with the given configuration. The returned error may be a parse error, compilation error or exception.

func (*Evaler) Global

func (ev *Evaler) Global() *Ns

Global returns the global Ns.

func (*Evaler) PurelyEvalCompound

func (ev *Evaler) PurelyEvalCompound(cn *parse.Compound) (string, bool)

func (*Evaler) PurelyEvalPartialCompound

func (ev *Evaler) PurelyEvalPartialCompound(cn *parse.Compound, upto int) (string, bool)

func (*Evaler) PurelyEvalPrimary

func (ev *Evaler) PurelyEvalPrimary(pn *parse.Primary) interface{}

PurelyEvalPrimary evaluates a primary node without causing any side effects. If this cannot be done, it returns nil.

Currently, only string literals and variables with no @ can be evaluated.

func (*Evaler) SetArgs

func (ev *Evaler) SetArgs(args []string)

SetArgs sets the value of the $args variable to a list of strings, built from the given slice.

func (*Evaler) SetDaemonClient

func (ev *Evaler) SetDaemonClient(client daemon.Client)

SetDaemonClient sets the daemon client associated with the Evaler.

func (*Evaler) SetLibDir

func (ev *Evaler) SetLibDir(libDir string)

SetLibDir sets the library directory for finding external modules.

func (*Evaler) ValuePrefix

func (ev *Evaler) ValuePrefix() string

ValuePrefix returns the prefix to prepend to value outputs when writing them to terminal.

type Exception

type Exception interface {
    Reason() error
    StackTrace() *StackTrace
    // contains filtered or unexported methods

Exception represents exceptions. It is both a Value accessible to Elvish code, and can be returned by methods like like (*Evaler).Eval.

func NewException

func NewException(reason error, stackTrace *StackTrace) Exception

NewException creates a new Exception.

type ExternalCmdExit

type ExternalCmdExit struct {
    CmdName string
    Pid     int

ExternalCmdExit contains the exit status of external commands.

func (ExternalCmdExit) Error

func (exit ExternalCmdExit) Error() string

func (ExternalCmdExit) Fields

func (exit ExternalCmdExit) Fields() vals.StructMap

type FailError

type FailError struct{ Content interface{} }

FailError is an error returned by the "fail" command.

func (FailError) Error

func (e FailError) Error() string

Error returns the string representation of the cause.

func (FailError) Fields

func (e FailError) Fields() vals.StructMap

Fields returns a structmap for accessing fields from Elvish.

type Flow

type Flow uint

Flow is a special type of error used for control flows.

const (
    Return Flow = iota

Control flows.

func (Flow) Error

func (f Flow) Error() string

func (Flow) Fields

func (f Flow) Fields() vals.StructMap

func (Flow) Show

func (f Flow) Show(string) string

Show shows the flow "error".

type Frame

type Frame struct {
    Evaler *Evaler
    // contains filtered or unexported fields

Frame contains information of the current running function, akin to a call frame in native CPU execution. A Frame is only modified during and very shortly after creation; new Frame's are "forked" when needed.

func (*Frame) CaptureOutput

func (fm *Frame) CaptureOutput(f func(*Frame) error) ([]interface{}, error)

CaptureOutput captures the output of a given callback that operates on a Frame.

func (*Frame) Close

func (fm *Frame) Close() error

Close releases resources allocated for this frame. It always returns a nil error. It may be called only once.

func (*Frame) Deprecate

func (fm *Frame) Deprecate(msg string, ctx *diag.Context, minLevel int)

Deprecate shows a deprecation message. The message is not shown if the same deprecation message has been shown for the same location before.

func (*Frame) ErrorFile

func (fm *Frame) ErrorFile() *os.File

ErrorFile returns a file onto which error messages can be written.

func (*Frame) Eval

func (fm *Frame) Eval(src parse.Source, r diag.Ranger, ns *Ns) (*Ns, error)

Eval evaluates a piece of code in a copy of the current Frame. It returns the altered local namespace, and any parse error, compilation error or exception.

See PrepareEval for a description of the arguments.

func (*Frame) InputChan

func (fm *Frame) InputChan() chan interface{}

InputChan returns a channel from which input can be read.

func (*Frame) InputFile

func (fm *Frame) InputFile() *os.File

InputFile returns a file from which input can be read.

func (*Frame) Interrupts

func (fm *Frame) Interrupts() <-chan struct{}

Interrupts returns a channel that is closed when an interrupt signal comes.

func (*Frame) IsInterrupted

func (fm *Frame) IsInterrupted() bool

IsInterrupted reports whether there has been an interrupt.

func (*Frame) IterateInputs

func (fm *Frame) IterateInputs(f func(interface{}))

IterateInputs calls the passed function for each input element.

func (*Frame) OutputChan

func (fm *Frame) OutputChan() chan<- interface{}

OutputChan returns a channel onto which output can be written.

func (*Frame) OutputFile

func (fm *Frame) OutputFile() *os.File

OutputFile returns a file onto which output can be written.

func (*Frame) PipeOutput

func (fm *Frame) PipeOutput(f func(*Frame) error, vCb func(<-chan interface{}), bCb func(*os.File)) error

PipeOutput calls a callback with output piped to the given output handlers.

func (*Frame) PrepareEval

func (fm *Frame) PrepareEval(src parse.Source, r diag.Ranger, ns *Ns) (*Ns, func() Exception, error)

PrepareEval prepares a piece of code for evaluation in a copy of the current Frame. If r is not nil, it is added to the traceback of the evaluation context. If ns is not nil, it is used in place of the current local namespace as the namespace to evaluate the code in.

If there is any parse error or compilation error, it returns a nil *Ns, nil function and the error. If there is no parse error or compilation error, it returns the altered local namespace, function that can be called to actuate the evaluation, and a nil error.

type Inputs

type Inputs func(func(interface{}))

Inputs is the type that the last parameter of a Go-native function can take. When that is the case, it is a callback to get inputs. See the doc of GoFn for details.

type Ns

type Ns struct {
    // contains filtered or unexported fields

Ns is the runtime representation of a namespace. The zero value of Ns is an empty namespace. To create a non-empty Ns, use either NsBuilder or CombineNs.

An Ns is immutable after creation.

func CombineNs

func CombineNs(ns1 *Ns, ns2 *Ns) *Ns

CombineNs returns an *Ns that contains all the bindings from both ns1 and ns2. Names in ns2 takes precedence over those in ns1.

func (*Ns) Equal

func (ns *Ns) Equal(rhs interface{}) bool

Equal returns whether rhs has the same identity as ns.

func (*Ns) HasName

func (ns *Ns) HasName(k string) bool

HasName reports whether the Ns has a variable with the given name.

func (*Ns) Hash

func (ns *Ns) Hash() uint32

Hash returns a hash of the address of ns.

func (*Ns) Index

func (ns *Ns) Index(k interface{}) (interface{}, bool)

Index looks up a variable with the given name, and returns its value if it exists. This is only used for introspection from Elvish code; for introspection from Go code, use IndexName.

func (*Ns) IndexName

func (ns *Ns) IndexName(k string) vars.Var

Index looks up a variable with the given name, and returns its value if it exists, or nil if it does not. This is the type-safe version of Index and is useful for introspection from Go code.

func (*Ns) IterateKeys

func (ns *Ns) IterateKeys(f func(interface{}) bool)

IterateKeys produces the names of all the variables in this Ns.

func (*Ns) IterateNames

func (ns *Ns) IterateNames(f func(string))

IterateNames produces the names of all variables in the Ns. It is the type-safe version of IterateKeys and is useful for introspection from Go code. It doesn't support breaking early.

func (*Ns) Kind

func (ns *Ns) Kind() string

Kind returns "ns".

func (*Ns) Repr

func (ns *Ns) Repr(int) string

Repr returns an opaque representation of the Ns showing its address.

type NsBuilder

type NsBuilder map[string]vars.Var

NsBuilder is a helper type used for building an Ns.

func (NsBuilder) Add

func (nb NsBuilder) Add(name string, v vars.Var) NsBuilder

Add adds a variable.

func (NsBuilder) AddFn

func (nb NsBuilder) AddFn(name string, v Callable) NsBuilder

AddFn adds a function. The resulting variable will be read-only.

func (NsBuilder) AddGoFn

func (nb NsBuilder) AddGoFn(nsName, name string, impl interface{}) NsBuilder

AddGoFn adds a Go function. The resulting variable will be read-only.

func (NsBuilder) AddGoFns

func (nb NsBuilder) AddGoFns(nsName string, fns map[string]interface{}) NsBuilder

AddGoFns adds Go functions. The resulting variables will be read-only.

func (NsBuilder) AddNs

func (nb NsBuilder) AddNs(name string, v *Ns) NsBuilder

AddNs adds a sub-namespace. The resulting variable will be read-only.

func (NsBuilder) Ns

func (nb NsBuilder) Ns() *Ns

Build builds an Ns.

type PipelineError

type PipelineError struct {
    Errors []Exception

PipelineError represents the errors of pipelines, in which multiple commands may error.

func (PipelineError) Error

func (pe PipelineError) Error() string

Error returns a plain text representation of the pipeline error.

func (PipelineError) Fields

func (pe PipelineError) Fields() vals.StructMap

type Port

type Port struct {
    File *os.File
    Chan chan interface{}
    // contains filtered or unexported fields

Port conveys data stream. It always consists of a byte band and a channel band.

func CapturePort

func CapturePort() (*Port, func() []interface{}, error)

CapturePort returns an output *Port whose value and byte components are both connected to an internal pipe that saves the output. It also returns a function to call to obtain the captured output.

func FilePort

func FilePort(f *os.File, valuePrefix string) (*Port, func())

FilePort returns an output *Port where the byte component is the file itself, and the value component is converted to an internal channel that writes each value to the file, prepending with a prefix. It also returns a cleanup function, which should be called when the *Port is no longer needed.

func PipePort

func PipePort(vCb func(<-chan interface{}), bCb func(*os.File)) (*Port, func(), error)

PipePort returns an output *Port whose value and byte components are both piped. The supplied functions are called on a separate goroutine with the read ends of the value and byte components of the port. It also returns a function to clean up the port and wait for the callbacks to finish.

func PortsFromFiles

func PortsFromFiles(files [3]*os.File, prefix string) ([]*Port, func())

PortsFromFiles builds 3 ports from 3 files. It also returns a function that should be called when the ports are no longer needed.

func PortsFromStdFiles

func PortsFromStdFiles(prefix string) ([]*Port, func())

PortsFromStdFiles is a shorthand for calling PortsFromFiles with os.Stdin, os.Stdout and os.Stderr.

func StringCapturePort

func StringCapturePort() (*Port, func() []string, error)

StringCapturePort is like CapturePort, but processes value outputs by stringifying them and prepending an output marker.

type RawOptions

type RawOptions map[string]interface{}

RawOptions is the type of an argument a Go-native function can take to declare that it wants to parse options itself. See the doc of NewGoFn for details.

type StackTrace

type StackTrace struct {
    Head *diag.Context
    Next *StackTrace

StackTrace represents a stack trace as a linked list of diag.Context. The head is the innermost stack.

Since pipelines can call multiple functions in parallel, all the StackTrace nodes form a DAG.

func MakeStackTrace

func MakeStackTrace(entries ...*diag.Context) *StackTrace

MakeStackTrace creates a new StackTrace from the given Context entries, using the first entry as the head.

type UnsupportedOptionsError

type UnsupportedOptionsError struct {
    Options []string

UnsupportedOptionsError is an error returned by a closure call when there are unsupported options.

func (UnsupportedOptionsError) Error


When evaluating closures, async access to global variables and ports can be problematic.


errsPackage errs declares error types used as exception causes.
valsPackage vals contains basic facilities for manipulating values used in the Elvish runtime.
varsPackage vars contains basic types for manipulating Elvish variables.

Package eval imports 47 packages (graph) and is imported by 6 packages. Updated now.

Tools for package owners.