Documentation
¶
Overview ¶
Package verbflag is the one seam every living tool's verbs parse their flags through, so help and the CLI standard hold the same way for every verb. A parse error comes back from Parse unchanged, so the verb prints its own one-line refusal, worded by Explain. -h, -help or --help on a flag set that does not define them is HELP, not a mistake: it unwinds to the dispatcher's deferred Recover, which prints that verb's help on stdout (its lines from the tool's own help text, then every flag the set defines) and exits 0. Nothing but flag parsing has run by then: no file read, no store dial, no write.
Index ¶
- Constants
- func Asked(args []string) bool
- func BoolAsked(args []string, name string) bool
- func BoolGiven(fs *flag.FlagSet, args []string, name string) bool
- func Excerpt(banner, prog, verb string) []string
- func Explain(fs *flag.FlagSet, err error) string
- func FlagSynopsis(fs *flag.FlagSet) string
- func HelpIfAsked(args []string, name string, flags ...Flag)
- func Insert(help, lines string) string
- func IsHelp(a string) bool
- func List(names []string) string
- func Nearest(got string, names []string) string
- func New(name string) *flag.FlagSet
- func Parse(fs *flag.FlagSet, args []string) error
- func Print(out io.Writer, prog, banner string, fs *flag.FlagSet, exit ...string)
- func RecoverWith(out io.Writer, prog, banner string, code *int, extra func(verb string) string)
- func Subverbs(banner, prog, verb string) []string
- func UsageLine(prog, verb string, subs []string) string
- func UsageLineSynopsis(prog, verb string, subs []string, synopsis string) string
- func Verb(prog string, fs *flag.FlagSet) string
- type Flag
- type Help
Constants ¶
const ListMax = 16
ListMax bounds a list of names in a refusal to one readable line; help lists the rest.
Variables ¶
This section is empty.
Functions ¶
func Asked ¶
Asked reports whether args hold -h, -help or --help before any --: the question a process-boundary check (a PATH or home read before the dispatcher) asks so that it can stand aside for help.
func BoolAsked ¶
BoolAsked reports whether args set the boolean flag name (-name, --name, or =true) before any --: the question a dispatcher asks of a flag it must honour before a flag set has parsed, such as --json on a refusal.
func BoolGiven ¶
BoolGiven reports whether args set the boolean flag name of fs, read as the flag package reads them, so it holds when the parse stopped at an error (a refusal asked for as --json is rendered as JSON): a flag fs defines with a value takes the next word, whatever it looks like (`--store --json` gives --store the value --json); `--name=v` is v; the terminator `--` and the first argument end the flags. A flag fs does not define is passed over, and a word after it that is not a flag ends the reading, since that word is its value or the first argument and nothing after it is surely a flag.
func Excerpt ¶
Excerpt returns the lines of banner that speak for `<prog> <verb>`: every line whose words begin with the tool and the verb's words (its usage synopses and its examples), each with the more-indented lines that continue it, left-trimmed, in order, each once. "" for the verb quotes nothing.
func Explain ¶
Explain words a parse error from fs (Parse's, or fs.Parse's) for an AI that has only the help and acts on one reading: an unknown flag is named with the flags of the verb and the nearest of them, a flag missing its value and a value its flag cannot take with what that flag wants. Explain never repeats the value given, since it may be a secret (a flag.Value of the tool's own may name it in its reason, which follows the flag). Any other error is its own words. A tool prints it as `<VERB> REFUSED: <Explain>; run: <tool> <verb> -h`. Parse returns the flag package's error unchanged, because tools still match its words; Explain is the one wording of it.
func FlagSynopsis ¶
FlagSynopsis names each flag of fs for a usage line, `[--name]` or `[--name <kind>]`, sorted by name. Empty when fs is nil or defines none. It never prints the placeholder [flags], and it never prints a default.
func HelpIfAsked ¶
HelpIfAsked is for the verbs that read their flags by hand, or take none: when args hold -h, -help or --help (before any --), it raises Help with a flag set of the flags given, each with what it wants, so the dispatcher prints the same usage text as for a verb that parses through Parse.
func Insert ¶
Insert puts lines into a printed verb help above its flags (above its exit codes when it lists none, at its end when it has neither).
func Nearest ¶
Nearest is the one name nearest to got within a third of its length (dashes aside, rounded up) in edits, else "": the name an unknown one was meant as.
func New ¶
New returns a ContinueOnError flag set named for the verb and subverb ("task push"): quiet on a parse error, Help on -h.
func Parse ¶
Parse is fs.Parse with the help rule applied, for a flag set the verb built itself. -h, -help or --help raises Help; any other result is exactly what fs.Parse returns, and a parse error writes exactly what it wrote before (the flag package's message, then the set's own Usage or its defaults, to the set's own output). On help nothing is written anywhere but by Recover.
func Print ¶
Print writes the usage line (UsageLine: a group's names its verbs), the verb's lines quoted from the tool's help text, one line per flag the set defines (sorted, with its value type and what it wants; no defaults, since a default can come from the environment and a help line must never print a secret), and the exit codes: exit, the verb's own lines, when given, else the tool's paragraph from its help text.
func RecoverWith ¶
RecoverWith is deferred directly by the dispatcher. A Help panic becomes that verb's help on out (stdout) and *code 0 (1 when out refuses the write); any other panic goes on unwinding. banner is the tool's own help text (what `<prog> help` prints), from which the verb's usage lines and examples are quoted; "" quotes nothing. extra is given the verb's name (as Verb gives it) and returns lines of the tool's own to print above the flags, each ending in a newline ("" for none): a worked example per verb. A line of extra that opens `exit codes:` and the lines after it are that verb's own exit codes: they stand where the tool's paragraph would.
func Subverbs ¶
Subverbs is the verbs of a group as the help text's usage block (the lines above its `example:` line) names them: when every line there that begins with the tool and the verb's words (a word of `fleet|sprint` is either) goes on with a verb word, the distinct words, in order; else nil, the verb is no group, or one whose verbs a line with a placeholder in its place (`<kind> list`) leaves unnamed. A line's command ends at a run of two spaces or a tab, where a pasted help puts its description.
func UsageLine ¶
UsageLine is `usage: <prog> <verb> [flags]`, and for a group, a verb whose words only lead to its verbs (subs), `usage: <prog> <group> <a|b> [flags]`. The bracketed word is the placeholder for a caller that passes no synopsis (UsageLineSynopsis). A tool whose help already prints that placeholder keeps it.
func UsageLineSynopsis ¶
UsageLineSynopsis is UsageLine with the verb's own synopsis in place of the placeholder [flags]: positionals and the flags the verb takes, as its usage line names them. An empty synopsis keeps the placeholder. A group (subs) keeps `<a|b> [flags]`; its verbs are the synopsis.
Source Files