golang flag

本文原文地址：flag - 命令行參數解析

在寫命令行程序（工具、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:<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() 用於實例化 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 這兩個強大的庫。