cli

package
v0.0.10 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 14, 2024 License: BSD-3-Clause Imports: 20 Imported by: 30

README

cli

Package cli generates powerful CLIs from Go struct types and functions. See package cliview to create a GUI representation of a CLI.

cli provides methods to set values on a Config struct through a (TOML) config file or command-line args (flags in Go terminology), with support for setting Network params and values on any other struct as well (e.g., an Env to be constructed later in a ConfigEnv method).

  • Standard usage:

    • cfg := &ss.Config
    • cfg.Defaults() -- sets hard-coded defaults -- user should define and call this method first.
    • It is better to use the default: field tag however because it then shows in -h or --help usage and in the Cogent Core GUI. See Default Tags for how to specify def values for more complex types.
    • cli.Config(cfg, "config.toml") -- sets config values according to the standard order, with given file name specifying the default config file name.

  • Has support for nested Include paths, which are processed in the natural deepest-first order. The processed Config struct field will contain a list of all such files processed. Config must implement the IncludesPtr() *[]string method which satisfies the Includer interface, and returns a pointer to an Includes []string field containing a list of config files to include. The default IncludePaths includes current dir (.) and configs directory, which is recommended location to store different configs.

  • Order of setting in cli.Config:

    • Apply any default: field tag default values.
    • Look for --config, --cfg arg, specifying config file(s) on the command line (comma separated if multiple, with no spaces).
    • Fall back on default config file name passed to Config function, if arg not found.
    • Read any Include[s] files in config file in deepest-first (natural) order, then the specified config file last -- includee overwrites included settings.
    • Process command-line args based on Config field names, with . separator for sub-fields.

  • All field name references in toml files and command-line args are case-insensitive. For args (flags) kebab-case (with either - or _ delimiter) can be used. For bool args, use "No" prefix in any form (e.g., "NoRunLog" or "no-run-log"). Instead of polluting the flags space with all the different options, custom args processing code is used.

  • Args in sub-structs are automatically available with just the field name and also nested within the name of the parent struct field -- for example, -Run.NEpochs and just -NEpochs (or -nepochs lowercase). Use nest:"+" to force a field to only be available in its nested form, in case of conflict of names without nesting (which are logged).

  • Is a replacement for ecmd and includes the helper methods for saving log files etc.

  • A map[string]any type can be used for deferred raw params to be applied later (Network, Env etc). Example: Network = {'.PFCLayer:Layer.Inhib.Layer.Gi' = '2.4', '#VSPatchPrjn:Prjn.Learn.LRate' = '0.01'} where the key expression contains the params selector : path to variable.

  • Supports full set of Open (file), OpenFS (takes fs.FS arg, e.g., for embedded), Read (bytes) methods for loading config files. The overall Config() version uses OpenWithIncludes which processes includes -- others are just for single files. Also supports Write and Save methods for saving from current state.

  • If needed, different config file encoding formats can be supported, with TOML being the default (currently only TOML).

Special fields, supported types, and field tags

  • To enable include file processing, add a Includes []string field and a func (cfg *Config) IncludesPtr() *[]string { return &cfg.Includes } method. The include file(s) are read first before the current one. A stack of such includes is created and processed in the natural order encountered, so each includer is applied after the includees, recursively. Note: use --config to specify the first config file read -- the Includes field is excluded from arg processing because it would be processed after the point where include files are processed.

  • Field map[string]any -- allows raw parsing of values that can be applied later. Use this for Network, Env etc fields.

  • Field tag default:"value", used in the Cogent Core GUI, sets the initial default value and is shown for the -h or --help usage info.

  • enums registered "enum" const types, with names automatically parsed from string values (including bit flags).

default Default Tags

The Cogent Core GUI processes default:"value" struct tags to highlight values that are not at their defaults. cli uses these same tags to auto-initialize fields as well, ensuring that the tag and the actual initial value are the same. The value for strings or numbers is just the string representation. For more complex types, here ar some examples:

  • struct: specify using standard Go literal expression as a string, with single-quotes ' used instead of double-quotes around strings, such as t he name of the fields:

    • evec.Vector2i: default:"{'X':10,'Y':10}"

  • slice: comma-separated list of values in square braces -- use ' for internal string boundaries:

    • []float32: default:"[1, 2.14, 3.14]"
    • []string: default:"{'A', 'bbb bbb', 'c c c'}"

  • map: comma-separated list of key:value in curly braces -- use ' for internal string boundaries:

    • map[string]float32: default:"{'key1': 1, 'key2': 2.14, 'key3': 3.14]"

Standard Config Example

Here's the Config struct from axon/examples/ra25, which can provide a useful starting point. It uses Params, Run and Log sub-structs to better organize things. For sims with extensive Env config, that should be added as a separate sub-struct as well. The view:"add-fields" struct tag shows all of the fields in one big dialog in the GUI -- if you want separate ones, omit that.

// ParamConfig has config parameters related to sim params
type ParamConfig struct {
	Network map[string]any `desc:"network parameters"`
	Set     string         `desc:"ParamSet name to use -- must be valid name as listed in compiled-in params or loaded params"`
	File    string         `desc:"Name of the JSON file to input saved parameters from."`
	Tag     string         `desc:"extra tag to add to file names and logs saved from this run"`
	Note    string         `desc:"user note -- describe the run params etc -- like a git commit message for the run"`
	SaveAll bool           `desc:"Save a snapshot of all current param and config settings in a directory named params_<datestamp> then quit -- useful for comparing to later changes and seeing multiple views of current params"`
}

// RunConfig has config parameters related to running the sim
type RunConfig struct {
	GPU          bool   `default:"true" desc:"use the GPU for computation -- generally faster even for small models if NData ~16"`
	Threads      int    `default:"0" desc:"number of parallel threads for CPU computation -- 0 = use default"`
	Run          int    `default:"0" desc:"starting run number -- determines the random seed -- runs counts from there -- can do all runs in parallel by launching separate jobs with each run, runs = 1"`
	Runs         int    `default:"5" min:"1" desc:"total number of runs to do when running Train"`
	Epochs       int    `default:"100" desc:"total number of epochs per run"`
	NZero        int    `default:"2" desc:"stop run after this number of perfect, zero-error epochs"`
	NTrials      int    `default:"32" desc:"total number of trials per epoch.  Should be an even multiple of NData."`
	NData        int    `default:"16" min:"1" desc:"number of data-parallel items to process in parallel per trial -- works (and is significantly faster) for both CPU and GPU.  Results in an effective mini-batch of learning."`
	TestInterval int    `default:"5" desc:"how often to run through all the test patterns, in terms of training epochs -- can use 0 or -1 for no testing"`
	PCAInterval  int    `default:"5" desc:"how frequently (in epochs) to compute PCA on hidden representations to measure variance?"`
	StartWts     string `desc:"if non-empty, is the name of weights file to load at start of first run -- for testing"`
}

// LogConfig has config parameters related to logging data
type LogConfig struct {
	SaveWts   bool `desc:"if true, save final weights after each run"`
	Epoch     bool `default:"true" desc:"if true, save train epoch log to file, as .epc.tsv typically"`
	Run       bool `default:"true" desc:"if true, save run log to file, as .run.tsv typically"`
	Trial     bool `default:"false" desc:"if true, save train trial log to file, as .trl.tsv typically. May be large."`
	TestEpoch bool `default:"false" desc:"if true, save testing epoch log to file, as .tst_epc.tsv typically.  In general it is better to copy testing items over to the training epoch log and record there."`
	TestTrial bool `default:"false" desc:"if true, save testing trial log to file, as .tst_trl.tsv typically. May be large."`
	NetData   bool `desc:"if true, save network activation etc data from testing trials, for later viewing in netview"`
}

// Config is a standard Sim config -- use as a starting point.
type Config struct {
	Includes []string    `desc:"specify include files here, and after configuration, it contains list of include files added"`
	GUI      bool        `default:"true" desc:"open the GUI -- does not automatically run -- if false, then runs automatically and quits"`
	Debug    bool        `desc:"log debugging information"`
	Params   ParamConfig `view:"add-fields" desc:"parameter related configuration options"`
	Run      RunConfig   `view:"add-fields" desc:"sim running related configuration options"`
	Log      LogConfig   `view:"add-fields" desc:"data logging related configuration options"`
}

func (cfg *Config) IncludesPtr() *[]string { return &cfg.Includes }

Key design considerations

  • Can set config values from command-line args and/or config file (TOML being the preferred format) (or env vars)

    • current axon models only support args. obelisk models only support TOML. conflicts happen.

  • Sims use a Config struct with fields that represents the definitive value of all arg / config settings (vs a map[string]any)

    • struct provides compile time error checking (and IDE completion) -- very important and precludes map.
    • Add Config to Sim so it is visible in the GUI for easy visual debugging etc (current args map is organized by types -- makes it hard to see everything).

  • Enable setting Network or Env params directly:

    • Use Network., Env., TrainEnv., TestEnv. etc prefixes followed by standard params selectors (e.g., Layer.Act.Gain) or paths to fields in relevant env. These can be added to Config as map[string]any and then applied during ConfigNet, ConfigEnv etc.

  • TOML Go implementations are case insensitive (TOML spec says case sensitive..) -- makes sense to use standard Go CamelCase conventions as in every other Go struct.

Documentation

Overview

Package cli generates powerful CLIs from Go struct types and functions. See package cliview to create a GUI representation of a CLI.

Index

Constants

View Source 
const (
	// ErrNotFound can be passed to [SetFromArgs] and [ParseFlags]
	// to indicate that they should return an error for a flag that
	// is set but not found in the configuration struct.
	ErrNotFound = true
	// ErrNotFound can be passed to [SetFromArgs] and [ParseFlags]
	// to indicate that they should NOT return an error for a flag that
	// is set but not found in the configuration struct.
	NoErrNotFound = false
)
View Source 
const AddAllFields = "*"

AddAllFields, when passed as the command to AddFields, indicates to add all fields, regardless of their command association.

Variables

View Source 
var ConfigFiles []string

ConfigFile are the names of the config file actually loaded, specified by the -config or -cfg command-line arg or the default file given in [Options.DefaultFiles]

View Source 
var Indent = "    "

Indent is the value used for indentation in Usage.

View Source 
var MetaCmds = []*Cmd[*MetaConfig]{
	{
		Func: func(mc *MetaConfig) error { return nil },
		Name: "help",
		Doc:  "show usage information for a command",
		Root: true,
	},
}

MetaCmds is a set of commands based on MetaConfig that contains a shell implementation of the help command. In almost all circumstances, it should only be used internally and not by end-user code.

Functions

func AddAllCases 

func AddAllCases(nm string, field *Field, allFlags *Fields)

AddAllCases adds all string cases (kebab-case, snake_case, etc) of the given field with the given name to the given set of flags.

func AddFields 

func AddFields(obj any, allFields *Fields, cmd string)

AddFields adds to the given fields map all of the fields of the given object, in the context of the given command name. A value of AddAllFields for cmd indicates to add all fields, regardless of their command association.

func AddFieldsImpl 

func AddFieldsImpl(obj any, path string, cmdPath string, allFields *Fields, usedNames map[string]*Field, cmd string)

AddFieldsImpl is the underlying implementation of AddFields. AddFieldsImpl should almost never be called by end-user code; see AddFields instead. The path is the current path state, the cmdPath is the current path state without command-associated names, and usedNames is a map keyed by used CamelCase names with values of their associated fields, used to track naming conflicts. The [Field.Name]s of the fields are set based on the path, whereas the names of the flags are set based on the command path. The difference between the two is that the path is always fully qualified, whereas the command path omits the names of structs associated with commands via the "cmd" struct tag, as the user already knows what command they are running, so they do not need that duplicated specificity for every flag.

func AddFlags 

func AddFlags(allFields *Fields, allFlags *Fields, args []string, flags map[string]string) ([]string, error)

AddFlags adds to given the given ordered flags map all of the different ways all of the given fields can can be specified as flags. It also uses the given positional arguments to set the values of the object based on any posarg struct tags that fields have. The posarg struct tag must either be "all" or a valid uint. Finally, it also uses the given map of flags passed to the command as context.

func AddMetaConfigFields 

func AddMetaConfigFields(allFields *Fields)

AddMetaConfigFields adds meta fields that control the config process to the given map of fields. These fields have no actual effect and map to a placeholder value because they are handled elsewhere, but they must be set to prevent errors about missing flags. The flags that it adds are those in MetaConfig.

func AllCases 

func AllCases(nm string) []string

AllCases returns all of the string cases (kebab-case, snake_case, etc) of the given name.

func ApplyShortestUniqueName 

func ApplyShortestUniqueName(field *Field, idx int, usedNames map[string]*Field)

ApplyShortestUniqueName uses ShortestUniqueName to apply the shortest unique name for the given field, in the context of the given used names, at the given index. It should not typically be used by end-user code.

func BoolFlags 

func BoolFlags(obj any) map[string]bool

BoolFlags returns a map with a true value for every flag name that maps to a boolean field. This is needed so that bool flags can be properly set with their shorthand syntax. It should only be needed for internal use and not end-user code.

func CmdName 

func CmdName() string

CmdName returns the name of the command currently being run.

func CommandUsage 

func CommandUsage[T any](b *strings.Builder, cmdName string, cmd string, cmds ...*Cmd[T])

CommandUsage adds the command usage info for the given commands to the given strings.Builder. Typically, end-user code should use Usage instead. It also takes the full name of our command as it appears in the terminal (cmdName), (eg: "core build"), and the name of the command we are running (eg: "build").

To be a command that is included in the usage, we must be one command nesting depth (subcommand) deeper than the current command (ie, if we are on "x", we can see usage for commands of the form "x y"), and all of our commands must be consistent with the current command. For example, "" could generate usage for "help", "build", and "run", and "mod" could generate usage for "mod init", "mod tidy", and "mod edit". This ensures that only relevant commands are shown in the usage.

func Config 

func Config[T any](opts *Options, cfg T, cmds ...*Cmd[T]) (string, error)

Config is the main, high-level configuration setting function, processing config files and command-line arguments in the following order:

  • Apply any `default:` field tag default values.
  • Look for `--config`, `--cfg`, or `-c` arg, specifying a config file on the command line.
  • Fall back on default config file name passed to `Config` function, if arg not found.
  • Read any `Include[s]` files in config file in deepest-first (natural) order, then the specified config file last.
  • If multiple config files are found, then they are applied in reverse order, meaning that the first specified file takes the highest precedence.
  • Process command-line args based on Config field names.
  • Boolean flags are set on with plain -flag; use No prefix to turn off (or explicitly set values to true or false).

Config also processes -help and -h by printing the Usage and quitting immediately. It takes Options that control its behavior, the configuration struct, which is what it sets, and the commands, which it uses for context. Also, it uses os.Args for its command-line arguments. It returns the command, if any, that was passed in os.Args, and any error that ocurred during the configuration process.

func FlagUsage 

func FlagUsage(fields *Fields, b *strings.Builder)

FlagUsage adds the flag usage info for the given fields to the given strings.Builder. Typically, end-user code should use Usage instead.

func GetArgs 

func GetArgs(args []string, boolFlags map[string]bool) ([]string, map[string]string, error)

GetArgs processes the given args using the given map of bool flags, which should be obtained through BoolFlags. It returns the leftover (positional) args, the flags, and any error.

func GetFlag 

func GetFlag(s string, args []string, boolFlags map[string]bool) (name, value string, a []string, err error)

GetFlag parses the given flag arg string in the context of the given remaining arguments and bool flags. It returns the name of the flag, the value of the flag, the remaining arguments updated with any changes caused by getting this flag, and any error. It is designed for use in GetArgs and should typically not be used by end-user code.

func IncludeStack 

func IncludeStack(opts *Options, cfg Includer) ([]string, error)

IncludeStack returns the stack of include files in the natural order in which they are encountered (nil if none). Files should then be read in reverse order of the slice. Returns an error if any of the include files cannot be found on IncludePath. Does not alter cfg. It typically should not be used by end-user code.

func Open 

func Open(cfg any, file string) error

OpenFS reads the given config object from the given file.

func OpenFS 

func OpenFS(cfg any, fsys fs.FS, file string) error

OpenFS reads the given config object from given file, using the given fs.FS filesystem (e.g., for embed files).

func OpenWithIncludes 

func OpenWithIncludes(opts *Options, cfg any, file string) error

OpenWithIncludes reads the config struct from the given config file using the given options, looking on [Options.IncludePaths] for the file. It opens any Includes specified in the given config file in the natural include order so that includers overwrite included settings. Is equivalent to Open if there are no Includes. It returns an error if any of the include files cannot be found on [Options.IncludePaths].

func ParseArgsImpl 

func ParseArgsImpl[T any](cfg T, baseArgs []string, baseCmd string, cmds ...*Cmd[T]) (args []string, cmd string, err error)

ParseArgsImpl is the underlying implementation of ParseArgs that is called recursively and takes most of what ParseArgs does, plus the current command state, and returns most of what ParseArgs does, plus the args state. It should typically not be used by end-user code.

func ParseDirective 

func ParseDirective(comment string) (*types.Directive, error)

ParseDirective parses and returns a comment directive from the given comment string. The returned directive will be nil if there is no directive contained in the given comment. Directives are of the following form (the slashes are optional): 

//tool:directive args...

func ParseFlag 

func ParseFlag(name string, value string, allFlags *Fields, errNotFound bool) error

ParseFlag parses the flag with the given name and the given value using the given map of all of the available flags, setting the value in that map corresponding to the flag name accordingly. Setting errNotFound = true causes passing a flag name that is not in allFlags to trigger an error; otherwise, it just does nothing and returns no error. It is recommended that the ErrNotFound and NoErrNotFound constants be used for the value of errNotFound for clearer code. ParseFlag is designed for use in ParseFlags and should typically not be used by end-user code.

func ParseFlags 

func ParseFlags(flags map[string]string, allFlags *Fields, errNotFound bool) error

ParseFlags parses the given flags using the given ordered map of all of the available flags, setting the values from that map accordingly. Setting errNotFound to true causes flags that are not in allFlags to trigger an error; otherwise, it just skips those. It is recommended that the ErrNotFound and NoErrNotFound constants be used for the value of errNotFound for clearer code. Also, the flags should be gotten through GetArgs first, and the map of available flags should be gotten through ParseArgs first.

func Run 

func Run[T any, C CmdOrFunc[T]](opts *Options, cfg T, cmds ...C) error

Run runs an app with the given options, configuration struct, and commands. It does not run the GUI; see cogentcore.org/core/cliview.Run for that. The configuration struct should be passed as a pointer, and configuration options should be defined as fields on the configuration struct. The commands can be specified as either functions or struct objects; the functions are more concise but require using types. In addition to the given commands, Run adds a "help" command that prints the result of Usage, which will also be the root command if no other root command is specified. Also, it adds the fields in MetaConfig as configuration options. If [Options.Fatal] is set to true, the error result of Run does not need to be handled. Run uses os.Args for its arguments.

func RunCmd 

func RunCmd[T any](opts *Options, cfg T, cmd string, cmds ...*Cmd[T]) error

RunCmd runs the command with the given name using the given options, configuration information, and available commands. If the given command name is "", it runs the root command.

func Save 

func Save(cfg any, file string) error

Save writes the given config object to the given file. It only saves the non-default fields of the given object, as specified by reflectx.NonDefaultFields.

func SetFieldValue 

func SetFieldValue(f *Field, value string) error

SetFieldValue sets the value of the given configuration field to the given string argument value.

func SetFromArgs 

func SetFromArgs[T any](cfg T, args []string, errNotFound bool, cmds ...*Cmd[T]) (string, error)

SetFromArgs sets config values on the given config object from the given from command-line args, based on the field names in the config struct and the given list of available commands. It returns the command, if any, that was passed in the arguments, and any error than occurs during the parsing and setting process. If errNotFound is set to true, it is assumed that all flags (arguments starting with a "-") must refer to fields in the config struct, so any that fail to match trigger an error. It is recommended that the ErrNotFound and NoErrNotFound constants be used for the value of errNotFound for clearer code.

func SetFromDefaults 

func SetFromDefaults(cfg any) error

SetFromDefaults sets the values of the given config object from `default:` field tag values. Parsing errors are automatically logged.

func ShortestUniqueName 

func ShortestUniqueName(name string, usedNames map[string]*Field) string

ShortestUniqueName returns the shortest unique camel-case name for the given fully-qualified nest name of a field, using the given map of used names. It works backwards, so, for example, if given "A.B.C.D", it would check "D", then "C.D", then "B.C.D", and finally "A.B.C.D". It should not typically be used by end-user code.

func Usage 

func Usage[T any](opts *Options, cfg T, cmd string, cmds ...*Cmd[T]) string

Usage returns a usage string based on the given options, configuration struct, current command, and available commands. It contains [AppAbout], a list of commands and their descriptions, and a list of flags and their descriptions, scoped based on the current command and its associated commands and configuration. The resulting string contains color escape codes.

Types

type Cmd 

type Cmd[T any] struct {
	// Func is the actual function that runs the command.
	// It takes configuration information and returns an error.
	Func func(T) error
	// Name is the name of the command.
	Name string
	// Doc is the documentation for the command.
	Doc string
	// Root is whether the command is the root command
	// (what is called when no subcommands are passed)
	Root bool
	// Icon is the icon of the command in the tool bar
	// when running in the GUI via cliview
	Icon string
	// SepBefore is whether to add a separator before the
	// command in the tool bar when running in the GUI via cliview
	SepBefore bool
	// SepAfter is whether to add a separator after the
	// command in the tool bar when running in the GUI via cliview
	SepAfter bool
}

Cmd represents a runnable command with configuration options. The type constraint is the type of the configuration information passed to the command.

func AddCmd 

func AddCmd[T any](cmds []*Cmd[T], cmd *Cmd[T]) []*Cmd[T]

AddCmd adds the given command to the given set of commands if there is not already a command with the same name in the set of commands. Also, if [Cmd.Root] is set to true on the passed command, and there are no other root commands in the given set of commands, the passed command will be made the root command; otherwise, it will be made not the root command.

func CmdFromCmdOrFunc 

func CmdFromCmdOrFunc[T any, C CmdOrFunc[T]](cmd C) (*Cmd[T], error)

CmdFromCmdOrFunc returns a new Cmd object from the given CmdOrFunc object, using CmdFromFunc if it is a function.

func CmdFromFunc 

func CmdFromFunc[T any](fun func(T) error) (*Cmd[T], error)

CmdFromFunc returns a new Cmd object from the given function and any information specified on it using comment directives, which requires the use of types.

func CmdsFromCmdOrFuncs 

func CmdsFromCmdOrFuncs[T any, C CmdOrFunc[T]](cmds []C) ([]*Cmd[T], error)

CmdsFromCmdOrFuncs is a helper function that returns a slice of command objects from the given slice of CmdOrFunc objects, using CmdFromCmdOrFunc.

func CmdsFromFuncs 

func CmdsFromFuncs[T any](funcs []func(T) error) ([]*Cmd[T], error)

CmdsFromFuncs is a helper function that returns a slice of command objects from the given slice of command functions, using CmdFromFunc.

type CmdOrFunc 

type CmdOrFunc[T any] interface {
	*Cmd[T] | func(T) error
}

CmdOrFunc is a generic type constraint that represents either a *Cmd with the given config type or a command function that takes the given config type and returns an error.

type Field 

type Field struct {
	// Field is the reflect struct field object for this field
	Field reflect.StructField
	// Value is the reflect value of the settable pointer to this field
	Value reflect.Value
	// Struct is the parent struct that contains this field
	Struct reflect.Value
	// Name is the fully qualified, nested name of this field (eg: A.B.C).
	// It is as it appears in code, and is NOT transformed something like kebab-case.
	Name string
	// Names contains all of the possible end-user names for this field as a flag.
	// It defaults to the name of the field, but custom names can be specified via
	// the cli struct tag.
	Names []string
}

Field represents a struct field in a configuration struct. It is passed around in flag parsing functions, but it should not typically be used by end-user code going through the standard Run/Config/SetFromArgs API.

type Fields 

type Fields = ordmap.Map[string, *Field]

Fields is a simple type alias for an ordered map of Field objects.

func ParseArgs 

func ParseArgs[T any](cfg T, args []string, flags map[string]string, cmds ...*Cmd[T]) (cmd string, allFlags *Fields, err error)

ParseArgs parses the given non-flag arguments in the context of the given configuration struct, flags, and commands. The non-flag arguments and flags should be gotten through GetArgs first. It returns the command specified by the arguments, an ordered map of all of the flag names and their associated field objects, and any error.

type Includer 

type Includer interface {
	// IncludesPtr returns a pointer to the "Includes []string"
	// field containing file(s) to include before processing
	// the current config file.
	IncludesPtr() *[]string
}

Includer is an interface that facilitates processing include files in configuration objects. It typically should not be used by end-user code.

type MetaConfig 

type MetaConfig struct {
	// the file name of the config file to load
	Config string `flag:"cfg,config"`

	// whether to display a help message
	Help bool `flag:"h,help"`

	// the name of the command to display
	// help information for. It is only applicable to the
	// help command, but it is enabled for all commands so
	// that it can consume all positional arguments to prevent
	// errors about unused arguments.
	HelpCmd string `posarg:"all"`

	// whether to run the command in verbose mode
	// and print more information
	Verbose bool `flag:"v,verbose"`

	// whether to run the command in very verbose mode
	// and print as much information as possible
	VeryVerbose bool `flag:"vv,very-verbose"`

	// whether to run the command in quiet mode
	// and print less information
	Quiet bool `flag:"q,quiet"`
}

MetaConfig contains meta configuration information specified via command line arguments that controls the initial behavior of cli for all apps before anything else is loaded. Its main purpose is to support the help command and flag and the specification of custom config files on the command line. In almost all circumstances, it should only be used internally and not by end-user code.

type OnConfigurer 

type OnConfigurer interface {
	OnConfig(cmd string) error
}

OnConfigurer represents a configuration object that specifies a method to be called at the end of the Config function, with the command that has been parsed as an argument.

type Options 

type Options struct {

	// AppName is the name of the cli app.
	AppName string

	// AppAbout is the description of the cli app.
	AppAbout string

	// Fatal is whether to, if there is an error in [Run],
	// print it and fatally exit the program through [os.Exit]
	// with an exit code of 1.
	Fatal bool

	// PrintSuccess is whether to print a message indicating
	// that a command was successful after it is run, unless
	// the user passes -q or -quiet to the command, in which
	// case the success message will always not be printed.
	PrintSuccess bool

	// DefaultEncoding is the default encoding format for config files.
	// currently toml is the only supported format, but others could be added
	// if needed.
	DefaultEncoding string

	// DefaultFiles are the default configuration file paths
	DefaultFiles []string

	// IncludePaths is a list of file paths to try for finding config files
	// specified in Include field or via the command line --config --cfg or -c args.
	// Set this prior to calling Config; default is current directory '.' and 'configs'.
	// The include paths are searched in reverse order such that first specified include
	// paths get the highest precedence (config files found in earlier include paths
	// override those found in later ones).
	IncludePaths []string

	// SearchUp indicates whether to search up the filesystem
	// for the default config file by checking the provided default
	// config file location relative to each directory up the tree
	SearchUp bool

	// NeedConfigFile indicates whether a configuration file
	// must be provided for the command to run
	NeedConfigFile bool
}

Options contains the options passed to cli that control its behavior.

func DefaultOptions 

func DefaultOptions(name string, about ...string) *Options

DefaultOptions returns a new Options value with standard default values, based on the given app name and optional app about info.

Source Files

View all Source files

Directories

Path Synopsis
examples
basic

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.