diff options
| -rw-r--r-- | README.md | 12 | ||||
| -rw-r--r-- | example_test.go | 89 | ||||
| -rw-r--r-- | parse.go | 34 |
3 files changed, 133 insertions, 2 deletions
@@ -1,5 +1,9 @@ +[](https://godoc.org/github.com/alexflint/go-arg) + ## Structured argument parsing for Go +Declare the command line arguments your program accepts by defining a struct. + ```go var args struct { Foo string @@ -43,8 +47,8 @@ var args struct { Output []string `arg:"positional"` } arg.MustParse(&args) -fmt.Println("Input:", input) -fmt.Println("Output:", output) +fmt.Println("Input:", args.Input) +fmt.Println("Output:", args.Output) ``` ``` @@ -102,6 +106,10 @@ Fetching the following IDs from foo: [1 2 3] go get github.com/alexflint/go-arg ``` +### Documentation + +https://godoc.org/github.com/alexflint/go-arg + ### Rationale There are many command line argument parsing libraries for Go, including one in the standard library, so why build another? diff --git a/example_test.go b/example_test.go new file mode 100644 index 0000000..d2febf6 --- /dev/null +++ b/example_test.go @@ -0,0 +1,89 @@ +package arg + +import ( + "fmt" + "os" + + "github.com/alexflint/go-arg" +) + +// This example demonstrates basic usage +func Example_Basic() { + // These are the args you would pass in on the command line + os.Args = []string{"./example", "--foo=hello", "--bar"} + + var args struct { + Foo string + Bar bool + } + arg.MustParse(&args) + fmt.Println(args.Foo, args.Bar) +} + +// This example demonstrates arguments that have default values +func Example_DefaultValues() { + // These are the args you would pass in on the command line + os.Args = []string{"--help"} + + var args struct { + Foo string + Bar bool + } + args.Foo = "default value" + arg.MustParse(&args) + fmt.Println(args.Foo, args.Bar) +} + +// This example demonstrates arguments that are required +func Example_RequiredArguments() { + // These are the args you would pass in on the command line + os.Args = []string{"--foo=1", "--bar"} + + var args struct { + Foo string `arg:"required"` + Bar bool + } + arg.MustParse(&args) +} + +// This example demonstrates positional arguments +func Example_PositionalArguments() { + // These are the args you would pass in on the command line + os.Args = []string{"./example", "in", "out1", "out2", "out3"} + + var args struct { + Input string `arg:"positional"` + Output []string `arg:"positional"` + } + arg.MustParse(&args) + fmt.Println("Input:", args.Input) + fmt.Println("Output:", args.Output) +} + +// This example demonstrates arguments that have multiple values +func Example_MultipleValues() { + // The args you would pass in on the command line + os.Args = []string{"--help"} + + var args struct { + Database string + IDs []int64 + } + arg.MustParse(&args) + fmt.Printf("Fetching the following IDs from %s: %q", args.Database, args.IDs) +} + +// This example shows the usage string generated by go-arg +func Example_Usage() { + // These are the args you would pass in on the command line + os.Args = []string{"--help"} + + var args struct { + Input string `arg:"positional"` + Output []string `arg:"positional"` + Verbose bool `arg:"-v,help:verbosity level"` + Dataset string `arg:"help:dataset to use"` + Optimize int `arg:"-O,help:optimization level"` + } + arg.MustParse(&args) +} @@ -1,3 +1,37 @@ +// Package arg parses command line arguments using the fields from a struct. +// Any exported field is interpreted as a command line option, so +// +// var args struct { +// Iter int +// Debug bool +// } +// arg.MustParse(&args) +// +// defines two command line arguments, which can be set using any of +// +// ./example --iter=1 --bar // bar is a boolean flag so its value is optional +// ./example -iter 1 // bar will default to its zero value +// ./example --bar=true // foo will default to its zero value +// +// The fastest way to learn how to use go-arg is to read the examples below. +// +// Fields can be bool, string, any float type, or any signed or unsigned integer type. +// They can also be slices of any of the above, or slices of pointers to any of the above. +// +// Tags can be specified using the `arg` package name: +// +// var args struct { +// Input string `arg:"positional"` +// Log string `arg:"positional,required"` +// Debug bool `arg:"-d,help:turn on debug mode"` +// RealMode bool `arg:"--real" +// Wr io.Writer `arg:"-"` +// } +// +// The valid tag strings are `positional`, `required`, and `help`. Further, any tag string +// that starts with a single hyphen is the short form for an argument (e.g. `./example -d`), +// and any tag string that starts with two hyphens is the long form for the argument +// (instead of the field name). Fields can be excluded from processing with `arg:"-"`. package arg import ( |