yagap

yagap

Yet another Go argument parser

Why?

The basic argument parsing mechamisms in Go include package flag. It's pretty good, but maybe not good enough for your needs.

Neither mine.

The beauty of Go is that you can extend its library in a way that makes it easy for anyone interested to use it. Notable examples include go-flags and argparse. Don't get me wrong: they're both great, but they have some annoyances, and that's why I created yagap. It was inspired (but not based) on these libraries, and also on Python argparse.

Installation

Just run go get -u codeberg.org/taflaj/yagap on your application directory. Pretty simple, isn't it?

But you already knew that…

Usage

The below are the steps necessary to use the parser.

Initialization

To initialize it, use parser := yagap.NewParser(progname, description), where progname and description are strings that will be shown when presenting your program's help.

Configuration

Two methods allow for parser configuration, both returning a reference to the parser object. This way, methods can be concatenated. For example, you could do something like parser.SetEpilog().AddOption() and so forth.

The first one is parser.SetEpilog(epilog), where epilog (a string) contains the message to be printed at the end of the help text. This is entirely optional.

The second one is parser.AddOption(option), where option is a reference to a yagap.OptionObject, which in turn defines each argument option.

Argument option

To define an argument option, you can use option := yagap.NewOption(). Just like above, the methods described below return a reference to the argument option itself, thus allowing you to concatenate the method calls and, as a result, configuring all option aspects in a single line of code.

Here's an example to show how to enable -h and --help as arguments:

help := yagap.NewOption().
  SetShort("h").
  SetLong("help").
  SetDescription("Print this message").
  SetFlag()

This isn't really necessary, though, as yagap.NewParser automatically does it for you. You can, however, customize it using the SetDescription and SetMultiple methods. Just be careful what you're doing, and keep in mind that there's no way to disable it.

Execution

The user launches the program specifying a number of arguments on the command line. Single character arguments can be entered following a -, jointly or independently. For example, if a, b, and c are valid arguments, the user can enter them as -a -b -c or -abc. Long arguments are entered individually following a --, as in --help. Entering -- with no arguments stops parsing immediately; all remaining arguments are passed as entered, regardless of being preceded by - or --.

To capture the arguments, use values, err := parser.Parse(), which is a convenience method. Alternatively you could use values, err := parser.ParseArgs(os.Args[1:]). The first returned value is a slice of strings with all arguments that were not subject to parsing. The second one indicates any errors that took place during parsing, or nil otherwise.

Obtaining results

These methods are available directly on the Option object:

These methods are available on the Parser object:

A practical example

This program accepts -d or --debug to enable debugging mode, -c or --config to specify an alternate configuration file, and obviously -h or --help for help.

func main() {
	parser := yagap.NewParser("myprog", "Just for testing").SetEpilog("And nothing else")
	debug := yagap.NewOption().
		SetShort("d").
		SetLong("debug").
		SetDescription("Enable debugging mode").
		SetFlag()
	parser.AddOption(debug.(*yagap.OptionObject))
	config := yagap.NewOption().
		SetShort("c").
		SetLong("config").
		SetDescription("Configuration file").
		SetDefault("config.cfg")
	parser.AddOption(config.(*yagap.OptionObject))
	args, err := parser.Parse()
	if err != nil {
		fmt.Println(err)
		os.Exit(1)
	}
	if parser.GetHelpOption().IsSet() {
		parser.PrintUsage()
		fmt.Println()
	} else {
		filename, _ := config.GetValue()
		fmt.Printf("Debugging mode: %t\nUsing configuration file %s\nAdditional arguments: %v\n", debug.IsSet(), filename, args)
	}
}

Sample runs

$ example
Debugging mode: false
Using configuration file config.cfg
Additional arguments: []

$ example --help
Just for testing
Usage: myprog <arguments>
Arguments:
  -h  --help    Print this message
  -d  --debug   Enable debugging mode
  -c  --config  Configuration file
  --            Stop parsing (all further arguments are passed through)
And nothing else

$ example --debug -c test.cfg Hello world
Debugging mode: true
Using configuration file test.cfg
Additional arguments: [Hello world]

Future improvements

I definitely need to refactor ParseArgs. In its current shape and form, it's overly complicated.

I usually like to stop the program once help is presented. Today, it's in the hands of the developer to force an exit if -h or --help are entered. I may want to add a method to stop parsing once the user asks for help.

Talking about help, I should show the default value for any arguments that have it defined.

One thing that could be useful (which I also saw elsewhere) is to have a callback function for when selected arguments are entered.

I can't think of anything else at the moment. Once you start using it (with my heartful thanks), you might come up with an idea or too; please share them with me. Thank you for your support!