Documentation
¶
Overview ¶
Package cliparse implements subflux's flat CLI grammar: a single ParseAndValidate pass that splits "--key value" / "--key=value" tokens, rejects unknown flags (with typo suggestions) and stray positionals, parses bool flags from the spec table, validates typed values, enforces required flags, and applies spec defaults. It also renders per-command and root help.
The design choice is deliberate: the CLI surface is auxiliary to subflux's HTTP/JSON API and web UI, so a heavyweight CLI framework (kong, cobra) would be over-engineered for ~15 flat subcommands. This package closes the user-visible gaps (missing --help, silent typos, silent type errors) in roughly one file.
Index ¶
Constants ¶
const ( TypeString = "string" TypeInt = "int" TypeBool = "bool" TypeDuration = "duration" )
Flag type vocabulary for Flag.Type. An empty Type means TypeString.
Variables ¶
This section is empty.
Functions ¶
func HelpRequested ¶
HelpRequested returns true if args contains --help or -h. Call before invoking the parser so help short-circuits before validation runs.
func PrintRootHelp ¶
PrintRootHelp writes a list of all subcommands to w. specs are listed in the order provided; the caller may sort or filter (e.g. drop hidden subcommands like "health").
func SuggestName ¶
SuggestName finds the closest match in candidates (by Levenshtein distance, max 2) to input. Returns the matched name and true; or empty string and false when nothing within distance 2.
Used by main.go to suggest "did you mean 'search'?" when an unknown subcommand is invoked.
Types ¶
type Flag ¶
type Flag struct {
Name string
Help string
Type string // TypeString (default), TypeInt, TypeBool, TypeDuration
Default string
Required bool
}
Flag describes one CLI flag for a subcommand.
type Params ¶ added in v0.1.148
type Params struct {
// contains filtered or unexported fields
}
Params is the validated result of one ParseAndValidate pass: typed access to flag values with spec defaults applied. Bool flags live in their own set; every other flag is stored in its string form (typed flags were already validated as parseable).
func ParseAndValidate ¶ added in v0.1.148
ParseAndValidate parses args (the argv slice after the subcommand name, e.g. os.Args[2:]) against spec in a single pass: "--key value" and "--key=value" forms are split (the "=" form on the FIRST "=", so values may themselves contain "="), unknown flags are rejected with a "did you mean" suggestion, stray positional tokens are rejected, bool flags are parsed from the spec table (bare "--flag", or "--flag=true|false"), typed values (int, duration) are validated, required flags are enforced, and spec defaults are applied for absent flags.
Preserved edge semantics (pinned by tests): a trailing non-bool flag without a value is treated as unset (a required flag then errors), a non-bool flag whose next token starts with "--" is a missing-value error (the "--name=--literal" form is the escape hatch for intentional flag-like values), a duplicated flag keeps the last value, and "--help" / "-h" / bare "--" / empty-name "--=v" tokens are skipped (help short-circuits in the dispatch preamble before this parse runs).
type Spec ¶
type Spec struct {
// Run executes the subcommand with the parsed, validated params and
// returns the process exit code. Receiving Params keeps parsing to
// exactly one pass per invocation (a bare func() int would force
// runners to reparse os.Args).
Run func(Params) int
Name string // e.g. "search"
Synopsis string // one-line purpose, shown in root help
Help string // multi-line description for `<command> --help`
Args string // optional usage suffix, e.g. "<imdb-id>"
Flags []Flag
// Hidden excludes the spec from root help. Internal vehicles (the
// sync-worker child process) stay dispatchable without being
// advertised as user commands.
Hidden bool
}
Spec describes one subcommand: help metadata, the declared flag surface, and the runner dispatch invokes with the single parse's result.
func SortByName ¶
SortByName returns specs sorted alphabetically by Name. Useful before passing to PrintRootHelp.
Source Files