command

package
v0.3.0 Latest Latest
Warning

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

 Go to latest Published: Mar 10, 2026 License: Apache-2.0 Imports: 19 Imported by: 6

Documentation

Overview

Copyright © 2022 Roberto Hidalgo <chinampa@un.rob.mx> SPDX-License-Identifier: Apache-2.0

Copyright © 2022 Roberto Hidalgo <chinampa@un.rob.mx> SPDX-License-Identifier: Apache-2.0

Copyright © 2022 Roberto Hidalgo <chinampa@un.rob.mx> SPDX-License-Identifier: Apache-2.0

Copyright © 2022 Roberto Hidalgo <chinampa@un.rob.mx> SPDX-License-Identifier: Apache-2.0

Copyright © 2022 Roberto Hidalgo <chinampa@un.rob.mx> SPDX-License-Identifier: Apache-2.0

Copyright © 2022 Roberto Hidalgo <chinampa@un.rob.mx> SPDX-License-Identifier: Apache-2.0

Copyright © 2022 Roberto Hidalgo <chinampa@un.rob.mx> SPDX-License-Identifier: Apache-2.0

Index

Constants

This section is empty.

Variables

View Source 
var Root = &Command{
	Summary:     "Replace me with chinampa.Configure",
	Description: "",
	Path:        []string{runtime.Executable},
	Options: Options{
		_c.HelpCommandName: &Option{
			ShortName:   "h",
			Type:        "bool",
			Description: "Display help for any command",
		},
		"color": &Option{
			Type:        "bool",
			Description: "Always print colors to stderr",
			Default:     runtime.ColorEnabled(),
		},
		"no-color": &Option{
			Type:        "bool",
			Description: "Disable printing of colors to stderr",
			Default:     !runtime.ColorEnabled(),
		},
		"verbose": &Option{
			ShortName:   "v",
			Type:        "bool",
			Default:     runtime.VerboseEnabled(),
			Description: "Log verbose output to stderr",
		},
		"silent": &Option{
			Type:        "bool",
			Description: "Silence non-error logging",
		},
		"skip-validation": &Option{
			Type:        "bool",
			Description: "Do not validate any arguments or options",
		},
		"version": &Option{
			Type:        "bool",
			Default:     false,
			Description: "Display program version and exit",
		},
	},
}

Functions

func RegisterValueSource 

func RegisterValueSource(key string, completion CompletionFunc)

Registers a completion function for the given command.ValueType key name.

Types

type Action 

type Action func(cmd *Command) error

type Argument 

type Argument struct {
	// Name is how this variable will be exposed to the underlying command.
	Name string `json:"name" yaml:"name" validate:"required,excludesall=!$\\/%^@#?:'\""`
	// Description is what this argument is for.
	Description string `json:"description" yaml:"description" validate:"required"`
	// Default is the default value for this argument if none is provided.
	Default any `json:"default,omitempty" yaml:"default,omitempty" validate:"excluded_with=Required"`
	// Variadic makes an argument a list of all values from this one on.
	Variadic bool `json:"variadic" yaml:"variadic"`
	// Required raises an error if an argument is not provided.
	Required bool `json:"required" yaml:"required" validate:"excluded_with=Default"`
	// Values describes autocompletion and validation for an argument
	Values  *ValueSource `json:"values,omitempty" yaml:"values" validate:"omitempty"`
	Command *Command     `json:"-" yaml:"-" validate:"-"`
	// contains filtered or unexported fields
}

Argument represents a single command-line argument.

func (*Argument) EnvName 

func (arg *Argument) EnvName() string

func (*Argument) IsKnown 

func (arg *Argument) IsKnown() bool

func (*Argument) Repeats added in v0.3.0 

func (arg *Argument) Repeats() bool

Repeats tells if an argument should be presented as a list.

func (*Argument) Resolve 

func (arg *Argument) Resolve(current string) (values []string, flag cobra.ShellCompDirective, err error)

Resolve returns autocomplete values for an argument.

func (*Argument) SetValue 

func (arg *Argument) SetValue(value []string)

func (*Argument) ToDesc 

func (arg *Argument) ToDesc() string

ToDesc prints out the description of an argument for help and docs.

func (*Argument) ToString 

func (arg *Argument) ToString() string

func (*Argument) ToValue 

func (arg *Argument) ToValue() any

func (*Argument) Validate 

func (arg *Argument) Validate() error

func (*Argument) Validates 

func (arg *Argument) Validates() bool

Validates tells if the user-supplied value needs validation.

type Arguments 

type Arguments []*Argument

Arguments is an ordered list of Argument.

func (*Arguments) AllKnown 

func (args *Arguments) AllKnown() map[string]any

func (*Arguments) AllKnownStr 

func (args *Arguments) AllKnownStr() map[string]string

func (*Arguments) AreValid 

func (args *Arguments) AreValid() error

func (*Arguments) CompletionFunction 

func (args *Arguments) CompletionFunction(cc *cobra.Command, provided []string, toComplete string) ([]string, cobra.ShellCompDirective)

CompletionFunction is called by cobra when asked to complete arguments.

func (*Arguments) Parse 

func (args *Arguments) Parse(supplied []string) error

type AutocompleteTemplate 

type AutocompleteTemplate struct {
	Args map[string]string
	Opts map[string]string
}

func (*AutocompleteTemplate) Arg 

func (tpl *AutocompleteTemplate) Arg(name string) string

func (*AutocompleteTemplate) Opt 

func (tpl *AutocompleteTemplate) Opt(name string) string

type Command 

type Command struct {
	Path []string `json:"path" yaml:"path"`
	// Summary is a short description of a command, on supported shells this is part of the autocomplete prompt
	Summary string `json:"summary" yaml:"summary" validate:"required"`
	// Description is a long form explanation of how a command works its magic. Markdown is supported
	Description string `json:"description" yaml:"description" validate:"required"`
	// A list of arguments for a command
	Arguments Arguments `json:"arguments" yaml:"arguments" validate:"dive"`
	// A map of option names to option definitions
	Options  Options  `json:"options" yaml:"options" validate:"dive"`
	HelpFunc HelpFunc `json:"-" yaml:"-"`
	// The action to take upon running
	Action Action `json:"-" yaml:"-"`

	Cobra *cobra.Command `json:"-" yaml:"-"`
	// Meta stores application specific stuff
	Meta   any  `json:"meta" yaml:"meta"`
	Hidden bool `json:"-" yaml:"-"`
	// contains filtered or unexported fields
}

func (*Command) AdditionalHelp 

func (cmd *Command) AdditionalHelp(printLinks bool) *string

func (*Command) FlagSet 

func (cmd *Command) FlagSet() *pflag.FlagSet

func (*Command) FullName 

func (cmd *Command) FullName() string

func (*Command) HasAdditionalHelp 

func (cmd *Command) HasAdditionalHelp() bool

func (*Command) HelpRenderer 

func (cmd *Command) HelpRenderer(globalOptions Options) func(cc *cobra.Command, args []string)

func (*Command) IsRoot 

func (cmd *Command) IsRoot() bool

func (*Command) Name 

func (cmd *Command) Name() string

func (*Command) ParseInput 

func (cmd *Command) ParseInput(cc *cobra.Command, args []string) error

func (*Command) ResolveTemplate 

func (cmd *Command) ResolveTemplate(templateString string, currentValue string) (string, error)

func (*Command) Run 

func (cmd *Command) Run(cc *cobra.Command, args []string) error

func (*Command) SetBindings 

func (cmd *Command) SetBindings() *Command

func (*Command) SetCobra 

func (cmd *Command) SetCobra(cc *cobra.Command)

func (*Command) ShowHelp 

func (cmd *Command) ShowHelp(globalOptions Options, _ []string) ([]byte, error)

func (*Command) Validate 

func (cmd *Command) Validate() (report map[string]int)

type CompletionFunc 

type CompletionFunc func(cmd *Command, currentValue string, config string) (values []string, flag cobra.ShellCompDirective, err error)

type HelpFunc 

type HelpFunc func(printLinks bool) string

type Option 

type Option struct {
	// Type represents the type of value expected to be provided for this option.
	Type ValueType `json:"type" yaml:"type" validate:"omitempty,oneof=string bool int"`
	// Description is a required field that show up during completions and help.
	Description string `json:"description" yaml:"description" validate:"required"`
	// Default value for this option, if none provided.
	Default any `json:"default,omitempty" yaml:"default,omitempty"`
	// ShortName When set, enables representing this Option as a short flag (-x).
	ShortName string `json:"short-name,omitempty" yaml:"short-name,omitempty"` // nolint:tagliatelle
	// Values denote the source for completion/validation values of this option.
	Values *ValueSource `json:"values,omitempty" yaml:"values,omitempty" validate:"omitempty"`
	// Repeated options may be specified more than once.
	Repeated bool `json:"repeated" yaml:"repeated" validate:"omitempty"`
	// Command references the Command this Option is defined for.
	Command *Command `json:"-" yaml:"-" validate:"-"`
	// contains filtered or unexported fields
}

Option represents a command line flag.

func (*Option) CompletionFunction 

func (opt *Option) CompletionFunction(cmd *cobra.Command, args []string, toComplete string) (values []string, flag cobra.ShellCompDirective)

CompletionFunction is called by cobra when asked to complete an option.

func (*Option) IsKnown 

func (opt *Option) IsKnown() bool

IsKnown tells if the option was provided by the user.

func (*Option) Repeats added in v0.3.0 

func (opt *Option) Repeats() bool

func (*Option) Resolve 

func (opt *Option) Resolve(currentValue string) (values []string, flag cobra.ShellCompDirective, err error)

Resolve returns autocomplete values for an option.

func (*Option) ToString 

func (opt *Option) ToString() string

Returns a string representation of this Option's resolved value.

func (*Option) ToValue 

func (opt *Option) ToValue() any

Returns the resolved value for an option.

func (*Option) Validate 

func (opt *Option) Validate(name string) error

Validate validates the provided value if a value source.

func (*Option) Validates 

func (opt *Option) Validates() bool

Validates tells if the user-supplied value needs validation.

type Options 

type Options map[string]*Option

Options is a map of name to Option.

func (*Options) AllKnown 

func (opts *Options) AllKnown() map[string]any

AllKnown returns a map of option names to their resolved values.

func (*Options) AllKnownStr 

func (opts *Options) AllKnownStr() map[string]string

AllKnownStr returns a map of option names to their stringified values.

func (*Options) AreValid 

func (opts *Options) AreValid() error

AreValid tells if these options are all valid.

func (*Options) Parse 

func (opts *Options) Parse(supplied *pflag.FlagSet)

Parse populates values with those supplied in the provided pflag.Flagset.

type SourceCommand 

type SourceCommand struct {
	Path []string
	Args string
}

type ValueSource 

type ValueSource struct {
	// Directories prompts for directories with the given prefix.
	Directories *string `json:"dirs,omitempty" yaml:"dirs,omitempty" validate:"omitempty,excluded_with=Command Files Func Script Static"`
	// Files prompts for files with the given extensions
	Files *[]string `json:"files,omitempty" yaml:"files,omitempty" validate:"omitempty,excluded_with=Command Func Directories Script Static"`
	// Script runs the provided command with `bash -c "$script"` and returns an option for every line of stdout.
	Script string `json:"script,omitempty" yaml:"script,omitempty" validate:"omitempty,excluded_with=Command Directories Files Func Static"`
	// Static returns the given list.
	Static *[]string `json:"static,omitempty" yaml:"static,omitempty" validate:"omitempty,excluded_with=Command Directories Files Func Script"`
	// Command runs a subcommand and returns an option for every line of stdout.
	Command *SourceCommand `json:"command,omitempty" yaml:"command,omitempty" validate:"omitempty,excluded_with=Directories Files Func Script Static"`
	// Func runs a function
	Func CompletionFunc `json:"-" yaml:"-" validate:"omitempty,excluded_with=Command Directories Files Script Static"`
	// Timeout is the maximum amount of time we will wait for a Script, Command, or Func before giving up on completions/validations.
	Timeout int `json:"timeout,omitempty" yaml:"timeout,omitempty" validate:"omitempty,excluded_with=Directories Files Static"`
	// Suggestion if provided will only suggest autocomplete values but will not perform validation of a given value
	Suggestion bool `json:"suggest-only" yaml:"suggest-only" validate:"omitempty"` // nolint:tagliatelle
	// SuggestRaw if provided the shell will not add a space after autocompleting
	SuggestRaw bool `json:"suggest-raw" yaml:"suggest-raw" validate:"omitempty"` // nolint:tagliatelle
	// contains filtered or unexported fields
}

ValueSource represents the source for an auto-completed and/or validated option/argument.

func (*ValueSource) Resolve 

func (vs *ValueSource) Resolve(currentValue string) (values []string, flag cobra.ShellCompDirective, err error)

Resolve returns the values for autocomplete and validation.

func (*ValueSource) UnmarshalYAML 

func (vs *ValueSource) UnmarshalYAML(node *yaml.Node) error

func (*ValueSource) Validates 

func (vs *ValueSource) Validates() bool

Validates tells if a value needs to be validated.

type ValueType 

type ValueType string

ValueType represent the kinds of or option. 

const (
	// ValueTypeDefault is the empty string, maps to ValueTypeString.
	ValueTypeDefault ValueType = ""
	// ValueTypeString a value treated like a string.
	ValueTypeString ValueType = "string"
	// ValueTypeBoolean is a value treated like a boolean.
	ValueTypeBoolean ValueType = "bool"
	// ValueTypeBoolean is a value treated like an integer.
	ValueTypeInt ValueType = "int"
)

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.