eval

package
v0.21.0 Latest Latest
Warning

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

 Go to latest Published: Aug 13, 2024 License: BSD-2-Clause Imports: 49 Imported by: 12

Documentation

Overview

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

Index

Examples

Constants

View Source 
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 = ":"
)

Variables

View Source 
var (
	ErrNegativeSleepDuration = errors.New("sleep duration must be >= zero")
	ErrInvalidSleepDuration  = errors.New("invalid sleep duration")
)
View Source 
var (
	// NoArgs is an empty argument list. It can be used as an argument to Call.
	NoArgs = []any{}
	// NoOpts is an empty option map. It can be used as an argument to Call.
	NoOpts = map[string]any{}
)
View Source 
var (
	ErrBadglobPattern          = errors.New("bad globPattern; elvish bug")
	ErrCannotDetermineUsername = errors.New("cannot determine user name from glob pattern")
)

Errors thrown when globbing.

View Source 
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")
)
View Source 
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")
)
View Source 
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}

	// DummyPorts contains 3 dummy ports, suitable as stdin, stdout and stderr.
	DummyPorts = []*Port{DummyInputPort, DummyOutputPort, DummyOutputPort}
)
View Source 
var ErrBothTotalAndLessThan = errors.New("both &total and &less-than specified")

ErrBothTotalAndLessThan is returned by order when both the &total and &less-than options are specified.

View Source 
var ErrDivideByZero = errs.BadValue{
	What: "divisor", Valid: "number other than exact 0", Actual: "exact 0"}

ErrDivideByZero is thrown when attempting to divide by zero.

View Source 
var ErrInterrupted = errors.New("interrupted")

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

View Source 
var (
	// 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")
)
View Source 
var ErrNonExistentEnvVar = errors.New("non-existent environment variable")

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

View Source 
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.

View Source 
var ErrPortDoesNotSupportValueOutput = errors.New("port does not support value output")

ErrPortDoesNotSupportValueOutput is thrown when writing to a port that does not support value output.

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

ErrUncomparable is raised by the compare and order commands when inputs contain uncomparable values.

View Source 
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.

View Source 
var OK = &exception{}

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

Functions

func CallHook added in v0.21.0 

func CallHook(ev *Evaler, evalCfg *EvalCfg, name string, hook vals.List, args ...any)

CallHook runs all the functions in the list "hook", with "args".

If "evalCfg" is not specified, the standard files will be used for IO.

TODO: Eventually all callers should supply evalCfg. In general it's not correct to use standard files:

- Chdir hooks should use the frame from which the chdir is triggered. - Editor lifecycle hooks should use the editor's TTY.

func ListenInterrupts 

func ListenInterrupts() (context.Context, func())

ListenInterrupts returns a Context that is canceled when SIGINT or SIGQUIT has been received by the process. It also returns a function to cancel the Context, which should be called when it 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.

Types

type ByteOutput 

type ByteOutput interface {
	io.Writer
	io.StringWriter
}

ByteOutput defines the interface through which builtin commands access the byte output.

It is a thin wrapper around the underlying *os.File value, only exposing the necessary methods for writing bytes and strings, and converting any syscall.EPIPE errors to errs.ReaderGone.

type CallCfg 

type CallCfg struct {
	// Arguments to pass to the function.
	Args []any
	// Options to pass to the function.
	Opts map[string]any
	// 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 []any, opts map[string]any) 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 any) 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 are written to the stdout channel, after being converted using vals.FromGo. Return values whose types are arrays or slices, and not defined types, have their individual elements written to the output.

If the last return value has nominal type error and is not nil, it is turned into an exception and no return value is written. If the last return value is a nil error, it is ignored.

type Closure added in v0.18.0 

type Closure struct {
	ArgNames []string
	// The index of the rest argument. -1 if there is no rest argument.
	RestArg     int
	OptNames    []string
	OptDefaults []any
	Src         parse.Source
	DefRange    diag.Ranging
	// contains filtered or unexported fields
}

Closure is a function defined with Elvish code. Each Closure has its unique identity.

func (*Closure) Call added in v0.18.0 

func (c *Closure) Call(fm *Frame, args []any, opts map[string]any) error

Call calls a closure.

func (*Closure) Equal added in v0.18.0 

func (c *Closure) Equal(rhs any) bool

Equal compares by address.

func (*Closure) Fields added in v0.18.0 

func (c *Closure) Fields() vals.StructMap

func (*Closure) Hash added in v0.18.0 

func (c *Closure) Hash() uint32

Hash returns the hash of the address of the closure.

func (*Closure) Kind added in v0.18.0 

func (*Closure) Kind() string

Kind returns "fn".

type CompilationError added in v0.20.0 

type CompilationError = diag.Error[CompilationErrorTag]

func UnpackCompilationErrors added in v0.19.0 

func UnpackCompilationErrors(e error) []*CompilationError

UnpackCompilationErrors returns the constituent compilation errors if the given error contains one or more compilation errors. Otherwise it returns nil.

type CompilationErrorTag added in v0.20.0 

type CompilationErrorTag struct{}

CompilationErrorTag parameterizes diag.Error to define CompilationError.

func (CompilationErrorTag) ErrorTag added in v0.20.0 

func (CompilationErrorTag) ErrorTag() string

type EvalCfg 

type EvalCfg struct {
	// Context that can be used to cancel the evaluation.
	Interrupts context.Context
	// 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
	// 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 {

	// Command-line arguments, exposed as $args.
	Args vals.List
	// Hooks to run before exit or exec.
	PreExitHooks []func()
	// Chdir hooks, exposed indirectly as $before-chdir and $after-chdir.
	BeforeChdir, AfterChdir []func(string)
	// Directories to search libraries.
	LibDirs []string
	// Source code of internal bundled modules indexed by use specs.
	BundledModules map[string]string
	// Callback to notify the success or failure of background jobs. Must not be
	// mutated once the Evaler is used to evaluate any code.
	BgJobNotify func(string)
	// Path to the rc file, and path to the rc file actually evaluated. These
	// are not used by the Evaler itself right now; they are here so that they
	// can be exposed to the runtime: module.
	RcPath, EffectiveRcPath string
	// 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) 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, and updates $E:PWD on success

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) (error, []string, error)

Check checks the given source code for any parse error, autofixes, and compilation error. It always tries to compile the code even if there is a parse error. If w is not nil, deprecation messages are written to it.

func (*Evaler) CheckTree 

func (ev *Evaler) CheckTree(tree parse.Tree, w io.Writer) ([]string, error)

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

func (*Evaler) DeleteFromGlobal added in v0.19.0 

func (ev *Evaler) DeleteFromGlobal(names map[string]struct{})

DeleteFromGlobal deletes names from the global namespace.

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.

Example (CapturingValueOutputs) 
package main

import (
	"fmt"

	"src.elv.sh/pkg/eval"
	"src.elv.sh/pkg/eval/vals"
	"src.elv.sh/pkg/parse"
)

func main() {
	ev := eval.NewEvaler()
	// The stdout port captures all values written to it, which can be retrieved
	// with the returned get function.
	stdout, get, err := eval.ValueCapturePort()
	if err != nil {
		panic(err)
	}

	ev.Eval(
		parse.Source{Name: "example 1", Code: "put [&foo=bar] [a b] data"},
		eval.EvalCfg{Ports: []*eval.Port{eval.DummyInputPort, stdout, eval.DummyOutputPort}})

	values := get()
	for i, value := range values {
		fmt.Printf("#%d: %s: %s\n", i, vals.Kind(value), vals.ReprPlain(value))
	}

}

Output:

#0: map: [&foo=bar]
#1: list: [a b]
#2: string: data
Example (InspectingGlobal) 
package main

import (
	"fmt"

	"src.elv.sh/pkg/eval"
	"src.elv.sh/pkg/eval/vals"
	"src.elv.sh/pkg/parse"
)

func main() {
	ev := eval.NewEvaler()
	ev.Eval(
		parse.Source{Name: "example 1", Code: "var map = [&foo=bar]"},
		// Omitting the ports connects all of them to "dummy" IO ports.
		eval.EvalCfg{})

	m, ok := ev.Global().Index("map")
	if !ok {
		fmt.Println("$map not found")
	}
	fmt.Printf("$map: %s: %s\n", vals.Kind(m), vals.ReprPlain(m))

}

Output:

$map: map: [&foo=bar]
Example (UsingPortsFromStdFiles) 
package main

import (
	"src.elv.sh/pkg/eval"
	"src.elv.sh/pkg/parse"
)

func main() {
	ev := eval.NewEvaler()
	// These ports are connected to the process's stdin, stdout and stderr. The
	// "> " part is the prefix to use for value outputs.
	ports, cleanup := eval.PortsFromStdFiles("> ")
	defer cleanup()

	ev.Eval(
		parse.Source{Name: "example 1", Code: "echo Hello Elvish!"},
		eval.EvalCfg{Ports: ports})

	// Value outputs are written with the prefix we specified earlier
	ev.Eval(
		parse.Source{Name: "example 2", Code: "put [&foo=bar]"},
		eval.EvalCfg{Ports: ports})

}

Output:

Hello Elvish!
> [&foo=bar]

func (*Evaler) ExtendBuiltin added in v0.17.0 

func (ev *Evaler) ExtendBuiltin(ns Nser)

ExtendBuiltin extends the builtin namespace with the given namespace.

func (*Evaler) ExtendGlobal added in v0.17.0 

func (ev *Evaler) ExtendGlobal(ns Nser)

ExtendGlobal extends the global namespace with the given namespace.

func (*Evaler) Global 

func (ev *Evaler) Global() *Ns

Global returns the global Ns.

func (*Evaler) PreExit added in v0.19.0 

func (ev *Evaler) PreExit()

PreExit runs all pre-exit hooks.

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) any

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) ReplaceBuiltin added in v0.19.0 

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

ReplaceBuiltin replaces the builtin namespace. It should only be used in tests.

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 {
	error
	diag.Shower
	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 (*Evaler).Eval.

func NewException 

func NewException(reason error, stackTrace *StackTrace) Exception

NewException creates a new Exception.

type ExternalCmdExit 

type ExternalCmdExit struct {
	syscall.WaitStatus
	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

func (ExternalCmdExit) Kind added in v0.20.0 

func (exit ExternalCmdExit) Kind() string

type FailError 

type FailError struct{ Content any }

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.

func (FailError) Kind added in v0.20.0 

func (FailError) Kind() string

Kind returns "fail-error".

type Flow 

type Flow uint

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

const (
	Return Flow = iota
	Break
	Continue
)

Control flows.

func (Flow) Error 

func (f Flow) Error() string

func (Flow) Fields 

func (f Flow) Fields() vals.StructMap

func (Flow) Kind added in v0.20.0 

func (f Flow) Kind() string

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) ByteOutput 

func (fm *Frame) ByteOutput() ByteOutput

ByteOutput returns a handle for writing byte outputs.

func (*Frame) Canceled added in v0.20.0 

func (fm *Frame) Canceled() bool

Canceled reports whether the Context of the Frame has been canceled.

func (*Frame) CaptureOutput 

func (fm *Frame) CaptureOutput(f func(*Frame) error) ([]any, 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) Context added in v0.20.0 

func (fm *Frame) Context() context.Context

Context returns a Context associated with the Frame.

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) Fork added in v0.18.0 

func (fm *Frame) Fork() *Frame

Fork returns a modified copy of fm. The ports are forked, and the name is changed to the given value. Other fields are copied shallowly.

func (*Frame) InputChan 

func (fm *Frame) InputChan() chan any

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) IterateInputs 

func (fm *Frame) IterateInputs(f func(any))

IterateInputs calls the passed function for each input element.

func (*Frame) PipeOutput 

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

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

func (*Frame) Port added in v0.19.0 

func (fm *Frame) Port(i int) *Port

Port returns port i. If the port doesn't exist, it returns nil

This is a low-level construct that shouldn't be used for writing output; for that purpose, use [(*Frame).ValueOutput] and [(*Frame).ByteOutput] instead.

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.

func (*Frame) ValueOutput 

func (fm *Frame) ValueOutput() ValueOutput

ValueOutput returns a handle for writing value outputs.

type Inputs 

type Inputs func(func(any))

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 InvalidFD added in v0.18.0 

type InvalidFD struct{ FD int }

func (InvalidFD) Error added in v0.18.0 

func (err InvalidFD) Error() string

type NoSuchModule added in v0.17.0 

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

NoSuchModule encodes an error where a module spec cannot be resolved.

func (NoSuchModule) Error added in v0.17.0 

func (err NoSuchModule) Error() string

Error implements the error interface.

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 its associated code chunk has finished execution.

func CombineNs 

func CombineNs(ns1, 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 any) bool

Equal returns whether rhs has the same identity as ns.

func (*Ns) HasKeyString added in v0.17.0 

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

HasKeyString 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 any) (any, 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 IndexString.

func (*Ns) IndexString added in v0.17.0 

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

IndexString 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(any) bool)

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

func (*Ns) IterateKeysString added in v0.17.0 

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

IterateKeysString 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) Ns added in v0.17.0 

func (ns *Ns) Ns() *Ns

Ns returns ns itself.

func (*Ns) Repr 

func (ns *Ns) Repr(int) string

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

type NsBuilder 

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

NsBuilder is a helper type used for building an Ns.

func BuildNs added in v0.17.0 

func BuildNs() NsBuilder

BuildNs returns a helper for building an Ns.

func BuildNsNamed added in v0.17.0 

func BuildNsNamed(name string) NsBuilder

BuildNsNamed returns a helper for building an Ns with the given name. The name is only used for the names of Go functions.

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(name string, impl any) NsBuilder

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

func (NsBuilder) AddGoFns 

func (nb NsBuilder) AddGoFns(fns map[string]any) NsBuilder

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

func (NsBuilder) AddNs 

func (nb NsBuilder) AddNs(name string, v Nser) NsBuilder

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

func (NsBuilder) AddVar added in v0.17.0 

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

AddVar adds a variable.

func (NsBuilder) AddVars added in v0.17.0 

func (nb NsBuilder) AddVars(m map[string]vars.Var) NsBuilder

AddVars adds all the variables given in the map.

func (NsBuilder) Ns 

func (nb NsBuilder) Ns() *Ns

Ns builds a namespace.

type Nser added in v0.17.0 

type Nser interface {
	Ns() *Ns
}

Nser is anything that can be converted to 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

func (PipelineError) Kind added in v0.20.0 

func (pe PipelineError) Kind() string

type PluginLoadError added in v0.21.0 

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

PluginLoadError wraps a plugin loading error.

func (PluginLoadError) Error added in v0.21.0 

func (err PluginLoadError) Error() string

Error implements the error interface.

func (PluginLoadError) Unwrap added in v0.21.0 

func (err PluginLoadError) Unwrap() error

Unwrap returns the wrapped error.

type Port 

type Port struct {
	File *os.File
	Chan chan any
	// 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() ([]any, []byte), error)

CapturePort returns an output *Port whose value and byte components are saved separately. 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 any), 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 ValueCapturePort, but converts value outputs by stringifying them and prepending an output marker.

func ValueCapturePort added in v0.19.0 

func ValueCapturePort() (*Port, func() []any, error)

ValueCapturePort returns an output *Port whose value and byte components are saved, with bytes saved one string value per line. It also returns a function to call to obtain the captured output.

type RawOptions 

type RawOptions map[string]any

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.

type UnknownOption added in v0.18.0 

type UnknownOption struct {
	OptName string
}

UnknownOption is thrown by a native function when called with an unknown option.

func (UnknownOption) Error added in v0.18.0 

func (e UnknownOption) Error() string

Error implements the error interface.

type UnsupportedOptionsError 

type UnsupportedOptionsError struct {
	Options []string
}

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

func (UnsupportedOptionsError) Error 

func (er UnsupportedOptionsError) Error() string

type ValueOutput 

type ValueOutput interface {
	// Outputs a value. Returns errs.ReaderGone if the reader is gone.
	Put(v any) error
}

ValueOutput defines the interface through which builtin commands access the value output.

The value output is backed by two channels, one for writing output, another for the back-chanel signal that the reader of the channel has gone.

type WrongArgType added in v0.18.0 

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

WrongArgType is thrown when calling a native function with an argument of the wrong type.

func (WrongArgType) Error added in v0.18.0 

func (e WrongArgType) Error() string

Error implements the error interface.

func (WrongArgType) Unwrap added in v0.18.0 

func (e WrongArgType) Unwrap() error

Unwrap returns the wrapped type error.

Notes

Bugs

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

Source Files

View all Source files

Directories

Path Synopsis
Package errs declares error types used as exception causes.
 Package errs declares error types used as exception causes.
Package evaltest supports testing the Elvish interpreter and libraries.
 Package evaltest supports testing the Elvish interpreter and libraries.
Package vals contains basic facilities for manipulating values used in the Elvish runtime.
 Package vals contains basic facilities for manipulating values used in the Elvish runtime.
Package vars contains basic types for manipulating Elvish variables.
 Package vars contains basic types for manipulating Elvish variables.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.