plugin

Documentation

Overview

Package plugin provides types and functions common among plugins.

See examples in "github.com/IBM-Cloud/ibm-cloud-cli-sdk/plugin_examples".

Index

• func Start(plugin Plugin)
• func StartWithArgs(plugin Plugin, args []string)
• type CFContext
• type Command
  • func (c Command) NameAndAliases() []string
• type Flag
• type Namespace
  • func (n Namespace) NameAndAliases() []string
• type Plugin
• type PluginConfig
• type PluginConfigInvalidTypeError
  • func (e PluginConfigInvalidTypeError) Error() string
• type PluginContext
  • func InitPluginContext(pluginName string) PluginContext
• type PluginMetadata
  • func (p PluginMetadata) NameAndAliases() []string
• type Stage
• type VersionType
  • func (v VersionType) String() string

Functions

func Start

func Start(plugin Plugin)

Start starts the plugin.

func StartWithArgs

func StartWithArgs(plugin Plugin, args []string)

StartWithArgs starts the plugin with the given arguments.

Types

type CFContext

type CFContext interface {
	// APIVersion returns the cloud controller API version
	APIVersion() string

	// APIEndpoint returns the Cloud Foundry API endpoint
	APIEndpoint() string

	// HasAPIEndpoint returns whether a Cloud Foundry API endpoint is set
	HasAPIEndpoint() bool

	//DopplerEndpoint returns the Doppler endpoint
	DopplerEndpoint() string

	// UAAEndpoint returns endpoint of UAA token service
	UAAEndpoint() string

	// ISLoggedIn returns if a user has logged into the cloudfoundry instance
	IsLoggedIn() bool

	// Username returns the name of the logged in user
	Username() string

	// UserEmail returns the Email of the logged in user
	UserEmail() string

	// UserGUID returns the GUID of the logged in user
	UserGUID() string

	// UAAToken returns the UAA access token
	// If the token is outdated, call RefreshUAAToken to refresh it
	UAAToken() string

	// UAARefreshToken return the UAA refreshed token
	UAARefreshToken() string

	// RefreshUAAToken refreshes and returns the UAA access token
	RefreshUAAToken() (string, error)

	// CurrentOrganization returns the targeted organization
	CurrentOrganization() models.OrganizationFields

	// HasTargetedOrganization returns if an organization has been targeted
	HasTargetedOrganization() bool

	// CurrentSpace returns the targeted space
	CurrentSpace() models.SpaceFields

	// HasTargetedSpace returns if a space has been targeted
	HasTargetedSpace() bool
}

CFContext is a context of the targeted CloudFoundry environment into plugin

type Command

type Command struct {
	Namespace   string   // full qualified name of the command's namespace
	Name        string   // name of the command
	Alias       string   // Deprecated: use Aliases instead.
	Aliases     []string // command aliases
	Description string   // short description of the command
	Usage       string   // usage detail to be displayed in command help
	Flags       []Flag   // command options
	Hidden      bool     // true to hide the command in help text
	Stage       Stage    // stage of the command
}

Command describes the metadata of a plugin command

func (Command) NameAndAliases

func (c Command) NameAndAliases() []string

type Flag

type Flag struct {
	Name        string // name of the option
	Description string // description of the option
	HasValue    bool   // whether the option requires a value or not
	Hidden      bool   // true to hide the option in command help
}

Flag describes a command option

type Namespace

type Namespace struct {
	ParentName  string   // full qualified name of the parent namespace
	Name        string   // base name
	Aliases     []string // aliases
	Description string   // description of the namespace
	Stage       Stage    // stage of the commands in the namespace
}

Namespace represents a category of commands that have similar functionalities. A command under a namespace is run using 'bx [namespace] [command]'.

Some namespaces are predefined by Bluemix CLI and sharable among plugins; others are non-shared and defined in each plugin. The Plugin can reference a predefined namespace or define a non-shared namespace of its own.

Namespace also supports hierarchy. For example, namespace 'A' can have a sub namespace 'B'. And the full qualified name of namespace B is 'A B'.

func (Namespace) NameAndAliases

func (n Namespace) NameAndAliases() []string

type Plugin

type Plugin interface {
	// GetMetadata returns the metadata of the plugin.
	GetMetadata() PluginMetadata

	// Run runs the plugin with given plugin context and arguments.
	//
	// Note: the first arg in args is a command or alias no matter the command
	// has namespace or not. To get the namespace, call
	// PluginContext.CommandNamespace.
	Run(c PluginContext, args []string)
}

Plugin is an interface for Bluemix CLI plugins.

type PluginConfig

type PluginConfig interface {
	// Get returns the value for a given key.
	// The value can be float64, bool, string, []interface{},
	// map[string]interface or nil if the key not exist.
	Get(key string) interface{}

	// GetWithDefault returns the value for a given key, or defaultVal if the
	// key not exist.
	GetWithDefault(key string, defaultVal interface{}) interface{}

	// GetString returns string value for a given key.
	GetString(key string) (string, error)

	// GetStringWithDefault returns string value for a given key or defaultVal
	// if the key not exist.
	GetStringWithDefault(key string, defaultVal string) (string, error)

	// GetBool returns boolean value for a given key.
	// If the value is a string, it attempts to convert it to bool.
	GetBool(key string) (bool, error)

	// GetBoolWithDefault returns boolean value for a given key or defaultVal if
	// the key not exist.
	GetBoolWithDefault(key string, defaultVal bool) (bool, error)

	// GetInt returns int value for a given key.
	// If the value is float or string, attempts to convert it to int.
	GetInt(key string) (int, error)

	// GetIntWithDefault returns int value for a given key or defaultVal if the
	// key not exist.
	// If the value is float or string, it attempts to convert it to int.
	GetIntWithDefault(key string, defaultVal int) (int, error)

	// GetFloat returns float64 value for a given key.
	// If the value is int or string, it attempts to convert it to float64.
	GetFloat(key string) (float64, error)

	// GetFloatWithDefault returns float64 value for a given key or defaultVal
	// if the key not exist.
	// If the value is int or string, it attempts to convert it to float64.
	GetFloatWithDefault(key string, defaultVal float64) (float64, error)

	// GetStringSlice return string slice for a given key.
	// If the key not exists, return empty string slice.
	GetStringSlice(key string) ([]string, error)

	// GetIntSlice return string slice for a given key.
	GetIntSlice(key string) ([]int, error)

	// GetFloatSlice return string slice for a given key.
	GetFloatSlice(key string) ([]float64, error)

	// GetStringMap return map[string]interface{} for a given key.
	GetStringMap(key string) (map[string]interface{}, error)

	// GetStringMap return map[string]string for a given key.
	GetStringMapString(key string) (map[string]string, error)

	// Exists checks whether the value for a given key exists or not.
	Exists(key string) bool

	// Set sets the value for a given key.
	Set(string, interface{}) error

	// Erase delete a given key.
	Erase(key string) error
}

PluginConfig defines methods to access plug-in's private configuration stored in a JSON format.

type PluginConfigInvalidTypeError

type PluginConfigInvalidTypeError struct {
	Key          string
	ExpectedType string
	Value        interface{}
}

PluginConfigInvalidTypeError describes the value for a given key in plugin configuration was not appropriate for a value of a specific type.

func (PluginConfigInvalidTypeError) Error

func (e PluginConfigInvalidTypeError) Error() string

type PluginContext

type PluginContext interface {
	// APIEndpoint returns the targeted API endpoint of IBM Cloud
	APIEndpoint() string

	// HasAPIEndpoint() returns whether an IBM Cloud has been targeted, does not
	// necessarily mean the user has targeted a CF environment.
	// Call HasTargetedCF() to return whether a CF environment has been targeted.
	HasAPIEndpoint() bool

	// IsPrivateEndpointEnabled returns whether use of the private endpoint has been chosen
	IsPrivateEndpointEnabled() bool

	// ConsoleEndpoint returns console's public endpoint if api endpoint is public, or returns
	// private endpoint if api endpoint is private.
	ConsoleEndpoint() string

	// ConsoleEndpoints returns both the public and private endpoint of console.
	ConsoleEndpoints() models.Endpoints

	// IAMEndpoint returns IAM's public endpoint if api endpoint is public, or returns private
	// endpoint if api endpoint is private.
	IAMEndpoint() string

	// IAMEndpoints returns both the public and private endpoint of IAM.
	IAMEndpoints() models.Endpoints

	// GetEndpoint is a utility method to return private or public endpoint for a requested service.
	// It supports public cloud only. For non public clouds, plugin needs its own way to determine endpoint.
	GetEndpoint(endpoints.Service) (string, error)

	// CloudName returns the name of the target cloud
	CloudName() string

	// CloudType returns the type of the target cloud (like 'public',
	// 'dedicated' etc)
	CloudType() string

	// Region returns the targeted region
	CurrentRegion() models.Region

	// HasTargetedRegion() return whether a region is targeted
	HasTargetedRegion() bool

	// IAMToken returns the IAM access token
	IAMToken() string

	// IAMRefreshToken returns the IAM refresh token
	IAMRefreshToken() string

	// RefreshIAMToken refreshes and returns the IAM access token
	RefreshIAMToken() (string, error)

	// UserEmail returns the Email of the logged in user
	UserEmail() string

	// IsLoggedIn returns if a user has logged into IBM cloud, does not
	// necessarily mean the user has logged in a CF environment.
	// Call CF().IsLoggedIn() to return whether user has been logged into the CF environment.
	IsLoggedIn() bool

	// IsLoggedInWithServiceID returns if a user has logged into IBM cloud using service ID.
	IsLoggedInWithServiceID() bool

	// IMSAccountID returns ID of the IMS account linked to the targeted BSS
	// account
	IMSAccountID() string

	// Account returns the targeted a BSS account
	CurrentAccount() models.Account

	// HasTargetedAccount returns whether an account has been targeted
	HasTargetedAccount() bool

	// ResourceGroup returns the targeted resource group
	CurrentResourceGroup() models.ResourceGroup

	// HasTargetedResourceGroup returns whether a resource group has been targeted
	HasTargetedResourceGroup() bool

	// CF returns the context of the targeted CloudFoundry environment
	CF() CFContext

	// HasTargetedCF returns whether a CloudFoundry environment has been targeted
	HasTargetedCF() bool

	// HasTargetedCF returns whether a enterprise CloudFoundry instance has been targeted
	HasTargetedCFEE() bool

	// CFEEEnvID returns ID of targeted CFEE environment
	CFEEEnvID() string

	// HasTargetedCF returns whether a public CloudFoundry instance has been targeted
	HasTargetedPublicCF() bool

	// Locale returns user specified locale
	Locale() string

	// Trace returns user specified trace setting.
	// The value is "true", "false" or path of the trace output file.
	Trace() string

	// ColorEnabled returns whether terminal displays color or not
	ColorEnabled() string

	// IsSSLDisabled returns whether skipping SSL validation or not
	IsSSLDisabled() bool

	// PluginDirectory returns the installation directory of the plugin
	PluginDirectory() string

	// HTTPTimeout returns a timeout for HTTP Client
	HTTPTimeout() int

	// VersionCheckEnabled() returns whether checking for update is performmed
	VersionCheckEnabled() bool

	// PluginConfig returns the plugin specific configuarion
	PluginConfig() PluginConfig

	// CommandNamespace returns the name of the parsed namespace
	CommandNamespace() string

	// CLIName returns binary name of the Bluemix CLI that is invoking the plugin
	CLIName() string
}

PluginContext is a Bluemix CLI context passed to plugin's Run method. It carries service endpoints info, login session, user configuration, plugin configuration and provides utility methods.

func InitPluginContext

func InitPluginContext(pluginName string) PluginContext

InitPluginContext initializes a plugin context for a given plugin

type PluginMetadata

type PluginMetadata struct {
	Name          string      // name of the plugin
	Aliases       []string    // aliases of the plugin
	Version       VersionType // version of the plugin
	MinCliVersion VersionType // minimal version of CLI required by the plugin
	Namespaces    []Namespace // list of namespaces provided by the plugin
	Commands      []Command   // list of commands provided by the plugin

	// SDKVersion is SDK version used by the plugin.
	// It is set by the plugin framework to check SDK compatibility with the CLI.
	SDKVersion VersionType

	// If DelegateBashCompletion is true, plugin command's completion is handled by plugin.
	// The CLI will invoke '<plugin_binary> SendCompletion <args>'
	DelegateBashCompletion bool

	// Whether the plugin supports private endpoint
	PrivateEndpointSupported bool
}

PluginMetadata describes metadata of a plugin.

func (PluginMetadata) NameAndAliases

func (p PluginMetadata) NameAndAliases() []string

type Stage

type Stage string

Stage decribes the stage of the namespace or command and will be shown in the help text

const (
	StageExperimental Stage = "experimental"
	StageBeta         Stage = "beta"
	StageDeprecated   Stage = "deprecated"
)

Valid stages

type VersionType

type VersionType struct {
	Major int // major version
	Minor int // minimal version
	Build int // build number
}

VersionType describes the version info

func (VersionType) String

func (v VersionType) String() string