Drop-in replacement for Go's flag package, implementing POSIX/GNU-style --flags.
Switch branches/tags
Nothing to show
Clone or download
ogier Merge pull request #22 from gamegos/master
Change PrintDefaults format to be similar to Go 1.5 style
Latest commit 45c278a Jan 29, 2016
Permalink
Failed to load latest commit information.
.travis.yml Add .travis.yml file Feb 15, 2015
LICENSE Add a LICENSE file May 4, 2012
README.md Add Travis build status marker to README Feb 15, 2015
bool.go Add support for custom boolean flags through IsBoolFlag() Jan 16, 2015
bool_test.go Fix typo in bool_test.go Jul 24, 2015
duration.go Compatibility: commandLine -> CommandLine Apr 2, 2014
example_test.go Import the full github path in tests May 4, 2012
export_test.go Update docs on GetCommandLine. Apr 2, 2014
flag.go Update PrintDefaults for Go 1.5 flag formatting Jan 26, 2016
flag_test.go Move test files to the 'pflag' package Feb 15, 2015
float32.go Compatibility: commandLine -> CommandLine Apr 2, 2014
float64.go Compatibility: commandLine -> CommandLine Apr 2, 2014
int.go Compatibility: commandLine -> CommandLine Apr 2, 2014
int32.go Compatibility: commandLine -> CommandLine Apr 2, 2014
int64.go Compatibility: commandLine -> CommandLine Apr 2, 2014
int8.go Compatibility: commandLine -> CommandLine Apr 2, 2014
ip.go Compatibility: commandLine -> CommandLine Apr 2, 2014
ipmask.go Compatibility: commandLine -> CommandLine Apr 2, 2014
string.go Compatibility: commandLine -> CommandLine Apr 2, 2014
uint.go Compatibility: commandLine -> CommandLine Apr 2, 2014
uint16.go Compatibility: commandLine -> CommandLine Apr 2, 2014
uint32.go Compatibility: commandLine -> CommandLine Apr 2, 2014
uint64.go Compatibility: commandLine -> CommandLine Apr 2, 2014
uint8.go Compatibility: commandLine -> CommandLine Apr 2, 2014

README.md

Build Status

Description

pflag is a drop-in replacement for Go's flag package, implementing POSIX/GNU-style --flags.

pflag is compatible with the GNU extensions to the POSIX recommendations for command-line options. For a more precise description, see the "Command-line flag syntax" section below.

pflag is available under the same style of BSD license as the Go language, which can be found in the LICENSE file.

Installation

pflag is available using the standard go get command.

Install by running:

go get github.com/ogier/pflag

Run tests by running:

go test github.com/ogier/pflag

Usage

pflag is a drop-in replacement of Go's native flag package. If you import pflag under the name "flag" then all code should continue to function with no changes.

import flag "github.com/ogier/pflag"

There is one exception to this: if you directly instantiate the Flag struct there is one more field "Shorthand" that you will need to set. Most code never instantiates this struct directly, and instead uses functions such as String(), BoolVar(), and Var(), and is therefore unaffected.

Define flags using flag.String(), Bool(), Int(), etc.

This declares an integer flag, -flagname, stored in the pointer ip, with type *int.

var ip *int = flag.Int("flagname", 1234, "help message for flagname")

If you like, you can bind the flag to a variable using the Var() functions.

var flagvar int
func init() {
    flag.IntVar(&flagvar, "flagname", 1234, "help message for flagname")
}

Or you can create custom flags that satisfy the Value interface (with pointer receivers) and couple them to flag parsing by

flag.Var(&flagVal, "name", "help message for flagname")

For such flags, the default value is just the initial value of the variable.

After all flags are defined, call

flag.Parse()

to parse the command line into the defined flags.

Flags may then be used directly. If you're using the flags themselves, they are all pointers; if you bind to variables, they're values.

fmt.Println("ip has value ", *ip)
fmt.Println("flagvar has value ", flagvar)

After parsing, the arguments after the flag are available as the slice flag.Args() or individually as flag.Arg(i). The arguments are indexed from 0 through flag.NArg()-1.

The pflag package also defines some new functions that are not in flag, that give one-letter shorthands for flags. You can use these by appending 'P' to the name of any function that defines a flag.

var ip = flag.IntP("flagname", "f", 1234, "help message")
var flagvar bool
func init() {
    flag.BoolVarP("boolname", "b", true, "help message")
}
flag.VarP(&flagVar, "varname", "v", 1234, "help message")

Shorthand letters can be used with single dashes on the command line. Boolean shorthand flags can be combined with other shorthand flags.

The default set of command-line flags is controlled by top-level functions. The FlagSet type allows one to define independent sets of flags, such as to implement subcommands in a command-line interface. The methods of FlagSet are analogous to the top-level functions for the command-line flag set.

Command line flag syntax

--flag    // boolean flags only
--flag=x

Unlike the flag package, a single dash before an option means something different than a double dash. Single dashes signify a series of shorthand letters for flags. All but the last shorthand letter must be boolean flags.

// boolean flags
-f
-abc

// non-boolean flags
-n 1234
-Ifile

// mixed
-abcs "hello"
-abcn1234

Flag parsing stops after the terminator "--". Unlike the flag package, flags can be interspersed with arguments anywhere on the command line before this terminator.

Integer flags accept 1234, 0664, 0x1234 and may be negative. Boolean flags (in their long form) accept 1, 0, t, f, true, false, TRUE, FALSE, True, False. Duration flags accept any input valid for time.ParseDuration.

More info

You can see the full reference documentation of the pflag package at godoc.org, or through go's standard documentation system by running godoc -http=:6060 and browsing to http://localhost:6060/pkg/github.com/ogier/pflag after installation.