libcmd

package module
v0.0.0-...-94e593e Latest Latest
Warning

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

Go to latest
Published: Sep 23, 2019 License: MIT Imports: 7 Imported by: 4

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

This section is empty.

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) Configure

func (app *App) Configure(options Options)

Configure change the App settings to the specified options object. Please see the Options struct documentation for details.

func (*App) Run

func (app *App) Run() error

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

func (*App) RunArgs

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

RunArgs behave like run, 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
	// 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) Args

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

Args returns the remaining non-parsed command line arguments.

func (*Cmd) Bool

func (cmd *Cmd) Bool(long, short string, 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, short string, defaultValue bool, help string)

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

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) 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, short string, 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, short string, 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, short string, 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, short string, defaultValue float64, help string)

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

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, short string, 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) Int8

func (cmd *Cmd) Int8(long, short string, 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, short string, defaultValue int8, help string)

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

func (*Cmd) Int16

func (cmd *Cmd) Int16(long, short string, 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, short string, 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, short string, 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, short string, 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, short string, 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, short string, defaultValue int64, help string)

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

func (*Cmd) IntP

func (cmd *Cmd) IntP(target *int, long, short string, 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) 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, short, defaultValue, 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, short, defaultValue, 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, short string, 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) Uint8

func (cmd *Cmd) Uint8(long, short string, 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, short string, defaultValue uint8, help string)

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

func (*Cmd) Uint16

func (cmd *Cmd) Uint16(long, short string, 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, short string, 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, short string, 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, short string, 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, short string, 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, short string, defaultValue uint64, help string)

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

func (*Cmd) UintP

func (cmd *Cmd) UintP(target *uint, long, short string, 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 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()

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 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() 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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL