unpuzzled

README

Unpuzzled

A user-first CLI library.

With the ability to import variables from many different sources: command line flags, environment variables, and configuration variables, it's often not clear what values are set, or why.

Unpuzzled gives you and your users a clear explanation of where variables are being set, and which ones are being overwritten.

Clarity prevents confusion.

Features

• First class importing from:
  • Environment Variables
  • JSON files
  • TOML files
  • CLI Flags
• Ability to choose the order of variable overrides (ex. cli flags > JSON > TOML > ENV)
• Main Command and Subcommands
• Defaults to verbose output out of the box, with the ability to turn it off. (app.Silent = true`)
• Warnings on overrides
  • Warnings on overrides by order of precedence.
    • If a variable is set as an ENV variable, and a CLI flag overwrites it, let the user know.
    • If two or more variables have references to the same pointer, let the user know.
• Displays what variables are set, and what they are set to.
• Add default values for variables.
• Ability to set Variables as Required.
  • If a value isn't set, print a warning to stdout, and exit.
  • If a variable has a Default value, it can never be marked as required, because a valid value will be set.

Left to do:

• More variable types

Types of Outputs

Missing Required Variables:

Unpuzzled will parse all the inputs, and then list all of the missing required variables before exiting the program. This includes required variables in parent commands.

Set Variables

Set Variables can be shown in two outputs.

Stdout is the default:

Table Option

A table option can be chosen by setting OverridesOutputIntTable to true:

app := unpuzzled.NewApp()
app.OverridesOutputInTable = true

Overwritten Destination

Since unpuzzled uses pointers to set the final values, it's possible that the same pointer may be left in multiple variables.

Unpuzzled will warn you that these values have been overwritten.

In the example below, the variables example-a and example-b both point to testString. If both are set, example-b will override example-a, because it is later in the Variables array.

var testString string
app := unpuzzled.NewApp()
app.Command = &unpuzzled.Command{
    Variables: []unpuzzled.Variable{
        &unpuzzled.StringVariable{
            Name:        "example-a",
            Destination: &testString,
        },
        &unpuzzled.StringVariable{
            Name:        "example-b",
            Destination: &testString,
        },
    },
    Action: func() {
        fmt.Println(testString)
    },
}
app.Run(os.Args)

(Full example in examples/overwritten_pointer)

Help Text:

Help text is provided whenever the app is run with the values provided in the app.HelpCommands. The defaults are: -h, --help or help. The help text content only includes the content for the current command selected.

How to use JSON / Toml configs:

TOML:

app := unpuzzled.NewApp()
app.Command = &unpuzzled.Command{
    Name: "main",
    Variables: []unpuzzled.Variable{
        &unpuzzled.ConfigVariable{
            StringVariable: &unpuzzled.StringVariable{
                Name: "config"
                Description: "Main configuration, use with `go run main.go --config=path_to_file.toml`",
                Type: unpuzzled.TomlConfig,
            },
        },
    },
}

JSON Config Example:

app := unpuzzled.NewApp()
app.Command = &unpuzzled.Command{
    Name: "main",
    Variables: []unpuzzled.Variable{
        &unpuzzled.ConfigVariable{
            StringVariable: &unpuzzled.StringVariable{
                Name: "config"
                Description: "Main configuration flag, use with `go run main.go --config=path_to_file.json`",
                Type: unpuzzled.JsonConfig,
            },
        },
    },
}

Documentation

Index

• Variables
• type App
  • func NewApp() *App
  • func (a *App) PrintHelpCommand(command *Command)
  • func (a *App) PrintMissingRequiredVariables()
  • func (a *App) Run(args []string)
• type Author
• type BoolVariable
  • func (b *BoolVariable) GetDefault() (interface{}, bool)
  • func (b *BoolVariable) GetDescription() string
  • func (b *BoolVariable) GetDestination() interface{}
  • func (b *BoolVariable) GetName() string
  • func (b *BoolVariable) IsRequired() bool
• type Command
  • func (c *Command) GetActiveCommands() []*Command
  • func (c *Command) GetExpandedActiveCommmands() map[string]*Command
  • func (c *Command) GetExpandedName() string
  • func (c *Command) GetVariableMap() map[string]Variable
• type ConfigVariable
  • func (c *ConfigVariable) ParseConfig(set *flag.FlagSet) error
• type DurationVariable
  • func (d *DurationVariable) GetDefault() (interface{}, bool)
  • func (d *DurationVariable) GetDescription() string
  • func (d *DurationVariable) GetDestination() interface{}
  • func (d *DurationVariable) GetName() string
  • func (d *DurationVariable) IsRequired() bool
• type Float64Variable
  • func (f *Float64Variable) GetDefault() (interface{}, bool)
  • func (f *Float64Variable) GetDescription() string
  • func (f *Float64Variable) GetDestination() interface{}
  • func (f *Float64Variable) GetName() string
  • func (f *Float64Variable) IsRequired() bool
• type Int64Variable
  • func (i *Int64Variable) GetDefault() (interface{}, bool)
  • func (i *Int64Variable) GetDescription() string
  • func (i *Int64Variable) GetDestination() interface{}
  • func (i *Int64Variable) GetName() string
  • func (i *Int64Variable) IsRequired() bool
• type IntVariable
  • func (i *IntVariable) GetDefault() (interface{}, bool)
  • func (i *IntVariable) GetDescription() string
  • func (i *IntVariable) GetDestination() interface{}
  • func (i *IntVariable) GetName() string
  • func (i *IntVariable) IsRequired() bool
• type ParsingType
• type StringVariable
  • func (s *StringVariable) GetDefault() (interface{}, bool)
  • func (s *StringVariable) GetDescription() string
  • func (s *StringVariable) GetDestination() interface{}
  • func (s *StringVariable) GetName() string
  • func (s *StringVariable) IsRequired() bool
• type Variable

Variables

var (
	ErrFailedToLoadToml  = errors.New("Failed to load toml.")
	ErrFailedToLoadJson  = errors.New("Failed to load json.")
	ErrConfigValueNotSet = errors.New("Config variable is not set.")
)

var ParsingTypeStringMap = map[ParsingType]string{
	EnvironmentVariables: "Environment",
	JsonConfig:           "JSON Config",
	TomlConfig:           "Toml Config",
	CliFlags:             "CLI Flag",
	DefaultValue:         "Default Value",
}

Types

type App

type App struct {
	// Used to name the App in the help text.
	Name string
	// The "Usage" section in the help text.
	Usage string
	// The text used for the copyright section in the help text.
	Copyright string
	// The order in which variable sources will be parsed, values later in the array will be parsed afterwards, overwriting earlier sources.
	// Default order is: CLI Flag > Toml Config > JSON Config > Environment
	ParsingOrder []ParsingType
	// Main command attached to the app.
	Command *Command
	// List of authors used in the help text.
	Authors []Author
	// The keys in this map are used to check for help values, defaults are "help", "-h", and "--help"
	HelpCommands map[string]bool
	// If help text variables will be displayed in a table. Defaults to true.
	HelpTextVariablesInTable bool
	// If overridden variables will be displayed in a table. Defaults to false.
	OverridesOutputInTable bool
	// All output will not include color
	RemoveColor bool
	// Turn off all output
	Silent bool
	// contains filtered or unexported fields
}

func NewApp

func NewApp() *App

Create a new application with default values set.

func (*App) PrintHelpCommand

func (a *App) PrintHelpCommand(command *Command)

func (*App) PrintMissingRequiredVariables

func (a *App) PrintMissingRequiredVariables()

func (*App) Run

func (a *App) Run(args []string)

Run the app. Should be called with: app := cli.NewApp() app.Run(os.Args)

type Author

type Author struct {
	Name  string
	Email string
}

type BoolVariable

type BoolVariable struct {
	Name        string
	Description string
	Required    bool
	Default     bool
	Destination *bool
	// contains filtered or unexported fields
}

func (*BoolVariable) GetDefault

func (b *BoolVariable) GetDefault() (interface{}, bool)

func (*BoolVariable) GetDescription

func (b *BoolVariable) GetDescription() string

func (*BoolVariable) GetDestination

func (b *BoolVariable) GetDestination() interface{}

func (*BoolVariable) GetName

func (b *BoolVariable) GetName() string

func (*BoolVariable) IsRequired

func (b *BoolVariable) IsRequired() bool

type Command

type Command struct {
	Name            string
	Usage           string
	LongDescription string
	BeforeFunc      func(c *Command) error
	Subcommands     []*Command
	Variables       []Variable
	Action          func()
	Active          bool
	// contains filtered or unexported fields
}

func (*Command) GetActiveCommands

func (c *Command) GetActiveCommands() []*Command

Get the set of active commands. All commands in the chain of arguments are considered active.

func (*Command) GetExpandedActiveCommmands

func (c *Command) GetExpandedActiveCommmands() map[string]*Command

Helper to get a map of expanded names to the actual command.

func (*Command) GetExpandedName

func (c *Command) GetExpandedName() string

Get the expanded name of a command, which includes the name of the parent commands, separated by a "." ex. main.sub1.sub2

func (*Command) GetVariableMap

func (c *Command) GetVariableMap() map[string]Variable

Helper to get a map of variables by variable name.

type ConfigVariable

type ConfigVariable struct {
	*StringVariable
	Type ParsingType
	// contains filtered or unexported fields
}

func (*ConfigVariable) ParseConfig

func (c *ConfigVariable) ParseConfig(set *flag.FlagSet) error

type DurationVariable

type DurationVariable struct {
	Name        string
	Description string
	Default     time.Duration
	Required    bool
	Destination *time.Duration
	// contains filtered or unexported fields
}

func (*DurationVariable) GetDefault

func (d *DurationVariable) GetDefault() (interface{}, bool)

func (*DurationVariable) GetDescription

func (d *DurationVariable) GetDescription() string

func (*DurationVariable) GetDestination

func (d *DurationVariable) GetDestination() interface{}

func (*DurationVariable) GetName

func (d *DurationVariable) GetName() string

func (*DurationVariable) IsRequired

func (d *DurationVariable) IsRequired() bool

type Float64Variable

type Float64Variable struct {
	Name        string
	Description string
	Default     float64
	Required    bool
	Destination *float64
	// contains filtered or unexported fields
}

func (*Float64Variable) GetDefault

func (f *Float64Variable) GetDefault() (interface{}, bool)

func (*Float64Variable) GetDescription

func (f *Float64Variable) GetDescription() string

func (*Float64Variable) GetDestination

func (f *Float64Variable) GetDestination() interface{}

func (*Float64Variable) GetName

func (f *Float64Variable) GetName() string

func (*Float64Variable) IsRequired

func (f *Float64Variable) IsRequired() bool

type Int64Variable

type Int64Variable struct {
	Name        string
	Description string
	Default     int64
	Required    bool
	Destination *int64
	// contains filtered or unexported fields
}

func (*Int64Variable) GetDefault

func (i *Int64Variable) GetDefault() (interface{}, bool)

func (*Int64Variable) GetDescription

func (i *Int64Variable) GetDescription() string

func (*Int64Variable) GetDestination

func (i *Int64Variable) GetDestination() interface{}

func (*Int64Variable) GetName

func (i *Int64Variable) GetName() string

func (*Int64Variable) IsRequired

func (i *Int64Variable) IsRequired() bool

type IntVariable

type IntVariable struct {
	Name        string
	Description string
	Default     int
	Required    bool
	Destination *int
	// contains filtered or unexported fields
}

func (*IntVariable) GetDefault

func (i *IntVariable) GetDefault() (interface{}, bool)

func (*IntVariable) GetDescription

func (i *IntVariable) GetDescription() string

func (*IntVariable) GetDestination

func (i *IntVariable) GetDestination() interface{}

func (*IntVariable) GetName

func (i *IntVariable) GetName() string

func (*IntVariable) IsRequired

func (i *IntVariable) IsRequired() bool

type ParsingType

type ParsingType int

const (
	EnvironmentVariables ParsingType = iota
	JsonConfig
	TomlConfig
	CliFlags
	DefaultValue
)

type StringVariable

type StringVariable struct {
	Name        string
	Description string
	Default     string
	Required    bool
	Destination *string
	// contains filtered or unexported fields
}

func (*StringVariable) GetDefault

func (s *StringVariable) GetDefault() (interface{}, bool)

func (*StringVariable) GetDescription

func (s *StringVariable) GetDescription() string

func (*StringVariable) GetDestination

func (s *StringVariable) GetDestination() interface{}

func (*StringVariable) GetName

func (s *StringVariable) GetName() string

func (*StringVariable) IsRequired

func (s *StringVariable) IsRequired() bool

type Variable

type Variable interface {
	// Get the Name
	GetName() string
	// Get the Description
	GetDescription() string
	// Get the Destination pointer
	GetDestination() interface{}
	// return the default value, bool if it's set or not.
	GetDefault() (interface{}, bool)
	// Get if it's a required variable or not
	IsRequired() bool
	// contains filtered or unexported methods
}