A Go command-line parser
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
.editorconfig
.travis.yml
LICENSE
README.md
arg.go
command.go
command_test.go
flag.go
go.mod
parse.go
tokenize.go
tokenize_test.go
usage.go
usage_test.go
value.go
values.go
values_test.go

README.md

Gargle

GoDoc Reference Build Status

This is a work in progress and offers no compatibility guarantees.

Motivation

Gargle aims to provide a flexible command line parser while avoiding the complexity of deep integration.

What differentiates Gargle?

  • No special casing required for common flags and commands, such as --help.
  • Code-generated usage is more flexible, lighter weight, and often more readable than templates.
  • Minimal side-effects help separate declaration from execution.
  • Light-weight and isolated.

Examples

Adding Help

Any action can be written to write application usage. Following is an example which illustrates adding help using the default usage writer.

cmd := &Command{/*...*/}
cmd.AddFlags(gargle.NewHelpFlag(nil))

The value nil could be replaced by any Action to customize usage.

Negative Booleans

Some applications prefer to provide negated versions of boolean flags. This example shows how to create a flag which can be explicitly enabled or disabled via --enable-foo and --disable-foo.

var foo bool
cmd := &Command{/*...*/}
cmd.NewFlag("enable-foo", "...").BoolVar(&foo)
cmd.NewFlag("disable-foo", "...").NegatedBoolVar(&foo).Hide()
)

Environment Defaults

It's often convenient to accept environment variables in place of flags. This example shows how to wrap a value with an environment-backed default value.

func EnvDefault(v gargle.Value, key string) gargle.Value {
    if s, ok := os.LookupEnv(key); ok {
        return gargle.WithDefault(v, s)
    }
    return v
}
setting := "<none>"
Flag(Name: "setting", EnvDefault(gargle.StringVar(&setting), "APP_SETTING")

This sets value in order of precedence to:

  1. The flag --setting if provided.
  2. The environment variable APP_SETTING if provided.
  3. The value "<none>" if none of the above.

Why "Gargle"?

The Go ecosystem is rife with really bad puns. In short, GoArgParse -> GArg -> Gargle.

Alternatives

  • flag:
    • Fast, simple, and built in
    • Doesn't directly support sub-commands
    • Difficult to customize
  • Cobra:
    • Extremely customizable
    • Complex interface, provides a code generator
    • Integrates with Viper
    • Template-based usage formatting
  • Kingpin
    • Fluent-style interface
    • Template-based usage formatting