golang flag包使用笔记 - Golang教程网

在写命令行程序（工具、server）时，对命令参数进行解析是常见的需求。各种语言一般都会提供解析命令行参数的方法或库，以方便程序员使用。如果命令行参数纯粹自己写代码来解析，对于比较复杂的，还是挺费劲的。在 go 标准库中提供了一个包：flag，方便进行命令行解析。

flag

1.1 使用示例：

nginxnginx -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

nginx -h

package mainimport (    "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 有两种方式

var ip = flag.Int("flagname", 1234, "help message for flagname")

第一个参数：flag名称为flagname
第二个参数：flagname默认值为1234
第三个参数：flagname的提示信息

fmt.Println(*ip)

2）flag.XxxVar()，将 flag 绑定到一个变量上，如：

var flagValue intflag.IntVar(&flagValue, "flagname", 1234, "help message for flagname")

fmt.Println(ip)

1.2.2 自定义 Value

receiver

flag.Var(&flagVal, "name", "help message for flagname")

例如，解析我喜欢的编程语言，我们希望直接解析到 slice 中，我们可以定义如下 sliceValue类型，然后实现Value接口：

package mainimport (    "flag"
    "fmt"
    "strings")//定义一个类型，用于增加该类型方法type sliceValue []string//new一个存放命令行参数值的slicefunc 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]

DurationValue

1.2.3 解析 flag

flag.Parse()

命令行 flag 的语法有如下三种形式：

-flag // 只支持bool类型-flag=x
-flag x // 只支持非bool类型

-flag-flagflag.Bool/BoolVar-flag=false

int 类型可以是十进制、十六进制、八进制甚至是负数；bool 类型可以是1, 0, t, f, true, false, TRUE, FALSE, True, False。Duration 可以接受任何 time.ParseDuration 能解析的类型。

-flag false

1.3 类型和函数

在看类型和函数之前，先看一下变量。

ErrHelp：该错误类型用于当命令行指定了 ·-help` 参数但没有定义时。

-help-h

Usage of myflag.exe:
  -slice languages
        I like programming languages

flag.Usage = func(){}

-help-h

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.Lookup("c")

&Flag{    Name: c,
    Usage: set configuration file,
    Value: /etc/nginx.conf,
    DefValue: conf/nginx.conf,
}

Lookup函数：获取flag集合中名称为name值的flag指针，如果对应的flag不存在，返回nil
示例：

package mainimport (    "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:<nil>test:12345
test1:<nil>

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()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.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 参数定义后而具体参数值被访问前调用。

-helpErrHelp

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

parseOnenon-flag

Flag parsing stops just before the first non-flag argument ("-" is a non-flag argument) or after the terminator "--".

我们需要了解解析什么时候停止。

false, nilfalse, nil

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

-cnon-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 --

-flag=x-flag-flag x

另外，在 parseOne 中有这么一句：

f.args = f.args[1:]

non-flag

1.4.4 Arg(i int) 和 Args()、NArg()、NFlag()

non-flagnon-flag

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 这两个强大的库。