aboutsummaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
authorAlex Ogier <[email protected]>2012-05-09 14:11:14 -0400
committerAlex Ogier <[email protected]>2012-05-09 14:11:14 -0400
commitfd456b3a45afd5b9eb9204556d5b2d5ab809b90f (patch)
treee1efedd5bd81c645a735b7bec2b57677ac8b6752 /README.md
parentd96927a210aaa64f95e2c8f83c51aa290b45c7fb (diff)
Reformat go snippets in the README
Diffstat (limited to 'README.md')
-rw-r--r--README.md90
1 files changed, 64 insertions, 26 deletions
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