plugin

package
v1.4.6 Latest Latest
Warning

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

 Go to latest Published: Nov 21, 2024 License: Apache-2.0 Imports: 20 Imported by: 16

Documentation

Overview

Package plugin provides functions to create new CLI plugins.

Index

Constants

View Source 
const (
	// NativePluginCompletion indicates command line completion is determined using the built in
	// cobra.Command __complete mechanism.
	NativePluginCompletion PluginCompletionType = iota
	// StaticPluginCompletion indicates command line completion will be done by using a statically
	// defined list of options.
	StaticPluginCompletion
	// DynamicPluginCompletion indicates command line completion will be retrieved from the plugin
	// at runtime.
	DynamicPluginCompletion

	// RunCmdGroup are commands associated with Tanzu Run.
	RunCmdGroup CmdGroup = "Run"

	// ManageCmdGroup are commands associated with Tanzu Manage.
	ManageCmdGroup CmdGroup = "Manage"

	// BuildCmdGroup are commands associated with Tanzu Build.
	BuildCmdGroup CmdGroup = "Build"

	// ObserveCmdGroup are commands associated with Tanzu Observe.
	ObserveCmdGroup CmdGroup = "Observe"

	// SystemCmdGroup are system commands.
	SystemCmdGroup CmdGroup = "System"

	// TargetCmdGroup are various target commands.
	TargetCmdGroup CmdGroup = "Target"

	// VersionCmdGroup are version commands.
	VersionCmdGroup CmdGroup = "Version"

	// AdminCmdGroup are admin commands.
	AdminCmdGroup CmdGroup = "Admin"

	// TestCmdGroup is the test command group.
	TestCmdGroup CmdGroup = "Test"

	// ExtraCmdGroup is the extra command group.
	ExtraCmdGroup CmdGroup = "Extra"
)
View Source 
const CmdTemplate = `` /* 1897-byte string literal not displayed */

CmdTemplate is the template for plugin commands. Deprecated: This variable is deprecated.

View Source 
const DefaultDocsDir = "docs/cli/commands"

DefaultDocsDir is the base docs directory

View Source 
const ErrorDocsOutputFolderNotExists = "" /* 137-byte string literal not displayed */
View Source 
const (
	PluginRuntimeModulePath = "github.com/vmware-tanzu/tanzu-plugin-runtime"
)

Variables

View Source 
var TemplateFuncs = template.FuncMap{
	"printHelp": printHelp,

	"rpad":                    component.Rpad,
	"bold":                    component.Bold,
	"underline":               component.Underline,
	"trimTrailingWhitespaces": component.TrimRightSpace,
	"beginsWith":              component.BeginsWith,
}

TemplateFuncs are the template usage funcs.

View Source 
var UsageFunc = func(c *cobra.Command) error {
	t, err := template.New("usage").Funcs(TemplateFuncs).Parse(cmdTemplate)
	if err != nil {
		return err
	}
	return t.Execute(os.Stdout, c)
}

UsageFunc is the usage func for a plugin.

Functions

func ApplyDefaultConfig 

func ApplyDefaultConfig(p *PluginDescriptor)

ApplyDefaultConfig applies default configurations to plugin descriptor.

func SyncPluginsForContextType added in v1.1.0 

func SyncPluginsForContextType(contextType types.ContextType, opts ...CommandOptions) (string, error)

SyncPluginsForContextType will attempt to install plugins required by the active Context of the provided contextType. This is most useful for any plugin implementation which creates a new Context or updates an existing one as part of its operation, and prefers that the plugins appropriate for the Context are immediately available for use.

Note: This API is considered EXPERIMENTAL. Both the function's signature and implementation are subjected to change/removal if an alternative means to provide equivalent functionality can be introduced.

By default this API will write to os.Stdout and os.Stderr. To write the logs to different output and error streams as part of the plugin sync command invocation, configure CommandOptions as part of the parameters.

Example: 

var outBuf bytes.Buffer
var errBuf bytes.Buffer
SyncPluginsForContextType(types.ContextTypeK8s, WithOutputWriter(&outBuf), WithErrorWriter(&errBuf))

func SyncPluginsForTarget deprecated added in v0.90.0 

func SyncPluginsForTarget(target types.Target, opts ...CommandOptions) (string, error)

SyncPluginsForTarget will attempt to install plugins required by the active Context of the provided target. This is most useful for any plugin implementation which creates a new Context or updates an existing one as part of its operation, and prefers that the plugins appropriate for the Context are immediately available for use.

Note: This API is considered EXPERIMENTAL. Both the function's signature and implementation are subjected to change/removal if an alternative means to provide equivalent functionality can be introduced.

By default this API will write to os.Stdout and os.Stderr. To write the logs to different output and error streams as part of the plugin sync command invocation, configure CommandOptions as part of the parameters.

Example: 

var outBuf bytes.Buffer
var errBuf bytes.Buffer
SyncPluginsForTarget(types.TargetK8s, WithOutputWriter(&outBuf), WithErrorWriter(&errBuf))

Deprecated: SyncPluginsForTarget is deprecated. Use SyncPluginsForContextType instead

func ValidatePlugin 

func ValidatePlugin(p *PluginDescriptor) (err error)

ValidatePlugin validates the plugin descriptor.

Types

type CmdGroup 

type CmdGroup string

CmdGroup is a group of CLI commands.

type CommandMapEntry added in v1.3.0 

type CommandMapEntry struct {
	// SourceCommandPath is a space-delimited path to the command relative to
	// the root Command of this plugin, with the root Command's path being ""
	SourceCommandPath string `json:"srcPath" yaml:"srcPath"`
	// DestinationCommandPath is a space-delimited path to the command relative
	// to the root Command of the Tanzu CLI
	DestinationCommandPath string `json:"dstPath" yaml:"dstPath"`
	// By default, the command previously situated at the
	// DestinationCommandPath of the Tanzu CLI, if one exist, will be the one
	// overridden by this entry. If this mapping attempt is intended to override
	// another part of the Tanzu CLI command tree, the override path should be used.
	// Specified as a space-delimited path relative to the Tanzu CLI command tree.
	Overrides string `json:"overrides" yaml:"overrides"`
	// Required when remapping a subcommand of this plugin outside of the
	// plugin's command tree (e.g. when elevating a subcommand to a top level
	// command of the Tanzu CLI). This enables the CLI to provide better help
	// information about the remapped command.
	// Not used for plugin-level mapping. Optional for subcommand mapping in the
	// sense that if unset, the short description of the actual Command at the
	// SourceCommandPath will be used.
	Description string `json:"description" yaml:"description"`
	// Aliases are other text strings used to call the mapped command.
	// Not used for plugin-level mapping. Optional for subcommand mapping in the
	// sense that if unset, the aliases of the actual Command at the
	// SourceCommandPath will be used.
	Aliases []string `json:"aliases,omitempty" yaml:"aliases,omitempty"`
	// RequiredContextType specifies one or more ContextType's that has to be active in order for this
	// mapping to take effect. If unset, this entry's mapping will apply regardless of state of active
	// contexts.
	RequiredContextType []types.ContextType `json:"requiredContextType,omitempty" yaml:"requiredContextType,omitempty"`
}

CommandMapEntry describes how a command or subcommand should be remapped in the Tanzu CLI

type CommandOptions added in v1.0.1 

type CommandOptions func(o *cmdOptions)

func WithErrorWriter added in v1.0.1 

func WithErrorWriter(errWriter io.Writer) CommandOptions

WithErrorWriter specifies the CommandOption for configuring Stderr

func WithNoStderr added in v1.0.1 

func WithNoStderr() CommandOptions

WithNoStderr specifies to ignore stderr

func WithNoStdout added in v1.0.1 

func WithNoStdout() CommandOptions

WithNoStdout specifies to ignore stdout

func WithOutputWriter added in v1.0.1 

func WithOutputWriter(outWriter io.Writer) CommandOptions

WithOutputWriter specifies the CommandOption for configuring Stdout

type Hook 

type Hook func() error

Hook is the mechanism used to define function for plugin hooks

type InvocationContext added in v1.3.0 

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

InvocationContext provides details regarding how a plugin's command is being called by the Tanzu CLI. These details allow the plugin to, among other things, construct proper help information, and learn if the command being invoked is done via a command-level mapping or not.

func GetInvocationContext added in v1.3.0 

func GetInvocationContext() *InvocationContext

GetInvocationContext returns information about how a Tanzu CLI command is invoked (from the CLI's perspective). Note that at the moment a valid InvocationContext is only returned when the invoked plugin command (or its ancestor) has been remapped

func (*InvocationContext) CLIInvocationString added in v1.3.0 

func (ic *InvocationContext) CLIInvocationString() string

func (*InvocationContext) CLIInvocationStringForCommand added in v1.3.0 

func (ic *InvocationContext) CLIInvocationStringForCommand(cmd *cobra.Command) string

CLIInvocationStringForCommand returns the CLI invocation string when cmd was invoked under this invocation context. Invoking "tanzu + (the string returned) as a CLI command would be equivalent to executing cmd with no arguments

func (*InvocationContext) InvokedCommandName added in v1.3.0 

func (ic *InvocationContext) InvokedCommandName() string

func (*InvocationContext) InvokedGroupPath added in v1.3.0 

func (ic *InvocationContext) InvokedGroupPath() string

func (*InvocationContext) MappedSourceCommandPath added in v1.3.0 

func (ic *InvocationContext) MappedSourceCommandPath() string

type Plugin 

type Plugin struct {
	Cmd *cobra.Command
}

Plugin is a Tanzu CLI plugin.

func NewPlugin 

func NewPlugin(descriptor *PluginDescriptor) (*Plugin, error)

NewPlugin creates an instance of Plugin.

func (*Plugin) AddCommands 

func (p *Plugin) AddCommands(commands ...*cobra.Command)

AddCommands adds commands to the plugin.

func (*Plugin) Execute 

func (p *Plugin) Execute() error

Execute executes the plugin.

type PluginCompletionType 

type PluginCompletionType int

PluginCompletionType is the mechanism used for determining command line completion options.

type PluginDescriptor 

type PluginDescriptor struct {
	// Name is the name of the plugin.
	Name string `json:"name" yaml:"name"`

	// Description is the plugin's description.
	Description string `json:"description" yaml:"description"`

	// Target is the target to which plugin is applicable.
	Target types.Target `json:"target" yaml:"target"`

	// Version of the plugin. Must be a valid semantic version https://semver.org/
	Version string `json:"version" yaml:"version"`

	// BuildSHA is the git commit hash the plugin was built with.
	BuildSHA string `json:"buildSHA" yaml:"buildSHA"`

	// Digest is the SHA256 hash of the plugin binary.
	Digest string `json:"digest" yaml:"digest"`

	// Command group for the plugin.
	Group CmdGroup `json:"group" yaml:"group"`

	// DocURL for the plugin.
	DocURL string `json:"docURL" yaml:"docURL"`

	// Hidden tells whether the plugin should be hidden from the help command.
	Hidden bool `json:"hidden,omitempty" yaml:"hidden,omitempty"`

	// CompletionType determines how command line completion will be determined.
	CompletionType PluginCompletionType `json:"completionType" yaml:"completionType"`

	// CompletionArgs contains the valid command line completion values if `CompletionType`
	// is set to `StaticPluginCompletion`.
	CompletionArgs []string `json:"completionArgs,omitempty" yaml:"completionArgs,omitempty"`

	// CompletionCommand is the command to call from the plugin to retrieve a list of
	// valid completion nouns when `CompletionType` is set to `DynamicPluginCompletion`.
	CompletionCommand string `json:"completionCmd,omitempty" yaml:"completionCmd,omitempty"`

	// Aliases are other text strings used to call this command
	Aliases []string `json:"aliases,omitempty" yaml:"aliases,omitempty"`

	// PostInstallHook is function to be run post install of a plugin.
	PostInstallHook Hook `json:"-" yaml:"-"`

	// DefaultFeatureFlags is default featureflags to be configured if missing when invoking plugin
	DefaultFeatureFlags map[string]bool `json:"defaultFeatureFlags,omitempty" yaml:"defaultFeatureFlags,omitempty"`

	// SupportedContextType specifies one or more ContextType that this plugin will specifically apply to.
	// When no context of matching type is active, the command tree specified by this plugin should be omitted.
	// When unset, the plugin does not define any specific opinions on this aspect.
	// EXPERIMENTAL: subject to change prior to the next official minor release
	SupportedContextType []types.ContextType `json:"supportedContextType,omitempty" yaml:"supportedContextType,omitempty"`

	// CommandMap specifies one or more CommandMapEntry's and describes how one
	// or more parts of the plugin's command tree will be remapped in the Tanzu CLI
	// Empty when the plugin does not offer any specific mapping opinions.
	// EXPERIMENTAL: subject to change prior to the next official minor release
	CommandMap []CommandMapEntry `json:"commandMap,omitempty" yaml:"commandMap,omitempty"`
}

PluginDescriptor describes a plugin binary.

Source Files

View all Source files

Directories

Path Synopsis
Package buildinfo holds global variables set at build time to provide information about the plugin build.
 Package buildinfo holds global variables set at build time to provide information about the plugin build.
Package lint provides linters to run against CLI plugins.
 Package lint provides linters to run against CLI plugins.

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.