cli

README

cli

Helpers for building command-line applications in Go.

See documentation on godoc

Documentation

Overview

Package cli is used to build the front-end of command-line applications.

Commands have zero or more mandatory arguments, and zero or more optional parameters. An example of a command invocation is:

myapp -root=somedir -z -x thecommand param1 param2

Optional parameters can be boolean values, which are specified with a single hyphen:

-z             This is a boolean option

Optional parameters that can take on a value must be specified like this:

-config=file   This is a value option

If no command is given, then the application help is displayed, for example:

>imqsauth

imqsauth -c=configfile [options] command

  createdb         Create the postgres database
  resetauthgroups  Reset the [admin,enabled] groups
  createuser       Create a user in the authentication system

  -c=configfile    Specify the authaus config file. A pseudo file called !TESTCONFIG1
                   is used by the REST test suite to load a test configuration.
                   This option is mandatory.

If one invokes help on a specific command, then details for that command are shown:

>imqsauth help createuser

createuser identity password

  Create a user in the authentication system.
  This affects only the 'authentication' system - the permit
  database is not altered by this command.

  -update   If specified, and the user already exists, then behave identically
            to 'setpassword'. If this is not specified, and the identity
            already exists, then the function returns with an error.

Index

• type App
  • func (app *App) AddBoolOption(name, description string)
  • func (app *App) AddCommand(name, description string, args ...string) *Command
  • func (app *App) AddValueOption(name, value, description string)
  • func (app *App) Run() int
  • func (app *App) ShowHelp(cmdName string)
• type Command
  • func (c *Command) AddBoolOption(name, description string)
  • func (c *Command) AddValueOption(name, value, description string)
  • func (c *Command) ExtraDescription() string
  • func (c *Command) ShortDescription() string
• type ExecFunc
• type Option
• type OptionSet
  • func (s OptionSet) Has(name string) bool

Types

type App

type App struct {
	Description string     // Single-line description
	DefaultExec ExecFunc   // Exec callback that is used if command's Exec is nil
	Commands    []*Command // Commands
	Options     []Option   // Global options
}

App is the cli application to be run

func (*App) AddBoolOption

func (app *App) AddBoolOption(name, description string)

AddBoolOption allows an application-wide bool option to be added (such as -z)

func (*App) AddCommand

func (app *App) AddCommand(name, description string, args ...string) *Command

AddCommand allows a command to be registered for use with the application

func (*App) AddValueOption

func (app *App) AddValueOption(name, value, description string)

AddValueOption allows an application-wide value option to be added (such as -c=config_file)

func (*App) Run

func (app *App) Run() int

Run the command list of the app. Returns the result of Exec(), or 1 for an error

func (*App) ShowHelp

func (app *App) ShowHelp(cmdName string)

ShowHelp is called automatically by Run().

type Command

type Command struct {
	Name        string
	Description string
	Args        []string // Mandatory arguments. To specify a variable number of arguments, write "...values" on the last argument. The name after the three dots can be anything.
	Options     []Option // Optional arguments
	Exec        ExecFunc // If this is nil, then App.DefaultExec is called
}

Command represents the top-level command

func (*Command) AddBoolOption

func (c *Command) AddBoolOption(name, description string)

AddBoolOption allows a command-specific bool to be added (such as -z)

func (*Command) AddValueOption

func (c *Command) AddValueOption(name, value, description string)

AddValueOption allows a command-specific value option to be added (such as -c=config_file)

func (*Command) ExtraDescription

func (c *Command) ExtraDescription() string

ExtraDescription returns the app description after the first newline character

func (*Command) ShortDescription

func (c *Command) ShortDescription() string

ShortDescription returns the app description before the first newline character

type ExecFunc

type ExecFunc func(cmd string, args []string, options OptionSet) int

ExecFunc is the callback when executing commands It is often easiest to implement a number of commands as a single big function with a switch statement on 'cmd'. The function must return the program exit code (0 = success)

type Option

type Option struct {
	Key         string // Must be present. Option is entered as -Key, or -Key=Value
	Value       string // If empty, then this is a boolean option, specified as -Key. If not empty, then this is a key/value option, specified as -Key=Value
	Description string
}

An Option to a command

type OptionSet

type OptionSet map[string]string

An OptionSet contains a set of Options

func (OptionSet) Has

func (s OptionSet) Has(name string) bool

Has checks if the option set contains the given option. Useful for bool operations