在使用 Go 进行开发的过程中,命令行参数解析是我们经常遇到的需求。而 flag 包正是一个用于实现命令行参数解析的 Go 标准库。在本文中,我们将深入探讨 flag 标准库的实现原理和使用技巧,以帮助读者更好地理解和掌握该库的使用方法。
使用
示例
flag 基本使用示例代码如下:
1 | package main |
可以通过指定 --help/-h
参数来查看这个命令行程序的使用帮助:
1 | $ go run main.go -h |
这个程序接收三个命令行参数:
int
类型的-flagvar
,默认值为2134
。int
类型的-n
,默认值为2134
。value
类型的-val
,无默认值。
我们可以将 -flagvar
、-n
、-val
称作 flag
,即「标志」,这也是 Go 内置命令行参数解析库被命名为 flag 的原因,见名知意。
这三个参数在示例代码中,分别使用了三种不同形式来指定:
flag.Type()
:
-n
标志是使用 var nFlag = flag.Int("n", 1234, "help message for flag n")
来指定的。
flag.Int
函数签名如下:
1 | func Int(name string, value int, usage string) *int |
flag.Int
函数接收三个参数,分别是标志名称、标志默认参数值、标志使用帮助信息。函数最终还会返回一个 *int
类型的值,表示用户在执行命令行程序时为这个标志指定的参数。
除了使用 flag.Int
来设置 int
类型标志,flag 还支持其他多种类型,如使用 flag.String
来设置 string
类型标志。
flag.TypeVar()
:
-flagvar
标志是使用 flag.IntVar(&flagvar, "flagvar", 1234, "help message for flagvar")
来指定的。
flag.IntVar
函数签名如下:
1 | func IntVar(p *int, name string, value int, usage string) |
与 flag.Int
不同的是,flag.IntVar
函数取消了返回值,而是会将用户传递的命令行参数绑定到第一个参数 p *int
。
除了使用 flag.IntVar
来绑定 int
类型参数到标志,flag 还提供其他多个函数来支持绑定不同类型参数到标志,如使用 flag.StringVar
来绑定 string
类型标志。
flag.Var()
:
-val
标志是使用 flag.Var(&val, "val", "help message for val")
来指定的。
flag.Var
函数签名如下:
1 | func Var(value Value, name string, usage string) |
flag.Var
函数接收三个参数,后两个参数分别是标志名称、标志使用帮助信息。而用户传递的命令行参数将被绑定到第一个参数 value
。
value
是 flag.Value
类型,而 flag.Value
是一个接口,定义如下:
1 | type Value interface { |
我们可以自定义类型,只要实现了 flag.Value
接口,都可以传递给 flag.Var
,这极大的增加了 flag 包的灵活性。
定义完三个标志,我们还需要使用 flag.Parse()
来解析命令行参数,只有解析成功以后,才会将户传递的命令行参数值绑定到对应的标志变量中。之后就可以使用 nFlag
、flagvar
、val
的变量值了。
在 main
函数底部,使用 flag.NFlag()
、flag.NArg()
、flag.Args()
、flag.Arg(1)
几个函数获取并展示了命令行参数相关信息。
现在我们尝试给这个命令行程序传递几个参数并执行它,看下输出结果:
1 | $ go run main.go -n 100 -val test a b c d |
我们通过 -n 100
为 -n
标志指定了参数值 100
,最终会被赋值给 nFlag
变量。
由于没有指定 flagvar
标志的参数值,所以 flagvar
变量会被赋予默认值 1234
。
接着,我们又通过 -val test
为 -val
标志指定了参数值 test
,最终赋值给了自定义的 flagVal
结构体的 val
字段。
因为只设置了 -n
和 -val
两个标志的参数值,所以函数 flag.NFlag()
返回结果为 2。
a b c d
四个参数由于没有被定义,所以 flag.NArg()
返回结果为 4。
flag.Args()
返回的切片中存储了 a b c d
四个参数。
flag.Arg(1)
返回切片中下标为 1
位置的参数,即 b
。
标志类型
在上面的示例中,我们展示了 int
类型和自定义的 flag.Value
的使用,flag 包支持的所有标志类型汇总如下:
参数类型 | 合法值 |
---|---|
bool | strconv.ParseBool 能够解析的有效值,接受:1, 0, t, f, T, F, true, false, TRUE, FALSE, True, False。 |
time.Duration | time.ParseDuration 能够解析的有效值,如:”300ms”, “-1.5h” or “2h45m”,合法单位:”ns”, “us” (or “µs”), “ms”, “s”, “m”, “h”。 |
float64 | 合法的浮点数类型。 |
int/int64/uint/uint64 | 合法的整数类型,如:1234, 0664, 0x1234,也可以是负数。 |
string | 合法的字符串类型。 |
flag.Value | 实现了该接口的类型。 |
除了支持几种 Go 默认的原生类型外,如果我们想实现其他类型标志的定义,都可以通过 flag.Value
接口类型来完成。其实 flag 包内部对于 bool
、int
等所有类型的定义,都实现了 flag.Value
接口,在稍后讲解源码过程中将会有所体现。
标志语法
命令行标志支持多种语法:
语法 |
说明 |
---|---|
-flag | bool 类型标志可以使用,表示参数值为 true。 |
–flag | 支持两个 - 字符,与 -flag 等价。 |
-flag=x | 所有类型通用,为标志 flag 传递参数值 x。 |
-flag x | 作用等价于 -flag=x,但是仅限非 bool 类型标志使用,假如这样使用 cmd -x * ,其中 * 是 Unix shell 通配符,如果存在名为 0、false 等文件,则参数值结果会发生变化。 |
flag 解析参数时会在第一个非标志参数之前(单独的一个 -
字符也是非标志参数)或终止符 --
之后停止。
源码解读
注意:本文以 Go 1.19.4 源码为例,其他版本可能存在差异。
熟悉了 flag 包的基本使用,接下来我们就要深入到 flag 的源码,来探究其内部是如何实现。
阅读 flag 包的源码,我们可以从使用 flag 包的流程来入手。
定义标志
在 main
函数中,我们首先通过如下代码定义了一个标志 -n
。
1 | var nFlag = flag.Int("n", 1234, "help message for flag n") |
flag.Int
函数定义如下:
1 | func Int(name string, value int, usage string) *int { |
可以发现,flag.Int
函数调用并返回了 CommandLine
对象的 Int
方法,并将参数原样传递进去。
来看看 CommandLine
是个什么:
1 | var CommandLine = NewFlagSet(os.Args[0], ExitOnError) |
CommandLine
是使用 NewFlagSet
创建的 FlagSet
结构体指针,在构造 FlagSet
对象时,需要两个参数 os.Args[0]
和 ExitOnError
。
我们知道 os.Args
存储了程序执行时指定的所有命令行参数,os.Args[0]
就是当前命令行程序的名称,ExitOnError
是一个常量,用来标记在出现 error
时应该如何做,ExitOnError
表示在遇到 error
时退出程序。
来看下 FlagSet
是如何定义:
1 | type FlagSet struct { |
Usage
字段是一个函数,根据名字大概能够猜测出,这个函数会在指定 --help/-h
参数查看命令行程序使用帮助时被调用。
parsed
用来标记是否调用过 flag.Parse()
。
actual
和 formal
分别用来存储从命令行解析的标志参数和在程序中指定的默认标志参数。它们都使用 map
来存储 Flag
类型的指针,FlagSet
可以看作是 Flag
结构体的「集合」。
args
用来保存处理完标志后剩余的参数列表。
errorHandling
标记在出现 error
时应该如何做。
output
用来设置输出位置,这可以改变 --help/-h
时展示帮助信息的输出位置。
现在来看下 Flag
的定义:
1 | type Flag struct { |
Flag
用来记录一个命令行参数,里面存储了一个标志所有信息。
可以说 Flag
和 FlagSet
两个结构体就是 flag 包的核心,所有功能都是围绕这两个结构体设计的。
标志所对应的命令行参数值为 flag.Value
接口类型,在前文中已经见过了,定义如下:
1 | type Value interface { |
之所以使用接口,是为了能够存储任何类型的值,除了 flag 包默认支持的内置类型,用户也可以定义自己的类型,只要实现了 Value
接口即可。
如我们在前文示例程序中定义的 flagVal
类型。
现在 CommandLine
的定义以及内部实现我们都看过了,是时候回过头来看一看 CommandLine
对象的 Int
方法了:
1 | func (f *FlagSet) Int(name string, value int, usage string) *int { |
Int
方法内部调用了 f.IntVar()
方法,定义如下:
1 | func (f *FlagSet) IntVar(p *int, name string, value int, usage string) { |
IntVar
方法又调用了 f.Var()
方法。
Var
方法第一个参数为 newIntValue(value, p)
,我们来看看 newIntValue
函数是如何定义的:
1 | type intValue int |
newIntValue
是一个构造函数,用来创建一个 intValue
类型的指针,intValue
底层类型实际上是 int
。
定义 intValue
类型的目的就是为了实现 flag.Value
接口。
再来看下 Var
方法如何定义:
1 | func (f *FlagSet) Var(value Value, name string, usage string) { |
name
参数即为标志名,在 Var
方法内部,首先对标志名的合法性进行了校验,不能以 -
开头且不包含 =
。
接着,根据参数创建了一个 Flag
类型,并且校验了标志是否被重复定义。
最后将 Flag
保存在 formal
属性中。
到这里,整个函数调用关系就结束了,我们来梳理一下代码执行流程:
flag.Int
-> CommandLine.Int
-> CommandLine.IntVar
-> CommandLine.Var
。
经过这个调用过程,我们就得到了一个 Flag
对象,其名称为 n
、默认参数值为 1234
、值的类型为 intValue
、帮助信息为 help message for flag n
。并将这个 Flag
对象保存在了 CommandLine
这个类型为 FlagSet
的结构体指针对象的 formal
属性中。
我们在示例程序中还使用了另外两种方式定义标志。
使用 flag.IntVar(&flagvar, "flagvar", 1234, "help message for flagvar")
定义标志 -flagvar
。
flag.IntVar
定义如下:
1 | func IntVar(p *int, name string, value int, usage string) { |
可以发现,flag.IntVar
函数内部没有调用 CommandLine.Int
和 CommandLine.IntVar
的过程,而是直接调用 CommandLine.Var
。
另外,我们还使用 flag.Var(&val, "val", "help message for val")
定义了 -val
标志。
flag.Var
定义如下:
1 | func Var(value Value, name string, usage string) { |
flag.Var
函数内部同样直接调用了 CommandLine.Var
,并且由于参数 value
已经是 Value
接口类型,可以无需调用 newIntValue
这类构造函数将 Go 内置类型转为 Value
类型,直接传递参数即可。
解析标志参数
命令行参数定义完成了,终于到了解析部分,可以使用 flag.Parse()
解析命令行参数。
flag.Parse
函数代码如下:
1 | func Parse() { |
内部同样是调用 CommandLine
对象对应的方法,并且将除程序名称以外的命令行参数都传递到 Parse
方法中,Parse
方法定义如下:
1 | func (f *FlagSet) Parse(arguments []string) error { |
首先将 f.parsed
标记为 true
,在调用 f.Parsed()
方法时会被返回:
1 | func (f *FlagSet) Parsed() bool { |
接着又将 arguments
保存在 f.args
属性中。
然后就是循环解析命令行参数的过程,每调用一次 f.parseOne()
解析一个标志,直到解析完成或遇到 error
退出程序。
parseOne
方法实现如下:
1 | func (f *FlagSet) parseOne() (bool, error) { |
parseOne
代码稍微多一点,不过整体脉络还是比较清晰的。
首先对 f.args
参数进行了校验,接着提取标志前导符号 -
的个数放到 numMinuses
变量中,然后取出标志名并对标志语法做了检查。
接下来取出参数 value
,并且判断标志名是否为 -help/-h
,如果是则说明用户只想打印程序使用帮助信息,打印后 parseOne
会返回 ErrHelp
,上层的调用者 f.Parse
就会捕获到 ErrHelp
,然后调用 os.Exit(0)
直接退出程序。
其中 f.usage()
实现了打印帮助信息的功能,内部具体实现这里就不讲解了,因为基本上是内容排版的实现,不是核心功能,感兴趣可以自己尝试看一看。
最后就是根据参数值是否为 bool
类型分别进行参数绑定,将参数设置到对应的标志变量中,并将标志保存到 f.actual
中。
以上步骤都执行完成后,在执行 fmt.Printf("nFlag: %d\n", *nFlag)
时,就能够获取到 nFlag
被赋予的参数值了。
至此,flag 包源码的整体脉络都已经清晰了。
其他代码
在我们的示例代码最后,还打印了 NFlag()
、NArg()
、Args()
、Arg(1)
几个函数的结果。
这几个函数实现非常简单,代码如下:
1 | func NFlag() int { return len(CommandLine.actual) } |
由于代码过于简单,我就不进行解释了,相信通过上面的讲解,这几个函数的作用你也能做到一目了然。
flag 包还有一些其他类型,如 stringValue
、float64Value
,这些类型实现思路都是一样的,也不再一一讲解。
最后,flag 包其他附属的函数实现,不是主要脉络,留给读者自行查看学习。
总结
在开发命令行程序时,Go 标准库中的 flag 包是一个不错的选择。
本文先对 flag 包的基本使用进行了演示,接着又对源码进行了深度剖析。
flag 包支持三种方式定义标志,flag.Parse()
能够对命令行参数进行解析,解析成功后,就可以在代码中使用参数值了。
希望本文能对读者有所帮助。
参考
Go flag 源码:https://github.com/golang/go/tree/go1.19.4/src/flag
Go flag 文档:https://pkg.go.dev/flag