echidna

Echidna Library for Go

echidna

import "github.com/bruceesmith/echidna"

Package echidna builds upon the Github packages knadh/koanf, urfave/cli/v3, bruceesmith/sflags to make it extremely simple to use the features of these excellent packages in concert.

Every program using echidna will expose a standard set of command-line flags (--json, --log, --trace, --verbose) in addition to the standard flags provided by urfave/cli/v3 (--help and --version).

If a configuration struct is provided to Run function by Configuration, then a further command-line flag (--config) is added to provide the source(s) of values for fields in the struct.

Command-line flags bound to fields in the configuration are created by providing ConfigFlags to Run. These flags can be bound either to the root command or to one or more child commands.

// Include an Action function
(&cli.Command{
	Action: func(ctx context.Context, cmd *cli.Command) error {
		fmt.Println("hello")
		return nil
	},
	Name:    "action",
	Version: "1",
}).Run(context.Background(), []string{"action"})
// Output:
// hello

hello

// The most basic example of urfave/cli/v3
(&cli.Command{Name: "basic"}).Run(context.Background(), os.Args)
// Output:
// NAME:
//    basic - A new cli application
//
// USAGE:
//    basic [global options]
//
// GLOBAL OPTIONS:
//    --help, -h  show help

NAME:
   basic - A new cli application

USAGE:
   basic [global options]

GLOBAL OPTIONS:
   --help, -h  show help

// Include a custom flag
(&cli.Command{
	Action: func(ctx context.Context, cmd *cli.Command) error {
		fmt.Println("hello")
		return nil
	},
	Flags: []cli.Flag{
		&cli.IntFlag{
			Name:  "i",
			Usage: "An integer",
		},
	},
	Name:    "action",
	Version: "1",
}).Run(context.Background(), []string{"action"})
// Output:
// hello

hello

// Include a custom flag
(&cli.Command{
	Action: func(ctx context.Context, cmd *cli.Command) error {
		fmt.Println("hello")
		return nil
	},
	Flags: []cli.Flag{
		&cli.IntFlag{
			Name:  "i",
			Usage: "An integer",
			Value: 22,
		},
	},
	Name:    "action",
	Version: "1",
}).Run(context.Background(), []string{"action", "--help"})
// Output:
// NAME:
//    action - A new cli application
//
// USAGE:
//    action [global options]
//
// VERSION:
//    1
//
// GLOBAL OPTIONS:
//    -i value       An integer (default: 22)
//    --help, -h     show help
//    --version, -v  print the version

NAME:
   action - A new cli application

USAGE:
   action [global options]

VERSION:
   1

GLOBAL OPTIONS:
   -i value       An integer (default: 22)
   --help, -h     show help
   --version, -v  print the version

// Include a Version field in the Command
(&cli.Command{
	Name:    "version",
	Version: "1",
}).Run(context.Background(), os.Args)
// Output:
// NAME:
//    version - A new cli application
//
// USAGE:
//    version [global options]
//
// VERSION:
//    1
//
// GLOBAL OPTIONS:
//    --help, -h     show help
//    --version, -v  print the version

NAME:
   version - A new cli application

USAGE:
   version [global options]

VERSION:
   1

GLOBAL OPTIONS:
   --help, -h     show help
   --version, -v  print the version

Index

• Variables
• func Run(ctx context.Context, command *cli.Command, options ...Option)
• type Configurator
• type FlagOption
  • func DescTag(tag string) FlagOption
  • func EnvDivider(divider string) FlagOption
  • func EnvPrefix(prefix string) FlagOption
  • func FlagDivider(divider string) FlagOption
  • func FlagTag(tag string) FlagOption
  • func Flatten(flatten bool) FlagOption
  • func Prefix(prefix string) FlagOption
  • func Validator(val sflags.ValidateFunc) FlagOption
• type Option
  • func ConfigFlags(configs []Configurator, command *cli.Command, ops ...FlagOption) Option
  • func Configuration(config Configurator) Option
  • func NoDefaultFlags() Option
  • func NoJSON() Option
  • func NoLog() Option
  • func NoTrace() Option
  • func NoVerbose() Option

Variables

var (
    // BuildDate is the timestamp for when this program was compiled
    BuildDate string = `Filled in during the build`
)

func Run

func Run(ctx context.Context, command *cli.Command, options ...Option)

Run is the primary external function of this library. It augments the cli.Command with default command-line flags, hooks in handling for processing a configuration, runs the appropriate Action, calls the terminator to wait for goroutine cleanup

type Configurator

Configurator is the interface for a configuration struct

type Configurator interface {
    Validate() error
}

type FlagOption

FlagOption is a functional option parameter for the ConfigFlags function

type FlagOption func()

func DescTag

func DescTag(tag string) FlagOption

DescTag sets the struct tag where usage text is configured

func EnvDivider

func EnvDivider(divider string) FlagOption

EnvDivider is the character in between parts of an environment variable bound to a command line struct-bound flag

func EnvPrefix

func EnvPrefix(prefix string) FlagOption

EnvPrefix is an optional prefix for an environment variable bound to a command line struct-bound flag

func FlagDivider

func FlagDivider(divider string) FlagOption

FlagDivider is the character in between parts of a struct-bound command line flag's name

func FlagTag

func FlagTag(tag string) FlagOption

FlagTag is the struct tag used to configure struct-bound command line flags

func Flatten

func Flatten(flatten bool) FlagOption

Flatten determines the name of a command line flag bound to a an anonymous struct field

func Prefix

func Prefix(prefix string) FlagOption

Prefix is an optional prefix for the names of all struct-bound command line flags

func Validator

func Validator(val sflags.ValidateFunc) FlagOption

Validator is an optional function that will be called to to validate each struct-field bound flag

type Option

Option is a functional parameter for Run()

type Option func() error

func ConfigFlags

func ConfigFlags(configs []Configurator, command *cli.Command, ops ...FlagOption) Option

ConfigFlags creates and configures Run to have command line flags bound to the fields of one or more parts of a configuration struct

func Configuration

func Configuration(config Configurator) Option

Configuration is an Option helper to define a configuration structure that will be populated from the sources given on a --config command-line flag

func NoDefaultFlags

func NoDefaultFlags() Option

NoDefaultFlags is a convenience function which is equivalent to calling all of NoJSON, NoLog, NoTrace, and NoVerbose

func NoJSON

func NoJSON() Option

func NoLog

func NoLog() Option

func NoTrace

func NoTrace() Option

func NoVerbose

func NoVerbose() Option

Generated by gomarkdoc