From fd456b3a45afd5b9eb9204556d5b2d5ab809b90f Mon Sep 17 00:00:00 2001 From: Alex Ogier Date: Wed, 9 May 2012 14:11:14 -0400 Subject: Reformat go snippets in the README --- README.md | 90 +++++++++++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 64 insertions(+), 26 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 34fd70c..b43b0dc 100644 --- a/README.md +++ b/README.md @@ -15,9 +15,11 @@ which can be found in the LICENSE file. 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 @@ -26,7 +28,9 @@ 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" +``` 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. @@ -35,25 +39,44 @@ functions such as String(), BoolVar(), and Var(), and is therefore unaffected. Define flags using flag.String(), Bool(), Int(), etc. Example: - var ip *int = flag.Int("flagname", 1234, "help message for flagname") + +``` 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. - var flagvar int - func init() { - flag.IntVar(&flagvar, "flagname", 1234, "help message for flagname") - } + +``` 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 - flag.Var(&flagVal, "name", "help message for flagname") + +``` 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 - flag.Parse() + +``` 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. - fmt.Println("ip has value ", *ip); - fmt.Println("flagvar has value ", flagvar); + +``` 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). @@ -62,34 +85,49 @@ The arguments are indexed from 0 up to flag.NArg(). 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") + +``` 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. Command line flag syntax: - --flag // boolean flags only - --flag=x - --flag x // non-boolean flags only + +``` go +--flag // boolean flags only +--flag=x +--flag x // non-boolean flags only +``` + The last form is not permitted for boolean flags because the meaning of the command - cmd --flag * + +``` go +cmd --flag * +``` + will change if there is a file called 0, false, etc. You must use the --flag=false form to turn off a boolean flag. 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. - -f // f must be boolean - -abc // all flags must be boolean - -abcn=1234 - -abcn 1234 // n must be non-boolean - -abcn1234 // n must be non-boolean - -Ifile // I must be non-boolean + +``` go +-f // f must be boolean +-abc // all flags must be boolean +-abcn=1234 +-abcn 1234 // n must be non-boolean +-abcn1234 // n must be non-boolean +-Ifile // I must be non-boolean +``` Flag parsing stops after the terminator "--". Unlike the flag package, flags can be interspersed with arguments anywhere on the command line -- cgit v1.2.3