~rjarry/go-opt

Argument parsing and completion based on struct tags
completion: return descriptions from callback values
mod: add v2 suffix
spec: add description field to arguments

clone

read-only
https://git.sr.ht/~rjarry/go-opt
read/write
git@git.sr.ht:~rjarry/go-opt

You can also use your local clone with git send-email.

#go-opt

builds.sr.ht status

go-opt is a library to parse command line arguments based on tag annotations on struct fields. It came as a spin-off from aerc to deal with its internal commands.

This project is a scaled down version of go-arg with different usage patterns in mind: command parsing and argument completion for internal application commands.

#License

MIT

The shlex.go file has been inspired from the github.com/google/shlex package which is licensed under the Apache 2.0 license.

#Contributing

Set patches via email to ~rjarry/public-inbox@lists.sr.ht or alternatively to ~rjarry/aerc-devel@lists.sr.ht with the PATCH go-opt subject prefix.

git config format.subjectPrefix "PATCH go-opt"
git config sendemail.to "~rjarry/public-inbox@lists.sr.ht"

#Usage

#Shell command line splitting

package main

import (
	"log"

	"git.sr.ht/~rjarry/go-opt/v2"
)

func main() {
	args, err := opt.LexArgs(`foo 'bar baz' -f\ boz -- " yolo "`)
	if err != nil {
		log.Fatalf("error: %s\n", err)
	}

	fmt.Printf("count: %d\n", args.Count())
	fmt.Printf("args: %#v\n", args.Args())
	fmt.Printf("raw: %q\n", args.String())

	fmt.Println("shift 2")
	args.Shift(2)

	fmt.Printf("count: %d\n", args.Count())
	fmt.Printf("args: %#v\n", args.Args())
	fmt.Printf("raw: %q\n", args.String())
}
$ go run main.go
count: 5
args: []string{"foo", "bar baz", "-f boz", "--", " yolo "}
raw: "foo 'bar baz' -f\\ boz -- \" yolo \""
shift 2
count: 3
args: []string{"-f boz", "--", " yolo "}
raw: "-f\\ boz -- \" yolo \""

#Argument parsing

package main

import (
	"fmt"
	"log"

	"git.sr.ht/~rjarry/go-opt/v2"
)

type Foo struct {
	Delay time.Duration `opt:"-t,--delay" action:"ParseDelay" default:"1s"`
	Force bool          `opt:"--force"`
	Name  string        `opt:"name" required:"false" metavar:"FOO"`
	Cmd   []string      `opt:"..."`
}

func (f *Foo) ParseDelay(arg string) error {
	d, err := time.ParseDuration(arg)
	if err != nil {
		return err
	}
	f.Delay = d
	return nil
}

func main() {
	var foo Foo
	err := opt.CmdlineToStruct("foo -f bar baz 'xy z' ", &foo)
	if err != nil {
		log.Fatalf("error: %s\n", err)
	}
	fmt.Printf("%#v\n", foo)
}
$ foo --force bar baz 'xy z'
main.Foo{Delay:1000000000, Force:true, Name:"bar", Cmd:[]string{"baz", "xy z"}}
$ foo -t
error: -t takes a value. Usage: foo [-t <delay>] [--force] [<name>] <cmd>...

#Argument completion

package main

import (
	"fmt"
	"log"
	"os"
	"strings"

	"git.sr.ht/~rjarry/go-opt/v2"
)

type CompleteStruct struct {
	Name    string   `opt:"-n,--name" required:"true" complete:"CompleteName"`
	Delay   float64  `opt:"--delay"`
	Zero    bool     `opt:"-z"`
	Backoff bool     `opt:"-B,--backoff"`
	Tags    []string `opt:"..." complete:"CompleteTag"`
}

func (c *CompleteStruct) CompleteName(arg string) []string {
	return []string{"leonardo", "michelangelo", "rafaelo", "donatello"}
}

func (c *CompleteStruct) CompleteTag(arg string) []string {
	var results []string
	prefix := ""
	if strings.HasPrefix(arg, "-") {
		prefix = "-"
	} else if strings.HasPrefix(arg, "+") {
		prefix = "+"
	}
	tags := []string{"unread", "sent", "important", "inbox", "trash"}
	for _, t := range tags {
		t = prefix + t
		if strings.HasPrefix(t, arg) {
			results = append(results, t)
		}
	}
	return results
}

func main() {
	args, err := opt.QuoteArgs(os.Args...)
	if err != nil {
		log.Fatalf("error: %s\n", err)
	}
	var s CompleteStruct
	completions, _ := opt.GetCompletions(args.String(), &s)
	for _, c := range completions {
		fmt.Println(c.Value)
	}
}
$ foo i
important
inbox
$ foo -
--backoff
--delay
--name
-B
-important
-inbox
-n
-sent
-trash
-unread
-z
$ foo +
+important
+inbox
+sent
+trash
+unread

#Supported tags

There is a set of tags that can be set on struct fields:

#opt:"-f,--foo"

Registers that this field is associated to the specified flag(s). Unless a custom action method is specified, the flag value will be automatically converted from string to the field type (only basic scalar types are supported: all integers (both signed and unsigned), all floats and strings. If the field type is bool, the flag will take no value.

#opt:"blah"

Field is associated to a positional argument.

#opt:"..."

Field will be mapped to all remaining arguments. If the field is string, the raw command line will be stored preserving any shell quoting, otherwise the field needs to be []string and will receive the remaining arguments after interpreting shell quotes.

#opt:"-"

Special value to indicate that this command will accept any argument without any check nor parsing. The field on which it is set will not be updated and should be called Unused struct{} as a convention. The field name must start with an upper case to avoid linter warnings because of unused fields.

#action:"ParseFoo"

Custom method to be used instead of the default automatic conversion. Needs to be a method with a pointer receiver to the struct itself, takes a single string argument and may return an error to abort parsing. The action method is responsible of updating the struct.

#description:"foobaz" or desc:"foobaz"

A description that is returned alongside arguments during autocompletion.

#default:"foobaz"

Default string value if not specified by the user. Will be processed by the same conversion/parsing as any other argument.

#metavar:"foo|bar|baz"

Displayed name for argument values in the generated usage help.

#required:"true|false"

By default, flag arguments are optional and positional arguments are required. Using this tag allows changing that default behaviour. If an argument is not required, it will be surrounded by square brackets in the generated usage help.

#aliases:"cmd1,cmd2"

By default, arguments are interpreted for all command aliases. If this is specified, this field/option will only be applicable to the specified command aliases.

#complete:"CompleteFoo"

Custom method to return the valid completions for the annotated option / argument. Needs to be a method with a pointer receiver to the struct itself, takes a single string argument and must return a []string slice containing the valid completions.

#Caveats

Depending on field types, the argument string values are parsed using the appropriate conversion function.

If no opt tag is set on a field, it will be excluded from automated argument parsing. It can still be updated indirectly via a custom action method.

Short flags can be combined like with getopt(3):

  • Flags with no value: -abc is equivalent to -a -b -c
  • Flags with a value (options): -j9 is equivalent to -j 9

The special argument -- forces an end to the flag parsing. The remaining arguments are interpreted as positional arguments (see getopt(3)).

Do not follow this link