publish command-line-arguments and command-line-flags

examples/command-line-flags/command-line-flags.go

@@ -1,19 +1,49 @@
+// [_Command-line flags_](http://en.wikipedia.org/wiki/Command-line_interface#Command-line_option)
+// are a common way to specify options for command-line
+// programs. For example, in `wc -l` the `-l` is a
+// command-line flag.
+
 package main
 
+// Go provides a `flag` package supporting basic
+// command-line flag parsing. We'll use this package to
+// implement our example command-line program.
 import "flag"
 import "fmt"
 
 func main() {
-    maxp := flag.Int("repeat", 3, "time to repeat args")
-    flag.Parse()
-    for i := 0; i < *maxp; i++ {
-        for _, arg := range flag.Args() {
-            fmt.Println(arg)
-        }
-    }
-}
 
-// todo: multiple flags
-// todo: trailing args
-// todo: arg escaping
-// todo: help text and usage errors
+    // Basic flag declarations are available for string,
+    // integer, and boolean options. Here we declare a
+    // string flag `word` with a default value `"foo"`
+    // and a short description. This `flag.String` function
+    // returns a string pointer (not a string value);
+    // we'll see how to use this pointer below.
+    wordPtr := flag.String("word", "foo", "a string")
+
+    // This declares `numb` and `fork` flags, using a
+    // similar approach to the `word` flag.
+    numbPtr := flag.Int("numb", 42, "an int")
+    boolPtr := flag.Bool("fork", false, "a bool")
+
+    // It's also possible to declare an option that uses an
+    // existing var declared elsewhere in the program.
+    // Note that we need to pass in a pointer to the flag
+    // declaration function.
+    var svar string
+    flag.StringVar(&svar, "svar", "bar", "a string var")
+
+    // Once all flags are declared, call `flag.Parse()`
+    // to execute the command-line parsing.
+    flag.Parse()
+
+    // Here we'll just dump out the parsed options and
+    // any trailing positional arguments. Note that we
+    // need to dereference the points with e.g. `*wordPtr`
+    // to get the actual option values.
+    fmt.Println("word:", *wordPtr)
+    fmt.Println("numb:", *numbPtr)
+    fmt.Println("fork:", *boolPtr)
+    fmt.Println("svar:", svar)
+    fmt.Println("tail:", flag.Args())
+}

examples/command-line-flags/command-line-flags.sh

@@ -0,0 +1,59 @@
+# To experiment with the command-line flags program it's
+# best to first compile it and then run the resulting
+# binary directly.
+$ go build command-line-flags.go
+
+# Try out the built program by first giving it values for
+# all flags.
+$ ./command-line-flags -word=opt -numb=7 -fork -svar=flag
+word: opt
+numb: 7
+fork: true
+svar: flag
+tail: []
+
+# Note that if you omit flags they automatically take
+# their default values.
+$ ./command-line-flags -word=opt
+word: opt
+numb: 42
+fork: false
+svar: bar
+tail: []
+
+# Trailing positional arguments can be provided after
+# any flags.
+$ ./command-line-flags -word=opt a1 a2 a3
+word: opt
+...
+tail: [a1 a2 a3]
+
+# Note that the `flag` package requires all flags to
+# appear before positional arguments (otherwise the flags
+# will be interpreted as positional arguments).
+$ ./command-line-flags -word=opt a1 a2 a3 -num=7
+word: opt
+numb: 42
+fork: false
+svar: bar
+trailing: [a1 a2 a3 -num=7]
+
+# Use `-h` or `--help` flags to get automatically
+# generated help text for the command-line program.
+$ ./command-line-flags -h
+Usage of ./command-line-flags:
+  -fork=false: a bool
+  -numb=42: an int
+  -svar="bar": a string var
+  -word="foo": a string
+
+# If you provide a flag that wasn't specified to the
+# `flag` package, the program will print an error message
+# an show the help text again.
+$ ./command-line-flags -wat
+flag provided but not defined: -wat
+Usage of ./command-line-flags:
+...
+
+# Next we'll look at environment variables, another common
+# way to parameterize programs.