goargs

README

goargs

Use command-line arguments as easy as:

var args struct {
	Host string `goargs:"short:h"`
	User string
}
goargs.Bind(&args)
goargs.Parse()

fmt.Printf("Host: %s\n", args.Host)

See full file

package main

import (
	"fmt"
	"os"

	"github.com/PKeidel/goargs"
)

var args struct {
	Host string `goargs:"short:h"`
	User string
}

func main() {
	goargs.Bind(&args)
	goargs.Parse()

	fmt.Printf("Host: %s\n", args.Host)
	fmt.Printf("User: %s\n", args.User)

	fmt.Println("To rerun, run:", os.Args[0], goargs.String())
}

Now you can run your program for example with: program --user PKeidel -h host01

strcase.ToKebab is applied to all "long" names. So a value like UserName will become --user-name as an arg.

Tags

There are a few tags to set/overrite the long form, short form and the required flag per field. long defaults to the field name in lowercase.

var args struct {
	Host string `goargs:"long:host,short:h,required"`
	User string
}

String()

goargs.String() returns a command-line variant of the current values. This can be usefull if the values are combined from different inputs but you want to rerun your program with the exact same arguments.

fmt.Println("To rerun, run:", os.Args[0], goargs.String())
// To rerun, run: program --host host01

Sources

goargs will search for the values in your os.Args, os.Environ and in the future in config files (json, yaml).

The order in which values overrite eachother can be configured with goargs.DefaultSourceOrder and defaults to: SourceFile, SourceEnv, SourceArgs with args overriding all other values.

Without structs

You can also register single values. For example:

var host string

func main() {
	goargs.WithString("host", &host)
	goargs.Parse()

	fmt.Printf("Host: %s\n", host)
}

To set for example the Required flag, you need to use the reference returned from the With* functions:

argHost := goargs.WithStringS("host", "h", &host)
argHost.Required = true
goargs.Parse()

Roadmap

[x] Support strings
[x] Support ints
[x] Support flags (bool)
[x] Support require flag
[x] Support os.Args parsing
[x] Support env parsing
[ ] Support multi flag to allow arrays like `--host host01 host02`
[ ] Support config file parsing
[ ] Detect undefined args
[ ] Detect wrong types
[x] Support externally changed values
[ ] Support values with spaces, quotes, ...
[ ] Print useage

Documentation

Index

• Variables
• func Bind(obj interface{})
• func Parse()
• func ParseWith(args, envs []string)
• func String() string
• type Arg
  • func NewDefaultArg(argtype ArgType, longName, shortName string) *Arg
  • func WithBoolS(longName, shortName string, ref *bool) *Arg
  • func WithIntS(longName, shortName string, ref *int) *Arg
  • func WithString(longName string, ref *string) *Arg
  • func WithStringS(longName, shortName string, ref *string) *Arg
  • func (a *Arg) HasVal() bool
  • func (a *Arg) String() string
  • func (a *Arg) Val() interface{}
• type ArgType
  • func (i ArgType) String() string
• type SourceType
  • func (i SourceType) String() string

Variables

var (
	DefaultArgs        []*Arg
	ArgsByLongname     = make(map[string]*Arg, 0)
	DefaultSourceOrder = []SourceType{SourceFile, SourceEnv, SourceArgs}
	EnvPrefix          = "GOARG_"
)

Functions

func Bind

func Bind(obj interface{})

func Parse

func Parse()

Parse will parse the input sources (goargs.DefaultSourceOrder) only once, these values are set for the full program lifetime

func ParseWith

func ParseWith(args, envs []string)

func String

func String() string

Types

type Arg

type Arg struct {
	Argtype                      ArgType
	LongName, ShortName, EnvName string
	Source                       SourceType

	Required bool
	// contains filtered or unexported fields
}

func NewDefaultArg

func NewDefaultArg(argtype ArgType, longName, shortName string) *Arg

func WithBoolS

func WithBoolS(longName, shortName string, ref *bool) *Arg

func WithIntS

func WithIntS(longName, shortName string, ref *int) *Arg

func WithString

func WithString(longName string, ref *string) *Arg

func WithStringS

func WithStringS(longName, shortName string, ref *string) *Arg

func (*Arg) HasVal

func (a *Arg) HasVal() bool

func (*Arg) String

func (a *Arg) String() string

func (*Arg) Val

func (a *Arg) Val() interface{}

type ArgType

type ArgType uint8

const (
	TypeString ArgType = iota
	TypeBool
	TypeInt
)

func (ArgType) String

func (i ArgType) String() string

type SourceType

type SourceType uint8

const (
	SourceNotFound SourceType = iota
	SourceFile
	SourceEnv
	SourceArgs
)

func (SourceType) String

func (i SourceType) String() string