# flag 包

import “flag”

简介

概览

flag包实现了命令行的参数解析。

使用flag.String()、Bool()、Int()等来定义flags。 以下声明了一个整形的flag。 -flagname存储在一个int型指针ip中。

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

然后你通过*ip来获得输入的参数。

当然你可以这样，使用Var()函数将flag绑定到一个变量上面。

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

或者，你可以创建自定义的flags，它满足指针接收，然后将它们一起进行flag解析：

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

对于这样的flags,默认值就是变量的初始值。 定义了所有的flags，然后调用flag.Parse()进行命令行参数解析。

执行flag.Parse()是必须的操作。

Flags可以直接使用。如果你用flags本身，他们就都是指针，如果你将他们绑定到变量，他们都是值。

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

解析完成以后，flag之后的参数就成了flag.Args()切片或者单独的flag.Args(i)。参数的索引从0直到flag.NArg()-1。

命令行语法：

  1. -flag
  2. -flag=x
  3. -flag x  // 只支持非bool类型

一个或者两个减号都可以，是等效的。最后一种形式对于bool flags是禁止的，因为如果一个文件名为0、false，cmd -x *的意思会改变。

你必须使用-flag=false形式来关闭bool flag。在第一个non-flag参数之前或者在终止符'--'停止Flag解析。 整形flags接收1234, 0664, 0x1234 ，而且可以是负值。bool flags可以是：1, 0, t, f, T, F, true, false, TRUE, FALSE, True, False。

布尔类型的参数防止解析时的二义性，应该使用等号的方式指定。

Duration flags接收任何符合time.ParseDuration的有效的输入参数。

顶层的函数控制默认的命令行flags集合。FlagSet的方法模拟了顶层函数定义了命令行 允许一个定义flags独立的集合，例如在一个命令行接口来实现子命令 。FlagSet的方法模拟了顶层函数定义了命令行flag集合。

变量

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

命令行是一个默认的命令行flags集合，从os.Args解析而来。顶层函数比如BoolVar、Arg和on都包含了命令行方法。

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

当flag-help被触发，但是没有flag定义，返回ErrHelp。

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

Usage函数为用户输出所有定义了的命令行参数和帮助信息usage message。一般，当命令行参数解析出错时，该函数会被调用。。这个函数是一个变量，可以指向一个自定义的函数。

func Arg

  1. func Arg(i int) string

返回第i个命令行参数。Arg(0)是当flags被处理后的第一个保留参数。

func Args

  1. func Args() []string

返回命令行中的non-flag参数。

func Bool

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

定义了一个bool类型的flag并指定了一个具体的flag名字name，默认值是value，使用说明是usage，也就是给用户的提示信息。返回值是一个bool指针，它所存储的地址用来保存flag的值。

func BoolVar

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

定义了一个bool类型的flag并指定了一个具体的flag名字name，默认值是value，使用说明是usage，也就是给用户的提示信息。指针p指向的bool变量用来存储flag的值。

func Duration

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

定义了一个time.Duration类型的flag并指定了一个具体的flag名字name，默认值是value，使用说明是usage，也就是给用户的提示信息。返回值是一个time.Duration指针，它所存储的地址用来保存flag的值。

func DurationVar

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

定义了一个time.Duration类型的flag并指定了一个具体的flag名字name，默认值是value，使用说明是usage，也就是给用户的提示信息。指针p指向的time.Duration变量用来存储flag的值。

func Float64

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

func Float64Var

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

func Int

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

定义了一个int类型的flag并指定了一个具体的flag名字name，默认值是value，使用说明是usage，也就是给用户的提示信息。返回值是一个int指针，它所存储的地址用来保存flag的值。

func Int64

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

func Int64Var

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

func IntVar

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

定义了一个int类型的flag并指定了一个具体的flag名字name，默认值是value，使用说明是usage，也就是给用户的提示信息。指针p指向的变量用来存储flag的值。

IntVar是绑定函数，适用的情形是已经预先声明了存储flag信息的变量。IntVar一般可以在包的Init()函数中执行。

func NArg

  1. func NArg() int

当flags完成后，返回non-flag参数的个数。

func NFlag

  1. func NFlag() int

返回命令行中已经设置的flags个数。

获得FlagSet中actual长度（即被设置了的参数个数）。

func Parse

  1. func Parse()

从os.Args[1:]解析命令行参数。必须在所有的flag都已经定义好并且在flags信息到达程序之前调用。

内部通过调用CommandLine.Parse(os.Args[1:])实现。

go标准库中，经常这么做： 定义了一个类型，提供了很多方法；为了方便使用，会在在全局变量中实例化一个该类型的实例，这样便可以直接使用该实例调用方法。

在flag包中，进行了进一步封装：将FlagSet的方法都重新定义了一遍，也就是提供了一系列函数，而函数中只是简单的调用已经实例化好了的FlagSet实例CommandLine的 的方法，这样FlagSet实例便不需要export。这样，使用者是这么调用：flag.Parse()而不是flag.NewFlagSet(x,y).Parse()。

func Parsed

  1. func Parsed() bool

当命令行flags已经被解析时返回true。

func PrintDefaults

  1. func PrintDefaults()

向标准错误输出打印所有已经定义的命令行参数的默认值。

func Set

  1. func Set(name, value string) error

给命名为name的命令行参数设置值value。

func String

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

定义了一个string类型的flag并指定了一个具体的flag名字name，默认值是value，使用说明是usage，也就是给用户的提示信息。返回值是一个string指针，它所存储的地址用来保存flag的值。

func StringVar

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

定义了一个string类型的flag并指定了一个具体的flag名字name，默认值是value，使用说明是usage，也就是给用户的提示信息。指针p指向的string变量用来存储flag的值。

func Uint

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

定义了一个uint类型的flag并指定了一个具体的flag名字name，默认值是value，使用说明是usage，也就是给用户的提示信息。返回值是一个uint指针，它所存储的地址用来保存flag的值。

func Uint64

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

func Uint64Var

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

func UintVar

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

func Var

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

定义了一个flag，并指定了具体的name和usage。flag的类型和值用第一个参数来指出，它实例化了用户自定义的类型。例如，调用者可以创建一个flag，它通过给切片Value方法将用逗号分隔的字符串转换为一个string切片。特别的，集合应该将用逗号分隔的字符串转换为一个string切片。

func Visit

  1. func Visit(fn func(*Flag))

按照字典顺序访问命令行参数，并对每个执行fn函数。只访问那些已经设置的flags。

func VisitAll

  1. func VisitAll(fn func(*Flag))

按照字典顺序访问命令行参数，并对每个执行fn函数。访问所有的flags，无论是否已经设置。

type ErrorHandling

  1. type ErrorHandling int

定义了如何处理flag解析错误。

  1. const (
  2.     ContinueOnError ErrorHandling = iota
  3.     ExitOnError
  4.     PanicOnError
  5. )

三个常量在源码的FlagSet方法Parse()中使用了。

type Flag

  1. type Flag struct {
  2.     Name     string // 命令行参数-flagname名字flagname
  3.     Usage    string // 帮助信息
  4.     Value    Value  // 获取的输入的值。Value是一个接口。
  5.     DefValue string // 默认值
  6. }

flag类型代表了一个flag的状态。

比如：autogo -f abc.txt，代码flag.String(“f”, “a.txt”, “this is usage”)，则该Flag实例（可以通过flag.Lookup(“f”)获得）相应的值为：f, this is usage , abc.txt, a.txt。

func Lookup

  1. func Lookup(name string) *Flag

给定命令行参数name并返回Flag。如果name不存在则返回nil。

type FlagSet

  1. type FlagSet struct {
  2.     // Usage 是一个函数，当解析flag出现错误的时候调用。
  3.     // The field is a function (not a method) that may be changed to point to
  4.     // a custom error handler.
  5.     Usage func()
  6.     // contains filtered or unexported fields
  7. }

func NewFlagSet

  1. func NewFlagSet(name string, errorHandling ErrorHandling) *FlagSet

返回一个新的空flag集合，它带有具体的名字和错误处理属性。

由于FlagSet中的字段没有export，其他方式获得FlagSet实例后，比如：FlagSet{}或new(FlagSet)，应该调用Init()方法，初始化name和errorHandling。

func (*FlagSet) Arg

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

返回第i个参数。Arg(0)是所有的flags解析后的第一个剩余的参数，

func (*FlagSet) Args

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

返回non-flag参数。

func (*FlagSet) Bool

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

func (*FlagSet) BoolVar

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

func (*FlagSet) Duration

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

func (*FlagSet) DurationVar

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

func (*FlagSet) Float64

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

func (*FlagSet) Float64Var

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

func (*FlagSet) Init

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

为一个flag集合设置name和errorHandling处理函数。默认情况下，zero FlagSet使用空name和ContinueOnError处理策略。

func (*FlagSet) Int

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

func (*FlagSet) Int64

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

func (*FlagSet) Int64Var

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

func (*FlagSet) IntVar

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

func (*FlagSet) Lookup

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

返回已命名的flag的Flag结构。如果没有则返回nil。

func (*FlagSet) NArg

  1. func (f *FlagSet) NArg() int

当所有的flags解析完成后，返回剩余的参数个数。

func (*FlagSet) NFlag

  1. func (f *FlagSet) NFlag() int

返回已经设置的flags个数。

func (*FlagSet) Parse

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

从参数列表中解析flag定义，不应该包含命令名字。必须在FlagSet中的所有flags都被定义并且flags被程序获取到之后调用。如果-help被设置但是没有定义，返回ErrHelp。

func (*FlagSet) Parsed

  1. func (f *FlagSet) Parsed() bool

返回f.Parse()是否已经调用。

func (*FlagSet) PrintDefaults

  1. func (f *FlagSet) PrintDefaults()

向标准错误输出打印所有flags的默认值。如果你自己设置了，另当别论。

func (*FlagSet) Set

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

设置已经命名了的flag。

func (*FlagSet) SetOutput

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

设置usage和错误信息的输出位置。如果output为空，那么使用默认的os.Stderr。

func (*FlagSet) String

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

func (*FlagSet) StringVar

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

func (*FlagSet) Uint

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

func (*FlagSet) Uint64

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

func (*FlagSet) Uint64Var

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

func (*FlagSet) UintVar

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

func (*FlagSet) Var

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

func (*FlagSet) Visit

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

按照字典顺序访问命令行参数，并对每个执行fn函数。只访问那些已经设置的flags。

func (*FlagSet) VisitAll

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

按照字典顺序访问命令行参数，并对每个执行fn函数。访问所有的flags，无论是否已经设置。

type Getter

  1. type Getter interface {
  2.     Value
  3.     Get() interface{}
  4. }

Getter是一个接口，允许重新取回Value的内容。它封装了值的接口，而不是作为它的一部分，因为它在GO 1版本后出现的，为了实现兼容性。

本包提供的所有的Value类型满足Getter接口。

type Value

  1. type Value interface {
  2.     String() string
  3.     Set(string) error
  4. }

Value是一个接口，为了存取flag中的动态数据而定义。默认值用字符串来代替。

如果Value有一个IsBoolFlag()布尔方法返回true, 命令行解析器使得 -name 和-name=true等效。