Documentation
¶
Overview ¶
Package interp implements an interpreter that executes shell programs. It aims to support POSIX, but its support is not complete yet. It also supports some Bash features.
This package is a work in progress and EXPERIMENTAL; its API is not subject to the 1.x backwards compatibility guarantee.
Index ¶
- func DefaultExec(ctx Ctxt, path string, args []string) error
- func DefaultOpen(ctx Ctxt, path string, flag int, perm os.FileMode) (io.ReadWriteCloser, error)
- type AssocArray
- type Ctxt
- type Environ
- type ExitCode
- type FuncEnviron
- type IndexArray
- type ModuleExec
- type ModuleOpen
- type Runner
- type StringVal
- type VarValue
- type Variable
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DefaultOpen ¶
Types ¶
type AssocArray ¶
type Ctxt ¶
type Ctxt struct {
Context context.Context
Env Environ
Dir string
Stdin io.Reader
Stdout io.Writer
Stderr io.Writer
KillTimeout time.Duration
}
Ctxt is the type passed to all the module functions. It contains some of the current state of the Runner, as well as some fields necessary to implement some of the modules.
type Environ ¶
type Environ interface {
Get(name string) (value string, exists bool)
Set(name, value string)
Delete(name string)
Names() []string
Copy() Environ
}
func EnvFromList ¶
type FuncEnviron ¶
func (FuncEnviron) Copy ¶
func (f FuncEnviron) Copy() Environ
func (FuncEnviron) Delete ¶
func (f FuncEnviron) Delete(name string)
func (FuncEnviron) Names ¶
func (f FuncEnviron) Names() []string
func (FuncEnviron) Set ¶
func (f FuncEnviron) Set(name, value string)
type IndexArray ¶
type IndexArray []string
type ModuleExec ¶
ModuleExec is the module responsible for executing a program. It is executed for all CallExpr nodes where the first argument is neither a declared function nor a builtin.
Note that the name is included as the first argument. If path is an empty string, it means that the executable did not exist or was not found in $PATH.
Use a return error of type ExitCode to set the exit code. A nil error has the same effect as ExitCode(0). If the error is of any other type, the interpreter will come to a stop.
type ModuleOpen ¶
ModuleOpen is the module responsible for opening a file. It is executed for all files that are opened directly by the shell, such as in redirects. Files opened by executed programs are not included.
The path parameter is absolute and has been cleaned.
Use a return error of type *os.PathError to have the error printed to stderr and the exit code set to 1. If the error is of any other type, the interpreter will come to a stop.
TODO: What about stat calls? They are used heavily in the builtin test expressions, and also when doing a cd. Should they have a separate module?
func OpenDevImpls ¶
func OpenDevImpls(next ModuleOpen) ModuleOpen
type Runner ¶
type Runner struct {
// Env specifies the environment of the interpreter.
// If Env is nil, Run uses the current process's environment.
Env Environ
// Dir specifies the working directory of the command. If Dir is
// the empty string, Run runs the command in the calling
// process's current directory.
Dir string
// Params are the current parameters, e.g. from running a shell
// file or calling a function. Accessible via the $@/$* family
// of vars.
Params []string
Exec ModuleExec
Open ModuleOpen
// Separate maps, note that bash allows a name to be both a var
// and a func simultaneously
Vars map[string]Variable
Funcs map[string]*syntax.Stmt
Stdin io.Reader
Stdout io.Writer
Stderr io.Writer
// Context can be used to cancel the interpreter before it finishes
Context context.Context
// KillTimeout holds how much time the interpreter will wait for a
// program to stop after being sent an interrupt signal, after
// which a kill signal will be sent. This process will happen when the
// interpreter's context is cancelled.
//
// The zero value will default to 2 seconds.
//
// A negative value means that a kill signal will be sent immediately.
//
// On Windows, the kill signal is always sent immediately,
// because Go doesn't currently support sending Interrupt on Windows.
KillTimeout time.Duration
// contains filtered or unexported fields
}
A Runner interprets shell programs. It cannot be reused once a program has been interpreted.
Note that writes to Stdout and Stderr may not be sequential. If you plan on using an io.Writer implementation that isn't safe for concurrent use, consider a workaround like hiding writes behind a mutex.
func (*Runner) FromArgs ¶
FromArgs populates the shell options and returns the remaining arguments. For example, running FromArgs("-e", "--", "foo") will set the "-e" option and return []string{"foo"}.
This is similar to what the interpreter's "set" builtin does.
func (*Runner) Reset ¶
Reset will set the unexported fields back to zero, fill any exported fields with their default values if not set, and prepare the runner to interpret a program.
This function should be called once before running any node. It can be skipped before any following runs to keep internal state, such as declared variables.
Source Files