cmd

README

cmd

Installation

go get github.com/ergosit/cmd

License

This package is licensed under the terms of the MIT License (see LICENSE file).

Documentation

Overview

Package cmd provides the helper wrapper over a command-line program.

Index

• type DefineFlagsFn
• type Option
  • func WithFlagSet(name string, errorHandling flag.ErrorHandling) Option
  • func WithFlags[Holder any](f DefineFlagsFn[Holder]) Option
  • func WithLoggerOptions(options ...zap.Option) Option
  • func WithUsage(f UsageFn) Option
• type RunFn
• type Runner
  • func New[Holder any](options ...Option) *Runner[Holder]
  • func (r *Runner[Holder]) Run(run RunFn[Holder], args ...string) (err error)
• type UsageFn
• type ValidateFlagsFn

Types

type DefineFlagsFn

type DefineFlagsFn[Holder any] func(set *flag.FlagSet) (Holder, ValidateFlagsFn[Holder])

DefineFlagsFn is intended to set flags via flag.FlagSet and returns a new Holder, where pointers to them are meant to be stored, along with ValidateFlagsFn, if any, or nil:

	type CmdHolder struct{ key *string }
	f := func(*flag.FlagSet) (CmdHolder, ValidateFlagsFn[CmdHolder]) {
 	holder := CmdHolder{
			key: set.String("key", "A", "a kind of key"),
		}
 	validator := func(set *flag.FlagSet, holder *CmdHolder) error {
			if len(*holder.key) > 1 {
				return errors.New("key must contain one character")
			}
			return nil
		}
 	return holder, validator // the latter can be nil
	}

type Option

type Option func(r runnerInitializer)

func WithFlagSet

func WithFlagSet(
	name string,
	errorHandling flag.ErrorHandling,
) Option

WithFlagSet is an Option that initializes flag.FlagSet with the given name and error handling policy.

func WithFlags

func WithFlags[Holder any](f DefineFlagsFn[Holder]) Option

WithFlags is an Option that calls the given DefineFlagsFn function and saves its returned values in Runner.

func WithLoggerOptions

func WithLoggerOptions(options ...zap.Option) Option

WithLoggerOptions is an Option that adds extra zap.Option's to build the logger.

func WithUsage

func WithUsage(f UsageFn) Option

WithUsage is an Option that sets flag.FlagSet.Usage.

type RunFn

type RunFn[Holder any] func(logger *zap.Logger, holder *Holder) error

RunFn is intended to run the command-line program itself.

type Runner

type Runner[Holder any] struct {
	// contains filtered or unexported fields
}

Runner is a helper struct for command-line programs.

func New

func New[Holder any](options ...Option) *Runner[Holder]

New creates a new Runner with optional Option's.

It defines a new flag.FlagSet with default options:

• "loglevel" to set the logging level (default: the Info level);
• "verbose" (or "v") for verbose output (the logging level will be overwritten to the Debug level);
• "color" for colorful output (default: depends on your terminal).

Options:

• WithFlagSet, otherwise, the default flag.FlagSet uses an empty name and the flag.ContinueOnError error handling policy according to flag.FlagSet.Init;
• WithUsage, otherwise, the flag.FlagSet uses flag.DefaultUsage;
• WithFlags, otherwise, no additional flags other than the default ones will be set;
• WithLoggerOptions.

func (*Runner[Holder]) Run

func (r *Runner[Holder]) Run(
	run RunFn[Holder],
	args ...string,
) (err error)

Run passes the given arguments to the command-line program, creates a logger, validates flags, and runs the command-line program itself via the given RunFn function.

If no arguments are present, os.Args[1:] are using.

type UsageFn

type UsageFn func(set *flag.FlagSet)

UsageFn is intended to set the flag.FlagSet behavior when flag.FlagSet.Usage is called.

type ValidateFlagsFn

type ValidateFlagsFn[Holder any] func(set *flag.FlagSet, holder *Holder) error

ValidateFlagsFn is intended to be a validator for flags of flag.FlagSet.