Documentation ¶
Index ¶
- func Run(runners ...Runner) error
- func RunCtx(ctx context.Context, runners ...Runner) error
- type BuildSetting
- type CLI
- func (cli *CLI[T]) GetVersionInfo() *VersionInfo[T]
- func (cli *CLI[T]) IsSet(options Options) bool
- func (cli *CLI[T]) Markdown(out io.Writer)
- func (cli *CLI[T]) Parse(options ...Options)
- func (cli *CLI[T]) ParseWithInit(initFn func() error, options ...Options) error
- func (cli *CLI[T]) Set(options ...Options)
- type Link
- type LoggerConfig
- type Module
- type NonSensitiveVersion
- type Options
- type Runner
- type VersionInfo
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type BuildSetting ¶
type BuildSetting struct { // Key and Value describe the build setting. // Key must not contain an equals sign, space, tab, or newline. // Value must not contain newlines ('\n'). Key string `json:"key"` Value string `json:"value"` }
BuildSetting describes a setting that may be used to understand how the binary was built. For example, VCS commit and dirty status is stored here.
func (BuildSetting) String ¶
func (s BuildSetting) String() string
type CLI ¶
type CLI[T any] struct { // Flags are the user-provided flags. Flags *T // Parser is the flags parser, this is only set after Parse() is called. // // NOTE: the "no-flag" struct field is required, otherwise the parser will parse // itself recursively, maxing out the stack. Parser *flags.Parser `no-flag:"true"` // VersionInfo is the version information for the CLI. You can provide // a custom version of this if you already have version information. VersionInfo *VersionInfo[T] `json:"version_info"` // Links are the links to the project's website, support, issues, security, // etc. This will be used in help and version output if provided. // Links are in the format of "name=url". Links []Link // Args are the remaining arguments after parsing. Args []string // Version can be used to print the version information to console. Use // NO_COLOR or FORCE_COLOR to change coloring. Version struct { Enabled bool `short:"v" long:"version" description:"prints version information and exits"` EnabledJSON bool `long:"version-json" description:"prints version information in JSON format and exits"` } // Debug can be used to enable/disable debugging as a global flag. Also // sets the log level to debug. Debug bool `short:"D" long:"debug" env:"DEBUG" description:"enables debug mode"` // GenerateMarkdown can be used to generate markdown documentation for // the cli. clix will intercept and output the documentation to stdout. GenerateMarkdown bool `long:"generate-markdown" hidden:"true" description:"generate markdown documentation and write to stdout" json:"-"` // Logger is the generated logger. Logger *log.Logger `json:"-"` LoggerConfig LoggerConfig `group:"Logging Options" namespace:"log" env-namespace:"LOG"` // contains filtered or unexported fields }
CLI is the main construct for clix. Do not manually set any fields until you've called Parse(). Initialize a new CLI like so:
var ( logger log.Interface cli = &clix.CLI[Flags]{} // Where Flags is a user-provided type (struct). ) type Flags struct { SomeFlag string `long:"some-flag" description:"some flag"` } // [...] cli.Parse(clix.OptDisableGlobalLogger|clix.OptDisableBuildSettings) logger = cli.Logger
Additional notes: * Use cli.Logger as a apex/log log.Interface (as shown above). * Use cli.Args to get the remaining arguments provided to the program.
func (*CLI[T]) GetVersionInfo ¶
func (cli *CLI[T]) GetVersionInfo() *VersionInfo[T]
GetVersionInfo returns the version information for the CLI.
func (*CLI[T]) Parse ¶
Parse executes the go-flags parser, returns the remaining arguments, as well as initializes a new logger. If cli.Version is set, it will print the version information (unless disabled).
func (*CLI[T]) ParseWithInit ¶
ParseWithInit executes the go-flags parser with the provided init function, returns the remaining arguments, as well as initializes a new logger. If cli.Version is set, it will print the version information (unless disabled).
Prefer using Parse() unless you're using sub-commands and want to run some initialization logic before the sub-command if invoked.
type Link ¶
Link allows you to define a link to be included in the version and usage output.
func GithubLinks ¶
GithubLinks return an opinonated set of links for the project, using common Github layout conventions.
type LoggerConfig ¶
type LoggerConfig struct { // Quiet disables all logging. Quiet bool `env:"QUIET" long:"quiet" description:"disable logging to stdout (also: see levels)"` // Level is the minimum level of log messages to output, must be one of info|warn|error|debug|fatal. Level string `` /* 140-byte string literal not displayed */ // JSON enables JSON logging. JSON bool `env:"JSON" long:"json" description:"output logs in JSON format"` // Github enables GitHub Actions logging. Github bool `env:"GITHUB" long:"github" description:"output logs in GitHub Actions format"` // Pretty enables cli-friendly logging. Pretty bool `env:"PRETTY" long:"pretty" description:"output logs in a pretty colored format (cannot be easily parsed)"` // Path is the path to the log file. Path string `env:"PATH" long:"path" description:"path to log file (disables stdout logging)"` }
LoggerConfig are the flags that define how log entries are processed/returned. If using github.com/jessevdk/go-flags, you can defined a LoggerConfig in your struct, and then call LoggerConfig.New(isDebug), directly, so you don't have to define additional flags. See the struct tags for what it will default to in terms of environment variables.
Example (where you can set LOG_LEVEL as an environment variable, for example):
type Flags struct { Debug bool `long:"debug" env:"DEBUG" description:"enable debugging"` Log *chix.LoggerConfig `group:"Logging Options" namespace:"log" env-namespace:"LOG"` } [...] cli.Log.New(cli.Debug)
type Module ¶
type Module struct { Path string `json:"path,omitempty"` // module path Version string `json:"version,omitempty"` // module version Sum string `json:"sum,omitempty"` // checksum Replace *Module `json:"replaces,omitempty"` // replaced by this module }
Module represents a module.
type NonSensitiveVersion ¶
type NonSensitiveVersion struct { Name string `json:"name"` // Name of cli tool. Version string `json:"build_version"` // Build version. Commit string `json:"build_commit"` // VCS commit SHA. Date string `json:"build_date"` // VCS commit date. Command string `json:"command"` // Executable name where the command was called from. GoVersion string `json:"go_version"` // Version of Go that produced this binary. OS string `json:"os"` // Operating system for this build. Arch string `json:"arch"` // CPU Architecture for build build. // Items hoisted from the parent CLI. Do not change this. Links []Link `json:"links,omitempty"` }
NonSensitiveVersion represents the version information for the CLI.
type Options ¶
type Options int
Options allows overriding default logic.
const ( OptDisableLogging Options = 1 << iota // Disable logging initialization. OptDisableVersion // Disable version printing (must handle manually). OptDisableDeps // Disable dependency printing in version output. OptDisableBuildSettings // Disable build info printing in version output. OptDisableGlobalLogger // Disable setting the global logger for apex/log. OptSubcommandsOptional // Subcommands are optional. )
type VersionInfo ¶
type VersionInfo[T any] struct { Name string `json:"name"` // Name of cli tool. Version string `json:"build_version"` // Build version. Commit string `json:"build_commit"` // VCS commit SHA. Date string `json:"build_date"` // VCS commit date. Settings []BuildSetting `json:"build_settings,omitempty"` // Other information about the build. Dependencies []Module `json:"dependencies,omitempty"` // Module dependencies. Command string `json:"command"` // Executable name where the command was called from. GoVersion string `json:"go_version"` // Version of Go that produced this binary. OS string `json:"os"` // Operating system for this build. Arch string `json:"arch"` // CPU Architecture for build build. // Items hoisted from the parent CLI. Do not change this. Links []Link `json:"links,omitempty"` // contains filtered or unexported fields }
VersionInfo represents the version information for the CLI.
func (*VersionInfo[T]) GetSetting ¶
func (v *VersionInfo[T]) GetSetting(key, defaultValue string) string
GetSetting returns the value of the setting with the given key, otherwise defaults to defaultValue.
func (*VersionInfo[T]) NonSensitive ¶
func (v *VersionInfo[T]) NonSensitive() *NonSensitiveVersion
NonSensitive returns a copy of VersionInfo with sensitive information removed.
func (*VersionInfo[T]) String ¶
func (v *VersionInfo[T]) String() string