Skip to content
Command-line options parsing library, POSIX/GNU compliant, supports struct tags as well as the Go's flag approach.
Go
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
examples Initial commit Jul 17, 2019
.travis.yml Code coverage Aug 10, 2019
LICENSE Initial commit Jul 17, 2019
README.md Add support for float64 Sep 27, 2019
flag.go Add support for float64 Sep 27, 2019
flag_test.go
usage.go
value.go
value_test.go

README.md

flaq

Build Status Coverage Status GoDoc

flaq is a command-line options parsing library for Go.

The package follows POSIX / GNU conventions, it notably supports:

  • short and long options
  • options with required, optional, or no argument
  • parsing options intermixed with args
  • defining options in a struct
  • customizable help usage
  • option abbreviations

Usage

As an example, we will specify a --name option with a -n shorthand, accepting a string argument. We will also define a --yell bool option.

There are mainly 2 approaches when using flaq.

Using a struct

The first approach is to define options through a struct:

package main

import (
	"fmt"
	"strings"

	"github.com/qdamm/flaq"
)

type Options struct {
	Name string `flaq:"-n, --name string  name of the person to greet"`
	Yell bool   `flaq:"    --yell         greet the person loudly"`
}

var opts = Options{Name: "world"}

func main() {
	flaq.Struct(&opts)
	flaq.Parse()

	if opts.Yell {
		opts.Name = strings.ToUpper(opts.Name)
	}
	fmt.Printf("Hello %s!\n", opts.Name)
}

Using a struct creates a self-documented piece of code. It also plays well with other projects such as caarlos0/env, if you want for example to read values from environment variables as well.

See the struct fields section for more information about this.

Using a variable per option

The second approach relies on a similar API than the flag package:

package main

import (
	"fmt"

	"github.com/qdamm/flaq"
)

var name = "world"
var yell = false

func main() {
	flaq.String(&name, "name", "n", "name of the person to greet")
	flaq.Bool(&yell, "yell", "", "whether to yell or not", false)
	flaq.Parse()

	if yell {
		name = strings.ToUpper(name)
	}
	fmt.Printf("Hello %s!\n", name)
}

Help usage

By default, help usage is printed whenever a --help or -h option is seen:

$ greet --help
Usage: greet [options]

Options:
  -h, --help           show usage help
  -n, --name <string>  name of the person to greet
      --yell           greet loudly

This behavior can be removed or customized.

Struct fields

Struct fields tags are expected to follow the -s, --long type description pattern, where:

  • -s is the option shortand.
  • --long is the option long form.
  • type is the type of argument the option accepts, if any.
  • description is the option description.

In order to ease alignment for readability, there can be an arbitrary number of whitespaces between the different sections.

Here is a reference of the supported field types:

type Options struct {
	String   string        `flaq:"-n, --name string         a string eg. --string=world"`
	Switch   bool          `flaq:"    --switch              --switch will set the value to true"`
	Bool     bool          `flaq:"    --bool bool           --bool, --bool=true or --bool=false"`
	Int      int           `flaq:"    --int int             an int value eg. --int=100"`
	Float64  float64       `flaq:"    --float64 float64     a float value eg. --float64=3.14159"`
	Count    int           `flaq:"-c, --count count         -ccc will set this count value to 3"`
	Duration time.Duration `flaq:"    --duration duration   a duration eg. --duration=5min"`
}
You can’t perform that action at this time.