cli

package
v0.1.4 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 25, 2023 License: Apache-2.0 Imports: 13 Imported by: 8

README

cli

A wrapper on top of cobra.Command to build CLIs with a functional style.

Command builder

  • no globals, only functions
  • inject viper.Viper configuration registry
  • allow dependency injection (e.g. logger, etc)

Utilities

  • injectable: logger, config that can be passed via context
  • wait: command sync utilities, e.g. to run as deployed containers & sync on events
  • version: retrieve version from go module information, or values baked at build-time

Documentation

Overview

Package cli exposes helpers to build command-line binaries with cobra and viper.

Example (ChildCmd)

Example_childCmd runs a child command. 

rootCmd := RootCmd()
if err := rootCmd.ExecuteWithArgs(
	"child",
	"--parallel",
	"20",
	"--url",
	"https://www.zorg.com",
	"--user",
	"zorg",
	"--workers",
	"12",
); err != nil {
	log.Fatal("executing:", err)
}

fmt.Println("done")

Output:

subcommand called
 URL config: https://www.zorg.com
 parallel config: 20
 user config: zorg
 workers config: 12

done
Example (GlobalChildCmd)

Example_childCmd runs a child command. 

rootCmd := RootCmdWithGlobal()
if err := rootCmd.ExecuteWithArgs(
	"child",
	"--parallel",
	"20",
	"--url",
	"https://www.zorg.com",
	"--user",
	"zorg",
	"--workers",
	"12",
); err != nil {
	log.Fatal("executing:", err)
}

fmt.Println("done")

Output:

subcommand called
 URL config: https://www.zorg.com
 parallel config: 20
 user config: zorg
 workers config: 12

global flags values evaluated by child
 cli_test.cliFlags{DryRun:false, URL:"https://www.zorg.com", Parallel:20, User:"zorg", LogLevel:"info", Child:cli_test.childFlags{Workers:12}}
done
Example (GlobalRootCmd) 
rootCmd := RootCmdWithGlobal()
rootCmd.SetArgs([]string{
	"--dry-run",
	"--log-level",
	"debug",
	"--parallel",
	"15",
	"--user",
	"fred",
},
)

if err := rootCmd.Execute(); err != nil {
	log.Fatal("executing:", err)
}

fmt.Println("done")

Output:

example called
 URL config: https://www.example.com
 log level config: debug
 parallel config: 15
 user config: fred

global flags values evaluated by root
 cli_test.cliFlags{DryRun:true, URL:"https://www.example.com", Parallel:15, User:"fred", LogLevel:"debug", Child:cli_test.childFlags{Workers:5}}
done
Example (Help) 
rootCmd := RootCmd()
rootCmd.SetArgs([]string{
	"--help",
})

if err := rootCmd.Execute(); err != nil {
	log.Fatal("executing:", err)
}

fmt.Println("done")

Output:

	...

Usage:
  example [flags]
  example [command]

Available Commands:
  child       sub-command example
  completion  Generate the autocompletion script for the specified shell
  help        Help about any command
  version     another sub-command example

Flags:
      --dry-run            Dry run
  -h, --help               help for example
      --log-level string   Controls logging verbosity (default "info")
  -p, --parallel int       Degree of parallelism (default 2)
      --url string         The URL to connect to (default "https://www.example.com")
      --user string        Originating user

Use "example [command] --help" for more information about a command.
done
Example (PrintCmd)

Example_printCmd prints out the tree structure of the root command. 

rootCmd := RootCmd()

fmt.Println(rootCmd.String())

Output:

example
 child
  grandchild
 version
Example (RootCmd)

Example_rootCmd runs the root command. 

rootCmd := RootCmd()
rootCmd.SetArgs([]string{
	"--dry-run",
	"--log-level",
	"debug",
	"--parallel",
	"15",
	"--user",
	"fred",
},
)

if err := rootCmd.Execute(); err != nil {
	log.Fatal("executing:", err)
}

fmt.Println("done")

Output:

example called
 URL config: https://www.example.com
 log level config: debug
 parallel config: 15
 user config: fred

done

Index

Examples

Constants

This section is empty.

Variables

View Source 
var (

	// ConfigEnv defines the environment variable used by the Config() function
	// to find the current environment.
	ConfigEnv = "CONFIG_ENV"

	// ConfigDebugEnv defines the environment variable used to instruct the config loader
	// to dump all config keys for debugging.
	ConfigDebugEnv = "DEBUG_CONFIG"
)

Functions

func Config 

func Config(defaulters ...func(*viper.Viper)) *viper.Viper

Config calls ConfigForEnv, with the current environment resolved from the variable "CONFIG_ENV".

func ConfigForEnv 

func ConfigForEnv(env string, defaulters ...func(*viper.Viper)) *viper.Viper

ConfigForEnv loads and merge a set of config files for a given environment and applies some default values.

It assumes that config files follow the conventions defined by "github.com/fredbi/go-cli/config".

It dies upon failure.

Environment variable settings:

  • If the environment variable "DEBUG_CONFIG" is set, the loaded settings are dumped to standard output as JSON.
  • The environment variable "CONFIG_DIR" defines the folder where the root configuration is located.

func ConfigForEnvWithOptions added in v0.1.1 

func ConfigForEnvWithOptions(env string, opts []config.Option, defaulters ...func(*viper.Viper)) *viper.Viper

ConfigForEnvWithOptions loads and merge a set of config files for a given environment and applies some default values.

This function accepts some config.Options to control where and how the configuration files should be loaded.

func Die 

func Die(format string, args ...any)

Die exits the current process with some final croak.

By default, Die is a wrapper around log.Fatalf.

Use SetDie to alter this behavior (e.g. for mocking). SetDie(nil) will make Die(format, args...) equivalent to panic(fmt.Sprintf(format, args...)).

This wraps log.Fatal, essentially for testing purpose.

func Must 

func Must(err error)

Must panic on error

func MustBindFromFlagSet 

func MustBindFromFlagSet(cfg *viper.Viper, key, flagName string, flags *pflag.FlagSet)

MustBindFromFlagSet binds a key in a *viper.Viper registry to command-line flag found in a flag set (*pflag.FlagSet).

Dies on error. This happens if the flag to be set is nil or if the requested flag has not been registered in the flag set yet.

func MustBindPFlag 

func MustBindPFlag(cfg *viper.Viper, key string, flag *pflag.Flag)

MustBindPlag binds a key in a *viper.Viper registry to a command-line flag (*pflag.Flag).

Dies on error. This happens if the flag is nil.

func SetConfigOptions 

func SetConfigOptions(opts ...config.Option)

SetConfigOption defines package-level defaults for config options, when using ConfigForEnv or Config.

By default, this package doesn't set any particular option and uses all defaults from the config package.

TODO: package-level options should be removed and injected.

func SetDie 

func SetDie(fatalFunc func(string, ...any))

SetDie alters the package level log.Fatalf implementation, to be used by Die(sring, ...any).

If fatalFunc is set to nil, calls to Die will issue their message with panic instead of log.Fatalf.

This should be used for testing only.

Types

type Command 

type Command struct {
	*cobra.Command
	// contains filtered or unexported fields
}

Command wraps a *cobra.Command with some options to register and bind flags with a functional style.

func NewCommand 

func NewCommand(cmd *cobra.Command, opts ...Option) *Command

NewCommand builds a new Command wrapping a *cobra.Command.

func (*Command) AddCommand 

func (c *Command) AddCommand(subs ...*Command)

AddCommand adds child command(s).

func (*Command) BindFlags 

func (c *Command) BindFlags()

BindFlags binds the command-line flags marked as such to the configuration registry.

This applies recursively to all sub-commands.

It doesn't perform anything if no flags or no config are set for the command (use the options WithFlagVar() and WithConfig())

func (*Command) Commands 

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

Commands returns the child commands.

func (*Command) Config 

func (c *Command) Config() *viper.Viper

Config returns the viper config registry shared by the command tree.

func (*Command) ExecuteContext 

func (c *Command) ExecuteContext(ctx context.Context) error

ExecuteContext wraps cobra.Command.ExecuteContext() by ensuring the config is in the context.

func (*Command) ExecuteWithArgs 

func (c *Command) ExecuteWithArgs(args ...string) error

ExecuteWithArgs is a convenience wrapper to execute a command with preset args.

This is primarily intended for testing commands.

func (*Command) RegisterFlags 

func (c *Command) RegisterFlags()

Register command-line flags for this command.

func (*Command) String 

func (c *Command) String() string

String provides a short text representation of the command subtree.

type FlagOption 

type FlagOption func(*flagOption)

func BindFlagToConfig 

func BindFlagToConfig(key string) FlagOption

BindFlagToConfig declares the flag as bound to a configuration key in the viper registry.

func FlagIsPersistent added in v0.1.1 

func FlagIsPersistent() FlagOption

FlagIsPersistent declares the flag as persistent for the command.

func FlagIsRequired 

func FlagIsRequired() FlagOption

FlagIsRequired declares the flag as required for the command.

type Option 

type Option func(*options)

Option configures a Command.

func WithAutoVersion added in v0.1.3 

func WithAutoVersion(versionFunc func() string) Option

WithAutoVersion wires a "--version" flag using version.Resolve().

This collects versioning from package-level variables set at build time OR go module metadata.

func WithBindFlagsToConfig added in v0.1.3 

func WithBindFlagsToConfig(bindings map[string]string) Option

WithBindFlagsToConfig binds all (non persistent) flags in the provided map to a config key.

The map is like map[string][string]{"flag-name": "viper-key"}

func WithBindPersistentFlagsToConfig added in v0.1.3 

func WithBindPersistentFlagsToConfig(bindings map[string]string) Option

WithBindPersistentFlagsToConfig binds all persistent flags in the provided map to a config key.

The map is like map[string][string]{"flag-name": "viper-key"}

TODO: should add a way to automatically determine if the flag is persistent or not.

func WithConfig 

func WithConfig(cfg *viper.Viper) Option

WithConfig adds a viper.Viper configuration to the command tree.

The config can be retrieved from the context of the command, using injectable.ConfigFromContext().

func WithFlag 

func WithFlag[T gflag.FlaggablePrimitives | gflag.FlaggableTypes](name string, defaultValue T, usage string, opts ...FlagOption) Option

WithFlag declares a flag of any type supported by gflag, with some options.

The pointer to the flag value is allocated automatically.

func WithFlagFunc 

func WithFlagFunc(regFunc RegisterFunc, opts ...FlagOption) Option

WithFlagFunc declares a command flag using a RegisterFunc function and some flag options.

func WithFlagP 

func WithFlagP[T gflag.FlaggablePrimitives | gflag.FlaggableTypes](name, shorthand string, defaultValue T, usage string, opts ...FlagOption) Option

WithFlagP declares a flag of any type supported by gflag, with a shorthand name and some options.

The pointer to the flag value is allocated automatically.

func WithFlagVar added in v0.1.1 

func WithFlagVar[T gflag.FlaggablePrimitives | gflag.FlaggableTypes](addr *T, name string, defaultValue T, usage string, opts ...FlagOption) Option

WithFlagVar declares a flag of any type supported by gflag, with some options.

The pointer to the flag value is provided explicitly.

func WithFlagVarP added in v0.1.1 

func WithFlagVarP[T gflag.FlaggablePrimitives | gflag.FlaggableTypes](addr *T, name, shorthand string, defaultValue T, usage string, opts ...FlagOption) Option

WithFlagVarP declares a flag of any type supported by gflag, with a shorthand name and some options.

The pointer to the flag value is provided explicitly.

func WithInjectables added in v0.1.2 

func WithInjectables(injectables ...injectable.ContextInjectable) Option

WithInjectables adds dependencies to be injected in the context of the command.

For each injectable, its Context() method will be called in the specified order to enrich the context of the command.

NOTE: the config registry is a special dependency because it may bind to CLI flags.

Configuration may be injected directly with the more explicit WithConfig() method.

Example 
package main

import (
	"errors"
	"fmt"
	"log"
	"log/slog"
	"os"

	"github.com/fredbi/go-cli/cli"
	"github.com/fredbi/go-cli/cli/injectable"
	"github.com/spf13/cobra"
)

func RootCmdWithDep() *cli.Command {
	return cli.NewCommand(
		&cobra.Command{
			Use:   "inject",
			Short: "examplifies a cobra command with dependency injection",
			Long:  "in this example, we inject a logger in the context of the command (from log/slog)",
			RunE:  rootWithDepRunFunc,
		},
		cli.WithFlag("log-level", "info", "Controls logging verbosity",
			cli.FlagIsPersistent(),
		),
		cli.WithInjectables( // injectables know how to be retrieved from context
			injectable.NewSLogger(slog.New(slog.NewJSONHandler(os.Stderr, nil))),
		),
	)
}

func rootWithDepRunFunc(cmd *cobra.Command, _ []string) error {
	// retrieve injected dependencies from the context of the command
	ctx := cmd.Context()
	logger := injectable.SLoggerFromContext(ctx).With("command", "root")
	if logger == nil {
		return errors.New("no logger provided")
	}

	fmt.Println("print log on stderr")
	logger.Info("structured log entry")

	return nil
}

func main() {
	rootCmd := RootCmdWithDep()
	rootCmd.SetArgs([]string{
		"inject",
		"log-level",
		"info",
	})

	if err := rootCmd.Execute(); err != nil {
		log.Fatal("executing:", err)
	}

}

Output:

print log on stderr

func WithSliceFlag 

func WithSliceFlag[T gflag.FlaggablePrimitives | gflag.FlaggableTypes](name string, defaultValue []T, usage string, opts ...FlagOption) Option

WithSliceFlag declares a flag of any slice type supported by gflag, with some options.

The pointer to the flag value is allocated automatically.

func WithSliceFlagP 

func WithSliceFlagP[T gflag.FlaggablePrimitives | gflag.FlaggableTypes](name, shorthand string, defaultValue []T, usage string, opts ...FlagOption) Option

WithSliceFlagP declares a flag of any slice type supported by gflag, with a shorthand name and some options.

The pointer to the flag value is allocated automatically.

func WithSliceFlagVar added in v0.1.1 

func WithSliceFlagVar[T gflag.FlaggablePrimitives | gflag.FlaggableTypes](addr *[]T, name string, defaultValue []T, usage string, opts ...FlagOption) Option

WithSliceFlagVar declares a flag of any slice type supported by gflag, with some options.

The pointer to the flag value is provided explicitly.

func WithSliceFlagVarP added in v0.1.1 

func WithSliceFlagVarP[T gflag.FlaggablePrimitives | gflag.FlaggableTypes](addr *[]T, name, shorthand string, defaultValue []T, usage string, opts ...FlagOption) Option

WithSliceFlagVarP declares a flag of any slice type supported by gflag, with a shorthand name and some options.

func WithSubCommands 

func WithSubCommands(subs ...*Command) Option

WithSubCommands adds child commands.

func WithVersion added in v0.1.3 

func WithVersion(versionFunc func() string) Option

WithVersion wires a "--version" flag from a function evaluated at command construction time.

type RegisterFunc 

type RegisterFunc func(*pflag.FlagSet) string

RegisterFunc registers a flag to a provided pflag.FlagSet and returns the flag name.

Source Files

View all Source files

Directories

Path Synopsis
Package version provides a built-in versioning based on the version of your go modules.
 Package version provides a built-in versioning based on the version of your go modules.
examples command
Package wait exposes utilities to synchronize containers based on file or network port.
 Package wait exposes utilities to synchronize containers based on file or network port.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.