Читать книгу Practical Go - Amit Saha - Страница 37

Before we dive into the flag package, let's refresh our memory of what a typical command-line application's user interface looks like. Let's consider a command-line application called application. Typically, it will have an interface similar to the following:

application [-h] [-n <value>] –silent <arg1> <arg2>

The user interface has the following components:

 -h is a Boolean option usually specified to print a help text.

 -n <value> expects the user to specify a value for the option, n. The application's logic determines the expected data type for the value.

 -silent is another Boolean option. Specifying it sets the value to true.

 arg1 and arg2 are referred to as positional arguments. A positional argument’s data type and interpretation is completely determined by the application.

The flag package implements types and methods to write command-line applications with standard behavior as above. When you specify the -h option while executing the application, all of the other arguments, if specified, will be ignored and a help message will be printed.

An application will have a mix of required and optional options.

It is also worth noting here that any positional argument must be specified after you have specified all of the required options. The flag package stops parsing the arguments once it encounters a positional argument, - or -- .

Table 1.1 summarizes the package's parsing behavior for a sample of command-line arguments.

Table 1.1: Parsing of command-line arguments via flag

COMMAND-LINE ARGUMENTS	FLAG PARSING BEHAVIOR
-h -n 1 hello -h -n 1 Hello -n 1 – Hello Hello -n 1	A help message is displayed.A help message is displayed.Value of the flag n is set to 1 and Hello is available as a positional argument to the application.Value of the flag n is set to 1 and everything else is ignored-n 1 is ignored.

Let's see an example by rewriting the greeter application so that the number of times the user's name is printed is specified by the option -n. After the rewrite, the user interface will be as follows:

$ ./application -n 2 Your name please? Press the Enter key when done. Joe Cool Nice to meet you Joe Cool Nice to meet you Joe Cool

Comparing the above to Listing 1.1, the key change is in how the parseArgs() function is written:

func parseArgs(w io.Writer, args []string) (config, error) { c := config{} fs := flag.NewFlagSet("greeter", flag.ContinueOnError) fs.SetOutput(w) fs.IntVar(&c.numTimes, "n", 0, "Number of times to greet") err := fs.Parse(args) if err != nil { return c, err } if fs.NArg() != 0 { return c, errors.New("Positional arguments specified") } return c, nil }

The function takes two parameters: a variable, w, whose value satisfies the io.Writer interface, and an array of strings representing the arguments to parse. It returns a config object and an error value. To parse the arguments, a new FlagSet object is created as follows:

fs := flag.NewFlagSet("greeter", flag.ContinueOnError)

The NewFlagSet() function defined in the flag package is used to create a FlagSet object. Think of it as an abstraction used to handle the arguments a command-line application can accept. The first argument to the NewFlagSet() function is the name of the command that will be shown in help messages. The second argument configures what happens when an error is encountered while parsing the command-line arguments; that is, when the fs.Parse() function is called. When the ContinueOnError option is specified, the execution of the program will continue, even if a non- nil error is returned by the Parse() function. This is useful when you want to perform your own processing if there is a parsing error. Other possible values are ExitOnError, which halts the execution of the program, and PanicOnError, which invokes the panic() function. The difference between ExitOnError and PanicOnError is that you can make use of the recover() function in the latter case to perform any cleanup actions before the program terminates.

The SetOutput() method specifies the writer that will be used by the initialized FlagSet object for writing any diagnostic or output messages. By default, it is set to the standard error, os.Stderr. Setting it to the specified writer, w, allows us write unit tests to verify the behavior.

Next, we define the first option:

fs.IntVar(&c.numTimes, "n", 0, "Number of times to greet")

The IntVar() method is used to create an option whose value is expected to be of type int. The first parameter of the method is the address of the variable in which the integer specified is stored. The second parameter of the method is the name of the option itself, n. The third parameter is the default value for the option, and the last parameter is a string that describes the purpose of the parameter to the program's user. It automatically gets displayed in the help text for the program. Similar methods are defined for other data types—float, string, and bool. You can also define a flag option for a custom type.

Next, we call the Parse() function, passing the args[] slice:

err := fs.Parse(args) if err != nil { return c, err }

This is the function that reads the elements of the slice and examines them against the flag options defined.

During the examination, it will attempt to fill in the values indicated in the specified variables, and if there is an error, it will either return an error to the calling function or terminate the execution, depending on the second argument specified to NewFlagSet() function. If a non-nil error is returned, the parseArgs() function returns the empty config object and the error value.

If a nil error is returned, we check to see if there was any positional argument specified, and if so, we return the object, c, and an error value:

if fs.NArg() != 0 { return c, errors.New("Positional arguments specified") }

Since the greeter program doesn't expect any positional arguments to be specified, it checks for that and displays an error if one or more arguments are specified. The NArg() method returns the number of positional arguments after the options have been parsed.

The complete program is shown in Listing 1.5.