Documentation ¶
Overview ¶
Package start combines four common tasks for setting up an commandline application:
* Reading settings from a configuration file * Reading environment variables * Reading command line flags * Defining commands and subcommands
See the file README.md about usage of the start package.
Copyright (c) Christoph Berger. All rights reserved. Use of this source code is governed by the BSD (3-Clause) License that can be found in the LICENSE.txt file.
This source code may import third-party source code whose licenses are provided in the respective license files.
Index ¶
- Variables
- func Add(cmd *Command) error
- func ConfigFilePath() string
- func ConfigFileToml() toml.Document
- func External() func(cmd *Command) error
- func GetUserConfigDir() (dir string, exists bool)
- func Parse() error
- func Reparse() error
- func SetConfigFile(fn string)
- func SetDescription(descr string)
- func SetInitFunc(initf func() error)
- func SetVersion(ver string)
- func Up()
- func Usage(cmd *Command) error
- type Command
- type CommandMap
Constants ¶
This section is empty.
Variables ¶
var ( // Commands is the global command list. Commands = CommandMap{} // Note: I do explicitly make use of my right to use package-global variables. // First, this package acts like a Singleton. No accidental reuse can happen. // Second, these variables do not pollute the global name spaces, as they are // package variables and private. // These variables might get refactored into a struct at a later time. App string // app name )
Functions ¶
func Add ¶
Add adds a command to either the global Commands map, or, if the command has a parent value, to its parent command as a subcommand.
func ConfigFilePath ¶
func ConfigFilePath() string
ConfigFilePath returns the path of the config file that has been read in. Use after calling Up() or Parse(). Returns an empty path if no config file was found.
func ConfigFileToml ¶
func ConfigFileToml() toml.Document
ConfigFileToml returns the toml document created from the config file. Useful for fetching additional content from the config file than the one used by the flags.
func External ¶ added in v0.4.2
External defines an external command to execute via os/exec. The external command's name follows Git subcommmand naming convention: "mycmd do" invokes the external command "mycmd-do".
func GetUserConfigDir ¶ added in v0.4.2
GetUserConfigDir finds the user's config directory in an OS-independent way. "OS-independent" means compatible with most Unix-like operating systems as well as with Microsoft Windows(TM). The boolean return value indicates if the directory exists at the location determined via environment variables.
func Parse ¶
func Parse() error
Parse initializes all flag variables from command line flags, environment variables, configuration file entries, or default values. After this, each flag variable has a value either - - from a command line flag, or - from an environment variable, if the flag is not set, or - from an entry in the config file, if the environment variable is not set, or - from its default value, if there is no entry in the config file. Note: For better efficiency, Parse reads the config file and environment variables only once. Subsequent calls only parse the flags again, so you can call Parse() from multiple places in your code without actually repeating the complete parse process. Use Reparse() if you must execute the full parse process again. This behavior diverges from the behavior of flag.Parse(), which parses always.
func SetConfigFile ¶
func SetConfigFile(fn string)
SetConfigFile allows to set a custom file name and/or path. Call this before Parse() or Up(), respectively. Afterwards it has of course no effect.
func SetDescription ¶
func SetDescription(descr string)
SetDescription sets a description of the app. It receives a string containing a brief description of the application. If a user runs the application with no arguments, or if the user invokes the help command, Usage() will print this description string and list the available commands.
func SetInitFunc ¶
func SetInitFunc(initf func() error)
SetInitFunc sets a function that is called after parsing the variables but before calling the command. Useful for global initialization that affects all commands alike.
func SetVersion ¶
func SetVersion(ver string)
SetVersion sets the version number of the application. Used by the pre-defined version command.
func Usage ¶
Usage prints a description of the application and the short help string of every command, when called with a nil argument. When called with a command as parameter, Usage prints this command's long help string as well as the short help strings of the available subcommands. Parse() or Up() must be called before invoking Usage().
Types ¶
type Command ¶
type Command struct { Name string Parent string Flags []string Short string Long string Cmd func(cmd *Command) error Args []string Path string // contains filtered or unexported fields }
Command defines a command or a subcommand. Flags is a list of flag names that the command accepts. If a flag is passed to the command that the command does not accept, and if that flag is not among the global flags available for all commands, then Up() returns an error. If Flags is empty, all global flags are allowed. ShortHelp contains a short help string that is used in --help. LongHelp contains a usage description that is used in --help <command>. Cmd contains the function to execute. It receives the list of arguments (without the flags, which are parsed already). For commands with child commands, Cmd can be left empty. Args gets filled with all arguments, excluding flags. Path is an optional path to external executables that reside outside $PATH. To be used with the External() function.
type CommandMap ¶
CommandMap represents a list of Command objects.
func (*CommandMap) Add ¶
func (c *CommandMap) Add(cmd *Command) error
Add for CommandMap adds a command to a list of commands.