libcmd

package module
v0.0.0-...-e753594 Latest Latest
Warning

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

 Go to latest Published: Nov 28, 2019 License: MIT Imports: 7 Imported by: 0

README

libcmd - Simple and flexible command-line parsing

Build Status codecov Go Report Card libcmd Docs

libcmd is a simple, no-nonsense, zero dependency library for command-line parsing, with support for subcommands. It differs from other libraries by taking a minimalist approach and focusing only in solving the core parsing problem, instead of trying to be a silver bullet.

License

MIT. See LICENSE for details.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func IsParserErr 

func IsParserErr(err error) bool

IsParserErr returns true is the error is an error generated by the parsing process itself.

Types

type App 

type App struct {
	*Cmd
}

App defines the main application parser. An application can define one or more command-line arguments to parse, as well as define a chain of subcommands supported by the application.

To get a new instance of App, use the NewApp function.

func NewApp 

func NewApp(name, brief string) *App

NewApp returns a new instance of an app parser.

func (*App) Parse 

func (app *App) Parse() error

Parse runs the parser, collecting the values from the command-line and running any needed subcommands.

func (*App) ParseArgs 

func (app *App) ParseArgs(args []string) error

ParseArgs behave like parse, but instead of looking to the command-line arguments, it takes an array of arguments as parameters.

type Cmd 

type Cmd struct {
	// The name to be used to invoke the command
	Name string

	// The brief description of the command
	Brief string

	// The long description of the command
	Long string

	// The text to be shown at the 'Usage' line of the help.
	// Set this value to "-" to omit the usage line
	Usage string

	// Options for this command
	Options Options
	// contains filtered or unexported fields
}

Cmd defines a (sub)command of the application. Since commands cannot do much by themselves, you should create your commands by calling the Command method in the App instance.

Subcommands can be created by calling Command of an existing command.

func (*Cmd) AddOperand 

func (cmd *Cmd) AddOperand(name string, modifer string)

AddOperand documents an expected operand. The modifier parameter can be either '?' for optional operands or '*' for repeating ones. The documentation is printed in the order that was used to add the operands, so it is advisable to put them in an order that makes sense for the user (required, optional and repeating, in this order).

Note that this modifier is used only for documentation purposes; no special validation is done, except by the one documented in Options.StrictOperands.

func (*Cmd) Args 

func (cmd *Cmd) Args() []string

Args returns the remaining non-parsed command line arguments.

func (*Cmd) Bool 

func (cmd *Cmd) Bool(long string, short rune, defaultValue bool, help ...string) *bool

Bool defines a new bool argument. After parsing, the argument value will be available in the returned pointer.

func (*Cmd) BoolP 

func (cmd *Cmd) BoolP(target *bool, long string, short rune, defaultValue bool, help ...string)

BoolP defines a new bool argument. After parsing, the argument value will be available in the specified pointer.

func (*Cmd) Choice 

func (cmd *Cmd) Choice(choices []string, long string, short rune, defaultValue string, help ...string) *string

Choice defines a new string argument, ith tha values limited by choices. After parsing, the argument value will be available in the returned pointer.

If the defaultValue is always considered 'valid', even when not listed on the choices parameter.

func (*Cmd) ChoiceP 

func (cmd *Cmd) ChoiceP(target *string, choices []string, long string, short rune, defaultValue string, help ...string)

ChoiceP defines a new string argument, ith tha values limited by choices. After parsing, the argument value will be available in the specified pointer.

If the defaultValue is always considered 'valid', even when not listed on the choices parameter.

func (*Cmd) Command 

func (cmd *Cmd) Command(name, brief string, callback CmdCallback)

Command defines a new subcommand. The name is mandatory (otherwise, the command will never run), and the callback function gives the caller the opportunity to configure the newly created command, by defining new flags, subcommands, or specifying what to run when the command is activated.

func (*Cmd) CommandMatch 

func (cmd *Cmd) CommandMatch(name, brief string, callback MatchCallback)

CommandMatch is a shortcut to Command() followed by Match() on the provided command.

func (*Cmd) CommandRun 

func (cmd *Cmd) CommandRun(name, brief string, callback RunCallback)

CommandRun is a shortcut to Command() followed by Run() on the provided command.

func (*Cmd) CustomP 

func (cmd *Cmd) CustomP(target CustomArg, long string, short rune, defaultValue string, help ...string)

CustomP defines a new argument with custom type. During parsing, the argument is manipulated via Get and Set methods of the CustomArg interface.

func (*Cmd) Err 

func (cmd *Cmd) Err(handler ErrCallback)

Err registers a handler to be run when the parsing fails.

func (*Cmd) Float32 

func (cmd *Cmd) Float32(long string, short rune, defaultValue float32, help ...string) *float32

Float32 defines a new float32 argument. After parsing, the argument value will be available in the returned pointer.

func (*Cmd) Float32P 

func (cmd *Cmd) Float32P(target *float32, long string, short rune, defaultValue float32, help ...string)

Float32P defines a new float32 argument. After parsing, the argument value will be available in the specified pointer.

func (*Cmd) Float64 

func (cmd *Cmd) Float64(long string, short rune, defaultValue float64, help ...string) *float64

Float64 defines a new float64 argument. After parsing, the argument value will be available in the returned pointer.

func (*Cmd) Float64P 

func (cmd *Cmd) Float64P(target *float64, long string, short rune, defaultValue float64, help ...string)

Float64P defines a new float64 argument. After parsing, the argument value will be available in the specified pointer.

func (*Cmd) GetBool 

func (cmd *Cmd) GetBool(name string) *bool

GetBool returns the bool pointer used as value for the argument 'name' (you can use either the short or long name). If the argument does not exist, this routine panics.

func (*Cmd) GetChoice 

func (cmd *Cmd) GetChoice(name string) *string

GetChoice returns the string pointer used as value for the argument 'name' (you can use either the short or long name). If the argument does not exist, this routine panics.

func (*Cmd) GetCustom 

func (cmd *Cmd) GetCustom(name string) CustomArg

GetCustom returns the CustomArg value used as value for the argument 'name' (you can use either the short or long name). If the argument does not exist, this routine panics.

func (*Cmd) GetFloat32 

func (cmd *Cmd) GetFloat32(name string) *float32

GetFloat32 returns the float32 pointer used as value for the argument 'name' (you can use either the short or long name). If the argument does not exist, this routine panics.

func (*Cmd) GetFloat64 

func (cmd *Cmd) GetFloat64(name string) *float64

GetFloat64 returns the float64 pointer used as value for the argument 'name' (you can use either the short or long name). If the argument does not exist, this routine panics.

func (*Cmd) GetInt 

func (cmd *Cmd) GetInt(name string) *int

GetInt returns the int pointer used as value for the argument 'name' (you can use either the short or long name). If the argument does not exist, this routine panics.

func (*Cmd) GetInt16 

func (cmd *Cmd) GetInt16(name string) *int16

GetInt16 returns the int16 pointer used as value for the argument 'name' (you can use either the short or long name). If the argument does not exist, this routine panics.

func (*Cmd) GetInt32 

func (cmd *Cmd) GetInt32(name string) *int32

GetInt32 returns the int32 pointer used as value for the argument 'name' (you can use either the short or long name). If the argument does not exist, this routine panics.

func (*Cmd) GetInt64 

func (cmd *Cmd) GetInt64(name string) *int64

GetInt64 returns the int64 pointer used as value for the argument 'name' (you can use either the short or long name). If the argument does not exist, this routine panics.

func (*Cmd) GetInt8 

func (cmd *Cmd) GetInt8(name string) *int8

GetInt8 returns the int8 pointer used as value for the argument 'name' (you can use either the short or long name). If the argument does not exist, this routine panics.

func (*Cmd) GetString 

func (cmd *Cmd) GetString(name string) *string

GetString returns the string pointer used as value for the argument 'name' (you can use either the short or long name). If the argument does not exist, this routine panics.

func (*Cmd) GetUint 

func (cmd *Cmd) GetUint(name string) *uint

GetUint returns the uint pointer used as value for the argument 'name' (you can use either the short or long name). If the argument does not exist, this routine panics.

func (*Cmd) GetUint16 

func (cmd *Cmd) GetUint16(name string) *uint16

GetUint16 returns the uint16 pointer used as value for the argument 'name' (you can use either the short or long name). If the argument does not exist, this routine panics.

func (*Cmd) GetUint32 

func (cmd *Cmd) GetUint32(name string) *uint32

GetUint32 returns the uint32 pointer used as value for the argument 'name' (you can use either the short or long name). If the argument does not exist, this routine panics.

func (*Cmd) GetUint64 

func (cmd *Cmd) GetUint64(name string) *uint64

GetUint64 returns the uint64 pointer used as value for the argument 'name' (you can use either the short or long name). If the argument does not exist, this routine panics.

func (*Cmd) GetUint8 

func (cmd *Cmd) GetUint8(name string) *uint8

GetUint8 returns the uint8 pointer used as value for the argument 'name' (you can use either the short or long name). If the argument does not exist, this routine panics.

func (*Cmd) Help 

func (cmd *Cmd) Help()

Help prints the help text in the stdout. Normally, this method is not manually called, since it will be automatically executed on the following scenarios:

  1. When '-h' or '--help' is used;
  2. In a multi-command scenario, when a given command has subcommands but does not have a Run callback;

In the case defined by (1), you can suppress this behavior by setting the option SupressPrintHelpWhenSet. This will not call the help function when '-h' or '--help' is passed, but the flags will still be defined if you have at least one more flag defined. To suppress even the '-h' and '--help' flags creation, set the SuppressHelpFlag option.

In the sceenario defined by (2), you can either define a Run callback for the command or set the SuppressPrintHelpPartialCommand configuration option.

Last, but not least, if you need to override the actual text of the help, set the OnHelp field of the App options instance.

func (*Cmd) Int 

func (cmd *Cmd) Int(long string, short rune, defaultValue int, help ...string) *int

Int defines a new int argument. After parsing, the argument value will be available in the returned pointer.

func (*Cmd) Int16 

func (cmd *Cmd) Int16(long string, short rune, defaultValue int16, help ...string) *int16

Int16 defines a new int16 argument. After parsing, the argument value will be available in the returned pointer.

func (*Cmd) Int16P 

func (cmd *Cmd) Int16P(target *int16, long string, short rune, defaultValue int16, help ...string)

Int16P defines a new int16 argument. After parsing, the argument value will be available in the specified pointer.

func (*Cmd) Int32 

func (cmd *Cmd) Int32(long string, short rune, defaultValue int32, help ...string) *int32

Int32 defines a new int32 argument. After parsing, the argument value will be available in the returned pointer.

func (*Cmd) Int32P 

func (cmd *Cmd) Int32P(target *int32, long string, short rune, defaultValue int32, help ...string)

Int32P defines a new int32 argument. After parsing, the argument value will be available in the specified pointer.

func (*Cmd) Int64 

func (cmd *Cmd) Int64(long string, short rune, defaultValue int64, help ...string) *int64

Int64 defines a new int64 argument. After parsing, the argument value will be available in the returned pointer.

func (*Cmd) Int64P 

func (cmd *Cmd) Int64P(target *int64, long string, short rune, defaultValue int64, help ...string)

Int64P defines a new int64 argument. After parsing, the argument value will be available in the specified pointer.

func (*Cmd) Int8 

func (cmd *Cmd) Int8(long string, short rune, defaultValue int8, help ...string) *int8

Int8 defines a new int8 argument. After parsing, the argument value will be available in the returned pointer.

func (*Cmd) Int8P 

func (cmd *Cmd) Int8P(target *int8, long string, short rune, defaultValue int8, help ...string)

Int8P defines a new int8 argument. After parsing, the argument value will be available in the specified pointer.

func (*Cmd) IntP 

func (cmd *Cmd) IntP(target *int, long string, short rune, defaultValue int, help ...string)

IntP defines a new int argument. After parsing, the argument value will be available in the specified pointer.

func (*Cmd) Match 

func (cmd *Cmd) Match(callback MatchCallback)

Match registers a callback to run when this command matches. A command matches if it is invoked and the parsing is successful.

func (*Cmd) Operand 

func (cmd *Cmd) Operand(name string) string

Operand returns the value of the named operand, if any. When specified using AddOperand, each unparsed arg is considered an operand and it's value is fetched - but not consumed - from the Args() method.

The behavior of this function is only guaranteed when used in a 'leaf' command or and Run() callback.

func (*Cmd) PrintHelp 

func (cmd *Cmd) PrintHelp(writer io.Writer)

PrintHelp prints the help text to the specified writer. It functions exactly like the Help method.

func (*Cmd) Run 

func (cmd *Cmd) Run(callback RunCallback)

Run registers a callback to run when this command is matched (see Match) and no more subcommands were invoked.

func (*Cmd) String 

func (cmd *Cmd) String(long string, short rune, defaultValue string, help ...string) *string

String defines a new string argument. After parsing, the argument value will be available in the returned pointer.

func (*Cmd) StringP 

func (cmd *Cmd) StringP(target *string, long string, short rune, defaultValue string, help ...string)

StringP defines a new string argument. After parsing, the argument value will be available in the specified pointer.

func (*Cmd) Uint 

func (cmd *Cmd) Uint(long string, short rune, defaultValue uint, help ...string) *uint

Uint defines a new uint argument. After parsing, the argument value will be available in the returned pointer.

func (*Cmd) Uint16 

func (cmd *Cmd) Uint16(long string, short rune, defaultValue uint16, help ...string) *uint16

Uint16 defines a new uint16 argument. After parsing, the argument value will be available in the returned pointer.

func (*Cmd) Uint16P 

func (cmd *Cmd) Uint16P(target *uint16, long string, short rune, defaultValue uint16, help ...string)

Uint16P defines a new uint16 argument. After parsing, the argument value will be available in the specified pointer.

func (*Cmd) Uint32 

func (cmd *Cmd) Uint32(long string, short rune, defaultValue uint32, help ...string) *uint32

Uint32 defines a new uint32 argument. After parsing, the argument value will be available in the returned pointer.

func (*Cmd) Uint32P 

func (cmd *Cmd) Uint32P(target *uint32, long string, short rune, defaultValue uint32, help ...string)

Uint32P defines a new uint32 argument. After parsing, the argument value will be available in the specified pointer.

func (*Cmd) Uint64 

func (cmd *Cmd) Uint64(long string, short rune, defaultValue uint64, help ...string) *uint64

Uint64 defines a new uint64 argument. After parsing, the argument value will be available in the returned pointer.

func (*Cmd) Uint64P 

func (cmd *Cmd) Uint64P(target *uint64, long string, short rune, defaultValue uint64, help ...string)

Uint64P defines a new uint64 argument. After parsing, the argument value will be available in the specified pointer.

func (*Cmd) Uint8 

func (cmd *Cmd) Uint8(long string, short rune, defaultValue uint8, help ...string) *uint8

Uint8 defines a new uint8 argument. After parsing, the argument value will be available in the returned pointer.

func (*Cmd) Uint8P 

func (cmd *Cmd) Uint8P(target *uint8, long string, short rune, defaultValue uint8, help ...string)

Uint8P defines a new uint8 argument. After parsing, the argument value will be available in the specified pointer.

func (*Cmd) UintP 

func (cmd *Cmd) UintP(target *uint, long string, short rune, defaultValue uint, help ...string)

UintP defines a new uint argument. After parsing, the argument value will be available in the specified pointer.

type CmdCallback 

type CmdCallback func(cmd *Cmd)

CmdCallback is a routine that runs when new command is configured. If the command don't need to define new arguments or subcommands, you can safely run your custom code directly in this callback.

type CustomArg 

type CustomArg interface {
	Get() string
	Set(value string) error
	TypeName() string
	Explain(template string) string
}

CustomArg is the interface used to create customized argument types. As long as you can read and write to a string, you can use this.

TypeName is the name to be used to represent this type on help messages (e. g. int, string, value, foo). This will only be used if the user does not supply a sencond help message.

Explain is a (optional) short string describing the custom type. This method receives a template string(that might be empty) in Printf style and 'injects' the type explanation on it. It may return different results based on the existence or not of a template string.

Note that a empty string ("") is assumed to be the zero value of your custom type

type ErrCallback 

type ErrCallback func(err error) error

ErrCallback is a callback that executes when the parser encounters an error. If you wish to recover (or ignore) the error, return a nil value to force the parser to continue it's normal process.

type HelpCallback 

type HelpCallback func(cmd *Cmd, out io.Writer)

HelpCallback is a callback that allows the user to customize the help text.

type MatchCallback 

type MatchCallback func(cmd *Cmd)

MatchCallback is a callback that is run when a command matches and and the parsing happens without raising an error. You can safely assume that the argument values are correctly loaded; however, since this callback runs before the subcommand processing occurs, this may not be the 'final' command to be executed by the user.

To run code when the final command is selected, take a look at the Run function and the RunCallback type.

type Options 

type Options struct {
	// When true, the automatic creation of help flags will
	// be suppressed.
	SuppressHelpFlag bool

	// When true, do not print the help automatically when a
	// help flag is set
	SupressPrintHelpWhenSet bool

	// When true, do not print the help automatically when a command with
	// subcommands and without a Run callback is executed
	SuppressPrintHelpPartialCommand bool

	// When true, returns an parsing error when the number of operands does not match
	// the expected number of required operands (optional and repeated operands are ignored).
	StrictOperands bool

	// When set, redirect the help output to the specified writer.
	// When it is nil, the help text will be printed to Stdout
	HelpOutput io.Writer

	// Function that overrides the auto-generated help text.
	OnHelp HelpCallback
}

Options defines the configuration options of the main App instance. The zero value of this struct reflect the default set of options.

type RunCallback 

type RunCallback func(cmd *Cmd) error

RunCallback is a callback that runs when a specified command is invoked. This callback only runs if the parsing did succeed.

You can safely assume that all parsed args are correctly loaded and no other subcommands are pending. If you return an error value in this callback, it will be available as a return to the Run or RunArgs on the App instance.

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.