kingpin

package module
Version: v0.3.0 Latest Latest
Warning

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

Go to latest
Published: Jun 12, 2014 License: MIT Imports: 13 Imported by: 0

README

Kingpin - A Go (golang) command line and flag parser Build Status

Features

  • POSIX-style short flag combining.
  • Parsed, type-safe flags.
  • Parsed, type-safe positional arguments.
  • Support for required flags and required positional arguments
  • Callbacks per command, flag and argument.
  • Help output that isn't as ugly as sin.

Changes

  • 2014-06-10 -- Place-holder streamlining.
    • Renamed MetaVar to PlaceHolder.
    • Removed MetaVarFromDefault. Kingpin now uses heuristics to determine what to display.

Simple Example

Kingpin can be used for simple flag+arg applications like so:

$ ping --help
usage: ping [<flags>] <ip> [<count>]

Flags:
  --debug            Enable debug mode.
  --help             Show help.
  -t, --timeout=5s   Timeout waiting for ping.

Args:
  <ip>        IP address to ping.
  [<count>]   Number of packets to send
$ ping 1.2.3.4 5
Would ping: 1.2.3.4 with timeout 5s and count 0

From the following source:

package main

import (
  "fmt"

  "github.com/alecthomas/kingpin"
)

var (
  debug   = kingpin.Flag("debug", "Enable debug mode.").Bool()
  timeout = kingpin.Flag("timeout", "Timeout waiting for ping.").Default("5s").OverrideDefaultFromEnvar("PING_TIMEOUT").Short('t').Duration()
  ip      = kingpin.Arg("ip", "IP address to ping.").Required().IP()
  count   = kingpin.Arg("count", "Number of packets to send").Int()
)

func main() {
  kingpin.Version("0.0.1")
  kingpin.Parse()
  fmt.Printf("Would ping: %s with timeout %s and count %d", *ip, *timeout, *count)
}

Complex Example

Kingpin can also produce complex command-line applications with global flags, subcommands, and per-subcommand flags, like this:

$ chat
usage: chat [<flags>] <command> [<flags>] [<args> ...]

A command-line chat application.

Flags:
  --debug              enable debug mode
  --help               Show help.
  --server=127.0.0.1   server address

Commands:
  help <command>
    Show help for a command.

  post [<flags>] <channel>
    Post a message to a channel.

  register <nick> <name>
    Register a new user.

$ chat help post
usage: chat [<flags>] post [<flags>] <channel> [<text>]

Post a message to a channel.

Flags:
  --image=IMAGE   image to post

Args:
  <channel>   channel to post to
  [<text>]    text to post
$ chat post --image=~/Downloads/owls.jpg pics
...

From this code:

package main

import (
  "os"
  "github.com/alecthomas/kingpin"
)

var (
  app      = kingpin.New("chat", "A command-line chat application.")
  debug    = app.Flag("debug", "Enable debug mode.").Bool()
  serverIP = app.Flag("server", "Server address.").Default("127.0.0.1").IP()

  register     = app.Command("register", "Register a new user.")
  registerNick = register.Arg("nick", "Nickname for user.").Required().String()
  registerName = register.Arg("name", "Name of user.").Required().String()

  post        = app.Command("post", "Post a message to a channel.")
  postImage   = post.Flag("image", "Image to post.").File()
  postChannel = post.Arg("channel", "Channel to post to.").Required().String()
  postText    = post.Arg("text", "Text to post.").Strings()
)

func main() {
  switch kingpin.MustParse(app.Parse(os.Args[1:])) {
  // Register user
  case "register":
    println(*registerNick)

  // Post message
  case "post":
    if *postImage != nil {
    }
    text := strings.Join(*postText, " ")
  }
}

Reference Documentation

Custom Parsers

Kingpin supports both flag and positional argument parsers for converting to Go types. For example, some included parsers are Int(), Float(), Duration() and ExistingFile().

Parsers conform to Go's flag.Value interface, so any existing implementations will work.

For example, a parser for accumulating HTTP header values might look like this:

type HTTPHeaderValue http.Header

func (h *HTTPHeaderValue) Set(value string) error {
  parts := strings.SplitN(value, ":", 2)
  if len(parts) != 2 {
    return fmt.Errorf("expected HEADER:VALUE got '%s'", value)
  }
  (*http.Header)(h).Add(parts[0], parts[1])
  return nil
}

func (h *HTTPHeaderValue) String() string {
  return ""
}

As a convenience, I would recommend something like this:

func HTTPHeader(s Settings) (target *http.Header) {
  target = new(http.Header)
  s.SetValue((*HTTPHeaderValue)(target))
  return
}

You would use it like so:

headers = HTTPHeader(kingpin.Flag("header", "Add a HTTP header to the request.").Short('H'))
Default Values

The default value is the zero value for a type. This can be overridden with the Default(value) function on flags and arguments. This function accepts a string, which is parsed by the value itself, so it must be compliant with the format expected.

Place-holders in Help

The place-holder value for a flag is the value used in the help to describe the value of a non-boolean flag.

The value provided to PlaceHolder() is used if provided, then the value provided by Default() if provided, then finally the capitalised flag name is used.

Here are some examples of flags with various permutations:

--name=NAME           // Flag(...).String()
--name="Harry"        // Flag(...).Default("Harry").String()
--name=FULL-NAME      // flag(...).PlaceHolder("FULL-NAME").Default("Harry").String()
Consuming all remaining arguments

A common command-line idiom is to use all remaining arguments for some purpose. eg. The following command accepts an arbitrary number of IP addresses as positional arguments:

./cmd ping 10.1.1.1 192.168.1.1

Kingpin supports this by having Value provide a IsCumulative() bool function. If this function exists and returns true, the value parser will be called repeatedly for every remaining argument.

Examples of this are the Strings() and StringMap() values.

To implement the above example we might do something like this:

type ipList []net.IP

func (i *ipList) Set(value string) error {
  if ip := net.ParseIP(value); ip == nil {
    return fmt.Errorf("'%s' is not an IP address", value)
  } else {
    *i = append(*i, ip)
    return nil
  }
}

func (i *ipList) String() string {
  return ""
}

func (i *ipList) IsCumulative() bool {
  return true
}

func IPList(s Settings) (target *[]net.IP) {
  target = new([]net.IP)
  s.SetValue((*ipList)(target))
  return
}

And use it like so:

ips := IPList(kingpin.Arg("ips", "IP addresses to ping."))

Documentation

Overview

Package kingpin provides command line interfaces like this:

$ chat
usage: chat [<flags>] <command> [<flags>] [<args> ...]

Flags:
  --debug              enable debug mode
  --help               Show help.
  --server=127.0.0.1   server address

Commands:
  help <command>
    Show help for a command.

  post [<flags>] <channel>
    Post a message to a channel.

  register <nick> <name>
    Register a new user.

$ chat help post
usage: chat [<flags>] post [<flags>] <channel> [<text>]

Post a message to a channel.

Flags:
  --image=IMAGE   image to post

Args:
  <channel>   channel to post to
  [<text>]    text to post
$ chat post --image=~/Downloads/owls.jpg pics

From code like this:

package main

import "github.com/alecthomas/kingpin"

var (
  debug    = kingpin.Flag("debug", "enable debug mode").Default("false").Bool()
  serverIP = kingpin.Flag("server", "server address").Default("127.0.0.1").IP()

  register     = kingpin.Command("register", "Register a new user.")
  registerNick = register.Arg("nick", "nickname for user").Required().String()
  registerName = register.Arg("name", "name of user").Required().String()

  post        = kingpin.Command("post", "Post a message to a channel.")
  postImage   = post.Flag("image", "image to post").File()
  postChannel = post.Arg("channel", "channel to post to").Required().String()
  postText    = post.Arg("text", "text to post").String()
)

func main() {
  switch kingpin.Parse() {
  // Register user
  case "register":
    println(*registerNick)

  // Post message
  case "post":
    if *postImage != nil {
    }
    if *postText != "" {
    }
  }
}

Index

Examples

Constants

View Source
const (
	TokenShort tokenType = iota
	TokenLong
	TokenArg
	TokenEOF
)

Token types.

Variables

View Source
var (
	// CommandLine is the default Kingpin parser.
	CommandLine = New(filepath.Base(os.Args[0]), "")
)
View Source
var (
	TokenEOFMarker = token{TokenEOF, ""}
)

Functions

func FatalIfError

func FatalIfError(err error, prefix string)

FatalIfError prints an error and exits if err is not nil. The error is printed with the given prefix.

func Fatalf

func Fatalf(format string, args ...interface{})

Fatalf prints an error message to stderr and exits.

func MustParse

func MustParse(command string, err error) string

MustParse can be used with app.Parse(args) to exit with an error if parsing fails.

func Parse

func Parse() string

Parse and return the selected command. Will exit with a non-zero status if an error was encountered.

func Tokenize

func Tokenize(args []string) (tokens tokens)

func Usage

func Usage()

Usage prints usage to stderr.

func UsageErrorf

func UsageErrorf(format string, args ...interface{})

UsageErrorf prints an error message followed by usage information, then exits with a non-zero status.

func Version added in v0.3.0

func Version(version string)

Version adds a flag for displaying the application version number.

Types

type Application

type Application struct {
	Name string
	Help string
	// contains filtered or unexported fields
}

An Application contains the definitions of flags, arguments and commands for an application.

func New

func New(name, help string) *Application

New creates a new Kingpin application instance.

func (Application) Arg

func (a Application) Arg(name, help string) *ArgClause

func (*Application) Command

func (c *Application) Command(name, help string) *CmdClause

Command adds a new top-level command to the application.

func (*Application) CommandUsage

func (c *Application) CommandUsage(w io.Writer, command string)

func (Application) Flag

func (f Application) Flag(name, help string) *FlagClause

Flag defines a new flag with the given long name and help.

func (*Application) Parse

func (c *Application) Parse(args []string) (command string, err error)

Parse parses command-line arguments.

func (*Application) Usage

func (c *Application) Usage(w io.Writer)

func (*Application) Version added in v0.3.0

func (a *Application) Version(version string) *Application

Version adds a --version flag for displaying the application version.

type ArgClause

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

func Arg

func Arg(name, help string) *ArgClause

Arg adds a new argument to the top-level of the default parser.

func (*ArgClause) Bool

func (p *ArgClause) Bool() (target *bool)

Bool sets the parser to a boolean parser. Supports --no-<X> to disable the flag.

func (*ArgClause) BoolVar

func (p *ArgClause) BoolVar(target *bool)

Bool sets the parser to a boolean parser. Supports --no-<X> to disable the flag.

func (*ArgClause) Default

func (a *ArgClause) Default(value string) *ArgClause

Default value for this argument. It *must* be parseable by the value of the argument.

func (*ArgClause) Dispatch

func (a *ArgClause) Dispatch(dispatch Dispatch) *ArgClause

func (*ArgClause) Duration

func (p *ArgClause) Duration() (target *time.Duration)

Duration sets the parser to a time.Duration parser.

func (*ArgClause) DurationVar

func (p *ArgClause) DurationVar(target *time.Duration)

Duration sets the parser to a time.Duration parser.

func (*ArgClause) ExistingDir

func (p *ArgClause) ExistingDir() (target *string)

ExistingDir sets the parser to one that requires and returns an existing directory.

func (*ArgClause) ExistingDirVar

func (p *ArgClause) ExistingDirVar(target *string)

ExistingDir sets the parser to one that requires and returns an existing directory.

func (*ArgClause) ExistingFile

func (p *ArgClause) ExistingFile() (target *string)

ExistingFile sets the parser to one that requires and returns an existing file.

func (*ArgClause) ExistingFileVar

func (p *ArgClause) ExistingFileVar(target *string)

ExistingFile sets the parser to one that requires and returns an existing file.

func (*ArgClause) File

func (p *ArgClause) File() (target **os.File)

File sets the parser to one that requires and opens a valid os.File.

func (*ArgClause) FileVar

func (p *ArgClause) FileVar(target **os.File)

File sets the parser to one that requires and opens a valid os.File.

func (*ArgClause) Float

func (p *ArgClause) Float() (target *float64)

Float sets the parser to a float64 parser.

func (*ArgClause) FloatVar

func (p *ArgClause) FloatVar(target *float64)

Float sets the parser to a float64 parser.

func (*ArgClause) IP

func (p *ArgClause) IP() (target *net.IP)

IP sets the parser to a net.IP parser.

func (*ArgClause) IPVar

func (p *ArgClause) IPVar(target *net.IP)

IP sets the parser to a net.IP parser.

func (*ArgClause) Int

func (p *ArgClause) Int() (target *int)

Int sets the parser to an int parser.

func (*ArgClause) Int64

func (p *ArgClause) Int64() (target *int64)

Int64 parses an int64

func (*ArgClause) Int64Var

func (p *ArgClause) Int64Var(target *int64)

Int64 parses an int64

func (*ArgClause) IntVar

func (p *ArgClause) IntVar(target *int)

Int sets the parser to an int parser.

func (*ArgClause) Required

func (a *ArgClause) Required() *ArgClause

Required arguments must be input by the user. They can not have a Default() value provided.

func (*ArgClause) SetValue

func (p *ArgClause) SetValue(value Value)

func (*ArgClause) String

func (p *ArgClause) String() (target *string)

String sets the parser to a string parser.

func (*ArgClause) StringMap

func (p *ArgClause) StringMap() (target *map[string]string)

StringMap provides key=value parsing into a map.

func (*ArgClause) StringMapVar

func (p *ArgClause) StringMapVar(target *map[string]string)

StringMap provides key=value parsing into a map.

func (*ArgClause) StringVar

func (p *ArgClause) StringVar(target *string)

String sets the parser to a string parser.

func (*ArgClause) Strings

func (p *ArgClause) Strings() (target *[]string)

Strings appends multiple occurrences to a string slice.

func (*ArgClause) StringsVar

func (p *ArgClause) StringsVar(target *[]string)

Strings appends multiple occurrences to a string slice.

func (*ArgClause) TCP

func (p *ArgClause) TCP() (target **net.TCPAddr)

TCP (host:port) address.

func (*ArgClause) TCPList

func (p *ArgClause) TCPList() (target *[]*net.TCPAddr)

TCP (host:port) address list.

func (*ArgClause) TCPListVar

func (p *ArgClause) TCPListVar(target *[]*net.TCPAddr)

TCPVar (host:port) address list.

func (*ArgClause) TCPVar

func (p *ArgClause) TCPVar(target **net.TCPAddr)

TCPVar (host:port) address.

func (*ArgClause) URL

func (p *ArgClause) URL() (target **url.URL)

URL provides a valid, parsed url.URL.

func (*ArgClause) URLList

func (p *ArgClause) URLList() (target *[]*url.URL)

URLList provides a parsed list of url.URL values.

func (*ArgClause) URLListVar

func (p *ArgClause) URLListVar(target *[]*url.URL)

URLListVar provides a parsed list of url.URL values.

func (*ArgClause) URLVar

func (p *ArgClause) URLVar(target **url.URL)

URL provides a valid, parsed url.URL.

func (*ArgClause) Uint64

func (p *ArgClause) Uint64() (target *uint64)

Uint64 parses a uint64

func (*ArgClause) Uint64Var

func (p *ArgClause) Uint64Var(target *uint64)

Uint64 parses a uint64

type CmdClause

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

func Command

func Command(name, help string) *CmdClause

Command adds a new command to the default parser.

func (CmdClause) Arg

func (a CmdClause) Arg(name, help string) *ArgClause

func (*CmdClause) Dispatch

func (c *CmdClause) Dispatch(dispatch Dispatch) *CmdClause

func (CmdClause) Flag

func (f CmdClause) Flag(name, help string) *FlagClause

Flag defines a new flag with the given long name and help.

type Dispatch

type Dispatch func() error

type FlagClause

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

FlagClause is a fluid interface used to build flags.

func Flag

func Flag(name, help string) *FlagClause

Flag adds a new flag to the default parser.

func (*FlagClause) Bool

func (f *FlagClause) Bool() (target *bool)

Bool makes this flag a boolean flag.

func (*FlagClause) BoolVar

func (p *FlagClause) BoolVar(target *bool)

Bool sets the parser to a boolean parser. Supports --no-<X> to disable the flag.

func (*FlagClause) Default

func (f *FlagClause) Default(value string) *FlagClause

Default value for this flag. It *must* be parseable by the value of the flag.

func (*FlagClause) Dispatch

func (f *FlagClause) Dispatch(dispatch Dispatch) *FlagClause

Dispatch to the given function when the flag is parsed.

func (*FlagClause) Duration

func (p *FlagClause) Duration() (target *time.Duration)

Duration sets the parser to a time.Duration parser.

func (*FlagClause) DurationVar

func (p *FlagClause) DurationVar(target *time.Duration)

Duration sets the parser to a time.Duration parser.

func (*FlagClause) ExistingDir

func (p *FlagClause) ExistingDir() (target *string)

ExistingDir sets the parser to one that requires and returns an existing directory.

func (*FlagClause) ExistingDirVar

func (p *FlagClause) ExistingDirVar(target *string)

ExistingDir sets the parser to one that requires and returns an existing directory.

func (*FlagClause) ExistingFile

func (p *FlagClause) ExistingFile() (target *string)

ExistingFile sets the parser to one that requires and returns an existing file.

func (*FlagClause) ExistingFileVar

func (p *FlagClause) ExistingFileVar(target *string)

ExistingFile sets the parser to one that requires and returns an existing file.

func (*FlagClause) File

func (p *FlagClause) File() (target **os.File)

File sets the parser to one that requires and opens a valid os.File.

func (*FlagClause) FileVar

func (p *FlagClause) FileVar(target **os.File)

File sets the parser to one that requires and opens a valid os.File.

func (*FlagClause) Float

func (p *FlagClause) Float() (target *float64)

Float sets the parser to a float64 parser.

func (*FlagClause) FloatVar

func (p *FlagClause) FloatVar(target *float64)

Float sets the parser to a float64 parser.

func (*FlagClause) IP

func (p *FlagClause) IP() (target *net.IP)

IP sets the parser to a net.IP parser.

func (*FlagClause) IPVar

func (p *FlagClause) IPVar(target *net.IP)

IP sets the parser to a net.IP parser.

func (*FlagClause) Int

func (p *FlagClause) Int() (target *int)

Int sets the parser to an int parser.

func (*FlagClause) Int64

func (p *FlagClause) Int64() (target *int64)

Int64 parses an int64

func (*FlagClause) Int64Var

func (p *FlagClause) Int64Var(target *int64)

Int64 parses an int64

func (*FlagClause) IntVar

func (p *FlagClause) IntVar(target *int)

Int sets the parser to an int parser.

func (*FlagClause) OverrideDefaultFromEnvar added in v0.3.0

func (f *FlagClause) OverrideDefaultFromEnvar(envar string) *FlagClause

OverrideDefaultFromEnvar overrides the default value for a flag from an environment variable, if available.

func (*FlagClause) PlaceHolder added in v0.2.0

func (f *FlagClause) PlaceHolder(placeholder string) *FlagClause

PlaceHolder sets the place-holder string used for flag values in the help. The default behaviour is to use the value provided by Default() if provided, then fall back on the capitalized flag name.

func (*FlagClause) Required

func (f *FlagClause) Required() *FlagClause

Required makes the flag required. You can not provide a Default() value to a Required() flag.

func (*FlagClause) SetValue

func (p *FlagClause) SetValue(value Value)

func (*FlagClause) Short

func (f *FlagClause) Short(name byte) *FlagClause

Short sets the short flag name.

func (*FlagClause) String

func (p *FlagClause) String() (target *string)

String sets the parser to a string parser.

func (*FlagClause) StringMap

func (p *FlagClause) StringMap() (target *map[string]string)

StringMap provides key=value parsing into a map.

func (*FlagClause) StringMapVar

func (p *FlagClause) StringMapVar(target *map[string]string)

StringMap provides key=value parsing into a map.

func (*FlagClause) StringVar

func (p *FlagClause) StringVar(target *string)

String sets the parser to a string parser.

func (*FlagClause) Strings

func (p *FlagClause) Strings() (target *[]string)

Strings appends multiple occurrences to a string slice.

func (*FlagClause) StringsVar

func (p *FlagClause) StringsVar(target *[]string)

Strings appends multiple occurrences to a string slice.

func (*FlagClause) TCP

func (p *FlagClause) TCP() (target **net.TCPAddr)

TCP (host:port) address.

func (*FlagClause) TCPList

func (p *FlagClause) TCPList() (target *[]*net.TCPAddr)

TCP (host:port) address list.

func (*FlagClause) TCPListVar

func (p *FlagClause) TCPListVar(target *[]*net.TCPAddr)

TCPVar (host:port) address list.

func (*FlagClause) TCPVar

func (p *FlagClause) TCPVar(target **net.TCPAddr)

TCPVar (host:port) address.

func (*FlagClause) URL

func (p *FlagClause) URL() (target **url.URL)

URL provides a valid, parsed url.URL.

func (*FlagClause) URLList

func (p *FlagClause) URLList() (target *[]*url.URL)

URLList provides a parsed list of url.URL values.

func (*FlagClause) URLListVar

func (p *FlagClause) URLListVar(target *[]*url.URL)

URLListVar provides a parsed list of url.URL values.

func (*FlagClause) URLVar

func (p *FlagClause) URLVar(target **url.URL)

URL provides a valid, parsed url.URL.

func (*FlagClause) Uint64

func (p *FlagClause) Uint64() (target *uint64)

Uint64 parses a uint64

func (*FlagClause) Uint64Var

func (p *FlagClause) Uint64Var(target *uint64)

Uint64 parses a uint64

type Getter

type Getter interface {
	Value
	Get() interface{}
}

Getter is an interface that allows the contents of a Value to be retrieved. It wraps the Value interface, rather than being part of it, because it appeared after Go 1 and its compatibility rules. All Value types provided by this package satisfy the Getter interface.

type Settings

type Settings interface {
	SetValue(value Value)
}

type Value

type Value interface {
	String() string
	Set(string) error
}

Value is the interface to the dynamic value stored in a flag. (The default value is represented as a string.)

If a Value has an IsBoolFlag() bool method returning true, the command-line parser makes --name equivalent to -name=true rather than using the next command-line argument, and adds a --no-name counterpart for negating the flag.

Example

This example ilustrates how to define custom parsers. HTTPHeader cumulatively parses each encountered --header flag into a http.Header struct.

package main

import (
	"fmt"
	"net/http"
	"strings"
)

type HTTPHeaderValue http.Header

func (h *HTTPHeaderValue) Set(value string) error {
	parts := strings.SplitN(value, ":", 2)
	if len(parts) != 2 {
		return fmt.Errorf("expected HEADER:VALUE got '%s'", value)
	}
	(*http.Header)(h).Add(parts[0], parts[1])
	return nil
}

func (h *HTTPHeaderValue) String() string {
	return ""
}

func HTTPHeader(s Settings) (target *http.Header) {
	target = new(http.Header)
	s.SetValue((*HTTPHeaderValue)(target))
	return
}

// This example ilustrates how to define custom parsers. HTTPHeader
// cumulatively parses each encountered --header flag into a http.Header struct.
func main() {
	var (
		curl    = New("curl", "transfer a URL")
		headers = HTTPHeader(curl.Flag("headers", "Add HTTP headers to the request.").Short('H').PlaceHolder("HEADER:VALUE"))
	)

	curl.Parse([]string{"-H Content-Type:application/octet-stream"})
	for key, value := range *headers {
		fmt.Printf("%s = %s\n", key, value)
	}
}
Output:

Directories

Path Synopsis
examples
curl
A curl-like HTTP command-line client.
A curl-like HTTP command-line client.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
t or T : Toggle theme light dark auto
y or Y : Canonical URL