Documentation
¶
Overview ¶
Package printer provides the expression operators which print the values which flow through an expression evaluation pipeline. These are the familiar operators from the Unix find command:
-fprint FILE -fprint0 FILE -fprintf FILE PATTERN -print -print0 -printf PATTERN
Each of these operators always yields the value it was given, which makes it possible to compose them with the rest of the pipeline.
The Printer does the actual work. It is a context service, which means that it is registered into the context when it is added to a pipeline and retrieved from the context with FromContext. Adding it to a pipeline also registers the expression operators listed above. A minimal app resembles:
app := &cli.App{
Uses: printer.New(),
Args: []*cli.Arg{
{
Name: "path",
NArg: 1,
},
{
Name: "expression",
Value: new(expr.Expression),
},
},
Action: func(c *cli.Context) error {
return expr.FromContext(c, "expression").Evaluate(c, time.Now())
},
}
Invoking this app as
app . -fprintf test.txt %(year)/%(month)
writes the year and month of the value which was pushed into the pipeline to the file test.txt. How the value is converted into the expander which resolves the names within a pattern is controlled by WithExpanderFactory; how patterns themselves are parsed is controlled by WithPatternOptions.
Index ¶
- func AddExprs() cli.Action
- func ContextValue(v *Printer) cli.Action
- func Fprint(file string) expr.Evaluator
- func Fprint0(file string) expr.Evaluator
- func Fprintf(file string, pattern *expander.Pattern) expr.Evaluator
- func Print() expr.Evaluator
- func Print0() expr.Evaluator
- func Printf(pattern *expander.Pattern) expr.Evaluator
- func SourceAnnotation() (string, string)
- type ExpanderFactory
- type Option
- type Printer
- func (p *Printer) Apply(opts ...Option)
- func (p *Printer) Close() error
- func (p *Printer) Compile(pattern string) *expander.Pattern
- func (p *Printer) Expander(ctx context.Context, v any) expander.Interface
- func (p *Printer) Fprint(ctx context.Context, file string, v any) error
- func (p *Printer) Fprint0(ctx context.Context, file string, v any) error
- func (p *Printer) Fprintf(ctx context.Context, file string, pattern *expander.Pattern, v any) error
- func (p *Printer) Pipeline() cli.Action
- func (p *Printer) Print(ctx context.Context, v any) error
- func (p *Printer) Print0(ctx context.Context, v any) error
- func (p *Printer) Printf(ctx context.Context, pattern *expander.Pattern, v any) error
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AddExprs ¶
AddExprs provides an action which registers each of the expression operators which the printer supports: -fprint, -fprint0, -fprintf, -print, -print0, and -printf.
When this action is used within the Uses pipeline of the arg which defines the expression, the operators are added to it directly. Otherwise it adds a hook which will add it to any arg that has an Expression, which is what enables New to be useable at the level of the command or app.
func ContextValue ¶
ContextValue provides an action that sets the given value into the context. The only supported type is *Printer.
func Fprint ¶
Fprint provides an evaluator which prints the value from the expression evaluation pipeline to the named file followed by a newline.
func Fprint0 ¶
Fprint0 provides an evaluator which prints the value from the expression evaluation pipeline to the named file followed by a null character.
func Fprintf ¶
Fprintf provides an evaluator which prints the value from the expression evaluation pipeline to the named file using the given pattern.
func Print ¶
Print provides an evaluator which prints the value from the expression evaluation pipeline to standard output followed by a newline.
func Print0 ¶
Print0 provides an evaluator which prints the value from the expression evaluation pipeline to standard output followed by a null character.
func Printf ¶
Printf provides an evaluator which prints the value from the expression evaluation pipeline to standard output using the given pattern.
func SourceAnnotation ¶
SourceAnnotation gets the name and value of the annotation added to the Data of all expression operators that are initialized from this package
Types ¶
type ExpanderFactory ¶
ExpanderFactory converts a value from the expression evaluation pipeline into the expander which is used to expand patterns.
var ( // DefaultExpanderFactory provides the default conversion of a value from the // expression evaluation pipeline into the expander which expands patterns. A // value which is itself an expander is used as-is; any other value uses the // reflection expander adapter [expander.Reflect], which resolves keys to the // fields and no-arg methods of the value. DefaultExpanderFactory ExpanderFactory = defaultExpanderFactory )
type Option ¶
type Option func(*Printer)
Option provides an option for configuring the printer.
func WithAction ¶
WithAction sets the action to use with the printer.
func WithDefaultAction ¶
func WithDefaultAction() Option
WithDefaultAction sets the action to the default, which sets the printer into the context, adds the expression operators, and closes any files which the printer opened.
func WithExpanderFactory ¶
WithExpanderFactory sets how a value from the expression evaluation pipeline is converted into the expander which is used to expand patterns. When unset, DefaultExpanderFactory is used.
func WithFS ¶
WithFS sets the file system which is used to interpret the file names given to the expression operators. When unset, the file system from the cli context is used, which also provides the convention that the file named with a dash refers to standard output.
func WithPatternOptions ¶
WithPatternOptions sets the options which are used when the patterns named by the expression operators are parsed. Refer to expander.Compile for the available options. This option is additive; each call appends to the options which are already present.
type Printer ¶
type Printer struct {
// Action provides the action to run when the printer is added to a
// pipeline.
cli.Action
// contains filtered or unexported fields
}
Printer facilitates the fprint-style expression operators. It resolves the expander to use for each value in the expression evaluation pipeline, it compiles patterns, and it owns the files which the operators name. Use New to create one which registers itself as a context service and registers the expression operators.
A file is created the first time that it is named and it is held open for the remainder of the run, which causes each subsequent print to append to it. Use Printer.Close to close the files, which the default action does automatically in the After timing.
func FromContext ¶
FromContext retrieves the printer from the context. This panics if the printer has not been registered, which is done by adding it to a pipeline (see New) or by using ContextValue.
func New ¶
New creates a printer which uses the default action. The default action registers the printer as a context service, adds each of the expression operators via AddExprs, and closes any files which were opened when the app exits.
func (*Printer) Close ¶
Close closes each of the files which the printer opened and forgets them, which means that naming one of these files again re-creates it.
func (*Printer) Compile ¶
Compile compiles the given pattern using the pattern options which were configured for the printer. Patterns are cached, so compiling the same pattern text obtains the same pattern.
func (*Printer) Expander ¶
Expander obtains the expander for the given value from the expression evaluation pipeline using the expander factory.
func (*Printer) Fprintf ¶
Fprintf prints the value to the named file after expanding the pattern with the expander which corresponds to the value.
func (*Printer) Printf ¶
Printf prints the value to standard output after expanding the pattern with the expander which corresponds to the value. The writer which is used understands the stdout and stderr control expressions (see expander.Renderer).
Source Files