libcfg

README

libcfg - Configuration parameters made easy

libcfg is meant to be an all-in-one solution to load you application parameters.

Some people prefer environment variables, while others love command-line options. Both have pros and cons, so we should ask why not both?.

License

MIT. See LICENSE for details.

Documentation

Index

• type App
  • func NewApp(name, brief string) *App
  • func (app *App) Run() error
  • func (app *App) RunArgs(args []string) error
• type Cmd
  • func (cmd *Cmd) Args() []string
  • func (cmd *Cmd) Bool(long, short string, defaultValue bool, help string) *bool
  • func (cmd *Cmd) BoolP(target *bool, long, short string, defaultValue bool, help string)
  • func (cmd *Cmd) Command(name, brief string, callback CmdCallback)
  • func (cmd *Cmd) Err(handler ErrCallback)
  • func (cmd *Cmd) Float32(long, short string, defaultValue float32, help string) *float32
  • func (cmd *Cmd) Float32P(target *float32, long, short string, defaultValue float32, help string)
  • func (cmd *Cmd) Float64(long, short string, defaultValue float64, help string) *float64
  • func (cmd *Cmd) Float64P(target *float64, long, short string, defaultValue float64, help string)
  • func (cmd *Cmd) Int(long, short string, defaultValue int, help string) *int
  • func (cmd *Cmd) Int8(long, short string, defaultValue int8, help string) *int8
  • func (cmd *Cmd) Int8P(target *int8, long, short string, defaultValue int8, help string)
  • func (cmd *Cmd) Int16(long, short string, defaultValue int16, help string) *int16
  • func (cmd *Cmd) Int16P(target *int16, long, short string, defaultValue int16, help string)
  • func (cmd *Cmd) Int32(long, short string, defaultValue int32, help string) *int32
  • func (cmd *Cmd) Int32P(target *int32, long, short string, defaultValue int32, help string)
  • func (cmd *Cmd) Int64(long, short string, defaultValue int64, help string) *int64
  • func (cmd *Cmd) Int64P(target *int64, long, short string, defaultValue int64, help string)
  • func (cmd *Cmd) IntP(target *int, long, short string, defaultValue int, help string)
  • func (cmd *Cmd) Match(callback MatchCallback)
  • func (cmd *Cmd) Run(callback RunCallback)
  • func (cmd *Cmd) String(long, short, defaultValue, help string) *string
  • func (cmd *Cmd) StringP(target *string, long, short, defaultValue, help string)
  • func (cmd *Cmd) Uint(long, short string, defaultValue uint, help string) *uint
  • func (cmd *Cmd) Uint8(long, short string, defaultValue uint8, help string) *uint8
  • func (cmd *Cmd) Uint8P(target *uint8, long, short string, defaultValue uint8, help string)
  • func (cmd *Cmd) Uint16(long, short string, defaultValue uint16, help string) *uint16
  • func (cmd *Cmd) Uint16P(target *uint16, long, short string, defaultValue uint16, help string)
  • func (cmd *Cmd) Uint32(long, short string, defaultValue uint32, help string) *uint32
  • func (cmd *Cmd) Uint32P(target *uint32, long, short string, defaultValue uint32, help string)
  • func (cmd *Cmd) Uint64(long, short string, defaultValue uint64, help string) *uint64
  • func (cmd *Cmd) Uint64P(target *uint64, long, short string, defaultValue uint64, help string)
  • func (cmd *Cmd) UintP(target *uint, long, short string, defaultValue uint, help string)
• type CmdCallback
• type ErrCallback
• type MatchCallback
• type RunCallback

Types

type App

type App struct {
	*Cmd

	// The text to be shown at the 'Usage' line of the help
	Usage string
}

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