package flag
import "flag"
Package flag 实现命令行标志解析。
用法
使用 flag.String、Bool、Int 等来定义标志。
下面声明了一个整数标志 -n,存储在 *int 类型的指针 nFlag 中:
import "flag"
var nFlag = flag.Int("n", 1234, "help message for flag n")
如果你愿意,也可以使用 Var() 函数将标志绑定到一个变量。
var flagvar int
func init() {
flag.IntVar(&flagvar, "flagname", 1234, "help message for flagname")
}
或者,你可以创建满足 Value 接口(带有指针接收者)的自定义标志, 并通过以下方式将它们与标志解析关联起来
flag.Var(&flagVal, "name", "help message for flagname")
对于这类标志,默认值就是该变量的初始值。
在所有标志都定义好之后,调用
flag.Parse()
将命令行解析到已定义的标志中。
之后便可以直接使用这些标志。如果直接使用标志本身, 它们都是指针;如果绑定到变量,它们就是值。
fmt.Println("ip has value ", *ip)
fmt.Println("flagvar has value ", flagvar)
解析完成后,标志后面的参数可以作为切片 flag.Args 获取, 也可以通过 flag.Arg(i) 单独获取。 参数下标从 0 到 flag.NArg-1。
命令行标志语法
允许以下形式:
-flag --flag // double dashes are also permitted -flag=x -flag x // non-boolean flags only
可以使用一个或两个短横线;它们是等价的。 最后一种形式不适用于布尔标志,因为命令
cmd -x *
(其中 * 是 Unix shell 通配符)的含义会因存在名为 0、false 等文件而改变。要关闭布尔标志,必须使用 -flag=false 形式。
标志解析会在第一个非标志参数之前("-" 是非标志参数) 或终止符 "--" 之后停止。
整数标志接受 1234、0664、0x1234,且可以为负数。 布尔标志可以是:
1, 0, t, f, T, F, true, false, TRUE, FALSE, True, False
Duration 标志接受任何对 time.ParseDuration 有效的输入。
默认的命令行标志集合由顶层函数控制。
FlagSet 类型允许定义相互独立的标志集合,
例如在命令行界面中实现子命令。
FlagSet 的方法与命令行标志集合的顶层函数类似。
Example
// These examples demonstrate more intricate uses of the flag package.
package main
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 main() {
// 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 call it here because this code is a function called "Example"
// that is part of the testing suite for the package, which has already
// parsed the flags. When viewed at pkg.go.dev, however, the function is
// renamed to "main" and it could be run as a standalone example.
}
Index
- Variables
- func Arg(i int) string
- func Args() []string
- func Bool(name string, value bool, usage string) *bool
- func BoolFunc(name, usage string, fn func(string) error)
- 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 Func(name, usage string, fn func(string) error)
- 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 TextVar(p encoding.TextUnmarshaler, name string, value encoding.TextMarshaler, ...)
- 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
-
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) BoolFunc(name, usage string, fn func(string) error)
- 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) ErrorHandling() ErrorHandling
- 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) Func(name, usage string, fn func(string) error)
- 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) Name() string
- func (f *FlagSet) Output() io.Writer
- 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) TextVar(p encoding.TextUnmarshaler, name string, value encoding.TextMarshaler, ...)
- 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
Examples
Variables
var ErrHelp = errors.New("flag: help requested")
ErrHelp 是在调用了 -help 或 -h 标志但未定义该标志时返回的错误。
var Usage = func() { fmt.Fprintf(CommandLine.Output(), "Usage of %s:\n", os.Args[0]) PrintDefaults() }
Usage 将记录所有已定义命令行标志的用法消息打印到 CommandLine 的输出,默认是 os.Stderr。 它在解析标志过程中发生错误时被调用。 该函数是一个变量,可以改为指向自定义函数。 默认情况下它会打印一个简单的头部并调用 PrintDefaults;关于输出格式 以及如何控制它的详细信息,请参见 PrintDefaults 的文档。 自定义的 usage 函数可以选择退出程序;默认情况下退出本来就会发生, 因为命令行的错误处理策略被设置为 ExitOnError。
Functions
func Arg
func Arg(i int) string
Arg 返回第 i 个命令行参数。Arg(0) 是处理完标志后剩下的第一个参数。 如果请求的元素不存在,Arg 返回空字符串。
func Args
func Args() []string
Args 返回非标志命令行参数。
func Bool
func Bool(name string, value bool, usage string) *bool
Bool 定义一个具有指定名称、默认值和用法字符串的 bool 标志。 返回值是一个 bool 变量的地址,该变量存储标志的值。
func BoolFunc
func BoolFunc(name, usage string, fn func(string) error)
BoolFunc 定义一个具有指定名称和用法字符串且不需要提供值的标志。
每次遇到该标志时,都会用标志的值调用 fn。
如果 fn 返回非 nil 错误,它将被视为标志值解析错误。
Output:Example
package main
import (
"flag"
"fmt"
"os"
)
func main() {
fs := flag.NewFlagSet("ExampleBoolFunc", flag.ContinueOnError)
fs.SetOutput(os.Stdout)
fs.BoolFunc("log", "logs a dummy message", func(s string) error {
fmt.Println("dummy message:", s)
return nil
})
fs.Parse([]string{"-log"})
fs.Parse([]string{"-log=0"})
}
dummy message: true
dummy message: 0
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 Func
func Func(name, usage string, fn func(string) error)
Func 定义一个具有指定名称和用法字符串的标志。
每次遇到该标志时,都会用标志的值调用 fn。
如果 fn 返回非 nil 错误,它将被视为标志值解析错误。
Output:Example
package main
import (
"errors"
"flag"
"fmt"
"net"
"os"
)
func main() {
fs := flag.NewFlagSet("ExampleFunc", flag.ContinueOnError)
fs.SetOutput(os.Stdout)
var ip net.IP
fs.Func("ip", "`IP address` to parse", func(s string) error {
ip = net.ParseIP(s)
if ip == nil {
return errors.New("could not parse IP")
}
return nil
})
fs.Parse([]string{"-ip", "127.0.0.1"})
fmt.Printf("{ip: %v, loopback: %t}\n\n", ip, ip.IsLoopback())
// 256 is not a valid IPv4 component
fs.Parse([]string{"-ip", "256.0.0.1"})
fmt.Printf("{ip: %v, loopback: %t}\n\n", ip, ip.IsLoopback())
}
{ip: 127.0.0.1, loopback: true}
invalid value "256.0.0.1" for flag -ip: could not parse IP
Usage of ExampleFunc:
-ip IP address
IP address to parse
{ip: <nil>, loopback: false}
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:] 解析命令行标志。必须在所有标志 都已定义之后、且程序访问标志之前调用。
func Parsed
func Parsed() bool
Parsed 报告命令行标志是否已被解析。
func PrintDefaults
func PrintDefaults()
PrintDefaults 将显示所有已定义命令行标志默认设置的用法消息 打印到标准错误(除非另有配置)。 对于整数值的标志 x,默认输出形式为
-x int usage-message-for-x (default 7)
除单字节名称的 bool 标志外,用法消息都会出现在单独一行。 对于 bool 标志,类型会被省略;若标志名是一个字节, 用法消息会出现在同一行。如果默认值是该类型的零值, 则省略括号中的默认值。所列出的类型(这里是 int)可以通过 在标志的用法字符串中放置一个反引号括起的名称来更改; 消息中第一个这样的项会被视为要显示的参数名, 显示时会去掉消息中的反引号。例如,给定
flag.String("I", "", "search `directory` for include files")
输出将是
-I directory search directory for include files.
要更改标志消息的目标,请调用 CommandLine.SetOutput。
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 TextVar
func TextVar(p encoding.TextUnmarshaler, name string, value encoding.TextMarshaler, usage string)
TextVar 定义一个具有指定名称、默认值和用法字符串的标志。
参数 p 必须是指向将保存该标志值的变量的指针,
并且 p 必须实现 encoding.TextUnmarshaler。
如果使用了该标志,标志值将被传递给 p 的 UnmarshalText 方法。
默认值的类型必须与 p 的类型相同。
Output:Example
package main
import (
"flag"
"fmt"
"net"
"os"
)
func main() {
fs := flag.NewFlagSet("ExampleTextVar", flag.ContinueOnError)
fs.SetOutput(os.Stdout)
var ip net.IP
fs.TextVar(&ip, "ip", net.IPv4(192, 168, 0, 100), "`IP address` to parse")
fs.Parse([]string{"-ip", "127.0.0.1"})
fmt.Printf("{ip: %v}\n\n", ip)
// 256 is not a valid IPv4 component
ip = nil
fs.Parse([]string{"-ip", "256.0.0.1"})
fmt.Printf("{ip: %v}\n\n", ip)
}
{ip: 127.0.0.1}
invalid value "256.0.0.1" for flag -ip: invalid IP address: 256.0.0.1
Usage of ExampleTextVar:
-ip IP address
IP address to parse (default 192.168.0.100)
{ip: <nil>}
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 从标志的用法字符串中提取反引号括起的名称, 并返回该名称以及去掉反引号的用法字符串。 给定 "a `name` to show",它返回 ("name", "a name to show")。 如果没有反引号,则该名称是对标志值类型的一个合理猜测, 如果标志是布尔类型,则为空字符串。
func Var
func Var(value Value, name string, usage string)
Var 定义一个具有指定名称和用法字符串的标志。标志的类型和值 由第一个参数表示,其类型为 Value,通常持有 用户自定义的 Value 实现。例如, 调用者可以通过为切片提供 Value 的方法,创建一个将逗号分隔的 字符串转换为字符串切片的标志;特别是 Set 会将 逗号分隔的字符串分解到该切片中。
func Visit
func Visit(fn func(*Flag))
Visit 按字典序访问命令行标志,对每个标志调用 fn。 它只访问已设置的标志。
func VisitAll
func VisitAll(fn func(*Flag))
VisitAll 按字典序访问命令行标志,对每个标志调用 fn。它会访问所有标志,包括未设置的标志。
Types
type ErrorHandling
type ErrorHandling int
ErrorHandling 定义了解析失败时 FlagSet.Parse 的行为。
const ( ContinueOnError ErrorHandling = iota // 返回一个描述性错误。 ExitOnError // 调用 os.Exit(2),对于 -h/-help 则调用 Exit(0)。 PanicOnError // 调用 panic 并附带描述性错误。 )
这些常量使 FlagSet.Parse 在解析失败时按所述方式运行。
type Flag
type Flag struct { Name string // 名称,如命令行中出现的那样 Usage string // 帮助消息 Value Value // 设置的值 DefValue string // 默认值(以文本形式);用于用法消息 }
Flag 表示一个标志的状态。
func Lookup
func Lookup(name string) *Flag
Lookup 返回指定名称命令行标志的 Flag 结构, 若不存在则返回 nil。
type FlagSet
type FlagSet struct { // Usage 是在解析标志过程中发生错误时调用的函数。 // 该字段是一个函数(而非方法),可以改为指向 // 自定义的错误处理函数。调用 Usage 之后发生什么取决于 // ErrorHandling 设置;对于命令行来说,它默认为 // ExitOnError,即在调用 Usage 之后退出程序。 Usage func() // contains filtered or unexported fields }
FlagSet 表示一组已定义的标志。FlagSet 的零值 没有名称,并具有 ContinueOnError 错误处理方式。
Flag 名称在同一个 FlagSet 内必须唯一。若尝试定义一个名称
已被使用的标志,将导致 panic。
Output:Example
package main
import (
"flag"
"fmt"
"time"
)
func main() {
start := func(args []string) {
// A real program (not an example) would use flag.ExitOnError.
fs := flag.NewFlagSet("start", flag.ContinueOnError)
addr := fs.String("addr", ":8080", "`address` to listen on")
if err := fs.Parse(args); err != nil {
fmt.Printf("error: %s", err)
return
}
fmt.Printf("starting server on %s\n", *addr)
}
stop := func(args []string) {
fs := flag.NewFlagSet("stop", flag.ContinueOnError)
timeout := fs.Duration("timeout", time.Second, "stop timeout duration")
if err := fs.Parse(args); err != nil {
fmt.Printf("error: %s", err)
return
}
fmt.Printf("stopping server (timeout=%v)\n", *timeout)
}
main := func(args []string) {
subArgs := args[2:] // Drop program name and command.
switch args[1] {
case "start":
start(subArgs)
case "stop":
stop(subArgs)
default:
fmt.Printf("error: unknown command - %q\n", args[1])
// In a real program (not an example) print to os.Stderr and exit the program with non-zero value.
}
}
main([]string{"httpd", "start", "-addr", ":9999"})
main([]string{"httpd", "stop"})
main([]string{"http", "start", "-log-level", "verbose"})
}
starting server on :9999
stopping server (timeout=1s)
error: flag provided but not defined: -log-level
var CommandLine *FlagSet
CommandLine 是默认的命令行标志集合,从 os.Args 解析而来。 诸如 BoolVar、Arg 等顶层函数都是 CommandLine 方法的包装。
func NewFlagSet
func NewFlagSet(name string, errorHandling ErrorHandling) *FlagSet
NewFlagSet 返回一个新的空标志集合,具有指定的名称和 错误处理属性。如果名称非空,它将被打印 在默认用法消息和错误消息中。
func (*FlagSet) Arg
func (f *FlagSet) Arg(i int) string
Arg 返回第 i 个参数。Arg(0) 是处理完标志后剩下的第一个参数。 如果请求的元素不存在,Arg 返回空字符串。
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) BoolFunc
func (f *FlagSet) BoolFunc(name, usage string, fn func(string) error)
BoolFunc 定义一个具有指定名称和用法字符串且不需要提供值的标志。 每次遇到该标志时,都会用标志的值调用 fn。 如果 fn 返回非 nil 错误,它将被视为标志值解析错误。
func (*FlagSet) BoolVar
func (f *FlagSet) BoolVar(p *bool, name string, value bool, usage string)
BoolVar 定义一个具有指定名称、默认值和用法字符串的 bool 标志。 参数 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) ErrorHandling
func (f *FlagSet) ErrorHandling() ErrorHandling
ErrorHandling 返回标志集合的错误处理行为。
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) Func
func (f *FlagSet) Func(name, usage string, fn func(string) error)
Func 定义一个具有指定名称和用法字符串的标志。 每次遇到该标志时,都会用标志的值调用 fn。 如果 fn 返回非 nil 错误,它将被视为标志值解析错误。
func (*FlagSet) Init
func (f *FlagSet) Init(name string, errorHandling ErrorHandling)
Init 设置标志集合的名称和错误处理属性。 默认情况下,零值 FlagSet 使用空名称和 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 返回指定名称标志的 Flag 结构,若不存在则返回 nil。
func (*FlagSet) NArg
func (f *FlagSet) NArg() int
NArg 是处理完标志后剩余参数的数量。
func (*FlagSet) NFlag
func (f *FlagSet) NFlag() int
NFlag 返回已设置标志的数量。
func (*FlagSet) Name
func (f *FlagSet) Name() string
Name 返回标志集合的名称。
func (*FlagSet) Output
func (f *FlagSet) Output() io.Writer
Output 返回用法消息和错误消息的目标。如果 output 未设置或被设为 nil,则返回 os.Stderr。
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) TextVar
func (f *FlagSet) TextVar(p encoding.TextUnmarshaler, name string, value encoding.TextMarshaler, usage string)
TextVar 定义一个具有指定名称、默认值和用法字符串的标志。 参数 p 必须是指向将保存该标志值的变量的指针, 并且 p 必须实现 encoding.TextUnmarshaler。 如果使用了该标志,标志值将被传递给 p 的 UnmarshalText 方法。 默认值的类型必须与 p 的类型相同。
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 实现。例如, 调用者可以通过为切片提供 Value 的方法,创建一个将逗号分隔的 字符串转换为字符串切片的标志;特别是 Set 会将 逗号分隔的字符串分解到该切片中。
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() any }
Getter 是一个接口,允许获取 Value 的内容。 它包装了 Value 接口,而不是作为其一部分,因为它 出现在 Go 1 及其兼容性规则之后。本包提供的所有 Value 类型 都满足 Getter 接口,除了 Func 使用的类型。
type Value
type Value interface { String() string Set(string) error }
Value 是存储在标志中的动态值的接口。 (默认值以字符串形式表示。)
如果某个 Value 具有返回 true 的 IsBoolFlag() bool 方法, 命令行解析器会将 -name 视为等价于 -name=true, 而不是使用下一个命令行参数。
对于每个出现的标志,Set 会按命令行顺序被调用一次。
flag 包可能会以零值接收者(例如 nil 指针)调用 String 方法。
Output:Example
package main
import (
"flag"
"fmt"
"net/url"
)
type URLValue struct {
URL *url.URL
}
func (v URLValue) String() string {
if v.URL != nil {
return v.URL.String()
}
return ""
}
func (v URLValue) Set(s string) error {
if u, err := url.Parse(s); err != nil {
return err
} else {
*v.URL = *u
}
return nil
}
var u = &url.URL{}
func main() {
fs := flag.NewFlagSet("ExampleValue", flag.ExitOnError)
fs.Var(&URLValue{u}, "url", "URL to parse")
fs.Parse([]string{"-url", "https://golang.org/pkg/flag/"})
fmt.Printf(`{scheme: %q, host: %q, path: %q}`, u.Scheme, u.Host, u.Path)
}
{scheme: "https", host: "golang.org", path: "/pkg/flag/"}