expand

Documentation

Overview

Package expand contains code to perform various shell expansions.

Index

• func Arithm(cfg *Config, expr syntax.ArithmExpr) (int, error)
• func Braces(words ...*syntax.Word) []*syntax.Word
• func Document(cfg *Config, word *syntax.Word) (string, error)
• func Fields(cfg *Config, words ...*syntax.Word) ([]string, error)
• func Format(cfg *Config, format string, args []string) (string, int, error)
• func Literal(cfg *Config, word *syntax.Word) (string, error)
• func Pattern(cfg *Config, word *syntax.Word) (string, error)
• func ReadFields(cfg *Config, s string, n int, raw bool) []string
• type Config
• type Environ
  • func FuncEnviron(fn func(string) string) Environ
  • func ListEnviron(pairs ...string) Environ
• type UnexpectedCommandError
  • func (u UnexpectedCommandError) Error() string
• type UnsetParameterError
  • func (u UnsetParameterError) Error() string
• type Variable
  • func (v Variable) IsSet() bool
  • func (v Variable) Resolve(env Environ) (string, Variable)
  • func (v Variable) String() string
• type WriteEnviron

Functions

func Arithm

func Arithm(cfg *Config, expr syntax.ArithmExpr) (int, error)

func Braces

func Braces(words ...*syntax.Word) []*syntax.Word

Braces performs Bash brace expansion on words. For example, passing it a literal word "foo{bar,baz}" will return two literal words, "foobar" and "foobaz".

It does not return an error; malformed brace expansions are simply skipped. For example, "a{b{c,d}" results in the words "a{bc" and "a{bd".

Note that the resulting words may have more word parts than necessary, such as contiguous *syntax.Lit nodes, and that these parts may be shared between words.

func Document

func Document(cfg *Config, word *syntax.Word) (string, error)

Document expands a single shell word as if it were within double quotes. It is simlar to Literal, but without brace expansion, tilde expansion, and globbing.

The config specifies shell expansion options; nil behaves the same as an empty config.

func Fields

func Fields(cfg *Config, words ...*syntax.Word) ([]string, error)

Fields expands a number of words as if they were arguments in a shell command. This includes brace expansion, tilde expansion, parameter expansion, command substitution, arithmetic expansion, and quote removal.

func Format

func Format(cfg *Config, format string, args []string) (string, int, error)

Format expands a format string with a number of arguments, following the shell's format specifications. These include printf(1), among others.

The resulting string is returned, along with the number of arguments used.

The config specifies shell expansion options; nil behaves the same as an empty config.

func Literal

func Literal(cfg *Config, word *syntax.Word) (string, error)

Literal expands a single shell word. It is similar to Fields, but the result is a single string. This is the behavior when a word is used as the value in a shell variable assignment, for example.

The config specifies shell expansion options; nil behaves the same as an empty config.

func Pattern

func Pattern(cfg *Config, word *syntax.Word) (string, error)

Pattern expands a single shell word as a pattern, using syntax.QuotePattern on any non-quoted parts of the input word. The result can be used on syntax.TranslatePattern directly.

The config specifies shell expansion options; nil behaves the same as an empty config.

func ReadFields

func ReadFields(cfg *Config, s string, n int, raw bool) []string

The config specifies shell expansion options; nil behaves the same as an empty config.

Types

type Config

type Config struct {
	// Env is used to get and set environment variables when performing
	// shell expansions. Some special parameters are also expanded via this
	// interface, such as:
	//
	//   * "#", "@", "*", "0"-"9" for the shell's parameters
	//   * "?", "$", "PPID" for the shell's status and process
	//   * "HOME foo" to retrieve user foo's home directory (if unset,
	//     os/user.Lookup will be used)
	//
	// If nil, there are no environment variables set. Use
	// ListEnviron(os.Environ()...) to use the system's environment
	// variables.
	Env Environ

	// NoGlob corresponds to the shell option that disables globbing.
	NoGlob bool
	// GlobStar corresponds to the shell option that allows globbing with
	// "**".
	GlobStar bool

	// CmdSubst expands a command substitution node, writing its standard
	// output to the provided io.Writer.
	//
	// If nil, encountering a command substitution will result in an
	// UnexpectedCommandError.
	CmdSubst func(io.Writer, *syntax.CmdSubst) error

	// ReadDir is used for file path globbing. If nil, globbing is disabled.
	// Use ioutil.ReadDir to use the filesystem directly.
	ReadDir func(string) ([]os.FileInfo, error)
	// contains filtered or unexported fields
}

A Config specifies details about how shell expansion should be performed. The zero value is a valid configuration.

type Environ

type Environ interface {
	// Get retrieves a variable by its name. To check if the variable is
	// set, use Variable.IsSet.
	Get(name string) Variable

	// Each iterates over all the currently set variables, calling the
	// supplied function on each variable. Iteration is stopped if the
	// function returns false.
	//
	// The names used in the calls aren't required to be unique or sorted.
	// If a variable name appears twice, the latest occurrence takes
	// priority.
	//
	// Each is required to forward exported variables when executing
	// programs.
	Each(func(name string, vr Variable) bool)
}

Environ is the base interface for a shell's environment, allowing it to fetch variables by name and to iterate over all the currently set variables.

func FuncEnviron

func FuncEnviron(fn func(string) string) Environ

FuncEnviron wraps a function mapping variable names to their string values, and implements Environ. Empty strings returned by the function will be treated as unset variables. All variables will be exported.

Note that the returned Environ's Each method will be a no-op.

func ListEnviron

func ListEnviron(pairs ...string) Environ

ListEnviron returns an Environ with the supplied variables, in the form "key=value". All variables will be exported.

On Windows, where environment variable names are case-insensitive, the resulting variable names will all be uppercase.

type UnexpectedCommandError

type UnexpectedCommandError struct {
	Node *syntax.CmdSubst
}

UnexpectedCommandError is returned if a command substitution is encountered when Config.CmdSubst is nil.

func (UnexpectedCommandError) Error

func (u UnexpectedCommandError) Error() string

type UnsetParameterError

type UnsetParameterError struct {
	Node    *syntax.ParamExp
	Message string
}

func (UnsetParameterError) Error

func (u UnsetParameterError) Error() string

type Variable

type Variable struct {
	Local    bool
	Exported bool
	ReadOnly bool
	NameRef  bool        // if true, Value must be string
	Value    interface{} // string, []string, or map[string]string
}

Variable describes a shell variable, which can have a number of attributes and a value.

A Variable is unset if its Value field is untyped nil, which can be checked via Variable.IsSet. The zero value of a Variable is thus a valid unset variable.

If a variable is set, its Value field will be a []string if it is an indexed array, a map[string]string if it's an associative array, or a string otherwise.

func (Variable) IsSet

func (v Variable) IsSet() bool

IsSet returns whether the variable is set. An empty variable is set, but an undeclared variable is not.

func (Variable) Resolve

func (v Variable) Resolve(env Environ) (string, Variable)

Resolve follows a number of nameref variables, returning the last reference name that was followed and the variable that it points to.

func (Variable) String

func (v Variable) String() string

String returns the variable's value as a string. In general, this only makes sense if the variable has a string value or no value at all.

type WriteEnviron

type WriteEnviron interface {
	Environ
	// Set sets a variable by name. If !vr.IsSet(), the variable is being
	// unset; otherwise, the variable is being replaced.
	//
	// It is the implementation's responsibility to handle variable
	// attributes correctly. For example, changing an exported variable's
	// value does not unexport it, and overwriting a name reference variable
	// should modify its target.
	Set(name string, vr Variable)
}

WriteEnviron is an extension on Environ that supports modifying and deleting variables.