cli

package
v0.5.1 Latest Latest
Warning

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

 Go to latest Published: Feb 19, 2025 License: MIT Imports: 12 Imported by: 0

README 

cli package coppied from tractordev/toolkit-go.git. (MIT Lic)

Added support for int32 flags. Its zero dep so nice to copy it for now.

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var HelpFuncs = template.FuncMap{
	"trim": strings.TrimSpace,
	"trimRight": func(s string) string {
		return strings.TrimRightFunc(s, unicode.IsSpace)
	},
	"padRight": func(s string, padding int) string {
		template := fmt.Sprintf("%%-%ds", padding)
		return fmt.Sprintf(template, s)
	},
}

HelpFuncs are used by the help templating system.

View Source 
var HelpTemplate = `` /* 545-byte string literal not displayed */

HelpTemplate is a template used to generate help.

Functions

func Execute 

func Execute(ctx context.Context, root *Command, args []string) error

Execute takes a root Command plus arguments, finds the Command to run, parses flags, checks for expected arguments, and runs the Command. It also adds a version flag if the root Command has Version set.

Types

type Command 

type Command struct {
	// Use is the one-line usage message.
	// Recommended syntax is as follow:
	//   [ ] identifies an optional argument. Arguments that are not enclosed in brackets are required.
	//   ... indicates that you can specify multiple values for the previous argument.
	//   |   indicates mutually exclusive information. You can use the argument to the left of the separator or the
	//       argument to the right of the separator. You cannot use both arguments in a single use of the command.
	//   { } delimits a set of mutually exclusive arguments when one of the arguments is required. If the arguments are
	//       optional, they are enclosed in brackets ([ ]).
	// Example: add [-F file | -D dir]... [-f format] <profile>
	Usage string

	// Short is the short description shown in the 'help' output.
	Short string

	// Long is the long message shown in the 'help <this-command>' output.
	Long string

	// Hidden defines, if this command is hidden and should NOT show up in the list of available commands.
	Hidden bool

	// Aliases is an array of aliases that can be used instead of the first word in Use.
	Aliases []string

	// Example is examples of how to use the command.
	Example string

	// Annotations are key/value pairs that can be used by applications to identify or
	// group commands.
	Annotations map[string]interface{}

	// Version defines the version for this command. If this value is non-empty and the command does not
	// define a "version" flag, a "version" boolean flag will be added to the command and, if specified,
	// will print content of the "Version" variable. A shorthand "v" flag will also be added if the
	// command does not define one.
	Version string

	// Expected arguments
	Args PositionalArgs

	// Run is the function that performs the command
	Run func(ctx *Context, args []string)
	// contains filtered or unexported fields
}

Command is a command or subcommand that can be run with Execute.

func Export 

func Export(fn interface{}, use string) *Command

Export wraps a function as a command.

func (*Command) AddCommand 

func (c *Command) AddCommand(sub *Command)

AddCommand adds one or more commands to this parent command.

func (*Command) CommandPath 

func (c *Command) CommandPath() string

CommandPath returns the full path to this command.

func (*Command) Find 

func (c *Command) Find(args []string) (cmd *Command, n int)

Find the target command given the args and command tree. Meant to be run on the highest node. Only searches down. Also returns the arguments consumed to reach the command.

func (*Command) Flags 

func (c *Command) Flags() *FlagSet

Flags returns the complete FlagSet that applies to this command.

func (*Command) Name 

func (c *Command) Name() string

Name returns the command's name: the first word in the usage line.

func (*Command) UseLine 

func (c *Command) UseLine() string

UseLine puts out the full usage for a given command (including parents).

type CommandHelp 

type CommandHelp struct {
	*Command
}

CommandHelp wraps a Command to generate help.

func (*CommandHelp) Available 

func (c *CommandHelp) Available() bool

Available determines if a command is available as a non-help command (this includes all non hidden commands).

func (*CommandHelp) Commands 

func (c *CommandHelp) Commands() (cmds []*CommandHelp)

Commands returns any subcommands as CommandHelp values.

func (*CommandHelp) FlagUsages 

func (c *CommandHelp) FlagUsages() string

FlagUsages creates a string for flag usage help.

func (*CommandHelp) HasExample 

func (c *CommandHelp) HasExample() bool

HasExample determines if the command has example.

func (*CommandHelp) HasFlags 

func (c *CommandHelp) HasFlags() bool

HasFlags checks if the command contains flags.

func (*CommandHelp) HasSubCommands 

func (c *CommandHelp) HasSubCommands() bool

HasSubCommands determines if a command has available sub commands that need to be shown in the usage/help default template under 'available commands'.

func (*CommandHelp) NameAndAliases 

func (c *CommandHelp) NameAndAliases() string

NameAndAliases returns a list of the command name and all aliases.

func (*CommandHelp) NamePadding 

func (c *CommandHelp) NamePadding() int

NamePadding returns padding for the name.

func (*CommandHelp) Runnable 

func (c *CommandHelp) Runnable() bool

Runnable determines if the command is itself runnable.

func (*CommandHelp) WriteHelp 

func (c *CommandHelp) WriteHelp(w io.Writer) error

WriteHelp generates help for the command written to an io.Writer.

type Context 

type Context struct {
	context.Context
	// contains filtered or unexported fields
}

func ContextWithIO 

func ContextWithIO(parent context.Context, in io.Reader, out io.Writer, err io.Writer) *Context

ContextWithIO returns a child context with a ContextIO value added using the given Stdio equivalents.

func (Context) Errout 

func (c Context) Errout() io.Writer

func (Context) Read 

func (c Context) Read(p []byte) (n int, err error)

func (Context) Write 

func (c Context) Write(p []byte) (n int, err error)

type FlagSet 

type FlagSet struct {
	flag.FlagSet
}

FlagSet is a wrapper around flag.FlagSet It is used to add more functionality to the flag.FlagSet such as int32 support

func (*FlagSet) Int32 

func (f *FlagSet) Int32(name string, value int32, usage string) *int32

Int defines an int flag with specified name, default value, and usage string. The return value is the address of an int variable that stores the value of the flag.

func (*FlagSet) Int32Var 

func (f *FlagSet) Int32Var(p *int32, name string, value int32, usage string)

Int32 defines a int32 flag with specified name, default value, and usage string. The return value is the address of an int32 variable that stores the value of the flag.

type Framework 

type Framework struct {
	DefaultRunner Runner
	Initializers  []Initializer
	Preprocessors []Preprocessor
	Root          *Command
}

Framework manages a root command, allowing Initializers to modify it, which by default runs a DefaultRunner.

func (*Framework) Initialize 

func (f *Framework) Initialize()

Initialize sets up a Root command that simply runs the DefaultRunner, and also runs any Initializers.

func (*Framework) Run 

func (f *Framework) Run(ctx context.Context) error

Run executes the root command with os.Args and STDIO.

type Initializer 

type Initializer interface {
	InitializeCLI(root *Command)
}

Initializer is a hook to allow units to customize the root Command.

type PositionalArgs 

type PositionalArgs func(cmd *Command, args []string) error

PositionalArgs is a function type used by the Command Args field for detecting whether the arguments match a given expectation.

func ExactArgs 

func ExactArgs(n int) PositionalArgs

ExactArgs returns an error if there are not exactly n args.

func MaxArgs 

func MaxArgs(n int) PositionalArgs

MaxArgs returns an error if there are more than N args.

func MinArgs 

func MinArgs(n int) PositionalArgs

MinArgs returns an error if there is not at least N args.

func RangeArgs 

func RangeArgs(min int, max int) PositionalArgs

RangeArgs returns an error if the number of args is not within the expected range.

type Preprocessor 

type Preprocessor interface {
	PreprocessCLI(args []string) []string
}

type Runner 

type Runner interface {
	Run(ctx context.Context) error
}

Runner is a unit that takes over the program entrypoint.

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.