Cobra

// Copyright © 2015 Steve Francia <spf@spf13.com>.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package main

import (
	"os"

	"github.com/spf13/cobra/cobra/cmd"
)

func main() {
	if err := cmd.Execute(); err != nil {
		os.Exit(1)
	}
}

main.go 调用了 cmd 的 Excute 函数,如果没有错误信息则正常退出

var (
	// Used for flags.
	cfgFile     string
	userLicense string

	rootCmd = &cobra.Command{
		Use:   "cobra",
		Short: "A generator for Cobra based Applications",
		Long: `Cobra is a CLI library for Go that empowers applications.
This application is a tool to generate the needed files
to quickly create a Cobra application.`,
	}
)

首先定义了一些变量,cfgFile,userLicense,rootCmd

其中 rootCmd 是指针类型的 Command 结构体,传入了 Use,Short,Long,看一下 cobra 包下的 Command 结构体类型

type Command struct {
	// Use is the one-line usage message.
	Use string

	// Aliases is an array of aliases that can be used instead of the first word in Use.
	Aliases []string

	// SuggestFor is an array of command names for which this command will be suggested -
	// similar to aliases but only suggests.
	SuggestFor []string

	// Short is the short description shown in the 'help' output.
	Short string

	// Long is the long message shown in the 'help <this-command>' output.
	Long string

	// Example is examples of how to use the command.
	Example string

	// ValidArgs is list of all valid non-flag arguments that are accepted in bash completions
	ValidArgs []string
	// ValidArgsFunction is an optional function that provides valid non-flag arguments for bash completion.
	// It is a dynamic version of using ValidArgs.
	// Only one of ValidArgs and ValidArgsFunction can be used for a command.
	ValidArgsFunction func(cmd *Command, args []string, toComplete string) ([]string, ShellCompDirective)

	// Expected arguments
	Args PositionalArgs

	// ArgAliases is List of aliases for ValidArgs.
	// These are not suggested to the user in the bash completion,
	// but accepted if entered manually.
	ArgAliases []string

	// BashCompletionFunction is custom functions used by the bash autocompletion generator.
	BashCompletionFunction string

	// Deprecated defines, if this command is deprecated and should print this string when used.
	Deprecated string

	// Hidden defines, if this command is hidden and should NOT show up in the list of available commands.
	Hidden bool

	// Annotations are key/value pairs that can be used by applications to identify or
	// group commands.
	Annotations map[string]string

	// Version defines the version for this command. If this value is non-empty and the command does not
	// define a "version" flag, a "version" boolean flag will be added to the command and, if specified,
	// will print content of the "Version" variable. A shorthand "v" flag will also be added if the
	// command does not define one.
	Version string

	// The *Run functions are executed in the following order:
	//   * PersistentPreRun()
	//   * PreRun()
	//   * Run()
	//   * PostRun()
	//   * PersistentPostRun()
	// All functions get the same args, the arguments after the command name.
	//
	// PersistentPreRun: children of this command will inherit and execute.
	PersistentPreRun func(cmd *Command, args []string)
	// PersistentPreRunE: PersistentPreRun but returns an error.
	PersistentPreRunE func(cmd *Command, args []string) error
	// PreRun: children of this command will not inherit.
	PreRun func(cmd *Command, args []string)
	// PreRunE: PreRun but returns an error.
	PreRunE func(cmd *Command, args []string) error
	// Run: Typically the actual work function. Most commands will only implement this.
	Run func(cmd *Command, args []string)
	// RunE: Run but returns an error.
	RunE func(cmd *Command, args []string) error
	// PostRun: run after the Run command.
	PostRun func(cmd *Command, args []string)
	// PostRunE: PostRun but returns an error.
	PostRunE func(cmd *Command, args []string) error
	// PersistentPostRun: children of this command will inherit and execute after PostRun.
	PersistentPostRun func(cmd *Command, args []string)
	// PersistentPostRunE: PersistentPostRun but returns an error.
	PersistentPostRunE func(cmd *Command, args []string) error

	// SilenceErrors is an option to quiet errors down stream.
	SilenceErrors bool

	// SilenceUsage is an option to silence usage when an error occurs.
	SilenceUsage bool

	// DisableFlagParsing disables the flag parsing.
	// If this is true all flags will be passed to the command as arguments.
	DisableFlagParsing bool

	// DisableAutoGenTag defines, if gen tag ("Auto generated by spf13/cobra...")
	// will be printed by generating docs for this command.
	DisableAutoGenTag bool

	// DisableFlagsInUseLine will disable the addition of [flags] to the usage
	// line of a command when printing help or generating docs
	DisableFlagsInUseLine bool

	// DisableSuggestions disables the suggestions based on Levenshtein distance
	// that go along with 'unknown command' messages.
	DisableSuggestions bool
	// SuggestionsMinimumDistance defines minimum levenshtein distance to display suggestions.
	// Must be > 0.
	SuggestionsMinimumDistance int

	// TraverseChildren parses flags on all parents before executing child command.
	TraverseChildren bool

	// FParseErrWhitelist flag parse errors to be ignored
	FParseErrWhitelist FParseErrWhitelist

	ctx context.Context

	// commands is the list of commands supported by this program.
	commands []*Command
	// parent is a parent command for this command.
	parent *Command
	// Max lengths of commands' string lengths for use in padding.
	commandsMaxUseLen         int
	commandsMaxCommandPathLen int
	commandsMaxNameLen        int
	// commandsAreSorted defines, if command slice are sorted or not.
	commandsAreSorted bool
	// commandCalledAs is the name or alias value used to call this command.
	commandCalledAs struct {
		name   string
		called bool
	}

	// args is actual args parsed from flags.
	args []string
	// flagErrorBuf contains all error messages from pflag.
	flagErrorBuf *bytes.Buffer
	// flags is full set of flags.
	flags *flag.FlagSet
	// pflags contains persistent flags.
	pflags *flag.FlagSet
	// lflags contains local flags.
	lflags *flag.FlagSet
	// iflags contains inherited flags.
	iflags *flag.FlagSet
	// parentsPflags is all persistent flags of cmd's parents.
	parentsPflags *flag.FlagSet
	// globNormFunc is the global normalization function
	// that we can use on every pflag set and children commands
	globNormFunc func(f *flag.FlagSet, name string) flag.NormalizedName

	// usageFunc is usage func defined by user.
	usageFunc func(*Command) error
	// usageTemplate is usage template defined by user.
	usageTemplate string
	// flagErrorFunc is func defined by user and it's called when the parsing of
	// flags returns an error.
	flagErrorFunc func(*Command, error) error
	// helpTemplate is help template defined by user.
	helpTemplate string
	// helpFunc is help func defined by user.
	helpFunc func(*Command, []string)
	// helpCommand is command with usage 'help'. If it's not defined by user,
	// cobra uses default help command.
	helpCommand *Command
	// versionTemplate is the version template defined by user.
	versionTemplate string

	// inReader is a reader defined by the user that replaces stdin
	inReader io.Reader
	// outWriter is a writer defined by the user that replaces stdout
	outWriter io.Writer
	// errWriter is a writer defined by the user that replaces stderr
	errWriter io.Writer
}

Command 结构体中定义了好多属性，挨个看看都是干嘛的

然后是 init 函数,使用 root 文件 cmd.Excute 时自动调用

cobra.OnInitialize(initConfig)

这条代码调用到

func SetConfigFile(in string) { v.SetConfigFile(in) }
func (v *Viper) SetConfigFile(in string) {
	if in != "" {
		v.configFile = in
	}
}

SetConfigFile 调用结构体 Viper 的 SetConfigFIle 函数

viper 包的 init 函数

func New() *Viper {
	v := new(Viper)
	v.keyDelim = "."
	v.configName = "config"
	v.configPermissions = os.FileMode(0644)
	v.fs = afero.NewOsFs()
	v.config = make(map[string]interface{})
	v.override = make(map[string]interface{})
	v.defaults = make(map[string]interface{})
	v.kvstore = make(map[string]interface{})
	v.pflags = make(map[string]FlagValue)
	v.env = make(map[string]string)
	v.aliases = make(map[string]string)
	v.typeByDefValue = false

	return v
}

viper 是个什么东西呢，康康

type Viper struct {
	// 分隔键列表的定界符
	// 用于一次性访问嵌套值
	keyDelim string

	// 查找配置文件的路径
	configPaths []string

	// 读取配置文件地址的类型
	fs afero.Fs

	// 一组远程提供程序以搜索配置
	remoteProviders []*defaultRemoteProvider

	// 配置文件名称
	configName string
	configFile string
	configType string
	// 文件权限
	configPermissions os.FileMode
	// 环境前缀
	envPrefix           string
	automaticEnvApplied bool
	envKeyReplacer      *strings.Replacer
	allowEmptyEnv       bool

	config         map[string]interface{}
	override       map[string]interface{}
	defaults       map[string]interface{}
	kvstore        map[string]interface{}
	pflags         map[string]FlagValue
	env            map[string]string
	aliases        map[string]string
	typeByDefValue bool

	//将读取的属性存储在对象上，以便我们可以按顺序写回并带有注释。
	//仅当读取的配置是属性文件时才使用。
	properties *properties.Properties

	onConfigChange func(fsnotify.Event)
}

func SetConfigFile(in string) { v.SetConfigFile(in) }
func (v *Viper) SetConfigFile(in string) {
	if in != "" {
		// 将viper结构体重的 configFile配置成
		v.configFile = in
	}
}

func initConfig() {
	if cfgFile != "" {
		// 如果配置了配置文件地址则 viper结构体设置此文件
		viper.SetConfigFile(cfgFile)
	} else {
		// 否则从home开始找配置文件
		home, err := homedir.Dir()
		if err != nil {
			er(err)
		}
		// viper配置寻找配置文件的目录
		viper.AddConfigPath(home)
		// 寻找以.cobra结尾的文件
		viper.SetConfigName(".cobra")
	}
	// 自动判断系统环境并应用
	// 这个函数将viper.automaticEnvApplied gai we
	viper.AutomaticEnv()
	// 如果读取配置文件出错
	if err := viper.ReadInConfig(); err == nil {
		fmt.Println("Using config file:", viper.ConfigFileUsed())
	}
}

然后看下一句

rootCmd.PersistentFlags().StringVar(&cfgFile, "config", "", "config file (default is $HOME/.cobra.yaml)")

// 返回当前命令中设置的持久性FlagSet
func (c *Command) PersistentFlags() *flag.FlagSet {
	// 如果command的pflgs-FlagSet为空
	if c.pflags == nil {
		// 那么新建一个
		c.pflags = flag.NewFlagSet(c.Name(), flag.ContinueOnError)
		if c.flagErrorBuf == nil {
			c.flagErrorBuf = new(bytes.Buffer)
		}
		c.pflags.SetOutput(c.flagErrorBuf)
	}
	// return 回这个FlagSet,指针类型
	return c.pflags
}

什么是 flag 呢,比如 xxx create --name ferried,在这段 command 中,create 为 command,--name 为 create 的 flag
看一眼 FlagSet 结构体

type FlagSet struct {
	Usage func()
	SortFlags bool
	ParseErrorsWhitelist ParseErrorsWhitelist
	name              string
	parsed            bool
	actual            map[NormalizedName]*Flag
	orderedActual     []*Flag
	sortedActual      []*Flag
	formal            map[NormalizedName]*Flag
	orderedFormal     []*Flag
	sortedFormal      []*Flag
	shorthands        map[byte]*Flag
	args              []string // arguments after flags
	argsLenAtDash     int      
	errorHandling     ErrorHandling
	output            io.Writer 
	interspersed      bool      args
	normalizeNameFunc func(f *FlagSet, name string) NormalizedName
	addedGoFlagSets []*goflag.FlagSet
}

StringVar

func (f *FlagSet) StringVar(p *string, name string, value string, usage string) {
	f.VarP(newStringValue(value, p), name, "", usage)
}

最后走到,新建一个 Flag,然后加入到 FlagSet 中

func (f *FlagSet) VarPF(value Value, name, shorthand, usage string) *Flag {
	// Remember the default value as a string; it won't change.
	flag := &Flag{
		Name:      name,
		Shorthand: shorthand,
		Usage:     usage,
		Value:     value,
		DefValue:  value.String(),
	}
	f.AddFlag(flag)
	return flag
}

Flag 结构体,一个 FlagSet 对应多个 Flag

type Flag struct {
	Name                string              // name as it appears on command line
	Shorthand           string              // one-letter abbreviated flag
	Usage               string              // help message
	Value               Value               // value as set
	DefValue            string              // default value (as text); for usage message
	Changed             bool                // If the user set the value (or if left to default)
	NoOptDefVal         string              // default value (as text); if the flag is on the command line without any options
	Deprecated          string              // If this flag is deprecated, this string is the new or now thing to use
	Hidden              bool                // used by cobra.Command to allow flags to be hidden from help/usage text
	ShorthandDeprecated string              // If the shorthand of this flag is deprecated, this string is the new or now thing to use
	Annotations         map[string][]string // used by cobra.Command bash autocomple code
}

至此一个 flag 就加入到 command 中了.

再往下看

// 这里除了StringP 其余都与 上面的函数相同
rootCmd.PersistentFlags().StringP("author", "a", "YOUR NAME", "author name for copyright attribution")

不同点在于 shorthand 属性
举例
command create --name ferried
command create -n ferried
这里 --name 和 -n 分别对应 StringVar,StringP

再来重新对比一下三个 String 函数

StringP
StringVar
StringVarP

func (f *FlagSet) StringP(name, shorthand string, value string, usage string) *string {
	p := new(string)
	f.StringVarP(p, name, shorthand, value, usage)
	return p
}

func (f *FlagSet) StringVar(p *string, name string, value string, usage string) {
	f.VarP(newStringValue(value, p), name, "", usage)
}

func (f *FlagSet) StringVarP(p *string, name, shorthand string, value string, usage string) {
	f.VarP(newStringValue(value, p), name, shorthand, usage)
}

区别就在于 shorthand 和*string

再往下看

rootCmd.PersistentFlags().Bool

func (f *FlagSet) Bool(name string, value bool, usage string) *bool {
	return f.BoolP(name, "", value, usage)
}

func (f *FlagSet) BoolP(name, shorthand string, value bool, usage string) *bool {
	p := new(bool)
	f.BoolVarP(p, name, shorthand, value, usage)
	return p
}

func (f *FlagSet) BoolVarP(p *bool, name, shorthand string, value bool, usage string) {
	flag := f.VarPF(newBoolValue(value, p), name, shorthand, usage)
	flag.NoOptDefVal = "true"
}

func (f *FlagSet) VarPF(value Value, name, shorthand, usage string) *Flag {
	// Remember the default value as a string; it won't change.
	flag := &Flag{
		Name:      name,
		Shorthand: shorthand,
		Usage:     usage,
		Value:     value,
		DefValue:  value.String(),
	}
	f.AddFlag(flag)
	return flag
}

也是处理一下值的转换然后 shorhand 不同，加一个 Flag 结构体到 Command 的 pflag 中

再往下看

// 绑定 author ,第二个参数是 查找出的flag
viper.BindPFlag("author", rootCmd.PersistentFlags().Lookup("author"))

// lookup调用了FlagSet.lookup函数,传入了normalize配置的函数来 format一下flag的name
func (f *FlagSet) Lookup(name string) *Flag {
	return f.lookup(f.normalizeFlagName(name))
}
// 最后return 出去这个Flag
func (f *FlagSet) lookup(name NormalizedName) *Flag {
	return f.formal[name]
}
// 然后调用 Viper结构体中的BindPFlag
func BindPFlag(key string, flag *pflag.Flag) error { return v.BindPFlag(key, flag) }
func (v *Viper) BindPFlag(key string, flag *pflag.Flag) error {
	return v.BindFlagValue(key, pflagValue{flag})
}
// return error或者nil
func BindFlagValue(key string, flag FlagValue) error {
 return v.BindFlagValue(key, flag) 
}

func (v *Viper) BindFlagValue(key string, flag FlagValue) error {
	// 如果 flag为空
	if flag == nil {
		// 异常信息
		return fmt.Errorf("flag for %q is nil", key)
	}
	// 如果可以找到,那么viper的pflugs这个FlagSet[key]设置成flag结构体，返回nil
	v.pflags[strings.ToLower(key)] = flag
	return nil
}

再往下看

	// 绑定好了就可以设置默认值了
	viper.SetDefault("author", "NAME HERE <EMAIL ADDRESS>")
	viper.SetDefault("license", "apache")

看一下命令执行结果

然后看下面两条 cobra 下的子 command

rootCmd.AddCommand(addCmd)
rootCmd.AddCommand(initCmd)

addCmd

首先定义了一些变量

var (
	// string变量
	pkgName string
	// 一个Command
	initCmd = &cobra.Command{
		// 一些使用命令时的输出信息
		Use:     "init [name]",
		Aliases: []string{"initialize", "initialise", "create"},
		Short:   "Initialize a Cobra Application",
		Long: `Initialize (cobra init) will create a new application, with a license
and the appropriate structure for a Cobra-based CLI application.

  * If a name is provided, it will be created in the current directory;
  * If no name is provided, the current directory will be assumed;
  * If a relative path is provided, it will be created inside $GOPATH
    (e.g. github.com/spf13/hugo);
  * If an absolute path is provided, it will be created;
  * If the directory already exists but is empty, it will be used.

Init will not use an existing directory with contents.`,

		// 使用命令时实际运行的函数
		// 第一参为command结构体,第二参是传入的参数
		Run: func(cmd *cobra.Command, args []string) {

			wd, err := os.Getwd()
			if err != nil {
				er(err)
			}

			if len(args) > 0 {
				if args[0] != "." {
					wd = fmt.Sprintf("%s/%s", wd, args[0])
				}
			}

			project := &Project{
				AbsolutePath: wd,
				PkgName:      pkgName,
				Legal:        getLicense(),
				Copyright:    copyrightLine(),
				Viper:        viper.GetBool("useViper"),
				AppName:      path.Base(pkgName),
			}

			if err := project.Create(); err != nil {
				er(err)
			}

			fmt.Printf("Your Cobra application is ready at\n%s\n", project.AbsolutePath)
		},
	}