flag - 命令行参数解析（go中的gflags）
copy from https://books.studygolang.com/The-Golang-Standard-Library-by-Example/chapter13/13.1.html
在写命令行程序（工具、server）时，对命令参数进行解析是常见的需求。各种语言一般都会提供解析命令行参数的方法或库，以方便程序员使用。如果命令行参数纯粹自己写代码来解析，对于比较复杂的，还是挺费劲的。在 go 标准库中提供了一个包：flag，方便进行命令行解析。
首先，我们看flag包可以做什么，它具有什么样的能力。
1.1 使用示例：
- 我们以
nginx为例，执行nginx -h，输出如下：
nginx version: nginx/1.10.0
Usage: nginx [-?hvVtTq] [-s signal] [-c filename] [-p prefix] [-g directives]
Options:
-?,-h : this help
-v : show version and exit
-V : show version and configure options then exit
-t : test configuration and exit
-T : test configuration, dump it and exit
-q : suppress non-error messages during configuration testing
-s signal : send signal to a master process: stop, quit, reopen, reload
-p prefix : set prefix path (default: /usr/local/nginx/)
-c filename : set configuration file (default: conf/nginx.conf)
-g directives : set global directives out of configuration file
后续我们会利用flag包实现一个并发测试接口的程序。
现在我们来利用flag包简单实现一下nginx -h这个功能：
package main
import (
"flag"
"fmt"
"os"
)
// 实际中应该用更好的变量名
var (
h bool
v, V bool
t, T bool
q *bool
s string
p string
c string
g string
)
func init() {
flag.BoolVar(&h, "h", false, "this help")
flag.BoolVar(&v, "v", false, "show version and exit")
flag.BoolVar(&V, "V", false, "show version and configure options then exit")
flag.BoolVar(&t, "t", false, "test configuration and exit")
flag.BoolVar(&T, "T", false, "test configuration, dump it and exit")
// 另一种绑定方式
q = flag.Bool("q", false, "suppress non-error messages during configuration testing")
// 注意 `signal`。默认是 -s string，有了 `signal` 之后，变为 -s signal
flag.StringVar(&s, "s", "", "send `signal` to a master process: stop, quit, reopen, reload")
flag.StringVar(&p, "p", "/usr/local/nginx/", "set `prefix` path")
flag.StringVar(&c, "c", "conf/nginx.conf", "set configuration `file`")
flag.StringVar(&g, "g", "conf/nginx.conf", "set global `directives` out of configuration file")
// 改变默认的 Usage，flag包中的Usage 其实是一个函数类型。这里是覆盖默认函数实现，具体见后面Usage部分的分析
flag.Usage = usage
}
func main() {
flag.Parse()
if h {
flag.Usage()
}
}
func usage() {
fmt.Fprintf(os.Stderr, `nginx version: nginx/1.10.0
Usage: nginx [-hvVtTq] [-s signal] [-c filename] [-p prefix] [-g directives]
Options:
`)
flag.PrintDefaults()
}
nginx功能用go实现结果
看不懂以上的代码实现没关系，先明确flag的能力，看完下面的讲解回过头来看就可以看懂了。
1.2 flag 包概述
flag 包实现了命令行参数的解析。
1.2.1 定义 flags 有两种方式
1）flag.Xxx()，其中 Xxx 可以是 Int、String，Bool 等；返回一个相应类型的指针，如：var ip = flag.Int("flagname", 1234, "help message for flagname")
- 第一个参数 ：flag名称为flagname
- 第二个参数 ：flagname默认值为1234
- 第三个参数 ：flagname的提示信息
返回的ip是指针类型，所以这种方式获取ip的值应该fmt.Println(*ip)
2）flag.XxxVar()，将 flag 绑定到一个变量上，如：
var flagValue int
flag.IntVar(&flagValue, "flagname", 1234, "help message for flagname")
- 第一个参数 ：接收flagname的实际值的
- 第二个参数 ：flag名称为flagname
- 第三个参数 ：flagname默认值为1234
- 第四个参数 ：flagname的提示信息
这种方式获取ip的值fmt.Println(ip)就可以了：
1.2.2 自定义 Value
另外，还可以创建自定义 flag，只要实现 flag.Value 接口即可（要求 receiver是指针），这时候可以通过如下方式定义该 flag：
flag.Var(&flagVal, "name", "help message for flagname")
例如，解析我喜欢的编程语言，我们希望直接解析到 slice 中，我们可以定义如下 sliceValue类型，然后实现Value接口：
package main
import (
"flag"
"fmt"
"strings"
)
//定义一个类型，用于增加该类型方法
type sliceValue []string
//new一个存放命令行参数值的slice
func newSliceValue(vals []string, p *[]string) *sliceValue {
*p = vals
return (*sliceValue)(p)
}
/*
Value接口：
type Value interface {
String() string
Set(string) error
}
实现flag包中的Value接口，将命令行接收到的值用,分隔存到slice里
*/
func (s *sliceValue) Set(val string) error {
*s = sliceValue(strings.Split(val, ","))
return nil
}
//flag为slice的默认值default is me,和return返回值没有关系
func (s *sliceValue) String() string {
*s = sliceValue(strings.Split("default is me", ","))
return "It's none of my business"
}
/*
可执行文件名 -slice="java,go" 最后将输出[java,go]
可执行文件名 最后将输出[default is me]
*/
func main(){
var languages []string
flag.Var(newSliceValue([]string{}, &languages), "slice", "I like programming `languages`")
flag.Parse()
//打印结果slice接收到的值
fmt.Println(languages)
}
这样通过 -slice "go,php"这样的形式传递参数，languages得到的就是 [go, php]。如果不加-slice参数则打印默认值[default is me]
flag 中对 Duration这种非基本类型的支持，使用的就是类似这样的方式，即同样实现了Value接口。
1.2.3 解析 flag
在所有的 flag 定义完成之后，可以通过调用 flag.Parse()进行解析。
命令行 flag 的语法有如下三种形式：
-flag // 只支持bool类型
-flag=x
-flag x // 只支持非bool类型
以上语法对于一个或两个‘－’号，效果是一样的，但是要注意对于第三种情况，只能用于非 bool 类型的 flag。原因是：如果支持，那么对于这样的命令 cmd -x *，如果有一个文件名字是：0或false等，则命令的原意会改变（bool 类型可以和其他类型一样处理，其次 bool 类型支持 -flag这种形式，因为Parse()中，对 bool 类型进行了特殊处理）。默认的，提供了 -flag，则对应的值为 true，否则为 flag.Bool/BoolVar中指定的默认值；如果希望显示设置为 false 则使用 -flag=false。
int 类型可以是十进制、十六进制、八进制甚至是负数；bool 类型可以是1, 0, t, f, true, false, TRUE, FALSE, True, False。Duration 可以接受任何 time.ParseDuration 能解析的类型。
- 注：如果bool类型的参数在命令行中用了
-flag false这种形式时，其后的参数都会被当做非flag（non-flag）参数，non-flag 参数后面解释。
1.3 类型和函数
在看类型和函数之前，先看一下变量。
ErrHelp：该错误类型用于当命令行指定了 ·-help` 参数但没有定义时。
例如1.2.2例子中：如果执行时用了-help或者-h时就会输出help message：
Usage of myflag.exe:
-slice languages
I like programming languages
Usage：这是一个函数，用于输出所有定义了的命令行参数和帮助信息（usage message）。一般，当命令行参数解析出错时，该函数会被调用。我们可以指定自己的 Usage 函数，即：flag.Usage = func(){}
例如1.1示例中：如果执行时用了-help时就会输出和-h一样的usage message。
1.3.1 函数
go标准库中，经常这么做：
定义了一个类型，提供了很多方法；为了方便使用，会实例化一个该类型的实例（通用），这样便可以直接使用该实例调用方法。比如：encoding/base64 中提供了 StdEncoding 和 URLEncoding 实例，使用时：base64.StdEncoding.Encode()
在 flag 包使用了有类似的方法，比如 CommandLine 变量，只不过 flag 进行了进一步封装：将 FlagSet 的方法都重新定义了一遍，也就是提供了一系列函数，而函数中只是简单的调用已经实例化好了的 FlagSet 实例：CommandLine 的方法。这样，使用者是这么调用：flag.Parse() 而不是 flag. CommandLine.Parse()。（Go 1.2 起，将 CommandLine 导出，之前是非导出的）
这里不详细介绍各个函数，其他函数介绍可以参考astaxie的gopkg——flag章节。
1.3.2 类型（数据结构）
1）ErrorHandling
type ErrorHandling int
该类型定义了在参数解析出错时错误处理方式。定义了三个该类型的常量：
const (
ContinueOnError ErrorHandling = iota
ExitOnError
PanicOnError
)
三个常量在源码的 FlagSet 的方法 parseOne() 中使用了。
2）Flag
// A Flag represents the state of a flag.
type Flag struct {
Name string // name as it appears on command line
Usage string // help message
Value Value // value as set
DefValue string // default value (as text); for usage message
}
Flag 类型代表一个 flag 的状态。
比如，对于命令：./nginx -c /etc/nginx.conf，相应代码是：
flag.StringVar(&c, "c", "conf/nginx.conf", "set configuration `file`")
则该 Flag 实例（可以通过 flag.Lookup("c")获得）相应各个字段的值为：
&Flag{
Name: c,
Usage: set configuration file,
Value: /etc/nginx.conf,
DefValue: conf/nginx.conf,
}
Lookup函数：获取flag集合中名称为name值的flag指针，如果对应的flag不存在，返回nil
示例：
package main
import (
"flag"
"fmt"
)
//定义一个全局变量的命令行接收参数
var testFlag = flag.String("test", "default value", "help message.")
//打印值的函数
func print(f *flag.Flag) {
if f != nil {
fmt.Println(f.Value)
} else {
fmt.Println(nil)
}
}
func main() {
//没有用flag.Parse()解析前
fmt.Print("test:")
print(flag.Lookup("test"))
fmt.Print("test1:")
print(flag.Lookup("test1"))
//用flag.Parse()解析后
flag.Parse()
fmt.Print("test:")
print(flag.Lookup("test"))
fmt.Print("test1:")
print(flag.Lookup("test1"))
}
运行结果：
// ./testlookup -test "12345"
test:default value
test1:
test:12345
test1:
3）FlagSet
// A FlagSet represents a set of defined flags.
type FlagSet struct {
// Usage is the function called when an error occurs while parsing flags.
// The field is a function (not a method) that may be changed to point to
// a custom error handler.
Usage func()
name string // FlagSet的名字。CommandLine 给的是 os.Args[0]
parsed bool // 是否执行过Parse()
actual map[string]*Flag // 存放实际传递了的参数（即命令行参数）
formal map[string]*Flag // 存放所有已定义命令行参数
args []string // arguments after flags // 开始存放所有参数，最后保留 非flag（non-flag）参数
exitOnError bool // does the program exit if there's an error?
errorHandling ErrorHandling // 当解析出错时，处理错误的方式
output io.Writer // nil means stderr; use out() accessor
}
4）Value 接口
// Value is the interface to the dynamic value stored in a flag.
// (The default value is represented as a string.)
type Value interface {
String() string
Set(string) error
}
所有参数类型需要实现 Value 接口，flag 包中，为int、float、bool等实现了该接口。借助该接口，我们可以自定义flag。（上文已经给了具体的例子）
1.4 主要类型的方法（包括类型实例化）
flag 包中主要是 FlagSet 类型。
1.4.1 实例化方式
NewFlagSet()用于实例化 FlagSet。预定义的 FlagSet 实例 CommandLine的定义方式：
// The default set of command-line flags, parsed from os.Args.
var CommandLine = NewFlagSet(os.Args[0], ExitOnError)
可见，默认的 FlagSet 实例在解析出错时会退出程序。
由于 FlagSet 中的字段没有 export，其他方式获得 FlagSet实例后，比如：FlagSet{} 或 new(FlagSet)，应该调用Init() 方法，以初始化 name 和 errorHandling，否则 name 为空，errorHandling 为 ContinueOnError（errorHandling默认为0）。
1.4.2 定义 flag 参数的方法
这一系列的方法都有两种形式，在一开始已经说了两种方式的区别。这些方法用于定义某一类型的 flag 参数。
1.4.3 解析参数（Parse）
func (f *FlagSet) Parse(arguments []string) error
从参数列表中解析定义的 flag。方法参数 arguments 不包括命令名，即应该是os.Args[1:]。事实上，flag.Parse()函数就是这么做的：
// Parse parses the command-line flags from os.Args[1:]. Must be called
// after all flags are defined and before flags are accessed by the program.
func Parse() {
// Ignore errors; CommandLine is set for ExitOnError.
CommandLine.Parse(os.Args[1:])
}
该方法应该在 flag 参数定义后而具体参数值被访问前调用。
如果提供了 -help参数（命令中给了）但没有定义（代码中没有），该方法返回 ErrHelp错误。默认的 CommandLine，在 Parse 出错时会退出程序（ExitOnError）。
为了更深入的理解，我们看一下 Parse(arguments []string)的源码：
func (f *FlagSet) Parse(arguments []string) error {
f.parsed = true
f.args = arguments
for {
seen, err := f.parseOne()
if seen {
continue
}
if err == nil {
break
}
switch f.errorHandling {
case ContinueOnError:
return err
case ExitOnError:
os.Exit(2)
case PanicOnError:
panic(err)
}
}
return nil
}
真正解析参数的方法是非导出方法 parseOne。
结合 parseOne方法，我们来解释 non-flag以及包文档中的这句话：
Flag parsing stops just before the first non-flag argument ("-" is a non-flag argument) or after the terminator "--".
我们需要了解解析什么时候停止。
根据 Parse() 中 for 循环终止的条件（不考虑解析出错），我们知道，当 parseOne 返回 false, nil时，Parse 解析终止。正常解析完成我们不考虑。看一下 parseOne 的源码发现，有三处会返回 false, nil。
在这里先说一下non-flag命令行参数是指不满足命令行语法的参数，如命令行参数为cmd -flag=true abc则第一个非flag命令行参数为“abc”
1）参数列表长度为0
if len(f.args) == 0 {
return false, nil
}
2）第一个 non-flag 参数
s := f.args[0]
if len(s) == 0 || s[0] != '-' || len(s) == 1 {
return false, nil
}
也就是，当遇到单独的一个"-"或不是"-"开始时，会停止解析。比如：
./nginx - 或 ./nginx ba或者./nginx
这两种情况，-c都不会被正确解析。像该例子中的"-"或ba（以及之后的参数），我们称之为 non-flag参数。
3）两个连续的"--"
if s[1] == '-' {
num_minuses++
if len(s) == 2 { // "--" terminates the flags
f.args = f.args[1:]
return false, nil
}
}
也就是，当遇到连续的两个"-"时，解析停止。如：
./nginx --
*下面这种情况是可以正常解析的：
./nginx -c --
这里的"--"会被当成是 c的值
parseOne 方法中接下来是处理 -flag=x这种形式，然后是 -flag这种形式（bool类型）（这里对bool进行了特殊处理），接着是 -flag x这种形式，最后，将解析成功的 Flag 实例存入 FlagSet 的 actual map 中。
另外，在 parseOne 中有这么一句：
f.args = f.args[1:]
也就是说，每执行成功一次 parseOne，f.args 会少一个。所以，FlagSet 中的 args 最后留下来的就是所有 non-flag参数。
1.4.4 Arg(i int) 和 Args()、NArg()、NFlag()
Arg(i int) 和 Args() 这两个方法就是获取 non-flag参数的；NArg()获得 non-flag的个数；NFlag() 获得 FlagSet 中 actual 长度（即被设置了的参数个数）。
1.4.5 Visit/VisitAll
这两个函数分别用于访问 FlatSet 的 actual（存放参数值实际Flag的map） 和 formal（存放参数名默认Flag的map） 中的 Flag，而具体的访问方式由调用者决定。
具体使用demo见:
func (f FlagSet) Visit(fn func(Flag))
func (f FlagSet) VisitAll(fn func(Flag))
1.4.6 PrintDefaults()
打印所有已定义参数的默认值（调用 VisitAll 实现），默认输出到标准错误，除非指定了 FlagSet 的 output（通过SetOutput() 设置）。
在1.1示例中有使用。还可以参考:
func PrintDefaults()
1.4.7 Set(name, value string)
将名称为name的flag的值设置为value, 成功返回nil。
demo请见：
func Set(name, value string) error
1.5 总结
使用建议：虽然上面讲了那么多，一般来说，我们只简单的定义flag，然后 parse，就如同开始的例子一样。
如果项目需要复杂或更高级的命令行解析方式，可以使用 https://github.com/urfave/cli或者 https://github.com/spf13/cobra这两个强大的库。
作者：我的小碗汤
链接：https://www.jianshu.com/p/f9cf46a4de0e
来源：简书
简书著作权归作者所有，任何形式的转载都请联系作者获得授权并注明出处。