cmd

Documentation

Overview

Package cmd contains helper abstractions for working with the CLI parser.

Index

• Variables
• func ArgsIsHelpJSON(args []string) bool
• func Content(flagval string) string
• func ContextHasHelpFlag(ctx *kingpin.ParseContext) bool
• func DisplayServiceID(sid, flag string, s manifest.Source, out io.Writer)
• func GetActiveVersion(vs []*fastly.Version) (*fastly.Version, error)
• func GetSpecifiedVersion(vs []*fastly.Version, version string) (*fastly.Version, error)
• func IntToBool(i int) bool
• func IsCompletion(args []string) bool
• func IsCompletionScript(args []string) bool
• func IsGlobalFlagsOnly(args []string) bool
• func IsHelpFlagOnly(args []string) bool
• func IsHelpOnly(args []string) bool
• func ServiceDetails(opts ServiceDetailsOpts) (serviceID string, serviceVersion *fastly.Version, err error)
• func ServiceID(serviceName OptionalServiceNameID, data manifest.Data, client api.Interface, ...) (serviceID string, source manifest.Source, flag string, err error)
• type AutoCloneFlagOpts
• type Base
  • func (b Base) Name() string
  • func (b Base) RegisterAutoCloneFlag(opts AutoCloneFlagOpts)
  • func (b Base) RegisterFlag(opts StringFlagOpts)
  • func (b Base) RegisterFlagBool(opts BoolFlagOpts)
• type BoolFlagOpts
• type Command
  • func Select(name string, commands []Command) (Command, bool)
• type Globals
• type Optional
  • func (o *Optional) Set(e *kingpin.ParseElement, c *kingpin.ParseContext) error
• type OptionalAutoClone
  • func (ac *OptionalAutoClone) Parse(v *fastly.Version, sid string, verbose bool, out io.Writer, ...) (*fastly.Version, error)
• type OptionalBool
• type OptionalCustomerID
  • func (sv *OptionalCustomerID) Parse() error
• type OptionalInt
• type OptionalServiceNameID
  • func (sv *OptionalServiceNameID) Parse(client api.Interface) (serviceID string, err error)
• type OptionalServiceVersion
  • func (sv *OptionalServiceVersion) Parse(sid string, client api.Interface) (*fastly.Version, error)
• type OptionalString
• type OptionalStringSlice
• type OptionalUint
• type OptionalUint8
• type Registerer
• type ServiceDetailsOpts
• type StringFlagOpts

Variables

var (
	FlagCustomerIDName = "customer-id"
	FlagCustomerIDDesc = "Alphanumeric string identifying the customer (falls back to FASTLY_CUSTOMER_ID)"
	FlagJSONName       = "json"
	FlagJSONDesc       = "Render output as JSON"
	FlagServiceIDName  = "service-id"
	FlagServiceIDDesc  = "Service ID (falls back to FASTLY_SERVICE_ID, then fastly.toml)"
	FlagServiceName    = "service-name"
	FlagServiceDesc    = "The name of the service"
	FlagVersionName    = "version"
	FlagVersionDesc    = "'latest', 'active', or the number of a specific version"
)

var PaginationDirection = []string{"ascend", "descend"}

Functions

func ArgsIsHelpJSON

func ArgsIsHelpJSON(args []string) bool

ArgsIsHelpJSON determines whether the supplied command arguments are exactly `help --format=json` or `help --format json`.

func Content

func Content(flagval string) string

Content determines if the given flag value is a file path, and if so read the contents from disk, otherwise presume the given value is the content.

func ContextHasHelpFlag

func ContextHasHelpFlag(ctx *kingpin.ParseContext) bool

ContextHasHelpFlag asserts whether a given kingpin.ParseContext contains a `help` flag.

func DisplayServiceID

func DisplayServiceID(sid, flag string, s manifest.Source, out io.Writer)

DisplayServiceID acquires the Service ID (if provided) and displays both it and its source location.

func GetActiveVersion

func GetActiveVersion(vs []*fastly.Version) (*fastly.Version, error)

GetActiveVersion returns the active service version.

func GetSpecifiedVersion

func GetSpecifiedVersion(vs []*fastly.Version, version string) (*fastly.Version, error)

GetSpecifiedVersion returns the specified service version.

func IntToBool

func IntToBool(i int) bool

IntToBool converts a binary 0|1 to a boolean.

func IsCompletion

func IsCompletion(args []string) bool

IsCompletion determines whether the supplied command arguments are for shell completion (i.e. --completion-bash) that should produce output that the user's shell can utilise for handling autocomplete behaviour.

func IsCompletionScript

func IsCompletionScript(args []string) bool

IsCompletionScript determines whether the supplied command arguments are for shell completion output that is then eval()'ed by the user's shell.

func IsGlobalFlagsOnly

func IsGlobalFlagsOnly(args []string) bool

IsGlobalFlagsOnly indicates if the user called the binary with any permutation order of the globally defined flags.

NOTE: Some global flags accept a value while others do not. The following algorithm takes this into account by mapping the flag to an expected value. For example, --verbose doesn't accept a value so is set to zero.

EXAMPLES:

The following would return false as a command was specified:

args: [--verbose -v --endpoint ... --token ... -t ... --endpoint ... version] 11 total: 10

The following would return true as only global flags were specified:

args: [--verbose -v --endpoint ... --token ... -t ... --endpoint ...] 10 total: 10

func IsHelpFlagOnly

func IsHelpFlagOnly(args []string) bool

IsHelpFlagOnly indicates if the user called `fastly --help [...]`.

func IsHelpOnly

func IsHelpOnly(args []string) bool

IsHelpOnly indicates if the user called `fastly help [...]`.

func ServiceDetails

func ServiceDetails(opts ServiceDetailsOpts) (serviceID string, serviceVersion *fastly.Version, err error)

ServiceDetails returns the Service ID and Service Version.

func ServiceID

func ServiceID(serviceName OptionalServiceNameID, data manifest.Data, client api.Interface, li fsterr.LogInterface) (serviceID string, source manifest.Source, flag string, err error)

ServiceID returns the Service ID and the source of that information.

NOTE: If Service ID not provided then check if Service Name provided and use that information to acquire the Service ID.

Types

type AutoCloneFlagOpts

type AutoCloneFlagOpts struct {
	Action kingpin.Action
	Dst    *bool
}

AutoCloneFlagOpts enables easy configuration of the --autoclone flag defined via the RegisterAutoCloneFlag constructor.

type Base

type Base struct {
	CmdClause *kingpin.CmdClause
	Globals   *config.Data
}

Base is stuff that should be included in every concrete command.

func (Base) Name

func (b Base) Name() string

Name implements the Command interface, and returns the FullCommand from the kingpin.Command that's used to select which command to actually run.

func (Base) RegisterAutoCloneFlag

func (b Base) RegisterAutoCloneFlag(opts AutoCloneFlagOpts)

RegisterAutoCloneFlag defines a --autoclone flag that will cause a clone of the identified service version if it's found to be active or locked.

func (Base) RegisterFlag

func (b Base) RegisterFlag(opts StringFlagOpts)

RegisterFlag defines a flag.

func (Base) RegisterFlagBool

func (b Base) RegisterFlagBool(opts BoolFlagOpts)

RegisterFlagBool defines a boolean flag.

TODO: Use generics support in go 1.18 to remove the need for two functions.

type BoolFlagOpts

type BoolFlagOpts struct {
	Action      kingpin.Action
	Description string
	Dst         *bool
	Name        string
	Required    bool
	Short       rune
}

BoolFlagOpts enables easy configuration of a flag.

type Command

type Command interface {
	Name() string
	Exec(in io.Reader, out io.Writer) error
}

Command is an interface that abstracts over all of the concrete command structs. The Name method lets us select which command should be run, and the Exec method invokes whatever business logic the command should do.

func Select

func Select(name string, commands []Command) (Command, bool)

Select chooses the command matching name, if it exists.

type Globals

type Globals struct {
	Token   string
	Verbose bool
	Client  api.Interface
}

Globals are flags and other stuff that's useful to every command. Globals are passed to each concrete command's constructor as a pointer, and are populated after a call to Parse. A concrete command's Exec method can use any of the information in the globals.

type Optional

type Optional struct {
	WasSet bool
}

Optional models an optional type that consumers can use to assert whether the inner value has been set and is therefore valid for use.

func (*Optional) Set

func (o *Optional) Set(e *kingpin.ParseElement, c *kingpin.ParseContext) error

Set implements kingpin.Action and is used as callback to set that the optional inner value is valid.

type OptionalAutoClone

type OptionalAutoClone struct {
	OptionalBool
}

OptionalAutoClone defines a method set for abstracting the logic required to identify if a given service version needs to be cloned.

func (*OptionalAutoClone) Parse

func (ac *OptionalAutoClone) Parse(v *fastly.Version, sid string, verbose bool, out io.Writer, client api.Interface) (*fastly.Version, error)

Parse returns a service version.

The returned version is either the same as the input argument `v` or it's a cloned version if the input argument was either active or locked.

type OptionalBool

type OptionalBool struct {
	Optional
	Value bool
}

OptionalBool models an optional boolean flag value.

type OptionalCustomerID

type OptionalCustomerID struct {
	OptionalString
}

OptionalCustomerID represents a Fastly customer ID.

func (*OptionalCustomerID) Parse

func (sv *OptionalCustomerID) Parse() error

Parse returns a customer ID either from a flag or from a user defined environment variable (see pkg/env/env.go).

NOTE: Will fallback to FASTLY_CUSTOMER_ID environment variable if no flag value set.

type OptionalInt

type OptionalInt struct {
	Optional
	Value int
}

OptionalInt models an optional int flag value.

type OptionalServiceNameID

type OptionalServiceNameID struct {
	OptionalString
}

OptionalServiceNameID represents a mapping between a Fastly service name and its ID.

func (*OptionalServiceNameID) Parse

func (sv *OptionalServiceNameID) Parse(client api.Interface) (serviceID string, err error)

Parse returns a service ID based off the given service name.

type OptionalServiceVersion

type OptionalServiceVersion struct {
	OptionalString
}

OptionalServiceVersion represents a Fastly service version.

func (*OptionalServiceVersion) Parse

func (sv *OptionalServiceVersion) Parse(sid string, client api.Interface) (*fastly.Version, error)

Parse returns a service version based on the given user input.

type OptionalString

type OptionalString struct {
	Optional
	Value string
}

OptionalString models an optional string flag value.

type OptionalStringSlice

type OptionalStringSlice struct {
	Optional
	Value []string
}

OptionalStringSlice models an optional string slice flag value.

type OptionalUint

type OptionalUint struct {
	Optional
	Value uint
}

OptionalUint models an optional uint flag value.

type OptionalUint8

type OptionalUint8 struct {
	Optional
	Value uint8
}

OptionalUint8 models an optional unit8 flag value.

type Registerer

type Registerer interface {
	Command(name, help string) *kingpin.CmdClause
}

Registerer abstracts over a kingpin.App and kingpin.CmdClause. We pass it to each concrete command struct's constructor as the "parent" into which the command should install itself.

type ServiceDetailsOpts

type ServiceDetailsOpts struct {
	AllowActiveLocked  bool
	AutoCloneFlag      OptionalAutoClone
	APIClient          api.Interface
	Manifest           manifest.Data
	Out                io.Writer
	ServiceNameFlag    OptionalServiceNameID
	ServiceVersionFlag OptionalServiceVersion
	VerboseMode        bool
	ErrLog             fsterr.LogInterface
}

ServiceDetailsOpts provides data and behaviours required by the ServiceDetails function.

type StringFlagOpts

type StringFlagOpts struct {
	Action      kingpin.Action
	Description string
	Dst         *string
	Name        string
	Required    bool
	Short       rune
}

StringFlagOpts enables easy configuration of a flag.