kingpin

package module
v1.0.0 Latest Latest
Warning

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

 Go to latest Published: Jun 18, 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.

Versions

Kingpin uses gopkgin.in for versioning.

Changes

  • 2014-06-19 -- Stable v1.0.0 release.

    • Support cumulative positional arguments.
    • Return error rather than panic when there are fatal errors not caught by the type system. eg. when a default value is invalid.
    • Use gokpg.in.

  • 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"

  "gopkg.in/alecthomas/kingpin.v1"
)

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"
  "gopkg.in/alecthomas/kingpin.v1"
)

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 (a *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 (a *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:

Source Files

View all Source files

Directories

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

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.