Go Flag Package Detailed Explanation

Introduction#

The flag package is a package in the Go language standard library used for parsing command-line arguments. It provides a convenient way to define and parse command-line arguments, making it easier and more flexible to develop command-line tools and applications.

The main features of the flag package include:

Defining the type and default value of command-line arguments
Parsing command-line arguments and assigning them to corresponding variables
Providing help information and usage instructions

Simple Example#

Here is an example assuming we want to write a simple command-line tool that calculates the sum of two integers. We can use the flag package to define and parse command-line arguments.

package main

import (
	"flag"
	"fmt"
)

func main() {
	// Define command-line arguments
	num1 := flag.Int("num1", 0, "first integer")
	num2 := flag.Int("num2", 0, "second integer")

	// Parse command-line arguments
	flag.Parse()

	// Calculate sum
	sum := *num1 + *num2

	// Output result
	fmt.Println("Sum:", sum)
}

In the above example, we first use the flag.Int function to define two command-line arguments num1 and num2, representing two integers. These arguments have a default value of 0, and the third argument is a description for the help information.

Next, we call the flag.Parse() function to parse the command-line arguments. It searches for the defined arguments in the command-line and assigns the corresponding values to the variables.

Finally, we add the two integers and output the result.

Now we can run the program in the command-line and specify the command-line arguments:

$ go run main.go -num1=10 -num2=20
Sum: 30

The above example demonstrates how to use the flag package to define and parse command-line arguments, allowing us to control the behavior of the program through the command-line. We can further develop our own command-line tools and applications using the flag package.

The flag package also supports several commonly used types of command-line arguments:

Boolean type (bool):
- Usage: flag.Bool(name string, value bool, usage string) *bool
- Example: verbose := flag.Bool("verbose", false, "display detailed information")
- Description: Boolean command-line arguments are used to represent whether an option is enabled or disabled. If the option is specified in the command-line, the corresponding boolean variable will be set to true, otherwise false.
Integer type (int):
- Usage: flag.Int(name string, value int, usage string) *int
- Example: count := flag.Int("count", 0, "retry count")
- Description: Integer command-line arguments are used to represent integer values. The integer value specified in the command-line will be parsed and assigned to the corresponding integer variable.
String type (string):
- Usage: flag.String(name string, value string, usage string) *string
- Example: name := flag.String("name", "", "name")
- Description: String command-line arguments are used to represent text strings. The string value specified in the command-line will be parsed and assigned to the corresponding string variable.
Floating-point type (float64):
- Usage: flag.Float64(name string, value float64, usage string) *float64
- Example: price := flag.Float64("price", 0.0, "price")
- Description: Floating-point command-line arguments are used to represent floating-point values. The floating-point value specified in the command-line will be parsed and assigned to the corresponding floating-point variable.
Other types:
- Int64, Uint, Uint64: Similar to the integer type, but support larger integer ranges.
- Duration: Used to represent a duration of time, can parse strings containing time units such as "10s", "1h30m".
- IP, IPMask: Used to represent IP addresses and IP subnet masks.
- Var: Used for custom types of command-line arguments, needs to implement the flag.Value interface.

By using these different types of command-line arguments, various types of data requirements can be met, and the flag package provides simple and easy-to-use methods for parsing and handling these command-line arguments.

Here is an example demonstrating the commonly used types of command-line arguments in the flag package:

package main

import (
	"flag"
	"fmt"
)

func main() {
	// Define command-line arguments
	verbose := flag.Bool("verbose", false, "display detailed information")
	count := flag.Int("count", 0, "retry count")
	name := flag.String("name", "", "name")
	price := flag.Float64("price", 0.0, "price")

	// Parse command-line arguments
	flag.Parse()

	// Output parsed command-line arguments
	fmt.Println("Verbose:", *verbose)
	fmt.Println("Count:", *count)
	fmt.Println("Name:", *name)
	fmt.Println("Price:", *price)
}

In the above example, we define four command-line arguments of different types:

verbose is a boolean argument used to represent whether to display detailed information.
count is an integer argument used to represent the retry count.
name is a string argument used to represent a name.
price is a floating-point argument used to represent a price.

By using the flag.Bool, flag.Int, flag.String, and flag.Float64 functions, we define these different types of command-line arguments and specify their names, default values, and help information.

Next, we call the flag.Parse() function to parse the command-line arguments. After parsing, we use pointer dereferencing to access the values of each command-line argument and print them out.

Now we can run the program in the command-line and specify different command-line arguments:

$ go run main.go -verbose -count=3 -name=John -price=9.99
Verbose: true
Count: 3
Name: John
Price: 9.99

By modifying the values of the command-line arguments, you can try different types of arguments and observe the output results.

Var Form#

flag not only supports direct type parsing, but also supports parsing and overriding values directly to parse command-line data, such as BoolVar.

Example

package main

import (
	"flag"
	"fmt"
)

func main() {
	// Define command-line arguments
	var verbose bool
	flag.BoolVar(&verbose, "verbose", false, "display detailed information")

	var count int
	flag.IntVar(&count, "count", 0, "retry count")

	// Parse command-line arguments
	flag.Parse()

	// Output parsed command-line arguments
	fmt.Println("Verbose:", verbose)
	fmt.Println("Count:", count)
}

In the above example, we use the BoolVar and IntVar functions to create boolean and integer command-line arguments.

The BoolVar function is used to create a boolean command-line argument and store the parsed value in the corresponding boolean variable. Its parameters include a pointer to a boolean variable, the name of the command-line argument, the default value of the command-line argument, and a brief description of the argument.

The IntVar function is used to create an integer command-line argument and store the parsed value in the corresponding integer variable. Its parameters include a pointer to an integer variable, the name of the command-line argument, the default value of the command-line argument, and a brief description of the argument.

By calling the flag.Parse() function, we can parse the command-line arguments and assign them to the corresponding variables.

Finally, we output the parsed command-line arguments by directly accessing the variables of the corresponding types.

Now we can run the program in the command-line and specify different command-line arguments:

$ go run main.go -verbose -count=3
Verbose: true
Count: 3

By modifying the values of the command-line arguments, you can try different boolean values and integer values and observe the output results. This will help you better understand and use the BoolVar and IntVar functions in the flag package.

Custom Type Parsing#

flag.TypeVar is a function in the flag package used for command-line arguments of custom types. By implementing the flag.Value interface, we can create our own types and use them in command-line arguments.

flag.Value interface:

type Value interface {
	String() string
	Set(string) error
}

Here is an example demonstrating how to use flag.TypeVar to create command-line arguments of custom types:

package main

import (
	"flag"
	"fmt"
	"strconv"
)

// CustomType is a custom type
type CustomType int

// String returns the string representation of CustomType
func (c CustomType) String() string {
	return strconv.Itoa(int(c))
}

// Set parses the command-line argument and sets the value of CustomType
func (c *CustomType) Set(value string) error {
	// Custom parsing and handling of the custom type can be done here
	// Here we simply convert the command-line argument to an integer and assign it to CustomType
	num, err := strconv.Atoi(value)
	if err != nil {
		return err
	}
	*c = CustomType(num)
	return nil
}

func main() {
	// Define command-line argument
	var custom CustomType
	flag.Var(&custom, "custom", "custom argument")

	// Parse command-line arguments
	flag.Parse()

	// Output parsed command-line argument
	fmt.Println("Custom:", custom)
}

In the above example, we define a custom type called CustomType and implement two methods of the flag.Value interface: String and Set.

The String method returns the string representation of the custom type CustomType, in this case, we convert it to a string of the integer type.

The Set method parses the command-line argument and sets the value of the custom type CustomType. In this example, we convert the command-line argument to an integer and assign it to the CustomType variable.

Next, we use the flag.Var function to register the command-line argument of the custom type. By passing a pointer to a variable that implements the flag.Value interface, we tell the flag package how to parse and handle the command-line argument of that type.

Finally, we call the flag.Parse() function to parse the command-line arguments. After parsing, we can access the value of the custom type variable directly and print it out.

Now we can run the program in the command-line and specify the command-line argument of the custom type:

$ go run main.go -custom=42
Custom: 42

Of course, if you just want to get the command-line arguments, you don't need the flag package, os.Args can solve it:

os.Args is a string slice used to access command-line arguments. It stores all the command-line arguments passed to the program when it is started, including the program name itself.

Here is an example demonstrating how to use os.Args to get and iterate through command-line arguments:

package main

import (
	"fmt"
	"os"
)

func main() {
	// Get command-line arguments
	args := os.Args

	// Iterate through command-line arguments
	for index, arg := range args {
		fmt.Printf("Argument %d: %s\n", index, arg)
	}
}

In the above example, we use os.Args to get all the command-line arguments and store them in the args variable.

Then, we use a range loop to iterate through the args slice and get the index and value of each command-line argument. By using %d and %s placeholders, we print out the index and value of the argument.

Now we can run the program in the command-line and specify different command-line arguments:

$ go run main.go arg1 arg2 arg3
Argument 0: main.go
Argument 1: arg1
Argument 2: arg2
Argument 3: arg3

In the above example, main.go is the name of the program, and arg1, arg2, and arg3 are custom command-line arguments passed by the user. By iterating through the os.Args slice, we can get and process these command-line arguments.

Using os.Args, you can access and handle command-line arguments to perform corresponding logical operations based on the requirements of your program.