command

package
v0.0.0-...-d11cab6 Latest Latest
Warning

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

 Go to latest Published: Nov 16, 2024 License: MIT Imports: 15 Imported by: 6

Documentation

Overview

Package command provides classes and functions for defining custom CLIs.

Index

Constants

View Source 
const (
	// UnboundedList is used to indicate that an argument list should allow an unbounded amount of arguments.
	UnboundedList = -1
)

Variables

View Source 
var (
	PRE_ITEM_PREFIX = "┃   "
	ITEM_PREFIX     = map[bool]string{
					// contains filtered or unexported fields
	}
	POST_ITEM_PREFIX = map[bool]string{
						// contains filtered or unexported fields
	}
)
View Source 
var (
	// OSLookupEnv is the env lookup command used internally by the entire `command` project.
	// It's value can be stubbed in tests by using the `commandtest.*TestCase.Env` fields.
	OSLookupEnv = os.LookupEnv
)

Functions

func DevNull 

func DevNull() io.Writer

DevNull returns an io.Writer that ignores all output.

func ExtraArgsErr 

func ExtraArgsErr(input *Input) error

ExtraArgsErr returns an error for when too many arguments are provided to a command.

func GetData 

func GetData[T any](d *Data, key string) T

GetData fetches the value for a given key.

func InputRunAtOffset 

func InputRunAtOffset[T any](i *Input, atOffset int, f func(*Input) T) T

func IsExtraArgsError 

func IsExtraArgsError(err error) bool

IsExtraArgs returns whether or not the provided error is an `ExtraArgsErr`.

func StderrWriter 

func StderrWriter(o Output) io.Writer

StderrWriter returns an io.Writer that writes to stderr.

func StdoutWriter 

func StdoutWriter(o Output) io.Writer

StdoutWriter returns an io.Writer that writes to stdout.

Types

type Autocompletion 

type Autocompletion struct {
	// Suggestions is the set of autocomplete suggestions.
	Suggestions []string
	// SpacelessCompletion indicates that a space should *not* be added (which happens
	// automatically if there is only one completion suggestion).
	SpacelessCompletion bool
}

Autocompletion is a subset of the `Completion` type and contains only data relevant for the OS package to handle autocompletion logic.

type BranchUsage 

type BranchUsage struct {
	// Usage is the usage object for the branched node.
	Usage *Usage
}

type Completion 

type Completion struct {
	// Suggestions is the set of autocomplete suggestions.
	Suggestions []string
	// IgnoreFilter indicates whether prefixes that don't match should be filtered out or not.
	IgnoreFilter bool
	// DontComplete indicates whether or not we should fill in partial completions.
	// This is achieved by adding a " " suggestion.
	DontComplete bool
	// CaseInsensitiveSort returns whether or not we should sort irrespective of case.
	CaseInsensitiveSort bool
	// CaseInsensitve is whether or not case should be considered when filtering out suggestions.
	CaseInsensitive bool
	// Distinct is whether or not we should return only distinct suggestions (specifically to prevent duplicates in list arguments).
	// Note: this is only applied for built-in types like `Argument` and `Flag`. To ensure
	// distinctness for custom argument processors, you will need to implement
	// logic in those custom objects yourself.
	Distinct bool
	// SpacelessCompletion indicates that a space should *not* be added (which happens
	// automatically if there is only one completion suggestion).
	SpacelessCompletion bool
	// DeferredCompletion will *execute* another graph before generating the actual
	// completion object.
	DeferredCompletion *DeferredCompletion
}

Completion is the object constructed by a completer.

func (*Completion) Clone 

func (c *Completion) Clone() *Completion

func (*Completion) Process 

func (c *Completion) Process(lastArg string, delimiter *rune, skipDelimiter bool) []string

process processes a `Completion` object using the provided `lastArg` and `delimiter`. If skipDelimiter is true, then no delimiter changes are done.

func (*Completion) ProcessInput 

func (c *Completion) ProcessInput(input *Input) []string

ProcessInput processes a `Completion` object against a given `Input` object.

type Data 

type Data struct {
	// Values is a map from argument name to the data for that argument.
	Values map[string]interface{}
	// Complexecute indictes whether we are running complexecute logic.
	Complexecute bool
	// OS is the current operating system. It is primarily used to execute
	// run logic in the parent shell (e.g. setting/unsetting environment variables)
	OS OS
}

Data contains argument data.

func (*Data) Bool 

func (d *Data) Bool(k string) bool

Bool returns the bool data for an argument.

func (*Data) Float 

func (d *Data) Float(k string) float64

Float returns the float data for an argument.

func (*Data) FloatList 

func (d *Data) FloatList(k string) []float64

FloatList returns the float slice data for an argument.

func (*Data) Get 

func (d *Data) Get(k string) interface{}

Get returns the interface data for an argument.

func (*Data) Has 

func (d *Data) Has(k string) bool

Has returns whether or not key has been set in the `Data` object.

func (*Data) Int 

func (d *Data) Int(k string) int

Int returns the int data for an argument.

func (*Data) IntList 

func (d *Data) IntList(k string) []int

IntList returns the int slice data for an argument.

func (*Data) Set 

func (d *Data) Set(k string, i interface{})

Set sets the provided key-value pair in the `Data` object.

func (*Data) String 

func (d *Data) String(k string) string

String returns the string data for an argument.

func (*Data) StringList 

func (d *Data) StringList(k string) []string

StringList returns the string slice data for an argument.

type DeferredCompletion 

type DeferredCompletion struct {
	// Graph is the root of a command `Node` graph that will be *execute* (i.e.
	// not completed) before the respective function, `F`, is run. However, the
	// `ExecuteData` generated by executing this graph will be ignored.
	Graph Node
	// F is the function to run after `Graph` has been executed.
	F func(*Completion, *Data) (*Completion, error)
}

DeferredCompletion is a Completer that generates a `Completion` object after executing a graph.

type Edge 

type Edge interface {
	// Next fetches the next node in the command graph based on
	// the provided `Input` and `Data`.
	Next(*Input, *Data) (Node, error)
	// UsageNext fetches the next node in the command graph when
	// command graph usage is being constructed. This is separate from
	// the `Next` function because `Next` is input-dependent whereas `UsageNext`
	// receives no input arguments.
	UsageNext(*Input, *Data) (Node, error)
}

Edge determines which `Node` to execute next.

type ExecuteData 

type ExecuteData struct {
	// Executable is a list of bash commands to run after all nodes have been processed.
	Executable []string
	// Executor is a set of functions to run after all nodes have been processed.
	Executor []func(Output, *Data) error
	// FunctionWrap is whether or not to wrap the Executable contents
	// in a function. This allows Executable to use things like "return" and "local".
	FunctionWrap bool
}

ExecuteData contains operations to resolve after all nodes have been processed. This separation is needed for caching and shortcuts nodes.

type Input 

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

Input is a type that tracks the entire input and how much of the input has been parsed. It also takes care of input snapshots (i.e. snapshots for shortcuts and caching purposes).

func NewInput 

func NewInput(args []string, delimiter *rune) *Input

NewInput creates a new `Input` object from a set of args and quote delimiter.

func ParseCompLine 

func ParseCompLine(compLine string, passthroughArgs ...string) *Input

ParseCompLine parses the COMP_LINE value provided by the shell

func ParseExecuteArgs 

func ParseExecuteArgs(strArgs []string) *Input

ParseExecuteArgs converts a list of strings into an Input struct.

func (*Input) ConvertedArgs 

func (i *Input) ConvertedArgs() []string

func (*Input) FullyProcessed 

func (i *Input) FullyProcessed() bool

FullyProcessed returns whether or not the input has been fully processed.

func (*Input) GetSnapshot 

func (i *Input) GetSnapshot(is spycommand.InputSnapshot) []string

GetSnapshot retrieves the snapshot.

func (*Input) MustPop 

func (i *Input) MustPop(d *Data) string

MustPop runs `Pop` and panics if there isn't at least one value remaining.

func (*Input) NumRemaining 

func (i *Input) NumRemaining() int

func (*Input) NumSnapshots 

func (i *Input) NumSnapshots() int

NumSnapshots returns the number of snapshots

func (*Input) Peek 

func (i *Input) Peek() (string, bool)

Peek returns the next argument and whether or not there is another argument.

func (*Input) PeekAt 

func (i *Input) PeekAt(idx int) (string, bool)

PeekAt peeks at a specific argument and returns whether or not there are at least that many arguments.

func (*Input) Pop 

func (i *Input) Pop(d *Data) (string, bool)

Pop removes the next argument from the input and returns if there is at least one more argument.

func (*Input) PopAt 

func (i *Input) PopAt(offset int, d *Data) (string, bool)

func (*Input) PopBreakers 

func (i *Input) PopBreakers(n int)

func (*Input) PopN 

func (i *Input) PopN(n, optN int, breakers []InputBreaker, d *Data) ([]*string, bool)

PopN pops the next `n` arguments from the input and returns whether or not there are enough arguments left.

func (*Input) PopNAt 

func (outerInput *Input) PopNAt(atOffset, n, optN int, breakers []InputBreaker, d *Data) ([]*string, bool)

PopNAt pops the `n` arguments starting at the provided offset.

func (*Input) PushBreakers 

func (i *Input) PushBreakers(vs ...InputBreaker)

func (*Input) PushFront 

func (i *Input) PushFront(sl ...string)

PushFront pushes arguments to the front of the remaining input.

func (*Input) PushFrontAt 

func (i *Input) PushFrontAt(atOffset int, sl ...string)

PushFrontAt pushes arguments starting at a specific spot in the remaining arguments.

func (*Input) Remaining 

func (i *Input) Remaining() []string

Remaining returns the remaining arguments.

func (*Input) Snapshot 

func (i *Input) Snapshot() spycommand.InputSnapshot

Snapshot takes a snapshot of the remaining input arguments.

func (*Input) Used 

func (i *Input) Used() []string

Used returns the input arguments that have already been processed.

type InputBreaker 

type InputBreaker interface {
	// Break returns whether the input processing should stop.
	Break(string, *Data) bool
	// DiscardBreak returns whether the value responsible for breaking the input shoud be popped or not.
	DiscardBreak(string, *Data) bool
}

InputBreaker is an interface used to break a list of values returned by `Input.Pop` functions.

type InputTransformer 

type InputTransformer struct {
	// F is the function that will be run on each element in Input.
	F func(Output, *Data, string) ([]string, error)
	// UpToIndexInclusive is the input argument index that F will be run through.
	// This is zero-indexed so default behavior (UpToIndexInclusive: 0) will run
	// on the first argument only. If UpToIndexInclusive is less than zero
	// (or command.UnboundedList), then this will run on all remaining arguments.
	UpToIndexInclusive int
}

InputTransformer checks the next input argument (as a string), runs `F` on that argument, and inserts the values returned from `F` in its place. See `FileNumberInputTransformer` for a useful example.

Note: `InputTransformer` should only be used when the number of arguments or the argument type is expected to change. If the number of arguments and type will remain the same, use an `Argument` with a `Transformer` option.

func (*InputTransformer) Complete 

func (it *InputTransformer) Complete(input *Input, data *Data) (*Completion, error)

func (*InputTransformer) Execute 

func (it *InputTransformer) Execute(i *Input, o Output, data *Data, eData *ExecuteData) error

func (*InputTransformer) Transform 

func (it *InputTransformer) Transform(input *Input, output Output, data *Data, complete bool) error

func (*InputTransformer) Usage 

func (it *InputTransformer) Usage(*Input, *Data, *Usage) error

type Node 

type Node interface {
	Processor
	Edge
}

Node defines a cohesive node in the command graph. It is simply a combination of a `Processor` and an `Edge`.

type OS 

type OS interface {
	// SetEnvVar returns a shell command that sets the environment variable
	// `envVar` to `value`. Environment variable modifications can't and shouldn't
	// be done by os.Setenv because the go CLI executable is run in a sub-shell.
	SetEnvVar(envVar, value string) string

	// UnsetEnvVar returns a shell command that unsets the environment variable
	// `envVar`. Environment variable changes can't and shouldn't be done by
	// os.Unsetenv because the go CLI executable is run in a sub-shell.
	UnsetEnvVar(envVar string) string
}

type Output 

type Output interface {
	// Writes the provided text to stdout.
	Stdout(string)
	// Writes the provided text to stderr and returns an error with the same message.
	Stderr(string) error
	// Writes a formatted string to stdout.
	Stdoutf(string, ...interface{})
	// Writes a formatted string to stderr and returns an error with the same message.
	Stderrf(string, ...interface{}) error
	// Writes interfaces to stdout and appends a newline.
	Stdoutln(...interface{})
	// Writes interfaces to stderr and appends a newline.
	Stderrln(...interface{}) error
	// Writes the provided error to stderr and returns the provided error.
	Err(err error) error
	// Annotate prepends the message to the error
	Annotate(error, string) error
	// Annotatef prepends the message to the error
	Annotatef(error, string, ...interface{}) error
	// Terminate terminates the execution with the provided error (if it's not nil).
	Terminate(error)
	// Terminatef terminates the execution with a formatted error.
	Terminatef(string, ...interface{})
	// Tannotate terminates the execution with the an annotation of provided error (if it's not nil).
	Tannotate(error, string)
	// Tannotatef terminates the execution with an annotation of the provided error (if it's not nil).
	Tannotatef(error, string, ...interface{})
	// Close informs the os that no more data will be written.
	Close()
	// Color changes the format of stdout to the provided formats.
	Color(fs ...color.Format)
	// Colerr (color + err hehe) changes the format of stderr to the provided formats.
	Colerr(fs ...color.Format)
}

Output defines methods for writing output.

func NewIgnoreAllOutput 

func NewIgnoreAllOutput() Output

NewIgnoreAllOutput is an output that ignores all output.

func NewIgnoreErrOutput 

func NewIgnoreErrOutput(o Output, fs ...func(error) bool) Output

NewIgnoreErrOutput is an output that ignores errors that satisfy any of the provided functions.

func NewOutput 

func NewOutput() Output

NewOutput returns an output that points to stdout and stderr.

func OutputFromFuncs 

func OutputFromFuncs(stdoutFunc, stderrFunc func(string)) Output

OutputFromFuncs returns an Output object that forwards data to the provided stdout and stderr functions.

If you need an Output object for testing purposes, consider using commandtest.NewOutput() which provides the `GetStdout/GetStderr` and `GetStdoutByCalls/GetStderrByCalls` functions.

type Processor 

type Processor interface {
	// Execute is the function called when a command graph is
	// being executed.
	Execute(*Input, Output, *Data, *ExecuteData) error
	// Complete is the function called when a command graph is
	// being autocompleted. If it returns a non-nil `Completion` object,
	// then the graph traversal stops and uses the returned object
	// to construct the command completion suggestions.
	Complete(*Input, *Data) (*Completion, error)
	// Usage is the function called when the usage data for a command
	// graph is being constructed. A
	// The input `Usage` object should be
	// updated for each `Node`.
	Usage(*Input, *Data, *Usage) error
}

Processor defines the logic that should be executed at a `Node`.

type Usage 

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

func (*Usage) AddArg 

func (u *Usage) AddArg(name, description string, required, optional int)

func (*Usage) AddFlag 

func (u *Usage) AddFlag(fullFlag string, shortFlag rune, argName string, description string, required, optional int)

func (*Usage) AddSymbol 

func (u *Usage) AddSymbol(symbol, description string)

func (*Usage) SetBranches 

func (u *Usage) SetBranches(branches []*BranchUsage)

func (*Usage) SetDescription 

func (u *Usage) SetDescription(desc string)

func (*Usage) String 

func (u *Usage) String() string

type UsageSection 

type UsageSection string
const (
	// ArgSection is the title of the arguments usage section.
	ArgSection UsageSection = "Arguments"
	// FlagSection is the title of the flags usage section.
	FlagSection UsageSection = "Flags"
	// SymbolSection is the title of the symbols usage section.
	SymbolSection UsageSection = "Symbols"
)

Source Files

View all Source files

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.