layers

package
v0.2.79 Latest Latest
Warning

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

 Go to latest Published: May 10, 2023 License: MIT Imports: 9 Imported by: 52

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AddFlagGroupToCobraCommand 

func AddFlagGroupToCobraCommand(
	cmd *cobra.Command,
	id string,
	name string,
	flags []*parameters.ParameterDefinition,
	prefix string,
)

AddFlagGroupToCobraCommand adds a flag group to a cobra command. This is done by adding a set of annotations to the command:

  • glazed:flag-group-order: a comma-separated list of flag group IDs in the order they should be displayed
  • glazed:flag-group-count: the number of flag groups
  • glazed:flag-group:<id>:<name> - a list of the flag names in the group
  • glazed:flag-group-prefix:<id> - the prefix to use for the group

func SetFlagGroupOrder 

func SetFlagGroupOrder(cmd *cobra.Command, order []string)

Types

type CommandFlagGroupUsage 

type CommandFlagGroupUsage struct {
	LocalGroupUsages     []*FlagGroupUsage
	InheritedGroupUsages []*FlagGroupUsage
}

CommandFlagGroupUsage is used to render the flags for an entire command. This gets parsed at rendering time, and passed along the command to the usage or help template. Flags that are not assigned to any group are passed as the "" group, with the name "Other flags".

func ComputeCommandFlagGroupUsage 

func ComputeCommandFlagGroupUsage(c *cobra.Command) *CommandFlagGroupUsage

ComputeCommandFlagGroupUsage is used to compute the flag groups to be shown in the usage help function.

It is a fairly complex function that gathers all LocalFlags() and InheritedFlags() from the cobra backend. It then iterated over the FlagGroups that have been added through layers usually.

func (*CommandFlagGroupUsage) String 

func (c *CommandFlagGroupUsage) String() string

type FlagGroup 

type FlagGroup struct {
	ID     string
	Name   string
	Prefix string
	Flags  []string
	Order  int
}

FlagGroup is a group of flags that can be added to a cobra command. While we mostly deal with ParameterDefinitions, this uses strings because it can be applied to any cobra flag in general.

It limits us in the sense that we can't just get the full ParameterDefinition here, but at least we can format our help a little bit more nicely.

NOTE(manuel, 2023-02-20) This doesn't allow for hierarchical flag groups yet. Let's see how this feels overall, and if this is something we want to add later on. This is useful I think because subsystems such as glaze already pull in so many flags, and it could be used in conjunction with renaming the actual flags used on the CLI as more colisions are prone to happen.

func GetFlagGroups 

func GetFlagGroups(cmd *cobra.Command) []*FlagGroup

GetFlagGroups returns a list of flag groups for the given command. It does so by gathering all parents flag groups and then checking for cobra Annotations of the form `glazed:flag-group:<id>:<name>`.

The order of the groups is determined by the order of the ids in the `glazed:flag-group-order` annotation.

Finally, the `glazed:flag-group-prefix:<id>:<prefix>` annotation is used to determine the prefix for the group.

type FlagGroupUsage 

type FlagGroupUsage struct {
	Name          string
	FlagUsages    []*FlagUsage
	MaxFlagLength int
}

FlagGroupUsage is used to render the help for a flag group. It consists of the group Name for rendering purposes, and a single string per flag in the group

func (*FlagGroupUsage) AddFlagUsage 

func (f *FlagGroupUsage) AddFlagUsage(flag *FlagUsage)

func (*FlagGroupUsage) String 

func (f *FlagGroupUsage) String() string

type FlagUsage 

type FlagUsage struct {
	ShortHand  string
	Long       string
	FlagString string
	Help       string
	Default    string
}

FlagUsage is the structured information we want to show at help time. Instead of rendering the full time, we leave how these things are formatted all the way to the end, because for example aligning strings can only be done at runtime since we don't know which other flags might have been added to the one group.

type ParameterLayer 

type ParameterLayer interface {
	AddFlag(flag *parameters.ParameterDefinition)
	GetParameterDefinitions() map[string]*parameters.ParameterDefinition

	InitializeParameterDefaultsFromStruct(s interface{}) error

	GetName() string
	GetSlug() string
	GetDescription() string
	GetPrefix() string
}

ParameterLayer is a struct that is used by one specific functionality layer to group and describe all the parameter definitions that it uses. It also provides a location for a name, slug and description to be used in help pages.

type ParameterLayerImpl 

type ParameterLayerImpl struct {
	Name        string                            `yaml:"name"`
	Slug        string                            `yaml:"slug"`
	Description string                            `yaml:"description"`
	Prefix      string                            `yaml:"prefix"`
	Flags       []*parameters.ParameterDefinition `yaml:"flags,omitempty"`
}

ParameterLayerImpl is a straight forward simple implementation of ParameterLayer that can easily be reused in more complex implementations.

func NewParameterLayer 

func NewParameterLayer(slug string, name string, options ...ParameterLayerOptions) (*ParameterLayerImpl, error)

func NewParameterLayerFromYAML 

func NewParameterLayerFromYAML(s []byte, options ...ParameterLayerOptions) (*ParameterLayerImpl, error)

func (*ParameterLayerImpl) AddFlag 

func (p *ParameterLayerImpl) AddFlag(flag *parameters.ParameterDefinition)

func (*ParameterLayerImpl) AddFlagsToCobraCommand 

func (p *ParameterLayerImpl) AddFlagsToCobraCommand(cmd *cobra.Command) error

AddFlagsToCobraCommand adds all flags of the layer to the given Cobra command. It also creates a flag group representing the layer and adds it to the command. If the layer has a prefix, the flags are added with that prefix.

func (*ParameterLayerImpl) GetDescription added in v0.2.13 

func (p *ParameterLayerImpl) GetDescription() string

func (*ParameterLayerImpl) GetName added in v0.2.13 

func (p *ParameterLayerImpl) GetName() string

func (*ParameterLayerImpl) GetParameterDefinitions 

func (p *ParameterLayerImpl) GetParameterDefinitions() map[string]*parameters.ParameterDefinition

GetParameterDefinitions returns a map that maps all parameters (flags and arguments) to their name. I'm not sure if this is worth caching, but if we hook this up like something like a lambda that might become more relevant.

func (*ParameterLayerImpl) GetParameterValuesFromMap added in v0.2.54 

func (p *ParameterLayerImpl) GetParameterValuesFromMap(m map[string]interface{}) (map[string]interface{}, error)

func (*ParameterLayerImpl) GetPrefix added in v0.2.18 

func (p *ParameterLayerImpl) GetPrefix() string

func (*ParameterLayerImpl) GetSlug added in v0.2.13 

func (p *ParameterLayerImpl) GetSlug() string

func (*ParameterLayerImpl) InitializeParameterDefaultsFromParameters added in v0.2.19 

func (p *ParameterLayerImpl) InitializeParameterDefaultsFromParameters(
	ps map[string]interface{},
) error

func (*ParameterLayerImpl) InitializeParameterDefaultsFromStruct added in v0.2.13 

func (p *ParameterLayerImpl) InitializeParameterDefaultsFromStruct(defaults interface{}) error

InitializeParameterDefaultsFromStruct initializes the `ParameterDefinition` of the layer, which are often defined at compile time and loaded from a YAML file, with fresh ones from the struct. This is in some ways the opposite of `InitializeStructFromParameterDefaults`. The struct fields of `defaults` with a struct tag of `glazed.parameter` are used to initialize the `ParameterDefinition` with a matching name. If no matching `ParameterDefinition` is found, an error is returned.

func (*ParameterLayerImpl) InitializeStructFromParameterDefaults added in v0.2.13 

func (p *ParameterLayerImpl) InitializeStructFromParameterDefaults(s interface{}) error

func (*ParameterLayerImpl) LoadFromYAML 

func (p *ParameterLayerImpl) LoadFromYAML(s []byte) error

func (*ParameterLayerImpl) ParseFlagsFromCobraCommand 

func (p *ParameterLayerImpl) ParseFlagsFromCobraCommand(cmd *cobra.Command) (map[string]interface{}, error)

ParseFlagsFromCobraCommand parses the flags of the layer from the given Cobra command. If the layer has a prefix, the flags are parsed with that prefix (meaning, the prefix is stripped from the flag names before they are added to the returned map).

This will return a map containing the value (or default value) of each flag of the layer.

func (*ParameterLayerImpl) UnmarshalYAML 

func (p *ParameterLayerImpl) UnmarshalYAML(unmarshal func(interface{}) error) error

type ParameterLayerOptions 

type ParameterLayerOptions func(*ParameterLayerImpl) error

func WithDefaults added in v0.2.18 

func WithDefaults(s interface{}) ParameterLayerOptions

func WithDescription 

func WithDescription(description string) ParameterLayerOptions

func WithFlags 

func WithFlags(flags ...*parameters.ParameterDefinition) ParameterLayerOptions

func WithPrefix added in v0.2.18 

func WithPrefix(prefix string) ParameterLayerOptions

type ParameterLayerParser added in v0.2.18 

type ParameterLayerParser interface {
	RegisterParameterLayer(ParameterLayer) (ParameterLayerParserFunc, error)
}

ParameterLayerParser is a type for anything that can parse a layer. As mentioned above, this is a bit experimental and might actually not be necessary as an interface.

type ParameterLayerParserFunc added in v0.2.18 

type ParameterLayerParserFunc func() (*ParsedParameterLayer, error)

ParameterLayerParserFunc is a type meant to represent closures capturing some "complex" process by which a ParsedParameterLayer can be produced, for example parsing a layer out of a cobra.Command after flags were registered (see CobraParser).

NOTE(manuel, 2023-03-17) This seems a bit overengineered, but the thinking behind it is that depending on the frontend that a function provides (cobra, another CLI framework, REST, microservices), there would be a parser function that can extract the values for a specific layer. Those could potentially also be overriden by middlewares to do things like validation or masking. This is not really used right now (I think), and more of an experiment that will be worth revisiting.

type ParsedParameterLayer added in v0.2.18 

type ParsedParameterLayer struct {
	Layer      ParameterLayer
	Parameters map[string]interface{}
}

ParsedParameterLayer is the result of "parsing" input data using a ParameterLayer specification. For example, it could be the result of parsing cobra command flags, or a JSON body, or HTTP query parameters.

func (*ParsedParameterLayer) Clone added in v0.2.19 

func (ppl *ParsedParameterLayer) Clone() *ParsedParameterLayer

Clone returns a copy of the parsedParameterLayer with a fresh Parameters map. However, neither the Layer nor the Parameters are deep copied.

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.