README

PkgGoDev Go Report Card

Go Flag Utils

This is a Go library that provides a few types you can use with flag.Var().

Sample Code

There are detailed examples for each type on pkg.go.dev, but here's a quick example:

// Default to red
var color flagutils.RGB{
	R: 0xff,
}
flag.Var(
	&color,
	"color",
	"The color to use",
)
var featureA, featureB flagutils.OneOf
flagutils.GroupOneOf(&featureA, &featureB)
flag.Var(
	&featureA,
	"featureA",
	"Run feature A, unsets featureB",
)
flag.Var(
	&featureB,
	"featureB",
	"Run feature B, unsets featureA",
)
flag.Parse()
switch {
case featureA.Bool:
	// Run feature A
case featureB.Bool:
	// Run feature B
}

License

BSD License.

Documentation

Overview

Package flagutils provides a few types you can use with flag.Var().

Please refer to the examples to see more details.

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func GroupAllOneOf

func GroupAllOneOf(fs *flag.FlagSet)

GroupAllOneOf group all OneOf flag values inside the FlagSet together.

It finds all OneOf values in the FlagSet, then calls GroupOneOf.

func GroupOneOf

func GroupOneOf(values ...*OneOf)

GroupOneOf groups OneOf values together.

Please note that in case of regrouping, it only affects the values in the new group. For example say you have a previous group:

var a, b, c OneOf
GroupOneOf(&a, &b, &c)

Then you regroup a and b:

GroupOneOf(&a, &b)

After the second GroupOneOf, a and b have the group info of each other, but c still records the group info of all of them. You will need to also regroup c with itself to complete the regrouping:

GroupOneOf(&c)

Types

type OneOf

type OneOf struct {
	Bool bool
	// contains filtered or unexported fields
}

OneOf is a flag type that works like bool, but can be grouped together.

When you group several OneOf values together, (via GroupOneOf or GroupAllOneOf) whenever one of them is set to true, the rest of the group will be set to false automatically.

It implements flag.Getter interface.

Example

This example demostrates how to use OneOf in your program.

package main

import (
	"flag"
	"fmt"
	"os"

	"go.yhsif.com/flagutils"
)

func main() {
	// Or use flag.CommandLine instead.
	fs := flag.NewFlagSet("", flag.ExitOnError)
	// Define 3 features, can only run one of them at a time.
	var a, b, c flagutils.OneOf
	fs.Var(&a, "featureA", "Run feature A, unsets featureB and featureC")
	fs.Var(&b, "featureB", "Run feature B, unsets featureA and featureC")
	fs.Var(&c, "featureC", "Run feature C, unsets featureA and featureB")
	// You can also use
	//     flagutils.GroupAllOneOf(fs)
	// if you don't have any other OneOf flag values.
	flagutils.GroupOneOf(&a, &b, &c)
	// TODO: Set other flags here.

	fs.Parse(os.Args[1:])
	// Now your program supports -featureA, -featureB, and -featureC args,
	// and the last one in the command line overrides previous one(s).
	//
	// This means you can define a bash (or other shell) alias to specify a
	// default feature, e.g.:
	//     alias my-cmd='my-cmd -featureA'
	// and still be able to override it in command line:
	//     my-cmd -featureB
	// which is actually
	//     my-cmd -featureA -featureB
	// and runs featureB instead of featureA.

	switch {
	default:
		// Please note that OneOf group only guarantees that at most one of the
		// values will be set to true. It's still possible that all of them are
		// false.
		fmt.Fprintln(
			os.Stderr,
			"You have to specify one of -featureA, -featureB, or -featureC flags.",
		)
		os.Exit(-1)
	case a.Bool:
		// TODO: Implement feature A here.
	case b.Bool:
		// TODO: Implement feature B here.
	case c.Bool:
		// TODO: Implement feature C here.
	}
}
Output:

func (*OneOf) Get

func (b *OneOf) Get() interface{}

Get implements flag.Getter.

func (*OneOf) Group

func (b *OneOf) Group() []*OneOf

Group returns a copy of the group b is in.

func (*OneOf) IsBoolFlag

func (b *OneOf) IsBoolFlag() bool

IsBoolFlag implements flag.Value.

func (*OneOf) Set

func (b *OneOf) Set(s string) (err error)

Set implements flag.Value.

func (*OneOf) String

func (b *OneOf) String() string

type RGB

type RGB color.RGBA

RGB is a flag type that can be used for RGB colors.

It converts between string format "rrggbb" (no leading "#") and RGB color.

It implements color.Color and flag.Getter interfaces.

Example

This example demostrates how to use RGB in your program.

package main

import (
	"flag"
	"fmt"

	"go.yhsif.com/flagutils"
)

func main() {
	fs := flag.NewFlagSet("", flag.ExitOnError)
	// Default value
	color := flagutils.RGB{
		R: 0xff,
	}
	fs.Var(&color, "color", "the color you want")
	fs.Parse([]string{"-color", "0000ff"})
	fmt.Println(&color)
	fmt.Println(color.RGBA())
}
Output:

0000ff
0 0 65535 0

func (*RGB) Get

func (c *RGB) Get() interface{}

Get implements flag.Getter.

func (*RGB) RGBA

func (c *RGB) RGBA() (uint32, uint32, uint32, uint32)

RGBA implements color.Color.

func (*RGB) Set

func (c *RGB) Set(s string) error

Set implements flag.Value.

func (*RGB) String

func (c *RGB) String() string

type RGBA

type RGBA color.RGBA

RGBA is a flag type that can be used for RGBA colors.

It converts between string format "rrggbbaa" (no leading "#") and RGBA color.

It implements color.Color and flag.Getter interfaces.

Example

This example demostrates how to use RGBA in your program.

package main

import (
	"flag"
	"fmt"

	"go.yhsif.com/flagutils"
)

func main() {
	fs := flag.NewFlagSet("", flag.ExitOnError)
	// Default value
	color := flagutils.RGBA{
		R: 0xff,
	}
	fs.Var(&color, "color", "the color you want")
	fs.Parse([]string{"-color", "ff000080"})
	fmt.Println(&color)
	fmt.Println(color.RGBA())
}
Output:

ff000080
65535 0 0 32896

func (*RGBA) Get

func (c *RGBA) Get() interface{}

Get implements flag.Getter.

func (*RGBA) RGBA

func (c *RGBA) RGBA() (uint32, uint32, uint32, uint32)

RGBA implements color.Color.

func (*RGBA) Set

func (c *RGBA) Set(s string) error

Set implements flag.Value.

func (*RGBA) String

func (c *RGBA) String() string