cmd

package
v0.25.1 Latest Latest
Warning

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

 Go to latest Published: Dec 11, 2025 License: MIT Imports: 20 Imported by: 2

Documentation

Index

Constants

View Source 
const (
	OutputFormatPlain    = "plain"
	OutputFormatJSON     = "json"
	OutputFormatYAML     = "yaml"
	OutputFormatMarkdown = "markdown"
	OutputFormatTable    = "table"
	OutputFormatCSV      = "csv"
	OutputFormatHTML     = "html"
	OutputFormatXML      = "xml"
	OutputFormatJSONP    = "jsonp"
)
View Source 
const (
	GroupBase  = "group-base"
	GroupOther = "group-other"
)
View Source 
const DefaultWrapWidth = 80

Variables

This section is empty.

Functions

func AddPersistentFlags added in v0.8.12 

func AddPersistentFlags(cmd *cobra.Command, ec *ExecutionContext) *pflag.FlagSet

AddPersistentFlags adds global flags to the command and does some initialization

func AllLogFormatsJoined added in v0.8.12 

func AllLogFormatsJoined() string

AllLogFormatsJoined returns all formats joined by "|"

func AllLogFormatsStr added in v0.8.12 

func AllLogFormatsStr() []string

AllLogFormatsStr returns all formats as strings

func AllLogLevelsJoined added in v0.8.12 

func AllLogLevelsJoined() string

AllLogLevelsJoined returns all levels joined by "|"

func AllLogLevelsStr added in v0.8.12 

func AllLogLevelsStr() []string

AllLogLevelsStr returns all levels as strings

func GenDocsCommand added in v0.8.1 

func GenDocsCommand(ec *ExecutionContext) *cobra.Command

func NewEnum added in v0.8.12 

func NewEnum(allowed []string, d string) *enum

NewEnum gives a list of allowed flag parameters, where the second argument is the default

func ParseLogLevel added in v0.8.12 

func ParseLogLevel(level LogLevel) slog.Level

ParseLogLevel converts a log level to a slog level

Types

type DefaultErrorHandler added in v0.14.0 

type DefaultErrorHandler struct {
	Output io.Writer
	// contains filtered or unexported fields
}

DefaultErrorHandler handles errors providing colored output to a specified writer (defaults to stderr).

func NewDefaultHandler added in v0.14.0 

func NewDefaultHandler(output io.Writer) *DefaultErrorHandler

NewDefaultHandler creates a new DefaultErrorHandler with the specified output writer. If no writer is provided, it defaults to stderr.

func (*DefaultErrorHandler) HandleError added in v0.14.0 

func (h *DefaultErrorHandler) HandleError(err error)

HandleError checks if the given error implements the ErrorWithHelp interface. If it does, it prints the error message and help message in a colored format to the configured output writer. Otherwise, it prints a generic error message.

func (*DefaultErrorHandler) NewGeneralError added in v0.14.0 

func (h *DefaultErrorHandler) NewGeneralError(message, helpMsg string, err error, code int) *GeneralError

func (*DefaultErrorHandler) SetWrap added in v0.14.0 

func (h *DefaultErrorHandler) SetWrap(wrap bool)

func (*DefaultErrorHandler) SetWrapWidth added in v0.14.0 

func (h *DefaultErrorHandler) SetWrapWidth(width int)

type ErrorHandler added in v0.14.0 

type ErrorHandler interface {
	// HandleError handles the given error.
	HandleError(err error)
	// NewGeneralError creates a new GeneralError with the specified message, help message, error, and code.
	NewGeneralError(message, helpMsg string, err error, code int) *GeneralError
	// SetWrap sets whether to wrap the error message and help message.
	SetWrap(wrap bool)
	// SetWrapWidth sets the width to wrap the error message and help message.
	SetWrapWidth(width int)
}

ErrorHandler is an interface for handling errors.

type ErrorWithHelp added in v0.14.0 

type ErrorWithHelp interface {
	error

	// Help returns a help message for the error
	Help() string

	// Unwrap returns the underlying error
	Unwrap() error // Optional: for wrapped errors

	// Code returns the error code
	Code() int // Optional: for error codes
}

ErrorWithHelp interface is used for errors that can provide help

type ExecutionContext added in v0.8.12 

type ExecutionContext struct {
	// AppName is the executable app name
	// Keep it in lower case letters and use dashes for multi-word app names
	AppName string

	// ShortDescription is a short description of the app
	ShortDescription string

	// LongDescription is a long description of the app
	LongDescription string

	// Stdin is the input stream
	Stdin io.Reader

	// Stdout is the output stream
	Stdout io.Writer

	// Stderr is the error stream
	Stderr io.Writer

	// Command is the current command
	Command *cobra.Command

	// CommandArgs are the arguments passed to the command
	CommandArgs []string

	// Logger is the global logger
	Logger *slog.Logger

	// ErrorHandler
	ErrorHandler ErrorHandler

	// Spinner is the global spinner object used to show progress across the cli
	Spinner ui.Spinner

	// IsTerminal indicates whether the current session is a terminal or not
	IsTerminal bool

	// Version is the CLI version
	// Flag: --version
	Version string

	// PFlags are the persistent flag configuration
	PFlags PFlags

	// for changing log level
	LogLevel *slog.LevelVar
}

ExecutionContext holds configuration that can be used (and modified) across the application

func NewExecutionContext added in v0.8.12 

func NewExecutionContext(appName, shortDesc, version string) *ExecutionContext

NewExecutionContext creates a new Context

func (*ExecutionContext) SetColor added in v0.8.12 

func (ec *ExecutionContext) SetColor(noColor bool)

SetColor sets weather color should be used in the output If the output is not a terminal, color is disabled If the --no-color flag is set, color is disabled If the --no-input flag is set, color is disabled

func (*ExecutionContext) SetLogLevel added in v0.8.12 

func (ec *ExecutionContext) SetLogLevel()

SetLogLevel sets the ec.Logger log level

type GeneralError added in v0.14.0 

type GeneralError struct {
	Message string
	HelpMsg string
	CodeVal int
	Err     error
}

func (*GeneralError) Code added in v0.14.0 

func (e *GeneralError) Code() int

func (*GeneralError) Error added in v0.14.0 

func (e *GeneralError) Error() string

func (*GeneralError) Help added in v0.14.0 

func (e *GeneralError) Help() string

func (*GeneralError) Unwrap added in v0.14.0 

func (e *GeneralError) Unwrap() error

type GeneralErrorBuilder added in v0.14.0 

type GeneralErrorBuilder struct {
	*GeneralError
}

func NewGeneralError added in v0.14.0 

func NewGeneralError(err error) *GeneralErrorBuilder

NewGeneralError creates a new GeneralError with support for formatting the message and help message. The error is provided as an argument since it should always be present.

func (*GeneralErrorBuilder) Build added in v0.14.0 

func (b *GeneralErrorBuilder) Build() *GeneralError

Build returns the GeneralError.

func (*GeneralErrorBuilder) WithCode added in v0.14.0 

func (b *GeneralErrorBuilder) WithCode(code int) *GeneralErrorBuilder

WithCode assigns the exit code to the codeVal.

func (*GeneralErrorBuilder) WithHelp added in v0.14.0 

func (b *GeneralErrorBuilder) WithHelp(format string, a ...any) *GeneralErrorBuilder

WithHelp formats according to a format specifier and assigns the result to the helpMsg.

func (*GeneralErrorBuilder) WithMessage added in v0.14.0 

func (b *GeneralErrorBuilder) WithMessage(format string, a ...any) *GeneralErrorBuilder

WithMessage formats according to a format specifier and assigns the result to the message.

type InitFunc 

type InitFunc = func(cmd *cobra.Command, args []string) error

type InvalidArgumentError added in v0.14.0 

type InvalidArgumentError struct {
	Flag     string
	Val      string
	OneOf    []string
	SeeOther string
	Context  string
}

InvalidArgumentError is returned when an argument is invalid

func (*InvalidArgumentError) Code added in v0.14.0 

func (e *InvalidArgumentError) Code() int

func (*InvalidArgumentError) Error added in v0.14.0 

func (e *InvalidArgumentError) Error() string

func (*InvalidArgumentError) Help added in v0.14.0 

func (e *InvalidArgumentError) Help() string

Help returns the error message

func (*InvalidArgumentError) Unwrap added in v0.14.0 

func (e *InvalidArgumentError) Unwrap() error

type LogFormat added in v0.8.12 

type LogFormat string
const (
	LogFormatPlain LogFormat = "plain"
	LogFormatJSON  LogFormat = "json"

	LogFormatDefault = LogFormatPlain
)

func AllLogFormats added in v0.8.12 

func AllLogFormats() []LogFormat

AllLogFormats returns all formats

func (LogFormat) String added in v0.8.12 

func (f LogFormat) String() string

String returns the string representation of the format

type LogLevel added in v0.8.12 

type LogLevel string
const (
	LogLevelDebug LogLevel = "debug"
	LogLevelInfo  LogLevel = "info"
	LogLevelWarn  LogLevel = "warn"
	LogLevelError LogLevel = "error"

	LogLevelDefault = LogLevelInfo
)

func AllLogLevels added in v0.8.12 

func AllLogLevels() []LogLevel

AllLogLevels returns all levels

func (LogLevel) String added in v0.8.12 

func (l LogLevel) String() string

String returns the string representation of the level

type NoopRunner added in v0.8.2 

type NoopRunner[T any] struct{}

func (*NoopRunner[T]) Complete added in v0.8.2 

func (o *NoopRunner[T]) Complete(_ context.Context, _ T) error

func (*NoopRunner[T]) Run added in v0.8.2 

func (o *NoopRunner[T]) Run(_ context.Context, _ T) error

func (*NoopRunner[T]) SetupFlags added in v0.20.0 

func (o *NoopRunner[T]) SetupFlags(_ context.Context, _ T) error

func (*NoopRunner[T]) Validate added in v0.8.2 

func (o *NoopRunner[T]) Validate(_ context.Context, _ T) error

type PFlags added in v0.8.12 

type PFlags struct {
	// LogFormat is the log format used for the logger
	// The ForFormat flag is always enabled
	// Flag: --log-format [plain|json]
	LogFormat LogFormat

	// LogLevel is the log level used for the logger
	// The LogLevel flag is always enabled
	// Flag: --log-level [debug|info|warn|error]
	LogLevel LogLevel

	// Debug is used for debugging
	// Usually this implies verbose output
	// The Debug flag is always enabled
	// Flags: --debug, -d
	Debug bool

	// OutputFormat is the format used for outputting data
	// Examples: plain, json, yaml, markdown, table
	OutputFormat string

	// OutputFormat is used to enable the OutputFormat flag
	OutputFormatEnabled bool

	// Force is used to force actions
	// Flags: --force, -f
	Force bool

	// ForceEnabled is used to enable the Force flag
	ForceEnabled bool

	// DryRun is used to simulate actions
	// Flags: --dry-run
	DryRun bool

	// DryRunEnabled is used to enable the DryRun flag
	DryRunEnabled bool

	// NoInput can be used to disable interactive mode
	// Flags: --no-input
	NoInput bool

	// NoInputEnabled is used to enable the NoInput flag
	NoInputEnabled bool

	// NoColor is used to control whether color is used in output
	// The NoColor flag is always enabled
	// Flags: --no-color
	NoColor bool

	// Quiet is used to control whether output is suppressed
	// Flags: --quiet, -q
	Quiet bool

	// QuietEnabled is used to enable the Quiet flag
	QuietEnabled bool

	// NoHeaders is used to control whether headers are printed
	// Flag: --no-headers
	NoHeaders bool

	// NoHeadersEnabled is used to enable the NoHeaders flag
	NoHeadersEnabled bool
}

PFlags represents is persistent/global flags

type RootCommandBuilder added in v0.8.1 

type RootCommandBuilder struct {
	// contains filtered or unexported fields
}

func NewRootCommand 

func NewRootCommand(ec *ExecutionContext) *RootCommandBuilder

NewRootCommand creates a new root command Use this function to create a new root command that is used to add subcommands

It supports the following features:

- Adding global flags to the command - Automatically reads configuration from the configuration file - Automatically reads configuration from environment variables - Automatically binds the configuration to the command's flags - Automatically sets the log level based on the configuration - Automatically sets the log format based on the configuration

It uses ec.AppName as the base name for the configuration file and environment variables initFunc is a function that is called before the command is executed It can be used to add more context or do other initializations

func (*RootCommandBuilder) Build added in v0.8.1 

func (b *RootCommandBuilder) Build() *cobra.Command

Build builds the root command

func (*RootCommandBuilder) WithExample added in v0.8.17 

func (b *RootCommandBuilder) WithExample(example string) *RootCommandBuilder

WithExample sets the example of the root command

func (*RootCommandBuilder) WithInitFunc added in v0.8.1 

func (b *RootCommandBuilder) WithInitFunc(fn InitFunc) *RootCommandBuilder

WithInitFunc adds an init function to the root command This sets the PersistentPreRunE function of the command

func (*RootCommandBuilder) WithNoSubCommands added in v0.16.0 

func (b *RootCommandBuilder) WithNoSubCommands() *RootCommandBuilder

func (*RootCommandBuilder) WithPersistentFlags added in v0.8.1 

func (b *RootCommandBuilder) WithPersistentFlags(flags *pflag.FlagSet) *RootCommandBuilder

WithPreRunFunc adds persistent flags to the root command

type SubCommandBuilder added in v0.8.1 

type SubCommandBuilder[T any] struct {
	// contains filtered or unexported fields
}

SubCommandBuilder is a builder for a subcommand

func NewSubCommand 

func NewSubCommand[T any](
	name string,
	runner SubCommandRunner[T],
	runnerArg T,
) *SubCommandBuilder[T]

NewSubCommand creates a new subcommand args can be used to pass arguments to the runner

func (*SubCommandBuilder[T]) Build added in v0.8.1 

func (b *SubCommandBuilder[T]) Build() *cobra.Command

Build builds the subcommand

func (*SubCommandBuilder[T]) WithAliases added in v0.8.17 

func (b *SubCommandBuilder[T]) WithAliases(aliases ...string) *SubCommandBuilder[T]

WithAliases sets the aliases of the subcommand

func (*SubCommandBuilder[T]) WithExactArgs added in v0.8.14 

func (b *SubCommandBuilder[T]) WithExactArgs(n int) *SubCommandBuilder[T]

WithExactArgs causes the subcommand to return an error if there are not exactly n arguments

func (*SubCommandBuilder[T]) WithExample added in v0.8.1 

func (b *SubCommandBuilder[T]) WithExample(example string) *SubCommandBuilder[T]

WithExample sets the example of the subcommand

func (*SubCommandBuilder[T]) WithGroupID added in v0.8.1 

func (b *SubCommandBuilder[T]) WithGroupID(group string) *SubCommandBuilder[T]

WithGroupID sets the group id of the subcommand

func (*SubCommandBuilder[T]) WithLongDesc added in v0.8.1 

func (b *SubCommandBuilder[T]) WithLongDesc(desc string) *SubCommandBuilder[T]

WithLongDesc sets the long description of the subcommand

func (*SubCommandBuilder[T]) WithMaxArgs added in v0.8.14 

func (b *SubCommandBuilder[T]) WithMaxArgs(n int) *SubCommandBuilder[T]

WithMaxArgs causes the subcommand to return an error if there are more than n arguments

func (*SubCommandBuilder[T]) WithMinArgs added in v0.8.14 

func (b *SubCommandBuilder[T]) WithMinArgs(n int) *SubCommandBuilder[T]

WithMinArgs causes the subcommand to return an error if there is not at least n arguments

func (*SubCommandBuilder[T]) WithNoArgs added in v0.8.2 

func (b *SubCommandBuilder[T]) WithNoArgs() *SubCommandBuilder[T]

WithNoArgs causes the subcommand to return an error if any arguments are passed

func (*SubCommandBuilder[T]) WithShortDesc added in v0.8.1 

func (b *SubCommandBuilder[T]) WithShortDesc(desc string) *SubCommandBuilder[T]

WithShortDesc sets the short description of the subcommand

type SubCommandRunner 

type SubCommandRunner[T any] interface {
	// SetupFlags sets up the flags for the command
	// Returns error if flag setup fails
	SetupFlags(ctx context.Context, arg T) error

	// Complete performs any setup or completion of arguments
	Complete(ctx context.Context, arg T) error

	// Validate checks if the arguments are valid
	// Returns error if validation fails
	Validate(ctx context.Context, arg T) error

	// Run executes the command with the given arguments
	// Returns error if execution fails
	Run(ctx context.Context, arg T) error
}

SubCommandRunner is an interface for a subcommand runner

type TestRunner added in v0.8.1 

type TestRunner[T any] struct {
	SetupFlagsFunc func(context.Context, T) error
	CompleteFunc   func(context.Context, T) error
	ValidateFunc   func(context.Context, T) error
	RunFunc        func(context.Context, T) error
}

TestRunner is a test runner for commands

func (*TestRunner[T]) Complete added in v0.8.1 

func (tr *TestRunner[T]) Complete(ctx context.Context, runnerArg T) error

func (*TestRunner[T]) Run added in v0.8.1 

func (tr *TestRunner[T]) Run(ctx context.Context, runnerArg T) error

func (*TestRunner[T]) SetupFlags added in v0.20.0 

func (tr *TestRunner[T]) SetupFlags(ctx context.Context, runnerArg T) error

func (*TestRunner[T]) Validate added in v0.8.1 

func (tr *TestRunner[T]) Validate(ctx context.Context, runnerArg T) error

Source Files

View all Source files

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.