snek

package
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Jul 28, 2024 License: Apache-2.0, MIT Imports: 25 Imported by: 0

Documentation

Overview

Package snek provides a simplified, slimmed-down wrapper around the cobra CLI library.

Index

Constants

View Source 
const (
	ExitSuccess = 0
	ExitError   = 1
	ExitPanic   = 2
)

Variables

View Source 
var (
	// ArbitraryArgs is used to represent a command that can take any number of
	// positional arguments.
	ArbitraryArgs = positionalArgs(cobra.ArbitraryArgs)

	// NoArgs is used to represent a command that takes no positional arguments.
	NoArgs = positionalArgs(cobra.NoArgs)
)
View Source 
var (
	FormatLink    = ansi.Format(ansi.Underline, ansi.FGWhite)
	FormatHeading = ansi.FGYellow
	FormatFlag    = ansi.FGCyan
	FormatArg     = ansi.Format(ansi.Bold, ansi.FGWhite)
	FormatCommand = ansi.FGGreen
	FormatKeyword = ansi.FGCyan
	FormatStrong  = ansi.Bold
	FormatCall    = ansi.Format(ansi.FGWhite, ansi.Bold)
	FormatQuote   = ansi.FGGray
	FormatError   = ansi.FGRed
	FormatWarning = ansi.FGYellow
	FormatInfo    = ansi.FGBlue
)
View Source 
var CompletionError = completion(func() ([]string, cobra.ShellCompDirective) {
	return nil, cobra.ShellCompDirectiveError
})

CompletionError indicates that an error occurred while trying to provide completions, and the shell should not provide any completions.

View Source 
var NoCompletion = CompleteNoFiles()

Functions

func CommandErr 

func CommandErr(ctx context.Context) io.Writer

CommandErr returns the stderr writer from the context, if available, or os.Stderr.

func CommandOut 

func CommandOut(ctx context.Context) io.Writer

CommandOut returns the stdout writer from the context, if available, or os.Stdout.

func DisableColor 

func DisableColor(ctx context.Context) context.Context

DisableColor disables color output for the given context.

func ErrorPrefix 

func ErrorPrefix(ctx context.Context) string

ErrorPrefix returns the error prefix for the given context. If no application name can be extracted from the context, a default one will be provided.

func Errorf 

func Errorf(ctx context.Context, format string, args ...any)

Errorf writes a formatted string to the output stored within the context, or standard error if unavailable, with an error prefix.

func Examples 

func Examples(examples ...string) []string

Examples returns the given examples.

func ForceColor 

func ForceColor(ctx context.Context) context.Context

ForceColor forces color output for the given context.

func IsTerminal 

func IsTerminal(w io.Writer) bool

IsTerminal returns true if the writer is a terminal.

func IsUsageError 

func IsUsageError(err error) bool

IsUsageError returns true if the error is a usage error.

func Lines 

func Lines(lines ...string) string

Lines joins the given strings with newlines.

func NoticePrefix 

func NoticePrefix(ctx context.Context) string

NoticePrefix returns the notice prefix for the given context.

func Noticef 

func Noticef(ctx context.Context, format string, args ...any)

Noticef writes a formatted string to the output stored within the context, or standard output if unavailable, with a notice prefix.

func PanicPrefix 

func PanicPrefix(ctx context.Context) string

func Panicf 

func Panicf(ctx context.Context, format string, args ...any)

Panicf writes a formatted string to the output stored within the context, or standard error if unavailable, with a panic prefix.

func Printf 

func Printf(ctx context.Context, format string, args ...any)

Printf writes a formatted string to the output stored within the context, or standard output if unavailable.

func UsageError 

func UsageError(message string) error

UsageError returns an error that should be displayed to the user as a usage error. This will be accompanied with the usage instructions for the command.

func UsageErrorf 

func UsageErrorf(format string, args ...interface{}) error

UsageErrorf returns an error that should be displayed to the user as a usage error. This will be accompanied with the usage instructions for the command.

func WarningPrefix 

func WarningPrefix(ctx context.Context) string

WarningPrefix returns the warning prefix for the given context.

func Warningf 

func Warningf(ctx context.Context, format string, args ...any)

Warningf writes a formatted string to the output stored within the context, or standard error if unavailable, with a warning prefix.

Types

type Annotations 

type Annotations map[string]string

Annotations is a map of string keys to string values that can be used to annotate a command.

type AppInfo 

type AppInfo struct {
	// Name is the name of the application.
	Name string

	// Website is the URL for the contact person or organization responsible for
	// the application.
	Website string

	// RepositoryURL is the URL for the repository for the application.
	RepositoryURL string

	// ReportIssueURL is the URL for the issue tracker for the application.
	ReportIssueURL string

	// DocsURL is the URL for the documentation for the application, which may be
	// different from the base Website URL.
	DocsURL string

	// KeyTerms are words that are important in the command, and will be
	// highlighted in the help output. (Optional)
	KeyTerms []string

	// Variables are words that are variable inputs in the command, and will be
	// highlighted in the help output. (Optional)
	Variables []string

	// UserData is an optional (unspecified) piece of data that can be provided
	// to the application. Default is nil.
	UserData any
}

type Application 

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

Application is a wrapper around a cobra command that represents an application.

func NewApplication 

func NewApplication(root Command, appInfo *AppInfo) *Application

NewApplication creates a new application from the given root command. This function will panic if any of the commands in the root do not define a Command.Info function that returns non-nil information.

func (*Application) Execute 

func (a *Application) Execute(ctx context.Context) (code *StatusCode)

Execute runs the application with the given context.

func (*Application) SetErr 

func (a *Application) SetErr(w io.Writer)

SetErr sets the error writer for the application.

func (*Application) SetHelpTemplate 

func (a *Application) SetHelpTemplate(tmpl string)

SetHelpTemplate sets the template that will be used to render the help output.

func (*Application) SetOut 

func (a *Application) SetOut(w io.Writer)

SetOut sets the out writer for the application.

func (*Application) SetPanicTemplate 

func (a *Application) SetPanicTemplate(tmpl string)

SetPanicTemplate sets the template that will be used to render the panic output.

This function will panic if the template is invalid.

func (*Application) SetUsageTemplate 

func (a *Application) SetUsageTemplate(tmpl string)

SetUsageTemplate sets the template that will be used to render the usage output.

func (*Application) SetVersionTemplate 

func (a *Application) SetVersionTemplate(tmpl string)

SetVersionTemplate sets the template that will be used to render the version output.

type BaseCommand 

type BaseCommand struct{}

BaseCommand is a simple implementation of the Command interface that must be embedded in all command implementations.

func (*BaseCommand) Commands 

func (c *BaseCommand) Commands() Commands

func (*BaseCommand) Complete 

func (c *BaseCommand) Complete(args []string, toComplete string) Completion

func (*BaseCommand) Flags 

func (c *BaseCommand) Flags() []*FlagSet

func (*BaseCommand) Info 

func (c *BaseCommand) Info() *CommandInfo

func (*BaseCommand) PositionalArgs 

func (c *BaseCommand) PositionalArgs() PositionalArgs

func (*BaseCommand) Run 

func (c *BaseCommand) Run(ctx context.Context, args []string) error

type Command 

type Command interface {
	// Info returns information about the command.
	Info() *CommandInfo

	// Run executes the command with the given arguments.
	Run(ctx context.Context, args []string) error

	// Complete returns a list of possible completions for the current set of args
	// and argument being completed.
	Complete(args []string, toComplete string) Completion

	// PositionalArgs returns information about the positional arguments for this
	// command.
	PositionalArgs() PositionalArgs

	// Flags returns a list of flags that can be used with this command.
	Flags() []*FlagSet

	// Commands returns a list of sub-commands that can be run under this
	// command.
	Commands() Commands
	// contains filtered or unexported methods
}

Command is the primary entry-point interface for use in the snek package. This will be translated into a cobra.Command for use in the CLI.

type CommandGroup 

type CommandGroup []Command

func (*CommandGroup) Add 

func (c *CommandGroup) Add(commands ...Command)

type CommandInfo 

type CommandInfo struct {
	// Use is an example usage of the command.
	// This must be prefixed with the command name.
	Use string

	Aliases     []string
	Summary     string
	Description string
	Examples    []string

	// KeyTerms are words that are important in the command, and will be
	// highlighted in the help output. (Optional)
	KeyTerms []string

	// Variables are words that are variable inputs in the command, and will be
	// highlighted in the help output. (Optional)
	Variables []string

	Annotations Annotations

	Version string

	Hidden     bool
	ShowCursor bool
}

type Commands 

type Commands map[string]*CommandGroup

func (*Commands) Group 

func (c *Commands) Group(name string) *CommandGroup

type Completer 

type Completer interface {
	// Complete returns a list of possible completions for the current set of args
	// and argument being completed.
	Complete(args []string, toComplete string) Completion
}

Completer is an interface that can be implemented by commands to provide custom completions for arguments.

type CompleterFunc 

type CompleterFunc func(args []string, toComplete string) Completion

CompleterFunc is a function that can be used to implement the Completer interface.

func (CompleterFunc) Complete 

func (f CompleterFunc) Complete(args []string, toComplete string) Completion

Complete calls the underlying function to provide completions.

type Completion 

type Completion interface {
	// contains filtered or unexported methods
}

Completion is an interface that can be implemented by commands to provide custom completions for arguments.

func CompleteDirs 

func CompleteDirs(completions ...string) Completion

CompleteDirs indicates that only directory names should be provided in file completion. To request directory names within another directory, the returned completions should specify the directory within which to search. The BashCompSubdirsInDir annotation can be used to obtain the same behavior but only for flags.

func CompleteFileExts 

func CompleteFileExts(extensions ...string) Completion

CompleteFileExts indicates that the provided completions should be used as file extension filters.

For flags, using Command.MarkFlagFilename() and Command.MarkPersistentFlagFilename() is a shortcut to using this directive explicitly. The BashCompFilenameExt annotation can also be used to obtain the same behavior for flags.

func CompleteNoFiles 

func CompleteNoFiles(completions ...string) Completion

CompleteNoFiles indicates that the shell should not provide file completion even when no completion is provided.

func CompleteWithoutSpace 

func CompleteWithoutSpace(completions ...string) Completion

CompleteWithoutSpace indicates that the shell should not add a space after the completion even if there is only a single completion provided.

type Flag 

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

Flag is an interface for setting options on a flag.

func (*Flag) MarkDeprecated 

func (f *Flag) MarkDeprecated(message string) *Flag

MarkDeprecated marks the flag as deprecated.

func (*Flag) MarkHidden 

func (f *Flag) MarkHidden() *Flag

MarkHidden marks the flag as hidden.

func (*Flag) MarkRequired 

func (f *Flag) MarkRequired(required bool) *Flag

MarkRequired marks the flag as required.

func (*Flag) SetCompleter 

func (f *Flag) SetCompleter(completer Completer) *Flag

SetCompleter sets the completer for the flag.

type FlagCompleters 

type FlagCompleters map[string]Completer

FlagCompleters is a map of completion functions for flags.

type FlagSet 

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

FlagSet is a wrapper around pflag.FlagSet that provides a more fluent API for defining flags.

func FlagSets 

func FlagSets(fs ...*FlagSet) []*FlagSet

FlagSets returns a slice of FlagSetss.

func NewFlagSet 

func NewFlagSet(name string) *FlagSet

NewFlagSet creates a new FlagSet with the specified name.

func (*FlagSet) Bool 

func (fs *FlagSet) Bool(out *bool, name string, value bool, usage string) *Flag

Bool defines a bool flag with the specified name, default value, and usage string.

func (*FlagSet) BoolP 

func (fs *FlagSet) BoolP(out *bool, name, shorthand string, value bool, usage string) *Flag

BoolP defines a bool flag with the specified name, shorthand, default value, and usage string.

func (*FlagSet) CompletionFuncs 

func (fs *FlagSet) CompletionFuncs() FlagCompleters

CompletionFuncs returns the completion functions for the flags in the FlagSet.

func (*FlagSet) Duration 

func (fs *FlagSet) Duration(out *time.Duration, name string, value time.Duration, usage string) *Flag

Duration defines a time.Duration flag with the specified name, default value, and usage string.

func (*FlagSet) DurationP 

func (fs *FlagSet) DurationP(out *time.Duration, name, shorthand string, value time.Duration, usage string) *Flag

DurationP defines a time.Duration flag with the specified name, shorthand, default value, and usage string.

func (*FlagSet) FlagSet 

func (fs *FlagSet) FlagSet() *pflag.FlagSet

FlagSet returns the underlying pflag.FlagSet.

func (*FlagSet) FlagUsages 

func (f *FlagSet) FlagUsages() string

FlagUsages returns a string containing the usage information for the flags in the FlagSet.

func (*FlagSet) Float64 

func (fs *FlagSet) Float64(out *float64, name string, value float64, usage string) *Flag

Float64 defines a float64 flag with the specified name, default value, and usage string.

func (*FlagSet) Float64P 

func (fs *FlagSet) Float64P(out *float64, name, shorthand string, value float64, usage string) *Flag

Float64P defines a float64 flag with the specified name, shorthand, default value, and usage string.

func (*FlagSet) FormattedFlagUsages 

func (f *FlagSet) FormattedFlagUsages(opts *FormatOptions) string

FormattedFlagUsages returns a string containing the usage information for the flags in the FlagSet, formatted according to the provided options.

func (*FlagSet) Int 

func (fs *FlagSet) Int(out *int, name string, value int, usage string) *Flag

Int defines an int flag with the specified name, default value, and usage string.

func (*FlagSet) Int16 

func (fs *FlagSet) Int16(out *int16, name string, value int16, usage string) *Flag

Int16 defines an int16 flag with the specified name, default value, and usage string.

func (*FlagSet) Int16P 

func (fs *FlagSet) Int16P(out *int16, name, shorthand string, value int16, usage string) *Flag

Int16P defines an int16 flag with the specified name, shorthand, default value, and usage string.

func (*FlagSet) Int32 

func (fs *FlagSet) Int32(out *int32, name string, value int32, usage string) *Flag

Int32 defines an int32 flag with the specified name, default value, and usage string.

func (*FlagSet) Int32P 

func (fs *FlagSet) Int32P(out *int32, name, shorthand string, value int32, usage string) *Flag

Int32P defines an int32 flag with the specified name, shorthand, default value, and usage string.

func (*FlagSet) Int64 

func (fs *FlagSet) Int64(out *int64, name string, value int64, usage string) *Flag

Int64 defines an int64 flag with the specified name, default value, and usage string.

func (*FlagSet) Int64P 

func (fs *FlagSet) Int64P(out *int64, name, shorthand string, value int64, usage string) *Flag

Int64P defines an int64 flag with the specified name, shorthand, default value, and usage string.

func (*FlagSet) Int8 

func (fs *FlagSet) Int8(out *int8, name string, value int8, usage string) *Flag

Int8 defines an int8 flag with the specified name, default value, and usage string.

func (*FlagSet) Int8P 

func (fs *FlagSet) Int8P(out *int8, name, shorthand string, value int8, usage string) *Flag

Int8P defines an int8 flag with the specified name, shorthand, default value, and usage string.

func (*FlagSet) IntP 

func (fs *FlagSet) IntP(out *int, name, shorthand string, value int, usage string) *Flag

IntP defines an int flag with the specified name, shorthand, default value, and usage string.

func (*FlagSet) IntSlice 

func (fs *FlagSet) IntSlice(out *[]int, name string, value []int, usage string) *Flag

IntSlice defines an int slice flag with the specified name, default value, and usage string.

func (*FlagSet) IntSliceP 

func (fs *FlagSet) IntSliceP(out *[]int, name, shorthand string, value []int, usage string) *Flag

IntSliceP defines an int slice flag with the specified name, shorthand, default value, and usage string.

func (*FlagSet) MarkMutuallyExclusive 

func (fs *FlagSet) MarkMutuallyExclusive(flags ...*Flag)

MarkMutuallyExclusive marks the flags as mutually exclusive.

func (*FlagSet) Name 

func (f *FlagSet) Name() string

Name returns the name of the FlagSet.

func (*FlagSet) RequireOneOf 

func (fs *FlagSet) RequireOneOf(flags ...*Flag)

RequireOneOf marks the flags as requiring at least one of them to be set.

func (*FlagSet) RequireTogether 

func (fs *FlagSet) RequireTogether(flags ...*Flag)

RequireTogether marks the flags as required together.

func (*FlagSet) String 

func (fs *FlagSet) String(out *string, name, value, usage string) *Flag

String defines a string flag with the specified name, default value, and usage string.

func (*FlagSet) StringP 

func (fs *FlagSet) StringP(out *string, name, shorthand, value, usage string) *Flag

StringP defines a string flag with the specified name, shorthand, default value, and usage string.

func (*FlagSet) StringSlice 

func (fs *FlagSet) StringSlice(out *[]string, name string, value []string, usage string) *Flag

StringSlice defines a string slice flag with the specified name, default value, and usage string.

func (*FlagSet) StringSliceP 

func (fs *FlagSet) StringSliceP(out *[]string, name, shorthand string, value []string, usage string) *Flag

StringSliceP defines a string slice flag with the specified name, shorthand, default value, and usage string.

func (*FlagSet) Uint 

func (fs *FlagSet) Uint(out *uint, name string, value uint, usage string) *Flag

Uint defines a uint flag with the specified name, default value, and usage string.

func (*FlagSet) Uint16 

func (fs *FlagSet) Uint16(out *uint16, name string, value uint16, usage string) *Flag

Uint16 defines a uint16 flag with the specified name, default value, and usage string.

func (*FlagSet) Uint16P 

func (fs *FlagSet) Uint16P(out *uint16, name, shorthand string, value uint16, usage string) *Flag

Uint16P defines a uint16 flag with the specified name, shorthand, default value, and usage string.

func (*FlagSet) Uint32 

func (fs *FlagSet) Uint32(out *uint32, name string, value uint32, usage string) *Flag

Uint32 defines a uint32 flag with the specified name, default value, and usage string.

func (*FlagSet) Uint32P 

func (fs *FlagSet) Uint32P(out *uint32, name, shorthand string, value uint32, usage string) *Flag

Uint32P defines a uint32 flag with the specified name, shorthand, default value, and usage string.

func (*FlagSet) Uint64 

func (fs *FlagSet) Uint64(out *uint64, name string, value uint64, usage string) *Flag

Uint64 defines a uint64 flag with the specified name, default value, and usage string.

func (*FlagSet) Uint64P 

func (fs *FlagSet) Uint64P(out *uint64, name, shorthand string, value uint64, usage string) *Flag

Uint64P defines a uint64 flag with the specified name, shorthand, default value, and usage string.

func (*FlagSet) Uint8 

func (fs *FlagSet) Uint8(out *uint8, name string, value uint8, usage string) *Flag

Uint8 defines a uint8 flag with the specified name, default value, and usage string.

func (*FlagSet) Uint8P 

func (fs *FlagSet) Uint8P(out *uint8, name, shorthand string, value uint8, usage string) *Flag

Uint8P defines a uint8 flag with the specified name, shorthand, default value, and usage string.

func (*FlagSet) UintP 

func (fs *FlagSet) UintP(out *uint, name, shorthand string, value uint, usage string) *Flag

UintP defines a uint flag with the specified name, shorthand, default value, and usage string.

func (*FlagSet) UintSlice 

func (fs *FlagSet) UintSlice(out *[]uint, name string, value []uint, usage string) *Flag

func (*FlagSet) UintSliceP 

func (fs *FlagSet) UintSliceP(out *[]uint, name, shorthand string, value []uint, usage string) *Flag

func (*FlagSet) Var 

func (fs *FlagSet) Var(name string, value pflag.Value, usage string) *Flag

func (*FlagSet) VarP 

func (fs *FlagSet) VarP(value pflag.Value, name, shorthand, usage string) *Flag

type FormatOptions 

type FormatOptions struct {
	ArgFormat        ansi.Display
	FlagFormat       ansi.Display
	DeprecatedFormat ansi.Display
}

FormatOptions is used to configure the formatting of the flag usage.

type PanicError 

type PanicError string

PanicError is an error that is used to represent a panic in the application.

func (PanicError) Error 

func (e PanicError) Error() string

Error returns the string representation of the panic error.

type PositionalArgs 

type PositionalArgs interface {
	// contains filtered or unexported methods
}

PositionalArgs is used to represent positional argument requirements for a command.

func Condition 

func Condition(cond func(args []string) error) PositionalArgs

Condition returns a PositionalArgs that requires the condition to be met.

func ExactArgs 

func ExactArgs(n int) PositionalArgs

ExactArgs returns a PositionalArgs that requires exactly n arguments.

func MatchAll 

func MatchAll(pargs ...PositionalArgs) PositionalArgs

MinimumNArgs returns a PositionalArgs that requires at least n arguments.

func MaximumNArgs 

func MaximumNArgs(n int) PositionalArgs

MaximumNArgs returns a PositionalArgs that requires at most n arguments.

func MinimumNArgs 

func MinimumNArgs(n int) PositionalArgs

MinimumNArgs returns a PositionalArgs that requires at least n arguments.

func RangeArgs 

func RangeArgs(min, max int) PositionalArgs

RangeArgs returns a PositionalArgs that requires between min and max

type StatusCode 

type StatusCode struct {
	Result error
	Code   int
}

StatusCode represents the response from the Application.

This provides the exact underlying error that the system encountered, and provides a suggestion on the exit status-code, with an optional helper func to exit the program with.

func (*StatusCode) Error 

func (s *StatusCode) Error() string

func (*StatusCode) Exit 

func (s *StatusCode) Exit()

Exit exits the program with the status code.

Source Files

View all Source files

Directories

Path Synopsis

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.