opts: github.com/jpillora/opts Index | Files

package opts

import "github.com/jpillora/opts"

Package opts defines a struct-tag based API for rapidly building command-line interfaces. For example:

package main

import (
	"log"
	"github.com/jpillora/opts"
)

func main() {
	type config struct {
		File  string `opts:"help=file to load"`
		Lines int    `opts:"help=number of lines to show"`
	}
	c := config{}
	opts.Parse(&c)
	log.Printf("%+v", c)
}

Build and run:

$ go build -o my-prog
$ ./my-prog --help

  Usage: my-prog [options]

  Options:
  --file, -f   file to load
  --lines, -l  number of lines to show
  --help, -h   display help

$ ./my-prog -f foo.txt -l 42
{File:foo.txt Lines:42}

See https://github.com/jpillora/opts for more information and more examples.

Index

Package Files

doc.go item.go node.go node_build.go node_commands.go node_complete.go node_help.go node_parse.go opts.go strings.go

Variables

var DefaultOrder = []string{
    "usage",
    "summary",
    "args",
    "flaggroups",
    "cmds",
    "author",
    "version",
    "repo",
    "errmsg",
}

DefaultOrder defines which templates get rendered in which order. This list is referenced in the "help" template below.

var DefaultTemplates = map[string]string{
    "help":          `{{ $root := . }}{{range $t := .Order}}{{ templ $t $root }}{{end}}`,
    "usage":         `Usage: {{.Name }} [options]{{template "usageargs" .}}{{template "usagecmd" .}}` + "\n",
    "usageargs":     `{{range .Args}} {{.Name}}{{end}}`,
    "usagecmd":      `{{if .Cmds}} <command>{{end}}`,
    "extradefault":  `{{if .}}default {{.}}{{end}}`,
    "extraenv":      `{{if .}}env {{.}}{{end}}`,
    "extramultiple": `{{if .}}allows multiple{{end}}`,
    "summary":       "{{if .Summary}}\n{{ .Summary }}\n{{end}}",
    "args":          `{{range .Args}}{{template "arg" .}}{{end}}`,
    "arg":           "{{if .Help}}\n{{.Help}}\n{{end}}",
    "flaggroups":    `{{ range $g := .FlagGroups}}{{template "flaggroup" $g}}{{end}}`,
    "flaggroup": "{{if .Flags}}\n{{if .Name}}{{.Name}} options{{else}}Options{{end}}:\n" +
        `{{ range $f := .Flags}}{{template "flag" $f}}{{end}}{{end}}`,
    "flag":    `{{.Name}}{{if .Help}}{{.Pad}}{{.Help}}{{end}}` + "\n",
    "cmds":    "{{if .Cmds}}\nCommands:\n" + `{{ range $sub := .Cmds}}{{template "cmd" $sub}}{{end}}{{end}}`,
    "cmd":     "· {{ .Name }}{{if .Help}}{{.Pad}}  {{ .Help }}{{end}}\n",
    "version": "{{if .Version}}\nVersion:\n{{.Pad}}{{.Version}}\n{{end}}",
    "repo":    "{{if .Repo}}\nRead more:\n{{.Pad}}{{.Repo}}\n{{end}}",
    "author":  "{{if .Author}}\nAuthor:\n{{.Pad}}{{.Author}}\n{{end}}",
    "errmsg":  "{{if .ErrMsg}}\nError:\n{{.Pad}}{{.ErrMsg}}\n{{end}}",
}

DefaultTemplates define a set of individual templates that get rendered in DefaultOrder. You can replace templates or insert templates before or after existing templates using the DocSet, DocBefore and DocAfter methods. For example, you can insert a string after the usage text with:

DocAfter("usage", "this is a string, and if it is very long, it will be wrapped")

The entire help text is simply the "help" template listed below, which renders a set of these templates in the order defined above. All templates can be referenced using the keys in this map:

type Completer Uses

type Completer interface {
    //Complete is given user's input and should
    //return a corresponding set of valid inputs.
    //Note: all result strings must be prefixed
    //with the user's input.
    Complete(user string) []string
}

Completer represents a shell-completion implementation for a single field. By default, all fields will auto-complete files and directories. Use a field type which implements this Completer interface to override this behaviour.

type Opts Uses

type Opts interface {
    //Name of the command. For the root command, Name defaults to the executable's
    //base name. For subcommands, Name defaults to the package name, unless its the
    //main package, then it defaults to the struct name.
    Name(name string) Opts
    //Version of the command. Commonly set using a package main variable at compile
    //time using ldflags (for example, go build -ldflags -X main.version=42).
    Version(version string) Opts
    //ConfigPath is a path to a JSON file to use as defaults. This is useful in
    //global paths like /etc/my-prog.json. For a user-specified path. Use the
    //UserConfigPath method.
    ConfigPath(path string) Opts
    //UserConfigPath is the same as ConfigPath however an extra flag (--config-path)
    //is added to this Opts instance to give the user control of the filepath.
    //Configuration unmarshalling occurs after flag parsing.
    UserConfigPath() Opts
    //UseEnv enables the default environment variables on all fields. This is
    //equivalent to adding the opts tag "env" on all flag fields.
    UseEnv() Opts
    //Complete enables auto-completion for this command. When enabled, two extra
    //flags are added (--install and --uninstall) which can be used to install
    //a dynamic shell (bash, zsh, fish) completion for this command. Internally,
    //this adds a stub file which runs the Go binary to auto-complete its own
    //command-line interface. Note, the absolute path returned from os.Executable()
    //is used to reference to the Go binary.
    Complete() Opts
    //EmbedFlagSet embeds the given pkg/flag.FlagSet into
    //this Opts instance. Placing the flags defined in the FlagSet
    //along side the configuration struct flags.
    EmbedFlagSet(*flag.FlagSet) Opts
    //EmbedGlobalFlagSet embeds the global pkg/flag.CommandLine
    //FlagSet variable into this Opts instance.
    EmbedGlobalFlagSet() Opts

    //Summary adds a short sentence below the usage text
    Summary(summary string) Opts
    //Repo sets the source repository of the program and is displayed
    //at the bottom of the help text.
    Repo(repo string) Opts
    //Author sets the author of the program and is displayed
    //at the bottom of the help text.
    Author(author string) Opts
    //PkgRepo automatically sets Repo using the struct's package path.
    //This does not work for types defined in the main package.
    PkgRepo() Opts
    //PkgAuthor automatically sets Author using the struct's package path.
    //This does not work for types defined in the main package.
    PkgAuthor() Opts
    //DocSet replaces an existing template.
    DocSet(id, template string) Opts
    //DocBefore inserts a new template before an existing template.
    DocBefore(existingID, newID, template string) Opts
    //DocAfter inserts a new template after an existing template.
    DocAfter(existingID, newID, template string) Opts
    //DisablePadAll removes the padding from the help text.
    DisablePadAll() Opts
    //SetPadWidth alters the padding to specific number of spaces.
    //By default, pad width is 2.
    SetPadWidth(padding int) Opts
    //SetLineWidth alters the maximum number of characters in a
    //line (excluding padding). By default, line width is 96.
    SetLineWidth(width int) Opts

    //AddCommand adds another Opts instance as a subcommand.
    AddCommand(Opts) Opts
    //Parse uses os.Args to parse the current flags and args.
    Parse() ParsedOpts
    //ParseArgs uses a given set of args to to parse the
    //current flags and args. Assumes the executed program is
    //the first arg.
    ParseArgs(args []string) ParsedOpts
}

Opts is a single configuration command instance. It represents a node in a tree of commands. Use the AddCommand method to add subcommands (child nodes) to this command instance.

func New Uses

func New(config interface{}) Opts

New creates a new Opts instance using the given configuration struct pointer.

type ParsedOpts Uses

type ParsedOpts interface {
    //Help returns the final help text
    Help() string
    //IsRunnable returns whether the matched command has a Run method
    IsRunnable() bool
    //Run assumes the matched command is runnable and executes its Run method.
    //The target Run method must be 'Run() error' or 'Run()'
    Run() error
    //RunFatal assumes the matched command is runnable and executes its Run method.
    //However, any error will be printed, followed by an exit(1).
    RunFatal()
}

func Parse Uses

func Parse(config interface{}) ParsedOpts

Parse is shorthand for

opts.New(config).Parse()

type Setter Uses

type Setter interface {
    Set(string) error
}

Setter is any type which can be set from a string. This includes flag.Value.

Package opts imports 22 packages (graph) and is imported by 20 packages. Updated 2019-09-10. Refresh now. Tools for package owners.