kingpin

package module
v1.3.7 Latest Latest
Warning

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

 Go to latest Published: May 22, 2015 License: MIT Imports: 16 Imported by: 119

README

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

(check out v2-unstable for bleeding edge features)

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 gopkg.in for versioning.

Usage:

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

Changes

  • 2015-01-23 -- Stable v1.3.4 release.

    • Support "--" for separating flags from positional arguments.
    • Support loading flags from files (ParseWithFileExpansion()). Use @FILE as an argument.
    • Add post-app and post-cmd validation hooks. This allows arbitrary validation to be added.
    • A bunch of improvements to help usage and formatting.
    • Support arbitrarily nested sub-commands.

  • 2014-07-08 -- Stable v1.2.0 release.

    • Pass any value through to Strings() when final argument. Allows for values that look like flags to be processed.
    • Allow --help to be used with commands.
    • Support Hidden() flags.
    • Parser for units.Base2Bytes type. Allows for flags like --ram=512MB or --ram=1GB.
    • Add an Enum() value, allowing only one of a set of values to be selected. eg. Flag(...).Enum("debug", "info", "warning").

  • 2014-06-27 -- Stable v1.1.0 release.

    • Bug fixes.
    • Always return an error (rather than panicing) when misconfigured.
    • OpenFile(flag, perm) value type added, for finer control over opening files.
    • Significantly improved usage formatting.

  • 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 --help
usage: chat [<flags>] <command> [<flags>] [<args> ...]

A command-line chat application.

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

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

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

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

$ 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"
  "strings"
  "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.FullCommand():
    println(*registerNick)

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

Reference Documentation

Help

Second to parsing, providing the user with useful help is probably the most important thing a command-line parser does.

Since 1.3.x, Kingpin uses a bunch of heuristics to display help. For example, --help should generally "just work" without much thought from users.

Sub-commands

Kingpin supports nested sub-commands, with separate flag and positional arguments per sub-command. Note that positional arguments may only occur after sub-commands.

For example:

var (
  deleteCommand     = kingpin.Command("delete", "Delete an object.")
  deleteUserCommand = deleteCommand.Command("user", "Delete a user.")
  deleteUserUIDFlag = deleteUserCommand.Flag("uid", "Delete user by UID rather than username.")
  deleteUserUsername = deleteUserCommand.Arg("username", "Username to delete.")
  deletePostCommand = deleteCommand.Command("post", "Delete a post.")
)

func main() {
  switch kingpin.Parse() {
  case "delete user":
  case "delete post":
  }
}
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 "gopkg.in/alecthomas/kingpin.v1"

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

This section is empty.

Variables

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

Functions

func ExpandArgsFromFiles added in v1.3.4 

func ExpandArgsFromFiles(args []string) ([]string, error)

ExpandArgsFromFiles expands arguments in the form @<file> into one-arg-per- line read from that file.

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 ParseWithFileExpansion added in v1.3.4 

func ParseWithFileExpansion() string

ParseWithFileExpansion is the same as Parse() but will expand flags from arguments in the form @FILE.

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 

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.

func (*Application) CommandUsage 

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

func (*Application) Errorf added in v1.2.3 

func (a *Application) Errorf(w io.Writer, format string, args ...interface{})

Errorf prints an error message to w.

func (*Application) FatalIfError added in v1.2.3 

func (a *Application) FatalIfError(w io.Writer, err error, prefix string)

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

func (*Application) Fatalf added in v1.3.0 

func (a *Application) Fatalf(w io.Writer, format string, args ...interface{})

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. It returns the selected command and an error. The selected command will be a space separated subcommand, if subcommands have been configured.

func (*Application) Usage 

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

func (*Application) UsageErrorf added in v1.2.3 

func (a *Application) UsageErrorf(w io.Writer, format string, args ...interface{})

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

func (*Application) Validate added in v1.3.3 

func (a *Application) Validate(validator ApplicationValidator) *Application

Validate sets a validation function to run when parsing.

func (*Application) Version 

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

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

type ApplicationValidator added in v1.3.3 

type ApplicationValidator func(*Application) error

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) Bytes added in v1.2.0 

func (p *ArgClause) Bytes() (target *units.Base2Bytes)

Bytes parses numeric byte units. eg. 1.5KB

func (*ArgClause) BytesVar added in v1.2.0 

func (p *ArgClause) BytesVar(target *units.Base2Bytes)

BytesVar parses numeric byte units. eg. 1.5KB

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) Enum added in v1.2.0 

func (p *ArgClause) Enum(options ...string) (target *string)

Enum allows a value from a set of options.

func (*ArgClause) EnumVar added in v1.2.0 

func (p *ArgClause) EnumVar(target **string, options ...string)

EnumVar allows a value from a set of options.

func (*ArgClause) Enums added in v1.3.6 

func (p *ArgClause) Enums(options ...string) (target *[]string)

Enums allows a set of values from a set of options.

func (*ArgClause) EnumsVar added in v1.3.6 

func (p *ArgClause) EnumsVar(target *[]string, options ...string)

EnumVar allows a value from a set of options.

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 returns an os.File against an existing file.

func (*ArgClause) FileVar 

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

FileVar opens an existing 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) OpenFile added in v1.1.0 

func (p *ArgClause) OpenFile(flag int, perm os.FileMode) (target **os.File)

File attempts to open a File with os.OpenFile(flag, perm).

func (*ArgClause) OpenFileVar added in v1.1.0 

func (p *ArgClause) OpenFileVar(target **os.File, flag int, perm os.FileMode)

OpenFileVar calls os.OpenFile(flag, perm)

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
}

A CmdClause is a single top-level command. It encapsulates a set of flags and either subcommands or positional arguments.

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) Command added in v1.2.6 

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

Command adds a new sub-command.

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.

func (*CmdClause) FullCommand added in v1.3.1 

func (c *CmdClause) FullCommand() string

func (*CmdClause) Validate added in v1.3.3 

func (c *CmdClause) Validate(validator CmdClauseValidator) *CmdClause

Validate sets a validation function to run when parsing.

type CmdClauseValidator added in v1.3.3 

type CmdClauseValidator func(*CmdClause) error

type Dispatch 

type Dispatch func(*ParseContext) 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) Bytes added in v1.2.0 

func (p *FlagClause) Bytes() (target *units.Base2Bytes)

Bytes parses numeric byte units. eg. 1.5KB

func (*FlagClause) BytesVar added in v1.2.0 

func (p *FlagClause) BytesVar(target *units.Base2Bytes)

BytesVar parses numeric byte units. eg. 1.5KB

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) Enum added in v1.2.0 

func (p *FlagClause) Enum(options ...string) (target *string)

Enum allows a value from a set of options.

func (*FlagClause) EnumVar added in v1.2.0 

func (p *FlagClause) EnumVar(target **string, options ...string)

EnumVar allows a value from a set of options.

func (*FlagClause) Enums added in v1.3.6 

func (p *FlagClause) Enums(options ...string) (target *[]string)

Enums allows a set of values from a set of options.

func (*FlagClause) EnumsVar added in v1.3.6 

func (p *FlagClause) EnumsVar(target *[]string, options ...string)

EnumVar allows a value from a set of options.

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 returns an os.File against an existing file.

func (*FlagClause) FileVar 

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

FileVar opens an existing 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) Hidden added in v1.2.0 

func (f *FlagClause) Hidden() *FlagClause

Hidden hides a flag from usage but still allows it to be used.

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) OpenFile added in v1.1.0 

func (p *FlagClause) OpenFile(flag int, perm os.FileMode) (target **os.File)

File attempts to open a File with os.OpenFile(flag, perm).

func (*FlagClause) OpenFileVar added in v1.1.0 

func (p *FlagClause) OpenFileVar(target **os.File, flag int, perm os.FileMode)

OpenFileVar calls os.OpenFile(flag, perm)

func (*FlagClause) OverrideDefaultFromEnvar 

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

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

func (*FlagClause) PlaceHolder 

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 ParseContext added in v1.3.0 

type ParseContext struct {
	Tokens          Tokens
	SelectedCommand string
}

func Tokenize 

func Tokenize(args []string) *ParseContext

func (*ParseContext) Next added in v1.3.0 

func (p *ParseContext) Next()

func (*ParseContext) Peek added in v1.3.0 

func (p *ParseContext) Peek() *Token

func (*ParseContext) Return added in v1.3.0 

func (p *ParseContext) Return(token *Token)

func (*ParseContext) String added in v1.3.2 

func (p *ParseContext) String() string

type Settings 

type Settings interface {
	SetValue(value Value)
}

type Token added in v1.3.0 

type Token struct {
	Type  TokenType
	Value string
}

func (*Token) IsEOF added in v1.3.0 

func (t *Token) IsEOF() bool

func (*Token) IsFlag added in v1.3.0 

func (t *Token) IsFlag() bool

func (*Token) String added in v1.3.0 

func (t *Token) String() string

type TokenType added in v1.3.0 

type TokenType int
const (
	TokenShort TokenType = iota
	TokenLong
	TokenArg
	TokenEOL
)

Token types.

type Tokens added in v1.3.0 

type Tokens []*Token

func (Tokens) Next added in v1.3.0 

func (t Tokens) Next() Tokens

func (Tokens) Peek added in v1.3.0 

func (t Tokens) Peek() *Token

func (Tokens) Return added in v1.3.0 

func (t Tokens) Return(token *Token) Tokens

func (Tokens) String added in v1.3.0 

func (t Tokens) String() string

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.