fisk

package module
v0.6.2 Latest Latest
Warning

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

 Go to latest Published: Dec 19, 2023 License: MIT Imports: 27 Imported by: 36

README

Overview

Fisk is a fluent-style, type-safe command-line parser. It supports flags, nested commands, and positional arguments.

This is a fork of kingpin, a very nice CLI framework that has been in limbo for a few years. As this project and others we work on are heavily invested in Kingpin we thought to revive it for our needs. We'll likely make some breaking changes, so kingpin is kind of serving as a starting point here rather than this being designed as a direct continuation of that project.

For full help and intro see kingpin, this README will focus on our local changes.

Versions

We are not continuing the versioning scheme of Kingpin, the Go community has introduced onerous SemVer restrictions, we will start from 0.0.1 and probably never pass 0.x.x.

Some historical points in time are kept:

Tag Description
v0.0.1 Corresponds to the v2.2.6 release of Kingpin
v0.0.2 Corresponds with the master of Kingpin at the time of this fork
v0.1.0 The first release under choria-io org

Notable Changes

  • Renamed master branch to main
  • Incorporate github.com/alecthomas/units and github.com/alecthomas/template as local packages
  • Changes to make staticcheck happy
  • A new default template that shortens the help on large apps, old default preserved as KingpinDefaultUsageTemplate
  • Integration with cheat (see below)
  • Unnegatable booleans using a new UnNegatableBool() flag type, backwards compatibility kept
  • Extended parsing for durations that include weeks (w, W), months (M), years (y, Y) and days (d, D) units (v0.1.3 or newer)
  • More contextually useful help when using app.MustParseWithUsage(os.Args[1:]) (v0.1.4 or newer)
  • Default usage template is CompactMainUsageTemplate since v0.3.0
  • Support per Flag and Argument validation since v0.6.0
UnNegatableBool

Fisk will add to all Bool() kind flags a negated version, in other words --force will also get --no-force added and the usage will show these negatable booleans.

Often though one does not want to have the negatable version of a boolean added, with fisk you can achieve this using our UnNegatableBool() which would just be the basic boolean flag with no negatable version.

Arguably Bool() should be un-negatable and we should have added a NagatableBool() but the decision was made to keep existing apps backward compatible.

Cheats

I really like cheat, a great little tool that gives access to bite-sized hints on what's great about a CLI tool.

Since v0.1.1 Fisk supports cheats natively, you can get cheat formatted hints right from the app with no extra dependencies or export cheats into the cheat app for use via its interface and integrations.

$ nats cheat pub
# To publish 100 messages with a random body between 100 and 1000 characters
nats pub destination.subject "{{ Random 100 1000 }}" -H Count:{{ Count }} --count 100

Cheats are stored in a map[string]string, meaning it's flat, does not support subs and when saving cheats, due to the nature of the fluent api, 2 cheats with the same name will overwrite each other.

I therefore suggest you place your cheat in the top command for an intro and then place them where you need them in the first sub command only not deeper, this makes it easy to avoid clashes and easy for your users to discover them.

Let's look how that is done:

// WithCheats() enables cheats without adding any to the top, you
// can also just call Cheat() at the top to both set a cheat and enable it
// once enabled at the top all cheats in all sub commands are accessible
//
// Cheats can have multiple tags, here we set the tags "middleware", and "nats"
// that will be used when saving the cheats.  If no tags are supplied the
// application name is used as the only tag
nats := fisk.New("nats", "NATS Utility").WithCheats("middleware", "nats")

pub := nats.Command("pub", "Publish utility")
// The cheat will be available as "pub", the if the first argument
// is empty the name of the command will be used
pub.Cheat("pub", `# To publish 100 messages with a random.....`)

After that your app will have a new command cheat that gives access to the cheats. It will show a list of cheats when trying to access a command without cheats or when running nats cheat --list.

$ nats cheat unknown
Available Cheats:

  pub

You can save your cheats to a directory of your choice with nats cheat --save /some/dir, the directory must not already exist.

Flag and Argument Validations

To support a rich validation capability without the core fisk library having to implement it all we support passing in validators that operate on the string value given by the user

Here is a Regular expression validator:

func RegexValidator(pattern string) OptionValidator {
    return func(value string) error {
        ok, err := regexp.MatchString(pattern, value)
        if err != nil {
            return fmt.Errorf("invalid validation pattern %q: %w", pattern, err)
        }

        if !ok {
            return fmt.Errorf("does not validate using %q", pattern)
        }

        return nil
    }
}

Use this on a Flag or Argument:

app.Flag("name", "A object name consisting of alphanumeric characters").Validator(RegexValidator("^[a-zA-Z]+$")).StringVar(&val)

External Plugins

Often one wants to make a CLI tool that can be extended using plugins. Think for example the nats CLI that is built using fisk, it may want to add some commercial offering-specific commands that appear in the nats command as a fully native built-in command.

NOTE: This is an experimental feature that will see some iteration in the short term future.

Fisk 0.5.0 supports extending itself at run-time in this manner and any application built using this version of fisk can be plugged into another fisk application.

The host application need to do some work but the ones being embedded will just work.

app := fisk.New("nats", "NATS Utility")

// now load your plugin models from disk and extend the command
model := loadModelJson("ngs")

app.ExternalPluginCommand("/opt/nats/bin/ngs", model)

The model above can be obtained by running a fisk built command with --fisk-introspect flag.

The idea is that you would detect and register new plugins into your tool, you would call them once with the introspect flag and cache that model. All future startups would embed this command - here nats ngs - right into the command flow.

The model is our ApplicationModel. Plugins written in other languages or using other CLI frameworks would need to emit a compatible model.

Care should be taken not to have clashes with the top level global flags of the app you are embedding into, but if you do have a clash the value will be passed from top level into your app invocation. This should be good enough for most cases but could leed to some unexpected results when you might have a different concept of what a flag means than the one you are embedded into.

Documentation

Overview

Package fisk provides command line interfaces like this: 

$ chat
usage: chat [<flags>] <command> [<flags>] [<args> ...]

Flags:
  --debug              enable debug mode
  --help               Show help.
  --server=127.0.0.1   server address

Commands:
  help <command>
    Show help for a command.

  post [<flags>] <channel>
    Post a message to a channel.

  register <nick> <name>
    Register a new user.

$ chat help post
usage: chat [<flags>] post [<flags>] <channel> [<text>]

Post a message to a channel.

Flags:
  --image=IMAGE   image to post

Args:
  <channel>   channel to post to
  [<text>]    text to post
$ chat post --image=~/Downloads/owls.jpg pics

From code like this: 

package main

import "github.com/choria-io/fisk"

var (
  debug    = fisk.Flag("debug", "enable debug mode").Default("false").Bool()
  serverIP = fisk.Flag("server", "server address").Default("127.0.0.1").IP()

  register     = fisk.Command("register", "Register a new user.")
  registerNick = register.Arg("nick", "nickname for user").Required().String()
  registerName = register.Arg("name", "name of user").Required().String()

  post        = fisk.Command("post", "Post a message to a channel.")
  postImage   = post.Flag("image", "image to post").ExistingFile()
  postChannel = post.Arg("channel", "channel to post to").Required().String()
  postText    = post.Arg("text", "text to post").String()
)

func main() {
  switch fisk.Parse() {
  // Register user
  case "register":
    println(*registerNick)

  // Post message
  case "post":
    if *postImage != nil {
    }
    if *postText != "" {
    }
  }
}

Index

Examples

Constants

This section is empty.

Variables

View Source 
var (
	// ErrUnknownLongFlag indicates an unknown long form flag was passed
	ErrUnknownLongFlag = errors.New("unknown long flag")

	// ErrUnknownShortFlag indicates an unknown short form flag was passed
	ErrUnknownShortFlag = errors.New("unknown short flag")

	// ErrExpectedFlagArgument indicates a flag requiring an argument did not have one supplied
	ErrExpectedFlagArgument = errors.New("expected argument for flag")

	// ErrCommandNotSpecified indicates a command was expected
	ErrCommandNotSpecified = fmt.Errorf("command not specified")

	// ErrSubCommandRequired indicates that a command was invoked, but it required a sub command
	ErrSubCommandRequired = errors.New("must select a subcommand")

	// ErrRequiredArgument indicates a required argument was not given
	ErrRequiredArgument = errors.New("required argument")

	// ErrRequiredFlag indicates a required flag was not given
	ErrRequiredFlag = errors.New("required flag")

	// ErrExpectedKnownCommand indicates that an unknown command argument was encountered
	ErrExpectedKnownCommand = errors.New("expected command")

	// ErrFlagCannotRepeat indicates a flag cannot be passed multiple times to fill an array
	ErrFlagCannotRepeat = errors.New("cannot be repeated")

	// ErrUnexpectedArgument indicates an unexpected argument was encountered
	ErrUnexpectedArgument = errors.New("unexpected argument")
)
View Source 
var (
	// CommandLine is the default fisk parser.
	CommandLine = New(filepath.Base(os.Args[0]), "")
	// HelpFlag global help flag. Exposed for user customisation.
	HelpFlag = CommandLine.HelpFlag
	// HelpCommand Top-level help command. Exposed for user customisation. May be nil.
	HelpCommand = CommandLine.HelpCommand
	// VersionFlag global version flag. Exposed for user customisation. May be nil.
	VersionFlag = CommandLine.VersionFlag
	// EnableFileExpansion whether to file expansion with '@' is enabled.
	EnableFileExpansion = true
)
View Source 
var BashCompletionTemplate = `` /* 340-byte string literal not displayed */
View Source 
var CompactMainUsageTemplate = `` /* 1467-byte string literal not displayed */

CompactMainUsageTemplate formats commands and subcommands in a two column layout to make for a cleaners and more readable usage text. In this format, sections are rendered as follows. Global flags are also separate from local flags in this template. Global flags will be shown at the top level and local flags will be shown when showing help for a subcommand.

usage: <command> [<flags>] <command> [<arg> ...]

Help text

Commands|Subcommands: 

command1    Help text for command 1
command2    Help text for command 2
command2    Help text for command 3

Flags: 

-h, --help     Show context-sensitive help
View Source 
var CompactUsageTemplate = `` /* 1369-byte string literal not displayed */

CompactUsageTemplate is a usage template with compactly formatted commands.

View Source 
var KingpinDefaultUsageTemplate = `` /* 1299-byte string literal not displayed */

KingpinDefaultUsageTemplate is the default usage template as used by kingpin

View Source 
var LongHelpTemplate = `` /* 1033-byte string literal not displayed */

LongHelpTemplate is a usage template for --help-long

View Source 
var ManPageTemplate = `` /* 1161-byte string literal not displayed */

ManPageTemplate renders usage in unix man format

View Source 
var SeparateOptionalFlagsUsageTemplate = `` /* 1452-byte string literal not displayed */

SeparateOptionalFlagsUsageTemplate is a usage template where command's optional flags are listed separately

View Source 
var ShorterMainUsageTemplate = `` /* 1582-byte string literal not displayed */

ShorterMainUsageTemplate is similar to KingpinDefaultUsageTemplate except in the main app usage output it does not expand full help text for every single sub command all the way to the deepest leve, it also does not show global flags in the top app.

Additionally, it supports the new HelpLong on sub commands so one can either rely on it always printing just the first line of sub command help or only putting short help in the main help and long help in long - the long will only be shown when it's rendering usage for that command when it's the command the user is executing (select).

This yields a friendlier welcome to new users with the details should they do help on any sub command

View Source 
var (
	TokenEOLMarker = Token{-1, TokenEOL, ""}
)
View Source 
var ZshCompletionTemplate = `` /* 350-byte string literal not displayed */

Functions

func Errorf 

func Errorf(format string, args ...interface{})

Errorf prints an error message to stderr.

func ExpandArgsFromFile 

func ExpandArgsFromFile(filename string) (out []string, err error)

ExpandArgsFromFile expand arguments from a file. Lines starting with # will be treated as comments.

func FatalIfError 

func FatalIfError(err error, format string, args ...interface{})

FatalIfError prints an error and exits if err is not nil. The error is printed with the given prefix.

func FatalUsage 

func FatalUsage(format string, args ...interface{})

FatalUsage prints an error message followed by usage information, then exits with a non-zero status.

func FatalUsageContext 

func FatalUsageContext(context *ParseContext, format string, args ...interface{})

FatalUsageContext writes a printf formatted error message to stderr, then usage information for the given ParseContext, before exiting.

func Fatalf 

func Fatalf(format string, args ...interface{})

Fatalf prints an error message to stderr and exits.

func MustParse 

func MustParse(command string, err error) string

MustParse can be used with app.Parse(args) to exit with an error if parsing fails.

func Parse 

func Parse() string

Parse and return the selected command. Will call the termination handler if an error is encountered.

func ParseDuration added in v0.1.3 

func ParseDuration(d string) (time.Duration, error)

ParseDuration parse durations with additional units over those from standard go parser.

In addition to normal go parser time units it also supports these.

The reason these are not in go standard lib is due to precision around how many days in a month and about leap years and leap seconds. This function does nothing to try and correct for those.

* "w", "W" - a week based on 7 days of exactly 24 hours * "d", "D" - a day based on 24 hours * "M" - a month made of 30 days of 24 hours * "y", "Y" - a year made of 365 days of 24 hours each

Valid duration strings can be -1y1d1µs

func Usage 

func Usage()

Usage prints usage to stderr.

Types

type Action 

type Action func(*ParseContext) error

Action callback executed at various stages after all values are populated. The application, commands, arguments and flags all have corresponding actions.

type Application 

type Application struct {
	Name string
	Help string

	// Help flag. Exposed for user customisation.
	HelpFlag *FlagClause
	// Help command. Exposed for user customisation. May be nil.
	HelpCommand *CmdClause
	// Version flag. Exposed for user customisation. May be nil.
	VersionFlag *FlagClause
	// Cheat command. Exposed for user customisation. May be nil.
	CheatCommand *CmdClause
	// contains filtered or unexported fields
}

An Application contains the definitions of flags, arguments and commands for an application.

func New 

func New(name, help string) *Application

New creates a new Fisk application instance.

func Newf added in v0.1.1 

func Newf(name string, format string, a ...interface{}) *Application

Newf creates a new application with printf parsing of the help

func UsageTemplate 

func UsageTemplate(template string) *Application

UsageTemplate Set global usage template to use (defaults to ShorterMainUsageTemplate).

func Version 

func Version(version string) *Application

Version adds a flag for displaying the application version number.

func (*Application) Action 

func (a *Application) Action(action Action) *Application

Action callback to call when all values are populated and parsing is complete, but before any command, flag or argument actions.

All Action() callbacks are called in the order they are encountered on the command line.

func (*Application) Author 

func (a *Application) Author(author string) *Application

Author sets the author output by some help templates.

func (*Application) Cheat added in v0.1.1 

func (a *Application) Cheat(cheat string, help string) *Application

Cheat sets the cheat help text to associate with this application, the cheat is the name it will be surfaced as in help, if empty its the name of the application.

func (*Application) CheatFile added in v0.1.1 

func (a *Application) CheatFile(fs fs.ReadFileFS, cheat string, file string) *Application

CheatFile reads a file from fs and use its contents to call Cheat(). Read errors are fatal.

func (*Application) CmdCompletion 

func (c *Application) CmdCompletion(context *ParseContext) []string

CmdCompletion returns completion options for arguments, if that's where parsing left off, or commands if there aren't any unsatisfied args.

func (*Application) Command 

func (a *Application) Command(name, help string) *CmdClause

Command adds a new top-level command.

func (*Application) Commandf added in v0.1.1 

func (a *Application) Commandf(name string, format string, arg ...interface{}) *CmdClause

Commandf adds a new top-level command with printf parsing of help

func (*Application) DefaultEnvars 

func (a *Application) DefaultEnvars() *Application

DefaultEnvars configures all flags (that do not already have an associated envar) to use a default environment variable in the form "<app>_<flag>".

For example, if the application is named "foo" and a flag is named "bar- waz" the environment variable: "FOO_BAR_WAZ".

func (*Application) ErrorUsageTemplate added in v0.2.0 

func (a *Application) ErrorUsageTemplate(template string) *Application

ErrorUsageTemplate specifies the text template to use when displaying usage information after an ErrSubCommandRequired ErrExpectedKnownCommand. The default is compactWithoutFlagsOrArgs.

func (*Application) ErrorWriter 

func (a *Application) ErrorWriter(w io.Writer) *Application

ErrorWriter sets the io.Writer to use for errors.

func (*Application) Errorf 

func (a *Application) Errorf(format string, args ...interface{})

Errorf prints an error message to w in the format "<appname>: error: <message>".

func (*Application) ExternalPluginCommand added in v0.5.0 

func (a *Application) ExternalPluginCommand(command string, model json.RawMessage, name string, help string) (*CmdClause, error)

ExternalPluginCommand extends the application using a plugin and a model describing the application, when name or help is not an empty string it will override that from the plugin

func (*Application) FatalIfError 

func (a *Application) FatalIfError(err error, format string, args ...interface{})

FatalIfError prints an error and exits if err is not nil. The error is printed with the given formatted string, if any.

func (*Application) FatalUsage 

func (a *Application) FatalUsage(format string, args ...interface{})

FatalUsage prints an error message followed by usage information, then exits with a non-zero status.

func (*Application) FatalUsageContext 

func (a *Application) FatalUsageContext(context *ParseContext, format string, args ...interface{})

FatalUsageContext writes a printf formatted error message to w, then usage information for the given ParseContext, before exiting.

func (*Application) Fatalf 

func (a *Application) Fatalf(format string, args ...interface{})

Fatalf writes a formatted error to w then terminates with exit status 1.

func (*Application) FlagCompletion 

func (c *Application) FlagCompletion(flagName string, flagValue string) (choices []string, flagMatch bool, optionMatch bool)

func (*Application) Interspersed 

func (a *Application) Interspersed(interspersed bool) *Application

Interspersed control if flags can be interspersed with positional arguments

true (the default) means that they can, false means that all the flags must appear before the first positional arguments.

func (*Application) Model 

func (a *Application) Model() *ApplicationModel

func (*Application) MustParseWithUsage added in v0.1.4 

func (a *Application) MustParseWithUsage(args []string) (command string)

MustParseWithUsage parses args using Parse() and shows usage on certain errors

When a parent command with no action is called a compact usage will be shown listing the subcommands available without any flags or arguments allowing a user to quickly evaluate the next command to use, this is to assist in discovering the layout and design of a CLI tool.

When a various argument of flag errors are encountered an error is shown followed by the full help for that command showing available arguments and flags.

All other errors just shows the error.

func (*Application) Parse 

func (a *Application) Parse(args []string) (command string, err error)

Parse parses command-line arguments. It returns the selected command and an error. The selected command will be a space separated subcommand, if subcommands have been configured.

This will populate all flag and argument values, call all callbacks, and so on.

func (*Application) ParseContext 

func (a *Application) ParseContext(args []string) (*ParseContext, error)

ParseContext parses the given command line and returns the fully populated ParseContext.

func (*Application) PreAction 

func (a *Application) PreAction(action Action) *Application

PreAction action called after parsing completes but before validation and execution.

func (*Application) Terminate 

func (a *Application) Terminate(terminate func(int)) *Application

Terminate specifies the termination handler. Defaults to os.Exit(status). If nil is passed, a no-op function will be used.

func (*Application) Usage 

func (a *Application) Usage(args []string)

Usage writes application usage to w. It parses args to determine appropriate help context, such as which command to show help for.

func (*Application) UsageForContext 

func (a *Application) UsageForContext(context *ParseContext) error

UsageForContext displays usage information from a ParseContext (obtained from Application.ParseContext() or Action(f) callbacks).

func (*Application) UsageForContextWithTemplate 

func (a *Application) UsageForContextWithTemplate(context *ParseContext, indent int, tmpl string) error

UsageForContextWithTemplate is the base usage function. You generally don't need to use this.

func (*Application) UsageFuncs added in v0.1.0 

func (a *Application) UsageFuncs(funcs template.FuncMap) *Application

UsageFuncs adds extra functions that can be used in the usage template.

func (*Application) UsageTemplate 

func (a *Application) UsageTemplate(template string) *Application

UsageTemplate specifies the text template to use when displaying usage information. The default is UsageTemplate.

func (*Application) UsageWriter 

func (a *Application) UsageWriter(w io.Writer) *Application

UsageWriter sets the io.Writer to use for errors.

func (*Application) Validate 

func (a *Application) Validate(validator ApplicationValidator) *Application

Validate sets a validation function to run when parsing.

func (*Application) Version 

func (a *Application) Version(version string) *Application

Version adds a --version flag for displaying the application version.

func (*Application) WithCheats added in v0.1.1 

func (a *Application) WithCheats(tags ...string) *Application

WithCheats enables support for rendering cheat compatible output, tags can be supplied which would be set when saving cheat files

See https://github.com/cheat/cheat for information about this format

func (*Application) Writer 

func (a *Application) Writer(w io.Writer) *Application

Writer specifies the writer to use for usage and errors. Defaults to os.Stderr. DEPRECATED: See ErrorWriter and UsageWriter.

type ApplicationModel 

type ApplicationModel struct {
	Name      string            `json:"name"`
	Help      string            `json:"help"`
	Cheat     string            `json:"cheat,omitempty"`
	Version   string            `json:"version,omitempty"`
	Author    string            `json:"author,omitempty"`
	Cheats    map[string]string `json:"cheats,omitempty"`
	CheatTags []string          `json:"cheat_tags,omitempty"`

	*ArgGroupModel
	*CmdGroupModel
	*FlagGroupModel
}

type ApplicationValidator 

type ApplicationValidator func(*Application) error

ApplicationValidator can be used to validate entire application during parsing

type ArgClause 

type ArgClause struct {
	// contains filtered or unexported fields
}

func Arg 

func Arg(name, help string) *ArgClause

Arg adds a new argument to the top-level of the default parser.

func (*ArgClause) Action 

func (a *ArgClause) Action(action Action) *ArgClause

func (*ArgClause) Bool 

func (p *ArgClause) Bool() (target *bool)

Bool parses the next command-line value as bool.

func (*ArgClause) BoolList 

func (p *ArgClause) BoolList() (target *[]bool)

BoolList accumulates bool values into a slice.

func (*ArgClause) BoolListVar 

func (p *ArgClause) BoolListVar(target *[]bool)

func (*ArgClause) BoolVar 

func (p *ArgClause) BoolVar(target *bool)

func (*ArgClause) Bytes 

func (p *ArgClause) Bytes() (target *units.Base2Bytes)

Bytes parses numeric byte units. eg. 1.5KB

func (*ArgClause) BytesVar 

func (p *ArgClause) BytesVar(target *units.Base2Bytes)

BytesVar parses numeric byte units. eg. 1.5KB

func (*ArgClause) Counter 

func (p *ArgClause) Counter() (target *int)

A Counter increments a number each time it is encountered.

func (*ArgClause) CounterVar 

func (p *ArgClause) CounterVar(target *int)

func (*ArgClause) Default 

func (a *ArgClause) Default(values ...string) *ArgClause

Default values for this argument. They *must* be parseable by the value of the argument.

func (*ArgClause) Duration 

func (p *ArgClause) Duration() (target *time.Duration)

Duration sets the parser to a time.Duration parser.

func (*ArgClause) DurationList 

func (p *ArgClause) DurationList() (target *[]time.Duration)

DurationList accumulates time.Duration values into a slice.

func (*ArgClause) DurationListVar 

func (p *ArgClause) DurationListVar(target *[]time.Duration)

func (*ArgClause) DurationVar 

func (p *ArgClause) DurationVar(target *time.Duration)

Duration sets the parser to a time.Duration parser.

func (*ArgClause) Enum 

func (p *ArgClause) Enum(options ...string) (target *string)

Enum allows a value from a set of options.

func (*ArgClause) EnumVar 

func (p *ArgClause) EnumVar(target *string, options ...string)

EnumVar allows a value from a set of options.

func (*ArgClause) Enums 

func (p *ArgClause) Enums(options ...string) (target *[]string)

Enums allows a set of values from a set of options.

func (*ArgClause) EnumsVar 

func (p *ArgClause) EnumsVar(target *[]string, options ...string)

EnumsVar allows a value from a set of options.

func (*ArgClause) Envar 

func (a *ArgClause) Envar(name string) *ArgClause

Envar overrides the default value(s) for a flag from an environment variable, if it is set. Several default values can be provided by using new lines to separate them.

func (*ArgClause) ExistingDir 

func (p *ArgClause) ExistingDir() (target *string)

ExistingDir sets the parser to one that requires and returns an existing directory.

func (*ArgClause) ExistingDirVar 

func (p *ArgClause) ExistingDirVar(target *string)

ExistingDir sets the parser to one that requires and returns an existing directory.

func (*ArgClause) ExistingDirs 

func (p *ArgClause) ExistingDirs() (target *[]string)

ExistingDirs accumulates string values into a slice.

func (*ArgClause) ExistingDirsVar 

func (p *ArgClause) ExistingDirsVar(target *[]string)

func (*ArgClause) ExistingFile 

func (p *ArgClause) ExistingFile() (target *string)

ExistingFile sets the parser to one that requires and returns an existing file.

func (*ArgClause) ExistingFileOrDir 

func (p *ArgClause) ExistingFileOrDir() (target *string)

ExistingFileOrDir sets the parser to one that requires and returns an existing file OR directory.

func (*ArgClause) ExistingFileOrDirVar 

func (p *ArgClause) ExistingFileOrDirVar(target *string)

ExistingDir sets the parser to one that requires and returns an existing directory.

func (*ArgClause) ExistingFileVar 

func (p *ArgClause) ExistingFileVar(target *string)

ExistingFile sets the parser to one that requires and returns an existing file.

func (*ArgClause) ExistingFiles 

func (p *ArgClause) ExistingFiles() (target *[]string)

ExistingFiles accumulates string values into a slice.

func (*ArgClause) ExistingFilesOrDirs 

func (p *ArgClause) ExistingFilesOrDirs() (target *[]string)

ExistingFilesOrDirs accumulates string values into a slice.

func (*ArgClause) ExistingFilesOrDirsVar 

func (p *ArgClause) ExistingFilesOrDirsVar(target *[]string)

func (*ArgClause) ExistingFilesVar 

func (p *ArgClause) ExistingFilesVar(target *[]string)

func (*ArgClause) File 

func (p *ArgClause) File() (target **os.File)

File returns an os.File against an existing file.

func (*ArgClause) FileVar 

func (p *ArgClause) FileVar(target **os.File)

FileVar opens an existing file.

func (*ArgClause) Float 

func (p *ArgClause) Float() (target *float64)

Float sets the parser to a float64 parser.

func (*ArgClause) Float32 

func (p *ArgClause) Float32() (target *float32)

Float32 parses the next command-line value as float32.

func (*ArgClause) Float32List 

func (p *ArgClause) Float32List() (target *[]float32)

Float32List accumulates float32 values into a slice.

func (*ArgClause) Float32ListVar 

func (p *ArgClause) Float32ListVar(target *[]float32)

func (*ArgClause) Float32Var 

func (p *ArgClause) Float32Var(target *float32)

func (*ArgClause) Float64 

func (p *ArgClause) Float64() (target *float64)

Float64 parses the next command-line value as float64.

func (*ArgClause) Float64List 

func (p *ArgClause) Float64List() (target *[]float64)

Float64List accumulates float64 values into a slice.

func (*ArgClause) Float64ListVar 

func (p *ArgClause) Float64ListVar(target *[]float64)

func (*ArgClause) Float64Var 

func (p *ArgClause) Float64Var(target *float64)

func (*ArgClause) FloatVar 

func (p *ArgClause) FloatVar(target *float64)

Float sets the parser to a float64 parser.

func (*ArgClause) GetEnvarValue 

func (e *ArgClause) GetEnvarValue() string

func (*ArgClause) GetSplitEnvarValue 

func (e *ArgClause) GetSplitEnvarValue() []string

func (*ArgClause) HasEnvarValue 

func (e *ArgClause) HasEnvarValue() bool

func (*ArgClause) Help added in v0.1.0 

func (a *ArgClause) Help(help string) *ArgClause

Help sets the help message.

func (*ArgClause) HexBytes 

func (p *ArgClause) HexBytes() (target *[]byte)

Bytes as a hex string.

func (*ArgClause) HexBytesList 

func (p *ArgClause) HexBytesList() (target *[][]byte)

HexBytesList accumulates []byte values into a slice.

func (*ArgClause) HexBytesListVar 

func (p *ArgClause) HexBytesListVar(target *[][]byte)

func (*ArgClause) HexBytesVar 

func (p *ArgClause) HexBytesVar(target *[]byte)

func (*ArgClause) Hidden added in v0.1.0 

func (a *ArgClause) Hidden() *ArgClause

Hidden hides the argument from usage but still allows it to be used.

func (*ArgClause) HintAction 

func (a *ArgClause) HintAction(action HintAction) *ArgClause

HintAction registers a HintAction (function) for the arg to provide completions

func (*ArgClause) HintOptions 

func (a *ArgClause) HintOptions(options ...string) *ArgClause

HintOptions registers any number of options for the flag to provide completions

func (*ArgClause) IP 

func (p *ArgClause) IP() (target *net.IP)

IP sets the parser to a net.IP parser.

func (*ArgClause) IPList 

func (p *ArgClause) IPList() (target *[]net.IP)

IPList accumulates net.IP values into a slice.

func (*ArgClause) IPListVar 

func (p *ArgClause) IPListVar(target *[]net.IP)

func (*ArgClause) IPVar 

func (p *ArgClause) IPVar(target *net.IP)

IP sets the parser to a net.IP parser.

func (*ArgClause) Int 

func (p *ArgClause) Int() (target *int)

Int parses the next command-line value as int.

func (*ArgClause) Int16 

func (p *ArgClause) Int16() (target *int16)

Int16 parses the next command-line value as int16.

func (*ArgClause) Int16List 

func (p *ArgClause) Int16List() (target *[]int16)

Int16List accumulates int16 values into a slice.

func (*ArgClause) Int16ListVar 

func (p *ArgClause) Int16ListVar(target *[]int16)

func (*ArgClause) Int16Var 

func (p *ArgClause) Int16Var(target *int16)

func (*ArgClause) Int32 

func (p *ArgClause) Int32() (target *int32)

Int32 parses the next command-line value as int32.

func (*ArgClause) Int32List 

func (p *ArgClause) Int32List() (target *[]int32)

Int32List accumulates int32 values into a slice.

func (*ArgClause) Int32ListVar 

func (p *ArgClause) Int32ListVar(target *[]int32)

func (*ArgClause) Int32Var 

func (p *ArgClause) Int32Var(target *int32)

func (*ArgClause) Int64 

func (p *ArgClause) Int64() (target *int64)

Int64 parses the next command-line value as int64.

func (*ArgClause) Int64List 

func (p *ArgClause) Int64List() (target *[]int64)

Int64List accumulates int64 values into a slice.

func (*ArgClause) Int64ListVar 

func (p *ArgClause) Int64ListVar(target *[]int64)

func (*ArgClause) Int64Var 

func (p *ArgClause) Int64Var(target *int64)

func (*ArgClause) Int8 

func (p *ArgClause) Int8() (target *int8)

Int8 parses the next command-line value as int8.

func (*ArgClause) Int8List 

func (p *ArgClause) Int8List() (target *[]int8)

Int8List accumulates int8 values into a slice.

func (*ArgClause) Int8ListVar 

func (p *ArgClause) Int8ListVar(target *[]int8)

func (*ArgClause) Int8Var 

func (p *ArgClause) Int8Var(target *int8)

func (*ArgClause) IntVar 

func (p *ArgClause) IntVar(target *int)

func (*ArgClause) Ints 

func (p *ArgClause) Ints() (target *[]int)

Ints accumulates int values into a slice.

func (*ArgClause) IntsVar 

func (p *ArgClause) IntsVar(target *[]int)

func (*ArgClause) Model 

func (a *ArgClause) Model() *ArgModel

func (*ArgClause) NoEnvar 

func (a *ArgClause) NoEnvar() *ArgClause

NoEnvar forces environment variable defaults to be disabled for this flag. Most useful in conjunction with app.DefaultEnvars().

func (*ArgClause) OpenFile 

func (p *ArgClause) OpenFile(flag int, perm os.FileMode) (target **os.File)

File attempts to open a File with os.OpenFile(flag, perm).

func (*ArgClause) OpenFileVar 

func (p *ArgClause) OpenFileVar(target **os.File, flag int, perm os.FileMode)

OpenFileVar calls os.OpenFile(flag, perm)

func (*ArgClause) PlaceHolder added in v0.1.0 

func (a *ArgClause) PlaceHolder(value string) *ArgClause

PlaceHolder sets the place-holder string used for arg values in the help. The default behavior is to use the arg name between < > brackets.

func (*ArgClause) PreAction 

func (a *ArgClause) PreAction(action Action) *ArgClause

func (*ArgClause) Regexp 

func (p *ArgClause) Regexp() (target **regexp.Regexp)

Regexp parses the next command-line value as *regexp.Regexp.

func (*ArgClause) RegexpList 

func (p *ArgClause) RegexpList() (target *[]*regexp.Regexp)

RegexpList accumulates *regexp.Regexp values into a slice.

func (*ArgClause) RegexpListVar 

func (p *ArgClause) RegexpListVar(target *[]*regexp.Regexp)

func (*ArgClause) RegexpVar 

func (p *ArgClause) RegexpVar(target **regexp.Regexp)

func (*ArgClause) Required 

func (a *ArgClause) Required() *ArgClause

Required arguments must be input by the user. They can not have a Default() value provided.

func (*ArgClause) ResolvedIP 

func (p *ArgClause) ResolvedIP() (target *net.IP)

Resolve a hostname or IP to an IP.

func (*ArgClause) ResolvedIPList 

func (p *ArgClause) ResolvedIPList() (target *[]net.IP)

ResolvedIPList accumulates net.IP values into a slice.

func (*ArgClause) ResolvedIPListVar 

func (p *ArgClause) ResolvedIPListVar(target *[]net.IP)

func (*ArgClause) ResolvedIPVar 

func (p *ArgClause) ResolvedIPVar(target *net.IP)

func (*ArgClause) SetText added in v0.1.0 

func (p *ArgClause) SetText(text Text)

func (*ArgClause) SetValue 

func (p *ArgClause) SetValue(value Value)

func (*ArgClause) String 

func (p *ArgClause) String() (target *string)

String parses the next command-line value as string.

func (*ArgClause) StringMap 

func (p *ArgClause) StringMap() (target *map[string]string)

StringMap provides key=value parsing into a map.

func (*ArgClause) StringMapVar 

func (p *ArgClause) StringMapVar(target *map[string]string)

StringMap provides key=value parsing into a map.

func (*ArgClause) StringVar 

func (p *ArgClause) StringVar(target *string)

func (*ArgClause) Strings 

func (p *ArgClause) Strings() (target *[]string)

Strings accumulates string values into a slice.

func (*ArgClause) StringsVar 

func (p *ArgClause) StringsVar(target *[]string)

func (*ArgClause) TCP 

func (p *ArgClause) TCP() (target **net.TCPAddr)

TCP (host:port) address.

func (*ArgClause) TCPList 

func (p *ArgClause) TCPList() (target *[]*net.TCPAddr)

TCPList accumulates *net.TCPAddr values into a slice.

func (*ArgClause) TCPListVar 

func (p *ArgClause) TCPListVar(target *[]*net.TCPAddr)

func (*ArgClause) TCPVar 

func (p *ArgClause) TCPVar(target **net.TCPAddr)

TCPVar (host:port) address.

func (*ArgClause) URL 

func (p *ArgClause) URL() (target **url.URL)

URL provides a valid, parsed url.URL.

func (*ArgClause) URLList 

func (p *ArgClause) URLList() (target *[]*url.URL)

URLList provides a parsed list of url.URL values.

func (*ArgClause) URLListVar 

func (p *ArgClause) URLListVar(target *[]*url.URL)

URLListVar provides a parsed list of url.URL values.

func (*ArgClause) URLVar 

func (p *ArgClause) URLVar(target **url.URL)

URL provides a valid, parsed url.URL.

func (*ArgClause) Uint 

func (p *ArgClause) Uint() (target *uint)

Uint parses the next command-line value as uint.

func (*ArgClause) Uint16 

func (p *ArgClause) Uint16() (target *uint16)

Uint16 parses the next command-line value as uint16.

func (*ArgClause) Uint16List 

func (p *ArgClause) Uint16List() (target *[]uint16)

Uint16List accumulates uint16 values into a slice.

func (*ArgClause) Uint16ListVar 

func (p *ArgClause) Uint16ListVar(target *[]uint16)

func (*ArgClause) Uint16Var 

func (p *ArgClause) Uint16Var(target *uint16)

func (*ArgClause) Uint32 

func (p *ArgClause) Uint32() (target *uint32)

Uint32 parses the next command-line value as uint32.

func (*ArgClause) Uint32List 

func (p *ArgClause) Uint32List() (target *[]uint32)

Uint32List accumulates uint32 values into a slice.

func (*ArgClause) Uint32ListVar 

func (p *ArgClause) Uint32ListVar(target *[]uint32)

func (*ArgClause) Uint32Var 

func (p *ArgClause) Uint32Var(target *uint32)

func (*ArgClause) Uint64 

func (p *ArgClause) Uint64() (target *uint64)

Uint64 parses the next command-line value as uint64.

func (*ArgClause) Uint64List 

func (p *ArgClause) Uint64List() (target *[]uint64)

Uint64List accumulates uint64 values into a slice.

func (*ArgClause) Uint64ListVar 

func (p *ArgClause) Uint64ListVar(target *[]uint64)

func (*ArgClause) Uint64Var 

func (p *ArgClause) Uint64Var(target *uint64)

func (*ArgClause) Uint8 

func (p *ArgClause) Uint8() (target *uint8)

Uint8 parses the next command-line value as uint8.

func (*ArgClause) Uint8List 

func (p *ArgClause) Uint8List() (target *[]uint8)

Uint8List accumulates uint8 values into a slice.

func (*ArgClause) Uint8ListVar 

func (p *ArgClause) Uint8ListVar(target *[]uint8)

func (*ArgClause) Uint8Var 

func (p *ArgClause) Uint8Var(target *uint8)

func (*ArgClause) UintVar 

func (p *ArgClause) UintVar(target *uint)

func (*ArgClause) Uints 

func (p *ArgClause) Uints() (target *[]uint)

Uints accumulates uint values into a slice.

func (*ArgClause) UintsVar 

func (p *ArgClause) UintsVar(target *[]uint)

func (*ArgClause) UnNegatableBool added in v0.1.2 

func (p *ArgClause) UnNegatableBool() (target *bool)

UnNegatableBool parses the next command-line value as bool.

func (*ArgClause) UnNegatableBoolList added in v0.1.2 

func (p *ArgClause) UnNegatableBoolList() (target *[]bool)

UnNegatableBoolList accumulates bool values into a slice.

func (*ArgClause) UnNegatableBoolListVar added in v0.1.2 

func (p *ArgClause) UnNegatableBoolListVar(target *[]bool)

func (*ArgClause) UnNegatableBoolVar added in v0.1.2 

func (p *ArgClause) UnNegatableBoolVar(target *bool)

func (*ArgClause) Validator added in v0.6.0 

func (a *ArgClause) Validator(validator OptionValidator) *ArgClause

type ArgGroupModel 

type ArgGroupModel struct {
	Args []*ArgModel `json:"args,omitempty"`
}

func (*ArgGroupModel) ArgSummary 

func (a *ArgGroupModel) ArgSummary() string

type ArgModel 

type ArgModel struct {
	Name        string   `json:"name"`
	Help        string   `json:"help"`
	Default     []string `json:"default,omitempty"`
	Envar       string   `json:"envar,omitempty"`
	PlaceHolder string   `json:"place_holder,omitempty"`
	Required    bool     `json:"required,omitempty"`
	Hidden      bool     `json:"hidden,omitempty"`
	Value       Value    `json:"-"`

	// used by plugin model
	Cumulative bool `json:"cumulative"`
}

func (*ArgModel) HelpWithEnvar added in v0.1.0 

func (a *ArgModel) HelpWithEnvar() string

func (*ArgModel) IsCumulative added in v0.5.0 

func (a *ArgModel) IsCumulative() bool

func (*ArgModel) String 

func (a *ArgModel) String() string

type BoolFlag added in v0.1.2 

type BoolFlag interface {
	// BoolFlagIsNegatable Specify if the flag is negatable (ie. supports both --no-<name> and --name).
	BoolFlagIsNegatable() bool
}

BoolFlag is an optional interface to specify that a flag is a boolean flag.

type CmdClause 

type CmdClause struct {
	// contains filtered or unexported fields
}

A CmdClause is a single top-level command. It encapsulates a set of flags and either subcommands or positional arguments.

func Command 

func Command(name, help string) *CmdClause

Command adds a new command to the default parser.

func (*CmdClause) Action 

func (c *CmdClause) Action(action Action) *CmdClause

func (*CmdClause) Alias 

func (c *CmdClause) Alias(name string) *CmdClause

Alias add an Alias for this command.

func (*CmdClause) Cheat added in v0.1.1 

func (c *CmdClause) Cheat(cheat string, help string) *CmdClause

Cheat sets the cheat help text to associate with this command, the cheat is the name it will be surfaced as in help, if empty it's the name of the command.

func (*CmdClause) CheatFile added in v0.1.1 

func (c *CmdClause) CheatFile(fs fs.ReadFileFS, cheat string, file string) *CmdClause

CheatFile reads a file from fs and use its contents to call Cheat(). Read errors are fatal.

func (*CmdClause) CmdCompletion 

func (c *CmdClause) CmdCompletion(context *ParseContext) []string

CmdCompletion returns completion options for arguments, if that's where parsing left off, or commands if there aren't any unsatisfied args.

func (*CmdClause) Command 

func (c *CmdClause) Command(name, help string) *CmdClause

Command adds a new sub-command.

func (*CmdClause) Commandf added in v0.1.1 

func (c *CmdClause) Commandf(name string, format string, a ...interface{}) *CmdClause

Commandf adds a new sub-command with printf parsing of help

func (*CmdClause) Default 

func (c *CmdClause) Default() *CmdClause

Default makes this command the default if commands don't match.

func (*CmdClause) FlagCompletion 

func (c *CmdClause) FlagCompletion(flagName string, flagValue string) (choices []string, flagMatch bool, optionMatch bool)

func (*CmdClause) FullCommand 

func (c *CmdClause) FullCommand() string

func (*CmdClause) Help added in v0.1.0 

func (c *CmdClause) Help(help string) *CmdClause

Help sets the help message.

func (*CmdClause) HelpLong added in v0.1.0 

func (c *CmdClause) HelpLong(help string) *CmdClause

HelpLong adds a long help text, which can be used in usage templates. For example, to use a longer help text in the command-specific help than in the apps root help.

func (*CmdClause) Hidden 

func (c *CmdClause) Hidden() *CmdClause

func (*CmdClause) Model 

func (c *CmdClause) Model() *CmdModel

func (*CmdClause) PreAction 

func (c *CmdClause) PreAction(action Action) *CmdClause

func (*CmdClause) Validate 

func (c *CmdClause) Validate(validator CmdClauseValidator) *CmdClause

Validate sets a validation function to run when parsing.

type CmdClauseValidator 

type CmdClauseValidator func(*CmdClause) error

type CmdGroupModel 

type CmdGroupModel struct {
	Commands []*CmdModel `json:"commands,omitempty"`
}

func (*CmdGroupModel) FlattenedCommands 

func (c *CmdGroupModel) FlattenedCommands() (out []*CmdModel)

type CmdModel 

type CmdModel struct {
	Name        string   `json:"name"`
	Aliases     []string `json:"aliases,omitempty"`
	Help        string   `json:"help"`
	HelpLong    string   `json:"help_long,omitempty"`
	FullCommand string   `json:"-"`
	Depth       int      `json:"-"`
	Hidden      bool     `json:"hidden,omitempty"`
	Default     bool     `json:"default,omitempty"`

	*FlagGroupModel
	*ArgGroupModel
	*CmdGroupModel
}

func (*CmdModel) String 

func (c *CmdModel) String() string

type FlagClause 

type FlagClause struct {
	// contains filtered or unexported fields
}

FlagClause is a fluid interface used to build flags.

func Flag 

func Flag(name, help string) *FlagClause

Flag adds a new flag to the default parser.

func (*FlagClause) Action 

func (f *FlagClause) Action(action Action) *FlagClause

Dispatch to the given function after the flag is parsed and validated.

func (*FlagClause) Bool 

func (f *FlagClause) Bool() (target *bool)

Bool makes this flag a boolean flag.

func (*FlagClause) BoolList 

func (p *FlagClause) BoolList() (target *[]bool)

BoolList accumulates bool values into a slice.

func (*FlagClause) BoolListVar 

func (p *FlagClause) BoolListVar(target *[]bool)

func (*FlagClause) BoolVar 

func (p *FlagClause) BoolVar(target *bool)

func (*FlagClause) Bytes 

func (p *FlagClause) Bytes() (target *units.Base2Bytes)

Bytes parses numeric byte units. eg. 1.5KB

func (*FlagClause) BytesVar 

func (p *FlagClause) BytesVar(target *units.Base2Bytes)

BytesVar parses numeric byte units. eg. 1.5KB

func (*FlagClause) Counter 

func (p *FlagClause) Counter() (target *int)

A Counter increments a number each time it is encountered.

func (*FlagClause) CounterVar 

func (p *FlagClause) CounterVar(target *int)

func (*FlagClause) Default 

func (f *FlagClause) Default(values ...string) *FlagClause

Default values for this flag. They *must* be parseable by the value of the flag.

func (*FlagClause) Duration 

func (p *FlagClause) Duration() (target *time.Duration)

Duration sets the parser to a time.Duration parser.

func (*FlagClause) DurationList 

func (p *FlagClause) DurationList() (target *[]time.Duration)

DurationList accumulates time.Duration values into a slice.

func (*FlagClause) DurationListVar 

func (p *FlagClause) DurationListVar(target *[]time.Duration)

func (*FlagClause) DurationVar 

func (p *FlagClause) DurationVar(target *time.Duration)

Duration sets the parser to a time.Duration parser.

func (*FlagClause) Enum 

func (a *FlagClause) Enum(options ...string) (target *string)

func (*FlagClause) EnumVar 

func (a *FlagClause) EnumVar(target *string, options ...string)

func (*FlagClause) Enums 

func (p *FlagClause) Enums(options ...string) (target *[]string)

Enums allows a set of values from a set of options.

func (*FlagClause) EnumsVar 

func (p *FlagClause) EnumsVar(target *[]string, options ...string)

EnumsVar allows a value from a set of options.

func (*FlagClause) Envar 

func (f *FlagClause) Envar(name string) *FlagClause

Envar overrides the default value(s) for a flag from an environment variable, if it is set. Several default values can be provided by using new lines to separate them.

func (*FlagClause) ExistingDir 

func (p *FlagClause) ExistingDir() (target *string)

ExistingDir sets the parser to one that requires and returns an existing directory.

func (*FlagClause) ExistingDirVar 

func (p *FlagClause) ExistingDirVar(target *string)

ExistingDir sets the parser to one that requires and returns an existing directory.

func (*FlagClause) ExistingDirs 

func (p *FlagClause) ExistingDirs() (target *[]string)

ExistingDirs accumulates string values into a slice.

func (*FlagClause) ExistingDirsVar 

func (p *FlagClause) ExistingDirsVar(target *[]string)

func (*FlagClause) ExistingFile 

func (p *FlagClause) ExistingFile() (target *string)

ExistingFile sets the parser to one that requires and returns an existing file.

func (*FlagClause) ExistingFileOrDir 

func (p *FlagClause) ExistingFileOrDir() (target *string)

ExistingFileOrDir sets the parser to one that requires and returns an existing file OR directory.

func (*FlagClause) ExistingFileOrDirVar 

func (p *FlagClause) ExistingFileOrDirVar(target *string)

ExistingDir sets the parser to one that requires and returns an existing directory.

func (*FlagClause) ExistingFileVar 

func (p *FlagClause) ExistingFileVar(target *string)

ExistingFile sets the parser to one that requires and returns an existing file.

func (*FlagClause) ExistingFiles 

func (p *FlagClause) ExistingFiles() (target *[]string)

ExistingFiles accumulates string values into a slice.

func (*FlagClause) ExistingFilesOrDirs 

func (p *FlagClause) ExistingFilesOrDirs() (target *[]string)

ExistingFilesOrDirs accumulates string values into a slice.

func (*FlagClause) ExistingFilesOrDirsVar 

func (p *FlagClause) ExistingFilesOrDirsVar(target *[]string)

func (*FlagClause) ExistingFilesVar 

func (p *FlagClause) ExistingFilesVar(target *[]string)

func (*FlagClause) File 

func (p *FlagClause) File() (target **os.File)

File returns an os.File against an existing file.

func (*FlagClause) FileVar 

func (p *FlagClause) FileVar(target **os.File)

FileVar opens an existing file.

func (*FlagClause) Float 

func (p *FlagClause) Float() (target *float64)

Float sets the parser to a float64 parser.

func (*FlagClause) Float32 

func (p *FlagClause) Float32() (target *float32)

Float32 parses the next command-line value as float32.

func (*FlagClause) Float32List 

func (p *FlagClause) Float32List() (target *[]float32)

Float32List accumulates float32 values into a slice.

func (*FlagClause) Float32ListVar 

func (p *FlagClause) Float32ListVar(target *[]float32)

func (*FlagClause) Float32Var 

func (p *FlagClause) Float32Var(target *float32)

func (*FlagClause) Float64 

func (p *FlagClause) Float64() (target *float64)

Float64 parses the next command-line value as float64.

func (*FlagClause) Float64List 

func (p *FlagClause) Float64List() (target *[]float64)

Float64List accumulates float64 values into a slice.

func (*FlagClause) Float64ListVar 

func (p *FlagClause) Float64ListVar(target *[]float64)

func (*FlagClause) Float64Var 

func (p *FlagClause) Float64Var(target *float64)

func (*FlagClause) FloatVar 

func (p *FlagClause) FloatVar(target *float64)

Float sets the parser to a float64 parser.

func (*FlagClause) GetEnvarValue 

func (e *FlagClause) GetEnvarValue() string

func (*FlagClause) GetSplitEnvarValue 

func (e *FlagClause) GetSplitEnvarValue() []string

func (*FlagClause) HasEnvarValue 

func (e *FlagClause) HasEnvarValue() bool

func (*FlagClause) Help added in v0.1.0 

func (f *FlagClause) Help(help string) *FlagClause

Help sets the help message.

func (*FlagClause) HexBytes 

func (p *FlagClause) HexBytes() (target *[]byte)

Bytes as a hex string.

func (*FlagClause) HexBytesList 

func (p *FlagClause) HexBytesList() (target *[][]byte)

HexBytesList accumulates []byte values into a slice.

func (*FlagClause) HexBytesListVar 

func (p *FlagClause) HexBytesListVar(target *[][]byte)

func (*FlagClause) HexBytesVar 

func (p *FlagClause) HexBytesVar(target *[]byte)

func (*FlagClause) Hidden 

func (f *FlagClause) Hidden() *FlagClause

Hidden hides a flag from usage but still allows it to be used.

func (*FlagClause) HintAction 

func (a *FlagClause) HintAction(action HintAction) *FlagClause

HintAction registers a HintAction (function) for the flag to provide completions

func (*FlagClause) HintOptions 

func (a *FlagClause) HintOptions(options ...string) *FlagClause

HintOptions registers any number of options for the flag to provide completions

func (*FlagClause) IP 

func (p *FlagClause) IP() (target *net.IP)

IP sets the parser to a net.IP parser.

func (*FlagClause) IPList 

func (p *FlagClause) IPList() (target *[]net.IP)

IPList accumulates net.IP values into a slice.

func (*FlagClause) IPListVar 

func (p *FlagClause) IPListVar(target *[]net.IP)

func (*FlagClause) IPVar 

func (p *FlagClause) IPVar(target *net.IP)

IP sets the parser to a net.IP parser.

func (*FlagClause) Int 

func (p *FlagClause) Int() (target *int)

Int parses the next command-line value as int.

func (*FlagClause) Int16 

func (p *FlagClause) Int16() (target *int16)

Int16 parses the next command-line value as int16.

func (*FlagClause) Int16List 

func (p *FlagClause) Int16List() (target *[]int16)

Int16List accumulates int16 values into a slice.

func (*FlagClause) Int16ListVar 

func (p *FlagClause) Int16ListVar(target *[]int16)

func (*FlagClause) Int16Var 

func (p *FlagClause) Int16Var(target *int16)

func (*FlagClause) Int32 

func (p *FlagClause) Int32() (target *int32)

Int32 parses the next command-line value as int32.

func (*FlagClause) Int32List 

func (p *FlagClause) Int32List() (target *[]int32)

Int32List accumulates int32 values into a slice.

func (*FlagClause) Int32ListVar 

func (p *FlagClause) Int32ListVar(target *[]int32)

func (*FlagClause) Int32Var 

func (p *FlagClause) Int32Var(target *int32)

func (*FlagClause) Int64 

func (p *FlagClause) Int64() (target *int64)

Int64 parses the next command-line value as int64.

func (*FlagClause) Int64List 

func (p *FlagClause) Int64List() (target *[]int64)

Int64List accumulates int64 values into a slice.

func (*FlagClause) Int64ListVar 

func (p *FlagClause) Int64ListVar(target *[]int64)

func (*FlagClause) Int64Var 

func (p *FlagClause) Int64Var(target *int64)

func (*FlagClause) Int8 

func (p *FlagClause) Int8() (target *int8)

Int8 parses the next command-line value as int8.

func (*FlagClause) Int8List 

func (p *FlagClause) Int8List() (target *[]int8)

Int8List accumulates int8 values into a slice.

func (*FlagClause) Int8ListVar 

func (p *FlagClause) Int8ListVar(target *[]int8)

func (*FlagClause) Int8Var 

func (p *FlagClause) Int8Var(target *int8)

func (*FlagClause) IntVar 

func (p *FlagClause) IntVar(target *int)

func (*FlagClause) Ints 

func (p *FlagClause) Ints() (target *[]int)

Ints accumulates int values into a slice.

func (*FlagClause) IntsVar 

func (p *FlagClause) IntsVar(target *[]int)

func (*FlagClause) IsSetByUser added in v0.1.0 

func (f *FlagClause) IsSetByUser(setByUser *bool) *FlagClause

IsSetByUser let to know if the flag was set by the user

func (*FlagClause) Model 

func (f *FlagClause) Model() *FlagModel

func (*FlagClause) NoEnvar 

func (f *FlagClause) NoEnvar() *FlagClause

NoEnvar forces environment variable defaults to be disabled for this flag. Most useful in conjunction with app.DefaultEnvars().

func (*FlagClause) OpenFile 

func (p *FlagClause) OpenFile(flag int, perm os.FileMode) (target **os.File)

File attempts to open a File with os.OpenFile(flag, perm).

func (*FlagClause) OpenFileVar 

func (p *FlagClause) OpenFileVar(target **os.File, flag int, perm os.FileMode)

OpenFileVar calls os.OpenFile(flag, perm)

func (*FlagClause) OverrideDefaultFromEnvar 

func (f *FlagClause) OverrideDefaultFromEnvar(envar string) *FlagClause

DEPRECATED: Use Envar(name) instead.

func (*FlagClause) PlaceHolder 

func (f *FlagClause) PlaceHolder(placeholder string) *FlagClause

PlaceHolder sets the place-holder string used for flag values in the help. The default behavior is to use the value provided by Default() if provided, then fall back on the capitalized flag name.

func (*FlagClause) PreAction 

func (f *FlagClause) PreAction(action Action) *FlagClause

func (*FlagClause) Regexp 

func (p *FlagClause) Regexp() (target **regexp.Regexp)

Regexp parses the next command-line value as *regexp.Regexp.

func (*FlagClause) RegexpList 

func (p *FlagClause) RegexpList() (target *[]*regexp.Regexp)

RegexpList accumulates *regexp.Regexp values into a slice.

func (*FlagClause) RegexpListVar 

func (p *FlagClause) RegexpListVar(target *[]*regexp.Regexp)

func (*FlagClause) RegexpVar 

func (p *FlagClause) RegexpVar(target **regexp.Regexp)

func (*FlagClause) Required 

func (f *FlagClause) Required() *FlagClause

Required makes the flag required. You can not provide a Default() value to a Required() flag.

func (*FlagClause) ResolvedIP 

func (p *FlagClause) ResolvedIP() (target *net.IP)

Resolve a hostname or IP to an IP.

func (*FlagClause) ResolvedIPList 

func (p *FlagClause) ResolvedIPList() (target *[]net.IP)

ResolvedIPList accumulates net.IP values into a slice.

func (*FlagClause) ResolvedIPListVar 

func (p *FlagClause) ResolvedIPListVar(target *[]net.IP)

func (*FlagClause) ResolvedIPVar 

func (p *FlagClause) ResolvedIPVar(target *net.IP)

func (*FlagClause) SetText added in v0.1.0 

func (p *FlagClause) SetText(text Text)

func (*FlagClause) SetValue 

func (p *FlagClause) SetValue(value Value)

func (*FlagClause) Short 

func (f *FlagClause) Short(name rune) *FlagClause

Short sets the short flag name.

func (*FlagClause) String 

func (p *FlagClause) String() (target *string)

String parses the next command-line value as string.

func (*FlagClause) StringMap 

func (p *FlagClause) StringMap() (target *map[string]string)

StringMap provides key=value parsing into a map.

func (*FlagClause) StringMapVar 

func (p *FlagClause) StringMapVar(target *map[string]string)

StringMap provides key=value parsing into a map.

func (*FlagClause) StringVar 

func (p *FlagClause) StringVar(target *string)

func (*FlagClause) Strings 

func (p *FlagClause) Strings() (target *[]string)

Strings accumulates string values into a slice.

func (*FlagClause) StringsVar 

func (p *FlagClause) StringsVar(target *[]string)

func (*FlagClause) TCP 

func (p *FlagClause) TCP() (target **net.TCPAddr)

TCP (host:port) address.

func (*FlagClause) TCPList 

func (p *FlagClause) TCPList() (target *[]*net.TCPAddr)

TCPList accumulates *net.TCPAddr values into a slice.

func (*FlagClause) TCPListVar 

func (p *FlagClause) TCPListVar(target *[]*net.TCPAddr)

func (*FlagClause) TCPVar 

func (p *FlagClause) TCPVar(target **net.TCPAddr)

TCPVar (host:port) address.

func (*FlagClause) URL 

func (p *FlagClause) URL() (target **url.URL)

URL provides a valid, parsed url.URL.

func (*FlagClause) URLList 

func (p *FlagClause) URLList() (target *[]*url.URL)

URLList provides a parsed list of url.URL values.

func (*FlagClause) URLListVar 

func (p *FlagClause) URLListVar(target *[]*url.URL)

URLListVar provides a parsed list of url.URL values.

func (*FlagClause) URLVar 

func (p *FlagClause) URLVar(target **url.URL)

URL provides a valid, parsed url.URL.

func (*FlagClause) Uint 

func (p *FlagClause) Uint() (target *uint)

Uint parses the next command-line value as uint.

func (*FlagClause) Uint16 

func (p *FlagClause) Uint16() (target *uint16)

Uint16 parses the next command-line value as uint16.

func (*FlagClause) Uint16List 

func (p *FlagClause) Uint16List() (target *[]uint16)

Uint16List accumulates uint16 values into a slice.

func (*FlagClause) Uint16ListVar 

func (p *FlagClause) Uint16ListVar(target *[]uint16)

func (*FlagClause) Uint16Var 

func (p *FlagClause) Uint16Var(target *uint16)

func (*FlagClause) Uint32 

func (p *FlagClause) Uint32() (target *uint32)

Uint32 parses the next command-line value as uint32.

func (*FlagClause) Uint32List 

func (p *FlagClause) Uint32List() (target *[]uint32)

Uint32List accumulates uint32 values into a slice.

func (*FlagClause) Uint32ListVar 

func (p *FlagClause) Uint32ListVar(target *[]uint32)

func (*FlagClause) Uint32Var 

func (p *FlagClause) Uint32Var(target *uint32)

func (*FlagClause) Uint64 

func (p *FlagClause) Uint64() (target *uint64)

Uint64 parses the next command-line value as uint64.

func (*FlagClause) Uint64List 

func (p *FlagClause) Uint64List() (target *[]uint64)

Uint64List accumulates uint64 values into a slice.

func (*FlagClause) Uint64ListVar 

func (p *FlagClause) Uint64ListVar(target *[]uint64)

func (*FlagClause) Uint64Var 

func (p *FlagClause) Uint64Var(target *uint64)

func (*FlagClause) Uint8 

func (p *FlagClause) Uint8() (target *uint8)

Uint8 parses the next command-line value as uint8.

func (*FlagClause) Uint8List 

func (p *FlagClause) Uint8List() (target *[]uint8)

Uint8List accumulates uint8 values into a slice.

func (*FlagClause) Uint8ListVar 

func (p *FlagClause) Uint8ListVar(target *[]uint8)

func (*FlagClause) Uint8Var 

func (p *FlagClause) Uint8Var(target *uint8)

func (*FlagClause) UintVar 

func (p *FlagClause) UintVar(target *uint)

func (*FlagClause) Uints 

func (p *FlagClause) Uints() (target *[]uint)

Uints accumulates uint values into a slice.

func (*FlagClause) UintsVar 

func (p *FlagClause) UintsVar(target *[]uint)

func (*FlagClause) UnNegatableBool added in v0.1.2 

func (p *FlagClause) UnNegatableBool() (target *bool)

UnNegatableBool parses the next command-line value as bool.

func (*FlagClause) UnNegatableBoolList added in v0.1.2 

func (p *FlagClause) UnNegatableBoolList() (target *[]bool)

UnNegatableBoolList accumulates bool values into a slice.

func (*FlagClause) UnNegatableBoolListVar added in v0.1.2 

func (p *FlagClause) UnNegatableBoolListVar(target *[]bool)

func (*FlagClause) UnNegatableBoolVar added in v0.1.2 

func (p *FlagClause) UnNegatableBoolVar(target *bool)

func (*FlagClause) Validator added in v0.6.0 

func (f *FlagClause) Validator(validator OptionValidator) *FlagClause

type FlagGroupModel 

type FlagGroupModel struct {
	Flags []*FlagModel `json:"flags,omitempty"`
}

func (*FlagGroupModel) FlagSummary 

func (f *FlagGroupModel) FlagSummary() string

type FlagModel 

type FlagModel struct {
	Name        string   `json:"name"`
	Help        string   `json:"help"`
	Short       rune     `json:"short,omitempty"`
	Default     []string `json:"default,omitempty"`
	Envar       string   `json:"envar,omitempty"`
	PlaceHolder string   `json:"place_holder,omitempty"`
	Required    bool     `json:"required,omitempty"`
	Hidden      bool     `json:"hidden,omitempty"`

	// used by plugin model
	Boolean    bool `json:"boolean"`
	Negatable  bool `json:"negatable,omitempty"`
	Cumulative bool `json:"cumulative"`

	Value Value `json:"-"`
}

func (*FlagModel) FormatPlaceHolder 

func (f *FlagModel) FormatPlaceHolder() string

func (*FlagModel) HelpWithEnvar added in v0.1.0 

func (f *FlagModel) HelpWithEnvar() string

func (*FlagModel) IsBoolFlag 

func (f *FlagModel) IsBoolFlag() bool

func (*FlagModel) IsCumulative added in v0.5.0 

func (f *FlagModel) IsCumulative() bool

func (*FlagModel) IsNegatable added in v0.1.2 

func (f *FlagModel) IsNegatable() bool

func (*FlagModel) String 

func (f *FlagModel) String() string

type Getter 

type Getter interface {
	Value
	Get() interface{}
}

Getter is an interface that allows the contents of a Value to be retrieved. It wraps the Value interface, rather than being part of it, because it appeared after Go 1 and its compatibility rules. All Value types provided by this package satisfy the Getter interface.

type HintAction 

type HintAction func() []string

HintAction is a function type who is expected to return a slice of possible command line arguments.

type OptionValidator added in v0.6.0 

type OptionValidator func(string) error

OptionValidator can be used to validate individual flags or arguments during parsing

type ParseContext 

type ParseContext struct {
	SelectedCommand *CmdClause

	// Flags, arguments and commands encountered and collected during parse.
	Elements []*ParseElement
	// contains filtered or unexported fields
}

ParseContext holds the current context of the parser. When passed to Action() callbacks Elements will be fully populated with *FlagClause, *ArgClause and *CmdClause values and their corresponding arguments (if any).

func (*ParseContext) EOL 

func (p *ParseContext) EOL() bool

func (*ParseContext) Error 

func (p *ParseContext) Error() bool

func (*ParseContext) HasTrailingArgs 

func (p *ParseContext) HasTrailingArgs() bool

HasTrailingArgs returns true if there are unparsed command-line arguments. This can occur if the parser can not match remaining arguments.

func (*ParseContext) Next 

func (p *ParseContext) Next() *Token

Next token in the parse context.

func (*ParseContext) Peek 

func (p *ParseContext) Peek() *Token

func (*ParseContext) Push 

func (p *ParseContext) Push(token *Token) *Token

func (*ParseContext) String 

func (p *ParseContext) String() string

type ParseElement 

type ParseElement struct {
	// Clause is either *CmdClause, *ArgClause or *FlagClause.
	Clause interface{}
	// Value is corresponding value for an ArgClause or FlagClause (if any).
	Value *string
}

A union of possible elements in a parse stack.

type Settings 

type Settings interface {
	SetValue(value Value)
}

type Text added in v0.1.0 

type Text interface {
	encoding.TextMarshaler
	encoding.TextUnmarshaler
}

Text is the interface to the dynamic value stored in a flag. (The default value is represented as a string.)

type Token 

type Token struct {
	Index int
	Type  TokenType
	Value string
}

func (*Token) Equal 

func (t *Token) Equal(o *Token) bool

func (*Token) IsEOF 

func (t *Token) IsEOF() bool

func (*Token) IsFlag 

func (t *Token) IsFlag() bool

func (*Token) String 

func (t *Token) String() string

type TokenType 

type TokenType int
const (
	TokenShort TokenType = iota
	TokenLong
	TokenArg
	TokenError
	TokenEOL
)

Token types.

func (TokenType) String 

func (t TokenType) String() string

type Value 

type Value interface {
	String() string
	Set(string) error
}

Value is the interface to the dynamic value stored in a flag. (The default value is represented as a string.)

If a Value has an IsBoolFlag() bool method returning true, the command-line parser makes --name equivalent to -name=true rather than using the next command-line argument, and adds a --no-name counterpart for negating the flag.

Example

This example ilustrates how to define custom parsers. HTTPHeader cumulatively parses each encountered --header flag into a http.Header struct. 

package main

import (
	"fmt"
	"net/http"
	"strings"
)

type HTTPHeaderValue http.Header

func (h *HTTPHeaderValue) Set(value string) error {
	parts := strings.SplitN(value, ":", 2)
	if len(parts) != 2 {
		return fmt.Errorf("expected HEADER:VALUE got '%s'", value)
	}
	(*http.Header)(h).Add(parts[0], parts[1])
	return nil
}

func (h *HTTPHeaderValue) Get() interface{} {
	return (http.Header)(*h)
}

func (h *HTTPHeaderValue) String() string {
	return ""
}

func HTTPHeader(s Settings) (target *http.Header) {
	target = new(http.Header)
	s.SetValue((*HTTPHeaderValue)(target))
	return
}

// This example ilustrates how to define custom parsers. HTTPHeader
// cumulatively parses each encountered --header flag into a http.Header struct.
func main() {
	var (
		curl    = New("curl", "transfer a URL")
		headers = HTTPHeader(curl.Flag("headers", "Add HTTP headers to the request.").Short('H').PlaceHolder("HEADER:VALUE"))
	)

	curl.Parse([]string{"-H Content-Type:application/octet-stream"})
	for key, value := range *headers {
		fmt.Printf("%s = %s\n", key, value)
	}
}

Output:

Source Files

View all Source files

Directories

Path Synopsis
_examples
chat1
chat2
completion
curl
A curl-like HTTP command-line client.
 A curl-like HTTP command-line client.
modular
ping
cmd
genvalues
Package units provides helpful unit multipliers and functions for Go.
 Package units provides helpful unit multipliers and functions for Go.

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.