claptrap

claptrap

A simple but powerful Go package to parse command-line arguments getopt(3) style. Designed especially for making CLI based libraries with ease. It has built-in support for sub-commands, long and short flag name combination (for example --version <==> -v), --flag=<value> syntax, inverted flag (for example --no-clean), variadic arguments, global flags, and partial command matching.

★ ★

The project home is here. File bugs here.

Installation

claptrap is a library, and is added to your Go modules like any other:

$ go get ser1.net/claptrap@latest@latest

Usage

package main

import (
  "ser1.net/claptrap"
  "os"
  "fmt"
  "time"
)

func main() {

  reg := claptrap.NewRegistry()

  root := reg.Register("")
  root.AddFlag("!count", "c", []int{1,2,3})
  root.AddFlag("prob...", "p", []float64{1.5, 2.5, 0.5})
  root.AddFlag("delay...", "d", []time.Duration{10*time.Second, 20*time.Minute, time.Hour})
  root.AddFlag("verbose", "v", false)
  root.AddFlag("fuzzy", "f", true)             // A flag with a default true value
  root.AddArg("commestibles...", []string{"carrots", "cabbage", "ceyanne"})
  
  info := reg.Register("info")
  info.AddArg("first", true)                   // The first optional argument must be a boolean (default: true)
  info.AddArg("second", 99)                             // The second optional argument is an int (default: 99)
  info.AddArg("third...", []string{"a", "b", "c", "d"}) // The rest of the arguments must each be a letter, a-d
  info.AddFlag("verbose", "v", true)                      // A completely different verbose, defaulting to true

  c, e := reg.Parse(os.Args[1:])               // exclude the command!

  if e != nil {
    fmt.Printf("%+v\n", e)
  } else {
    switch c.Name {
    case "":
      fmt.Printf("%s %v\n", "commestibles", c.Args["commestibles"].Strings())
      fmt.Printf("%s %t\n", "verbose", c.Flags["verbose"].Bool())
      fmt.Printf("%s %t\n", "fuzzy", c.Flags["fuzzy"].Bool())
      fmt.Printf("%s %+v\n", "count", c.Flags["count"].Ints())
      fmt.Printf("%s %+v\n", "prob", c.Flags["prob"].Floats())
      fmt.Printf("%s %+v\n", "delay", c.Flags["delay"].Durations())
    case "info":
      fmt.Printf("info: %s %t\n", "first", c.Args["first"].Bool())
      fmt.Printf("info: %s %+v\n", "second", c.Args["second"].Ints())
      fmt.Printf("info: %s %+v\n", "third", c.Args["third"].Strings())
      fmt.Printf("info: %s %t\n", "verbose", c.Flags["verbose"].Bool())
    }
  }
}

Rules

There are commands, flags, and args. A parse scope is created with claptrap.NewRegistry().

package main
import "ser1.net/claptrap"
func main() {
  reg := claptrap.NewRegistry()
}

Commands

Commands are specified without dashes, and are like flag sets: each command can have its own set of flags and args. Commands are registered with the `Registry.Register()`` function. Commands usually have a name, but there is a special root command specified by the empty string; args and flags created on this root command don't require a command.

  root := reg.Register("")
  info := reg.Register("info")

The parser will match abbreviated strings to commands, so "lis", "ls", and "l" will match "list", as long as it is a unique match. If both "less" and "list" are registered, the user could supply "lss", "le", or "lt" for example; "ls" is ambiguous and would be a parse error.

Args

Args are placeholders for non-flagged arguments, and are created with CommandConfig.AddArg(); they consume variables in the order they're created. The very last Arg created (on a command) can be variadic, which means it consumes all of the remaining arguments.

  root.AddArg("first", "")
  root.AddArg("second", "")
  root.AddArg("third", "")

Arg names are just that: references to use in your program. They do not appear in the command line. In the above example, the program would take up to three arguments; it'd place the first into first, the second into second, and the third into third.

$ claptest x y z
# root.Args["first"]  => "x"
# root.Args["second"] => "y"
# root.Args["third"]  => "z"

More arguments would result in a parse error. The last Arg registered can be made variadic by adding ... to the name:

  root.AddArg("fourth...", "")

Now, the program will take any number of arguments, with the fourth and greater being placed in fourth. Arguments are optional by default, but can be made mandatory by prefixing the name with !:

  root.AddArg("!second")

Note that this has the effect of also making any previous arguments also mandatory, because claptrap fills arguments in order.

$ claptest x

would fail, because first would get x, and second would get nothing. Required variadic arguments need at least one argument.

claptrap supports strong typing; types are derived from the default value:

  root.AddArg("first", 1)            // ints
  root.AddArg("second", true)        // bools
  root.AddArg("third", 1.0)          // float64
  root.AddArg("fourth", "")          // strings
  root.AddArg("third", time.Now())   // time.Time
  root.AddArg("fourth", time.Second) // time.Duration

claptrap will validate the input data and return a parse error if the argument is not of the required type.

Choices are also supported. Choices limit the allowed arguments, and are set by passing an array of the choices to AddArg():

  root.AddArg("first", []int{1, 2, 3, 5, 8, 13})

This works with all types except bools. Booleans are always only ever true or false, and boolean arguments can not be variadic. With the exception of booleans, all of these features can be combined:

Values are retrieved using one of the type getters. If the wrong type is retrieved, an empty array is provided. If the argument was not provided by the user, the default is provided. An argument can be tested whether it is a default, or was provided by the user, with the Arg.IsSet() function.

• Bool() (the only getter that provides a single value)
• Strings()
• Ints()
• Floats()
• Times()
• Durations()

package main
import "ser1.net/claptrap"
import "os"
import "fmt"
func main() {
  reg := claptrap.NewRegistry()
  reg.Register("").AddArg("!first...", []string{"carrots", "cabbage", "ceyanne"})
  c, e := reg.Parse(os.Args[1:])  // exclude the command!
  if e != nil {
    fmt.Printf("%+v\n", e)
  } else {
    fmt.Printf("%+v\n", c.Args["first"].Strings())
  }
}

$ ./claptest a
first: illegal value a, must be [carrots cabbage ceyanne]
$ ./claptest carrots
[carrots]
$ ./claptest cabbage carrots
[cabbage carrots]

Durations can be any string parsable by Go time.ParseDuration(). Date/times can be in any one of the following formats: time.RFC3339, 2006-01-02T03:04:05, 2006-01-02T03:04, 2006-01-02, 01-02, 03:04:05 (full time), 03:04 (hour and minute), :04:05 (minute and second), 03: (just an hour), 04 (just the minute), :05 (just the second), 2006 (year only), 01- (month only), -02 (day only).

Flags

Flags are prefixed with dashes. Unlike Args, flags are always provided on input. Flags can have long and short forms; like getopt, long forms are specified with a double-dash -- and short forms with a single dash -. With a couple of exceptions, Flags follow all the rules and features of arguments: mandatory, variadic, defaults, choices, and types.

• All flags may be variadic, not only the last. Flags and Args can be combined, and do not interfere with each other.
• Mandatory and variadic syntax is specified on the long form.

The biggest differences are in boolean flags:

• Boolean flags take no arguments. If they're supplied, they're true; if they are not supplied, they get the default.
• Boolean long Flags automatically get a no- version that returns false if supplied.

For demonstration, if the example code at the top of this readme is run, it will produce the following outputs for the given inputs.

# Flag can be required
$ go run .
count is required

# Flag values can be constrained
$ go run . -c 5
count: illegal value 5, must be [1 2 3]

# Illegal variadic
$ go run . -c 1 --count 2
count: 2 values provided for non-variadic argument count

# Defaults for booleans can be true or false, and multiple flags can be variadic
$ go run . -c 1 -p 1.5 -p 2.5 --delay 10s -d 1h
commestibles [carrots cabbage ceyanne]
verbose false
fuzzy true
count [1]
prob [1.5 2.5]
delay [10s 1h0m0s]

# Supplying a boolean Flag is always true
$ go run . -c 1 -v -f
commestibles [carrots cabbage ceyanne]
verbose true
fuzzy true
count [1]
prob [1.5 2.5 0.5]
delay [10s 20m0s 1h0m0s]

# Automatic --no-longflag is always false, and args can be anywhere
$ go run . carrots -c 2 --no-fuzzy --no-verbose ceyanne
commestibles [carrots ceyanne]
verbose false
fuzzy false
count [2]
prob [1.5 2.5 0.5]
delay [10s 20m0s 1h0m0s]

# Short boolean arguments can be combined. A non-boolean argument can be included, but
# it must be at the end:
$ go run . -vfc 3
commestibles [carrots cabbage ceyanne]
verbose true
fuzzy true
count [3]
prob [1.5 2.5 0.5]
delay [10s 20m0s 1h0m0s]

# Flags with the same name can be given for different commands, and have different types and defaults
$ go run . info
info: first true
info: second [99]
info: third [a b c d]
info: verbose true

Important

Root arguments and flags are global: they can be provided on the command line before other arguments. However, if the root command has any arguments, they will consume commands before the commands are identified. For example:

  reg := claptrap.NewRegistry()
  root := reg.Register("")
  root.AddArg("foo", "")
  root.AddFlag("ex", "x", false)
  info := reg.Register("info")
  root.AddFlag("ex", "x", false)
  reg.Parse([]string{"info", "-x"})
  // the -x will go to root, not info
  root.Flags["ex"].Bool() == true
  root.Args["foo"].Strings() == []string{"info"}
  info.Flags["ex"].Bool() == false
  info.IsSet == false

UIs that have global flags should limit themselves to using Flags and not Args in the root command.

Caveats and future

• Times are really limited right now; you have to provide them in full YYYY-mm-ddThh:mm:ss format. There will a a smarter parser, eventually.
• There's (not yet) auto-generated help/USAGE text.

Credits

This library was based initially on clapper; it adds several features missing from clapper, but the main reason for the fork was that the several behaviors were changed in ways that differ fundamentally with how clapper treats arguments.

Features

The primary feature is general POSIX getopt compatability, so that the tools built with the library have a familiar interface for the largest popular command-line-using population in the world (hint: it isn't Plan 9). On top of that, I wanted the library to support some validation, to reduce runtime errors easily caused by repetitive validation code. The objective of claptrap is to be small but provide general getopt compatability and validation features. The most popular libraries are large, either directly or indirectly through dependencies. claptrap has 0 dependencies outside of the Go stdlib.

claptrap supports the following data types:

• bool
• string
• int
• float64
• time.Time
• time.Duration

Env vars would be nice, to be able to support 12-Factor apps, but that starts to feel like feature envy to me, and it's something that is easily added by a library such as GoBike. The biggest missing feature is synchronization with configuration files -- this often accounts for a significant amount of error-prone code; I'm hoping to provide (or find) support through a seperate library, such as go-ini.

Compared to other flags libraries, claptrap is among the smallest, and it pulls in no other dependencies.

LOC -- no tests, no comments
ABC Score -- ABC complexity for the project (excluding dependencies)

Elevator Pitch (toot-sized)

Every few months I go searching around for a flags library that isn't bigger than my program, conforms to getopt, and has basic validation features. I never find it, so I wrote one.

claptrap: very small, much features, getoptish https://sr.ht/~ser/claptrap/

claptrap has long & short, combined short, inverted, typed, mandatory, global, and variadic flags. It has subcommands and arguments, and partial command matching. And it's 490 non-comment, non- unit-test lines of code, and zero dependencies.

#golang #library #flags