...

Package flag

import "flag"
概览
索引
示例

概览 ▾

flag 包实现命令行标签解析.

使用:

定义标签需要使用flag.String(),Bool(),Int()等方法。

下面的代码定义了一个interger标签,标签名是flagname,标签解析的结果存放在ip指针(*int)指向的值中

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

你还可以选择使用Var()函数将标签绑定到指定变量中

var flagvar int
func init() {
	flag.IntVar(&flagvar, "flagname", 1234, "help message for flagname")
}

你也可以传入自定义类型的标签,只要标签满足对应的值接口(接收指针指向的接收者)。像下面代码一样定义标签

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

这样的标签,默认值就是自定义类型的初始值。

所有的标签都定义好了,就可以调用

flag.Parse()

来解析命令行参数并传入到定义好的标签了。

标签可以被用来直接使用。如果你直接使用标签(没有绑定变量),那他们都是指针类型。如果你将他们绑定到变量上,他们就是值类型。

fmt.Println("ip has value ", *ip)
fmt.Println("flagvar has value ", flagvar)

在解析之后,标签对应的参数可以从flag.Args()获取到,它返回的slice,也可以使用flag.Arg(i)来获取单个参数。 参数列的索引是从0到flag.NArg()-1。

命令行标签格式:

-flag
-flag=x
-flag x  // 只有非boolean标签能这么用

减号可以使用一个或者两个,效果是一样的。 上面最后一种方式不能被boolean类型的标签使用。因为当有个文件的名字是0或者false这样的词的话,下面的命令

cmd -x *

的原意会被改变。你必须使用-flag=false的方式来解析boolean标签。

一个标签的解析会在下次出现第一个非标签参数(“-”就是一个非标签参数)的时候停止,或者是在终止符号“--”的时候停止。

Interger标签接受如1234,0664,0x1234和负数这样的值。 Boolean标签接受1,0,t,f,true,false,TRUE,FALSE,True,False。 Duration标签接受任何可被time.ParseDuration解析的值。

默认的命令行标签是由最高层的函数来控制的。FlagSet类型允许每个包定义独立的标签集合,例如在命令行接口中实现子命令。 FlagSet的方法就是模拟使用最高层函数来控制命令行标签集的行为的。

示例

代码:

// These examples demonstrate more intricate uses of the flag package.
package flag_test

import (
    "errors"
    "flag"
    "fmt"
    "strings"
    "time"
)

// Example 1: A single string flag called "species" with default value "gopher".
var species = flag.String("species", "gopher", "the species we are studying")

// Example 2: Two flags sharing a variable, so we can have a shorthand.
// The order of initialization is undefined, so make sure both use the
// same default value. They must be set up with an init function.
var gopherType string

func init() {
    const (
        defaultGopher = "pocket"
        usage         = "the variety of gopher"
    )
    flag.StringVar(&gopherType, "gopher_type", defaultGopher, usage)
    flag.StringVar(&gopherType, "g", defaultGopher, usage+" (shorthand)")
}

// Example 3: A user-defined flag type, a slice of durations.
type interval []time.Duration

// String is the method to format the flag's value, part of the flag.Value interface.
// The String method's output will be used in diagnostics.
func (i *interval) String() string {
    return fmt.Sprint(*i)
}

// Set is the method to set the flag value, part of the flag.Value interface.
// Set's argument is a string to be parsed to set the flag.
// It's a comma-separated list, so we split it.
func (i *interval) Set(value string) error {
    // If we wanted to allow the flag to be set multiple times,
    // accumulating values, we would delete this if statement.
    // That would permit usages such as
    //	-deltaT 10s -deltaT 15s
    // and other combinations.
    if len(*i) > 0 {
        return errors.New("interval flag already set")
    }
    for _, dt := range strings.Split(value, ",") {
        duration, err := time.ParseDuration(dt)
        if err != nil {
            return err
        }
        *i = append(*i, duration)
    }
    return nil
}

// Define a flag to accumulate durations. Because it has a special type,
// we need to use the Var function and therefore create the flag during
// init.

var intervalFlag interval

func init() {
    // Tie the command-line flag to the intervalFlag variable and
    // set a usage message.
    flag.Var(&intervalFlag, "deltaT", "comma-separated list of intervals to use between events")
}

func Example() {
    // All the interesting pieces are with the variables declared above, but
    // to enable the flag package to see the flags defined there, one must
    // execute, typically at the start of main (not init!):
    //	flag.Parse()
    // We don't run it here because this is not a main function and
    // the testing suite has already parsed the flags.
}

索引 ▾

变量
func Arg(i int) string
func Args() []string
func Bool(name string, value bool, usage string) *bool
func BoolVar(p *bool, name string, value bool, usage string)
func Duration(name string, value time.Duration, usage string) *time.Duration
func DurationVar(p *time.Duration, name string, value time.Duration, usage string)
func Float64(name string, value float64, usage string) *float64
func Float64Var(p *float64, name string, value float64, usage string)
func Int(name string, value int, usage string) *int
func Int64(name string, value int64, usage string) *int64
func Int64Var(p *int64, name string, value int64, usage string)
func IntVar(p *int, name string, value int, usage string)
func NArg() int
func NFlag() int
func Parse()
func Parsed() bool
func PrintDefaults()
func Set(name, value string) error
func String(name string, value string, usage string) *string
func StringVar(p *string, name string, value string, usage string)
func Uint(name string, value uint, usage string) *uint
func Uint64(name string, value uint64, usage string) *uint64
func Uint64Var(p *uint64, name string, value uint64, usage string)
func UintVar(p *uint, name string, value uint, usage string)
func UnquoteUsage(flag *Flag) (name string, usage string)
func Var(value Value, name string, usage string)
func Visit(fn func(*Flag))
func VisitAll(fn func(*Flag))
type ErrorHandling
type Flag
    func Lookup(name string) *Flag
type FlagSet
    func NewFlagSet(name string, errorHandling ErrorHandling) *FlagSet
    func (f *FlagSet) Arg(i int) string
    func (f *FlagSet) Args() []string
    func (f *FlagSet) Bool(name string, value bool, usage string) *bool
    func (f *FlagSet) BoolVar(p *bool, name string, value bool, usage string)
    func (f *FlagSet) Duration(name string, value time.Duration, usage string) *time.Duration
    func (f *FlagSet) DurationVar(p *time.Duration, name string, value time.Duration, usage string)
    func (f *FlagSet) Float64(name string, value float64, usage string) *float64
    func (f *FlagSet) Float64Var(p *float64, name string, value float64, usage string)
    func (f *FlagSet) Init(name string, errorHandling ErrorHandling)
    func (f *FlagSet) Int(name string, value int, usage string) *int
    func (f *FlagSet) Int64(name string, value int64, usage string) *int64
    func (f *FlagSet) Int64Var(p *int64, name string, value int64, usage string)
    func (f *FlagSet) IntVar(p *int, name string, value int, usage string)
    func (f *FlagSet) Lookup(name string) *Flag
    func (f *FlagSet) NArg() int
    func (f *FlagSet) NFlag() int
    func (f *FlagSet) Parse(arguments []string) error
    func (f *FlagSet) Parsed() bool
    func (f *FlagSet) PrintDefaults()
    func (f *FlagSet) Set(name, value string) error
    func (f *FlagSet) SetOutput(output io.Writer)
    func (f *FlagSet) String(name string, value string, usage string) *string
    func (f *FlagSet) StringVar(p *string, name string, value string, usage string)
    func (f *FlagSet) Uint(name string, value uint, usage string) *uint
    func (f *FlagSet) Uint64(name string, value uint64, usage string) *uint64
    func (f *FlagSet) Uint64Var(p *uint64, name string, value uint64, usage string)
    func (f *FlagSet) UintVar(p *uint, name string, value uint, usage string)
    func (f *FlagSet) Var(value Value, name string, usage string)
    func (f *FlagSet) Visit(fn func(*Flag))
    func (f *FlagSet) VisitAll(fn func(*Flag))
type Getter
type Value

示例

Package

包文件

flag.go

变量

var CommandLine = NewFlagSet(os.Args[0], ExitOnError)

CommandLine 是命令行标记的默认集合,从 os.Args 解析而来。像 BoolVar、Arg 等这样的顶级函数为 CommandLine 方法的包装。

var ErrHelp = errors.New("flag: help requested")

ErrHelp 在 -help 或 -h 标志未定义却调用了它时返回一个错误。

var Usage = func() {
    fmt.Fprintf(os.Stderr, "Usage of %s:\n", os.Args[0])
    PrintDefaults()
}

Usage 将所有已定义命令行标记的用法信息文档打印到标准错误输出。它会在解析标记遇到错误时调用。 该函数是个变量,因此可指向自定义的函数。它默认打印一个简单的开头并调用 PrintDefaults; 关于输出格式的控制及详情,参见 PrintDefaults 的文档。

func Arg

func Arg(i int) string

Arg返回第i个命令行参数。当有标签被解析之后,Arg(0)就成为了保留参数。

func Args

func Args() []string

Args返回非标签的命令行参数。

func Bool

func Bool(name string, value bool, usage string) *bool

Bool定义了一个有指定名字,默认值,和用法说明的bool标签。 返回值是一个存储标签解析值的bool变量地址。

func BoolVar

func BoolVar(p *bool, name string, value bool, usage string)

BoolVar定义了一个有指定名字,默认值,和用法说明的bool标签。 参数p指向一个存储标签解析值的bool变量。

func Duration

func Duration(name string, value time.Duration, usage string) *time.Duration

Duration定义了一个有指定名字,默认值,和用法说明的time.Duration标签。 返回值是一个存储标签解析值的time.Duration变量地址。 此标记接受一个 time.ParseDuration 可接受的值。

func DurationVar

func DurationVar(p *time.Duration, name string, value time.Duration, usage string)

DurationVar定义了一个有指定名字,默认值,和用法说明的time.Duration标签。 参数p指向一个存储标签解析值的time.Duration变量。 此标记接受一个 time.ParseDuration 可接受的值。

func Float64

func Float64(name string, value float64, usage string) *float64

Float64定义了一个有指定名字,默认值,和用法说明的float64标签。 返回值是一个存储标签解析值的float64变量地址。

func Float64Var

func Float64Var(p *float64, name string, value float64, usage string)

Float64Var定义了一个有指定名字,默认值,和用法说明的float64标签。 参数p指向一个存储标签解析值的float64变量。

func Int

func Int(name string, value int, usage string) *int

Int定义了一个有指定名字,默认值,和用法说明的int标签。 返回值是一个存储标签解析值的int变量地址。

func Int64

func Int64(name string, value int64, usage string) *int64

Int64定义了一个有指定名字,默认值,和用法说明的int64标签。 返回值是一个存储标签解析值的int64变量地址。

func Int64Var

func Int64Var(p *int64, name string, value int64, usage string)

Int64Var定义了一个有指定名字,默认值,和用法说明的int64标签。 参数p指向一个存储标签解析值的int64变量。

func IntVar

func IntVar(p *int, name string, value int, usage string)

IntVar定义了一个有指定名字,默认值,和用法说明的int标签。 参数p指向一个存储标签解析值的int变量。

func NArg

func NArg() int

在命令行标签被解析之后,NArg就返回解析后参数的个数。

func NFlag

func NFlag() int

NFlag返回解析过的命令行标签的数量。

func Parse

func Parse()

Parse从参数os.Args[1:]中解析命令行标签。 这个方法调用时间点必须在FlagSet的所有标签都定义之后,程序访问这些标签之前。

func Parsed

func Parsed() bool

Parsed 判断命令行标签是否已被解析。

func PrintDefaults

func PrintDefaults()

PrintDefaults 在没有另行设置时会将用法信息打印到标准错误输出, 该信息显示了所有已定义的命令行参数。 对于接受整数值的参数 x,默认的输出格式为:

-x int
	usage-message-for-x (default 7)

除了单字节名的布尔参数外,一般的用法信息会独占一行。对于布尔参数,其类型会被忽略; 若参数名为单个字节,则用法信息会在同一行。若默认值为该参数类型的零值, 那么括号中的默认值会被省略。已列出的类型,例如这里的 int, 可替换为参数用法信息中被反引号括住的字符串;第一个这样的条目会作为形参名出现在该用法信息中, 而反引号则会在显示信息时去掉。例如,给定

flag.String("I", "", "search `directory` for include files")

那么输出会是

-I directory
	search directory for include files.

func Set

func Set(name, value string) error

Set设置命令行中已经定义过的标签的值。

func String

func String(name string, value string, usage string) *string

String定义了一个有指定名字,默认值,和用法说明的string标签。 返回值是一个存储标签解析值的string变量地址。

func StringVar

func StringVar(p *string, name string, value string, usage string)

StringVar定义了一个有指定名字,默认值,和用法说明的string标签。 参数p指向一个存储标签解析值的string变量。

func Uint

func Uint(name string, value uint, usage string) *uint

Uint定义了一个有指定名字,默认值,和用法说明的uint标签。 返回值是一个存储标签解析值的uint变量地址。

func Uint64

func Uint64(name string, value uint64, usage string) *uint64

Uint64定义了一个有指定名字,默认值,和用法说明的uint64标签。 返回值是一个存储标签解析值的uint64变量地址。

func Uint64Var

func Uint64Var(p *uint64, name string, value uint64, usage string)

Uint64Var定义了一个有指定名字,默认值,和用法说明的uint64标签。 参数p指向一个存储标签解析值的uint64变量。

func UintVar

func UintVar(p *uint, name string, value uint, usage string)

UintVar定义了一个有指定名字,默认值,和用法说明的uint标签。 参数p指向一个存储标签解析值的uint变量。

func UnquoteUsage

func UnquoteUsage(flag *Flag) (name string, usage string)

UnquoteUsage 从 usage 字符串中提取反引号括起的名字 name 用作命令参数, 并返回该 name 以及不带引号的 usage。例如传入 "a `name` to show",时它会返回 ("name", "a name to show")。若其中没有反引号,name 即为该命令参数值类型的最佳猜测, 若命令参数为布尔值,则返回空字符串。

func Var

func Var(value Value, name string, usage string)

Var定义了一个有指定名字和用法说明的标签。标签的类型和值是由第一个参数指定的,这个参数 是Value类型,并且是用户自定义的实现了Value接口的类型。举个例子,调用者可以定义一种标签,这种标签会把 逗号分隔的字符串变成字符串slice,并提供出这种转换的方法。这样,Set(FlagSet)就会将逗号分隔 的字符串转换成为slice。

func Visit

func Visit(fn func(*Flag))

Visit按照字典顺序遍历命令行标签,并且对每个标签调用fn。 这个函数只遍历定义过的标签。

func VisitAll

func VisitAll(fn func(*Flag))

VisitAll按照字典顺序遍历控制台标签,并且对每个标签调用fn。 这个函数会遍历所有标签,包括那些没有定义的标签。

type ErrorHandling

type ErrorHandling int

ErrorHandling定义了如何处理标签解析的错误

const (
    ContinueOnError ErrorHandling = iota
    ExitOnError
    PanicOnError
)

type 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表示标签的状态

func Lookup

func Lookup(name string) *Flag

Lookup返回命令行已经定义过的标签,如果标签不存在的话,返回nil。

type FlagSet

type FlagSet struct {

    // 当解析标签出现错误的时候,Usage就会被调用。这个字段是一个函数(不是一个方法),它可以指向
    // 用户自己定义的错误处理函数。
    Usage func()
    // contains filtered or unexported fields
}

FlagSet 是已经定义好的标签的集合。FlagSet 的零值没有名字且拥有 ContinueOnError 错误处理。

func NewFlagSet

func NewFlagSet(name string, errorHandling ErrorHandling) *FlagSet

NewFlagSet 通过设置一个特定的名字和错误处理属性,返回一个新的,空的FlagSet。

func (*FlagSet) Arg

func (f *FlagSet) Arg(i int) string

Arg返回第i个参数。当有标签被解析之后,Arg(0)就成为了保留参数。

func (*FlagSet) Args

func (f *FlagSet) Args() []string

Args返回非标签的参数。

func (*FlagSet) Bool

func (f *FlagSet) Bool(name string, value bool, usage string) *bool

Bool定义了一个有指定名字,默认值,和用法说明的bool标签。 返回值是一个存储标签解析值的bool变量地址。

func (*FlagSet) BoolVar

func (f *FlagSet) BoolVar(p *bool, name string, value bool, usage string)

BoolVar定义了一个有指定名字,默认值,和用法说明的标签。 参数p指向一个存储标签值的bool变量。

func (*FlagSet) Duration

func (f *FlagSet) Duration(name string, value time.Duration, usage string) *time.Duration

Duration定义了一个有指定名字,默认值,和用法说明的time.Duration标签。 返回值是一个存储标签解析值的time.Duration变量地址。 此标记接受一个 time.ParseDuration 可接受的值。

func (*FlagSet) DurationVar

func (f *FlagSet) DurationVar(p *time.Duration, name string, value time.Duration, usage string)

DurationVar定义了一个有指定名字,默认值,和用法说明的time.Duration标签。 参数p指向一个存储标签解析值的time.Duration变量。 此标记接受一个 time.ParseDuration 可接受的值。

func (*FlagSet) Float64

func (f *FlagSet) Float64(name string, value float64, usage string) *float64

Float64定义了一个有指定名字,默认值,和用法说明的float64标签。 返回值是一个存储标签解析值的float64变量地址。

func (*FlagSet) Float64Var

func (f *FlagSet) Float64Var(p *float64, name string, value float64, usage string)

Float64Var定义了一个有指定名字,默认值,和用法说明的float64标签。 参数p指向一个存储标签解析值的float64变量。

func (*FlagSet) Init

func (f *FlagSet) Init(name string, errorHandling ErrorHandling)

Init设置名字和错误处理标签集合的属性。 空标签集合默认使用一个空名字和ContinueOnError的错误处理属性。

func (*FlagSet) Int

func (f *FlagSet) Int(name string, value int, usage string) *int

Int定义了一个有指定名字,默认值,和用法说明的int标签。 返回值是一个存储标签解析值的int变量地址。

func (*FlagSet) Int64

func (f *FlagSet) Int64(name string, value int64, usage string) *int64

Int64定义了一个有指定名字,默认值,和用法说明的int64标签。 返回值是一个存储标签解析值的int64变量地址。

func (*FlagSet) Int64Var

func (f *FlagSet) Int64Var(p *int64, name string, value int64, usage string)

Int64Var定义了一个有指定名字,默认值,和用法说明的int64标签。 参数p指向一个存储标签解析值的int64变量。

func (*FlagSet) IntVar

func (f *FlagSet) IntVar(p *int, name string, value int, usage string)

IntVar定义了一个有指定名字,默认值,和用法说明的int标签。 参数p指向一个存储标签解析值的int变量。

func (*FlagSet) Lookup

func (f *FlagSet) Lookup(name string) *Flag

Lookup返回已经定义过的标签,如果标签不存在的话,返回nil。

func (*FlagSet) NArg

func (f *FlagSet) NArg() int

在标签被解析之后,NArg就返回解析后参数的个数。

func (*FlagSet) NFlag

func (f *FlagSet) NFlag() int

NFlag返回解析过的标签的数量。

func (*FlagSet) Parse

func (f *FlagSet) Parse(arguments []string) error

Parse从参数列表中解析定义的标签,这个参数列表并不包含执行的命令名字。 这个方法调用时间点必须在FlagSet的所有标签都定义之后,程序访问这些标签之前。 当 -help 或 -h 标签没有定义却被调用了的时候,这个方法返回 ErrHelp。

func (*FlagSet) Parsed

func (f *FlagSet) Parsed() bool

Parsed返回是否f.Parse已经被调用过。

func (*FlagSet) PrintDefaults

func (f *FlagSet) PrintDefaults()

PrintDefaults 将设置中所有已定义的命令行标记的默认值打印到标准错误输出。有关全局函数 PrintDefaults 的更多信息见文档。

func (*FlagSet) Set

func (f *FlagSet) Set(name, value string) error

Set设置定义过的标签的值

func (*FlagSet) SetOutput

func (f *FlagSet) SetOutput(output io.Writer)

SetOutput设置了用法和错误信息的输出目的地。 如果output是nil,输出目的地就会使用os.Stderr。

func (*FlagSet) String

func (f *FlagSet) String(name string, value string, usage string) *string

String定义了一个有指定名字,默认值,和用法说明的string标签。 返回值是一个存储标签解析值的string变量地址。

func (*FlagSet) StringVar

func (f *FlagSet) StringVar(p *string, name string, value string, usage string)

StringVar定义了一个有指定名字,默认值,和用法说明的string标签。 参数p指向一个存储标签解析值的string变量。

func (*FlagSet) Uint

func (f *FlagSet) Uint(name string, value uint, usage string) *uint

Uint定义了一个有指定名字,默认值,和用法说明的uint标签。 返回值是一个存储标签解析值的uint变量地址。

func (*FlagSet) Uint64

func (f *FlagSet) Uint64(name string, value uint64, usage string) *uint64

Uint64定义了一个有指定名字,默认值,和用法说明的uint64标签。 返回值是一个存储标签解析值的uint64变量地址。

func (*FlagSet) Uint64Var

func (f *FlagSet) Uint64Var(p *uint64, name string, value uint64, usage string)

Uint64Var定义了一个有指定名字,默认值,和用法说明的uint64标签。 参数p指向一个存储标签解析值的uint64变量。

func (*FlagSet) UintVar

func (f *FlagSet) UintVar(p *uint, name string, value uint, usage string)

UintVar定义了一个有指定名字,默认值,和用法说明的uint标签。 参数p指向一个存储标签解析值的uint变量。

func (*FlagSet) Var

func (f *FlagSet) Var(value Value, name string, usage string)

Var定义了一个有指定名字和用法说明的标签。标签的类型和值是由第一个参数指定的,这个参数 是Value类型,并且是用户自定义的实现了Value接口的类型。举个例子,调用者可以定义一种标签,这种标签会把 逗号分隔的字符串变成字符串slice,并提供出这种转换的方法。这样,Set(FlagSet)就会将逗号分隔 的字符串转换成为slice。

func (*FlagSet) Visit

func (f *FlagSet) Visit(fn func(*Flag))

Visit按照字典顺序遍历标签,并且对每个标签调用fn。 这个函数只遍历定义过的标签。

func (*FlagSet) VisitAll

func (f *FlagSet) VisitAll(fn func(*Flag))

VisitAll按照字典顺序遍历标签,并且对每个标签调用fn。 这个函数会遍历所有标签,包括那些没有定义的标签。

type Getter

type Getter interface {
    Value
    Get() interface{}
}

Getter is an interface that allows the contents of a Value to be retrieved. It wraps the Value interface, rather than being part of it, because it appeared after Go 1 and its compatibility rules. All Value types provided by this package satisfy the Getter interface.

type Value

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

Value接口是定义了标签对应的具体的参数值。 (默认值是string类型)

若 Value 拥有的 IsBoolFlag() bool 方法返回 ture,则命令行解析器会使 -name 等价于 -name=true,而非使用下一个命令行实参。