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

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 错误,它将被视为标志值解析错误。

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"})

}

Output:

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 错误,它将被视为标志值解析错误。

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())

}

Output:

{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 的类型相同。

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)

}

Output:

{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。

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"})

}

Output:

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 方法。

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)

}

Output:

{scheme: "https", host: "golang.org", path: "/pkg/flag/"}