Documentation
¶
Overview ¶
Package expander provides an extension for representing expandable expressions in command line arguments. The main use case is for dynamically evaluating these expressions with values that occur during the execution of the evaluators.
Index ¶
- Variables
- func Expand(pattern string, e Interface, opts ...Option) string
- func Fprint(pattern string, w io.Writer, e Interface, opts ...Option) (count int, err error)
- type ErrUnknownToken
- type Func
- type Interface
- func Colors() Interface
- func Compose(expanders ...Interface) Interface
- func Dig(v any) Interface
- func Env() Interface
- func ExpandSlice[T any](slice []T) Interface
- func Prefix(p string, e Interface) Interface
- func Reflect(v any) Interface
- func Runtime() Interface
- func Time(t time.Time) Interface
- func Unknown() Interface
- type Map
- type Option
- type Pattern
- func (p *Pattern) AppendText(b []byte) ([]byte, error)
- func (p *Pattern) Expand(expand Interface) string
- func (p *Pattern) ExpandAny(expand Interface) any
- func (p *Pattern) Fprint(w io.Writer, e Interface) (count int, err error)
- func (p *Pattern) MarshalText() ([]byte, error)
- func (p *Pattern) String() string
- func (p *Pattern) SubexpNames() []string
- func (p *Pattern) UnmarshalText(text []byte) error
- type PatternValue
- func (p *PatternValue) AppendText(b []byte) ([]byte, error)
- func (p *PatternValue) MarshalText() ([]byte, error)
- func (p *PatternValue) Reset()
- func (p *PatternValue) Set(s string) error
- func (p *PatternValue) String() string
- func (p *PatternValue) UnmarshalText(text []byte) error
- func (p *PatternValue) Value() *Pattern
- type Renderer
- type Syntax
Constants ¶
This section is empty.
Variables ¶
var Nil = Func(nilImpl)
Nil provides an expander which always provides nil
Functions ¶
Types ¶
type ErrUnknownToken ¶
type ErrUnknownToken string
ErrUnknownToken is an error reporting a key that no expander recognized. Its string value is the unrecognized key.
func (ErrUnknownToken) Error ¶
func (e ErrUnknownToken) Error() string
Error implements the error interface.
type Interface ¶
Interface converts the given string key into its variable expansion
func Colors ¶
func Colors() Interface
Colors provides an expander which resolves color and style names to their VT100 ANSI escape sequences, returning nil for unrecognized names.
func Compose ¶
Compose combines the given expanders into a single expander, returning the first non-nil expansion produced by them in order.
func Dig ¶ added in v0.20.0
Dig navigates the object graph of a value using qualified names as keys.
func Env ¶
func Env() Interface
Env provides an expander which looks up environment variables by name, returning nil when the variable is not set.
func ExpandSlice ¶ added in v0.17.0
ExpandSlice creates an expander which uses the underlying slice as its input. Keys resolve as the index into the slice, including supporting negative indexes to reference from the end of the slice.
func Prefix ¶
Prefix provides an expander which looks for and cuts a given prefix and delegates the result to the underlying expander
func Reflect ¶ added in v0.12.0
Reflect provides a simple expander around a given value using reflection. Keys resolve, case-insensitively, to the exported fields of the value (or of the struct it points to) and to its exported methods which take no arguments and return a single value. Methods make it possible to expand values which don't expose their state as fields. For example, the key "year" applied to a time.Time resolves to its Year method. Fields take precedence over methods. For slices and arrays, keys can be parsed as integers as indexes. Negative indexes can be used. For maps with string keys, keys can retrieve the value. Other keys resolves to nil.
type Map ¶
Map provides an expander backed by a map, resolving keys directly to their corresponding values.
type Option ¶ added in v0.17.0
type Option interface {
// contains filtered or unexported methods
}
Option configures how a pattern is compiled by Compile. The Syntax values are themselves options
func WithDelimiters ¶ added in v0.17.0
WithDelimiters overrides the start and end delimiters used to recognize expressions within a pattern. The end delimiter must be a single byte. The default delimiters are "%(" and ")".
type Pattern ¶
type Pattern struct {
// contains filtered or unexported fields
}
Pattern is a compiled expandable expression produced by Compile. A Pattern may be expanded repeatedly with different expanders.
func Compile ¶
Compile compiles pattern into a Pattern, applying any options. By default the SyntaxDefault syntax and the delimiters "%(" and ")" are used.
func CompilePattern
deprecated
func (*Pattern) AppendText ¶ added in v0.17.0
AppendText implements encoding.TextAppender. The output matches that of calling the Pattern.String method.
func (*Pattern) ExpandAny ¶ added in v0.16.0
ExpandAny expands the pattern, returning the underlying type of the expansion when the pattern consists of a single expression with no format specifier applied.. When the pattern has multiple expressions, a literal fallback, or a format specifier, it falls back to string interpolation like Expand.
func (*Pattern) Fprint ¶ added in v0.16.0
Fprint expands the pattern using the given expander and writes to the specified writer. As a special case, if w has a method Expander() Interface, this method will be called to obtain an expander which composes with the expander e. The main use of this convention is to allow writers to supply control expressions. For an example, see Renderer.
func (*Pattern) MarshalText ¶ added in v0.17.0
MarshalText implements encoding.TextMarshaler. The output matches that of calling the Pattern.AppendText method.
func (*Pattern) String ¶
String implements fmt.Stringer, reconstructing the pattern's source representation using its delimiters.
func (*Pattern) SubexpNames ¶ added in v0.19.0
SubexpNames returns the names of the sub-expressions in the Pattern which appear in the variable placeholders. Names are listed in the order they first occur, and each name is listed once no matter how many placeholders use it. Within SyntaxRecursive, this includes the names of the recursively named fallbacks. The whitespace expressions space, tab, newline, and empty are not variable placeholders and are therefore omitted.
func (*Pattern) UnmarshalText ¶ added in v0.17.0
UnmarshalText implements encoding.TextUnmarshaler by calling Compile on the encoded value using the default delimiters
type PatternValue ¶ added in v0.21.0
type PatternValue struct {
Options []Option
// contains filtered or unexported fields
}
PatternValue provides a wrapper around Pattern which can specify options and be used as the value for a flag or arg
func (*PatternValue) AppendText ¶ added in v0.21.0
func (p *PatternValue) AppendText(b []byte) ([]byte, error)
AppendText implements encoding.TextAppender. The output matches that of calling the Pattern.String method.
func (*PatternValue) MarshalText ¶ added in v0.21.0
func (p *PatternValue) MarshalText() ([]byte, error)
MarshalText implements encoding.TextMarshaler. The output matches that of calling the Pattern.AppendText method.
func (*PatternValue) Reset ¶ added in v0.21.0
func (p *PatternValue) Reset()
Reset clears the pattern for re-use. Options are considered configuration and are not reset.
func (*PatternValue) Set ¶ added in v0.21.0
func (p *PatternValue) Set(s string) error
Set provides the implementation of flag.Value
func (*PatternValue) String ¶ added in v0.21.0
func (p *PatternValue) String() string
String provides the string representation of the value
func (*PatternValue) UnmarshalText ¶ added in v0.21.0
func (p *PatternValue) UnmarshalText(text []byte) error
UnmarshalText implements encoding.TextUnmarshaler by calling Compile on the encoded value using the default delimiters
func (*PatternValue) Value ¶ added in v0.21.0
func (p *PatternValue) Value() *Pattern
Value compiles and obtains the pattern
type Renderer ¶
Renderer is a specialized writer that understands writing to multiple files and the corresponding variable support. When used as a writer to Fprint, two control expressions are exposed, stdout and stderr, which can be used to redirect to the underlying writers. For example, "%(stderr)debug: %(v:#v)%(newline)%(stdout)%(v)" would print debug text to whatever writer was set for stderr.
func NewRenderer ¶
NewRenderer creates a Renderer that writes to stdout by default and exposes the stdout and stderr control expressions for switching the active writer.
type Syntax ¶
type Syntax int
Syntax selects the expression syntax used when compiling a pattern. A Syntax value is itself an Option.
const ( // SyntaxDefault indicates that the expression syntax uses the // form <name>[':' <format>]. That is, an optional format string is allowed // to control the output. SyntaxDefault Syntax = iota // SyntaxRecursive causes recursive expression evaluation to // be allowed. For example, the expression ${VISUAL:${EDITOR}} // would evaluate both environment variables, falling back to EDITOR. SyntaxRecursive )
Source Files