Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/ogier/pflag

Drop-in replacement for Go's flag package, implementing POSIX/GNU-style --flags.
https://github.com/ogier/pflag

Last synced: 3 months ago
JSON representation

Drop-in replacement for Go's flag package, implementing POSIX/GNU-style --flags.

Awesome Lists containing this project

README 

        
[![Build Status](https://travis-ci.org/ogier/pflag.png?branch=master)](https://travis-ci.org/ogier/pflag)



## 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][1]. For a more precise description, see the

"Command-line flag syntax" section below.



[1]: http://www.gnu.org/software/libc/manual/html_node/Argument-Syntax.html



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.



``` go

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.



``` go

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.



``` go

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



``` go

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



``` go

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.



``` go

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.



``` go

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][3], or through go's standard documentation system by

running `godoc -http=:6060` and browsing to

[http://localhost:6060/pkg/github.com/ogier/pflag][2] after

installation.



[2]: http://localhost:6060/pkg/github.com/ogier/pflag

[3]: http://godoc.org/github.com/ogier/pflag