layers

package
v0.5.13 Latest Latest
Warning

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

 Go to latest Published: May 1, 2024 License: MIT Imports: 11 Imported by: 51

Documentation

Index

Constants

View Source 
const DefaultSlug = "default"
View Source 
const GlobalDefaultSlug = "global-default"

Variables

This section is empty.

Functions

func AddFlagGroupToCobraCommand 

func AddFlagGroupToCobraCommand(
	cmd *cobra.Command,
	id string,
	name string,
	flags *parameters.ParameterDefinitions,
	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 InitializeParameterLayerWithDefaults added in v0.5.9 

func InitializeParameterLayerWithDefaults(
	v ParameterLayer,
	parsedLayer *ParsedLayer,
	options ...parameters.ParseStepOption,
) error

func SetFlagGroupOrder 

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

Types

type BlacklistParameterLayer added in v0.4.36 

type BlacklistParameterLayer struct {
	ParameterLayer
	BlacklistedParameters map[string]interface{}
}

func NewBlacklistParameterLayer added in v0.4.36 

func NewBlacklistParameterLayer(layer ParameterLayer, blacklistedParameters map[string]interface{}) *BlacklistParameterLayer

func (*BlacklistParameterLayer) GetParameterDefinitions added in v0.4.36 

func (l *BlacklistParameterLayer) GetParameterDefinitions() *parameters.ParameterDefinitions

type CobraParameterLayer added in v0.2.18 

type CobraParameterLayer interface {
	ParameterLayer
	// AddLayerToCobraCommand adds all the flags and arguments defined in this layer to the given cobra command.
	AddLayerToCobraCommand(cmd *cobra.Command) error
	ParseLayerFromCobraCommand(cmd *cobra.Command, options ...parameters.ParseStepOption) (*ParsedLayer, error)
}

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. Parameters 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 ErrInvalidParameterLayer added in v0.4.13 

type ErrInvalidParameterLayer struct {
	Name     string
	Expected string
}

func (ErrInvalidParameterLayer) Error added in v0.4.13 

func (e ErrInvalidParameterLayer) Error() 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 {
	Slug          string
	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 {
	AddFlags(flag ...*parameters.ParameterDefinition)
	GetParameterDefinitions() *parameters.ParameterDefinitions

	InitializeParameterDefaultsFromStruct(s interface{}) error

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

	Clone() ParameterLayer
}

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.

TODO(manuel, 2023-12-20) This is a pretty messy interface, I think it used to be a struct?

type ParameterLayerImpl 

type ParameterLayerImpl struct {
	Name                 string                           `yaml:"name"`
	Slug                 string                           `yaml:"slug"`
	Description          string                           `yaml:"description"`
	Prefix               string                           `yaml:"prefix"`
	ParameterDefinitions *parameters.ParameterDefinitions `yaml:"flags,omitempty"`
	ChildLayers          []ParameterLayer                 `yaml:"childLayers,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) AddFlags added in v0.4.36 

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

func (*ParameterLayerImpl) AddLayerToCobraCommand added in v0.4.36 

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

AddLayerToCobraCommand 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) Clone added in v0.4.36 

func (p *ParameterLayerImpl) Clone() ParameterLayer

func (*ParameterLayerImpl) GatherParametersFromMap added in v0.4.36 

func (p *ParameterLayerImpl) GatherParametersFromMap(
	m map[string]interface{}, onlyProvided bool,
	options ...parameters.ParseStepOption,
) (*parameters.ParsedParameters, error)

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() *parameters.ParameterDefinitions

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) 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

InitializeParameterDefaultsFromParameters initializes the parameter definitions of the layer from the given map of parameter values. The parameter definitions are updated in-place.

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) ParseLayerFromCobraCommand added in v0.4.36 

func (p *ParameterLayerImpl) ParseLayerFromCobraCommand(
	cmd *cobra.Command,
	options ...parameters.ParseStepOption,
) (*ParsedLayer, error)

ParseLayerFromCobraCommand 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 WithArguments added in v0.4.36 

func WithArguments(arguments ...*parameters.ParameterDefinition) ParameterLayerOptions

func WithDefaults added in v0.2.18 

func WithDefaults(s interface{}) ParameterLayerOptions

func WithDescription 

func WithDescription(description string) ParameterLayerOptions

func WithName added in v0.4.13 

func WithName(name string) ParameterLayerOptions

func WithParameterDefinitions added in v0.4.36 

func WithParameterDefinitions(parameterDefinitions ...*parameters.ParameterDefinition) ParameterLayerOptions

func WithPrefix added in v0.2.18 

func WithPrefix(prefix string) ParameterLayerOptions

type ParameterLayers added in v0.4.36 

type ParameterLayers struct {
	*orderedmap.OrderedMap[string, ParameterLayer]
}

func NewParameterLayers added in v0.4.36 

func NewParameterLayers(options ...ParameterLayersOption) *ParameterLayers

func (*ParameterLayers) AddToCobraCommand added in v0.5.3 

func (pl *ParameterLayers) AddToCobraCommand(cmd *cobra.Command) error

func (*ParameterLayers) AppendLayers added in v0.4.36 

func (pl *ParameterLayers) AppendLayers(layers ...ParameterLayer)

func (*ParameterLayers) AsList added in v0.4.36 

func (pl *ParameterLayers) AsList() []ParameterLayer

func (*ParameterLayers) Clone added in v0.4.36 

func (pl *ParameterLayers) Clone() *ParameterLayers

func (*ParameterLayers) ForEach added in v0.4.36 

func (pl *ParameterLayers) ForEach(f func(key string, p ParameterLayer))

ForEach iterates over each element in the ParameterLayers map and applies the given function to each key-value pair.

func (*ParameterLayers) ForEachE added in v0.4.36 

func (pl *ParameterLayers) ForEachE(f func(key string, p ParameterLayer) error) error

ForEachE applies a function to each key-value pair in the ParameterLayers, in oldest-to-newest order. It stops iteration and returns the first error encountered, if any.

func (*ParameterLayers) GetAllParameterDefinitions added in v0.4.36 

func (pl *ParameterLayers) GetAllParameterDefinitions() *parameters.ParameterDefinitions

func (*ParameterLayers) InitializeFromDefaults added in v0.5.9 

func (pl *ParameterLayers) InitializeFromDefaults(options ...parameters.ParseStepOption) (*ParsedLayers, error)

func (*ParameterLayers) Merge added in v0.4.36 

func (pl *ParameterLayers) Merge(p *ParameterLayers) *ParameterLayers

func (*ParameterLayers) PrependLayers added in v0.4.36 

func (pl *ParameterLayers) PrependLayers(layers ...ParameterLayer)

func (*ParameterLayers) Subset added in v0.4.36 

func (pl *ParameterLayers) Subset(slugs ...string) *ParameterLayers

func (*ParameterLayers) UpdateWithDefaults added in v0.5.9 

func (pl *ParameterLayers) UpdateWithDefaults(parsedLayers *ParsedLayers, options ...parameters.ParseStepOption) error

type ParameterLayersOption added in v0.4.36 

type ParameterLayersOption func(*ParameterLayers)

func WithLayers added in v0.4.36 

func WithLayers(layers ...ParameterLayer) ParameterLayersOption

type ParsedLayer added in v0.4.36 

type ParsedLayer struct {
	Layer      ParameterLayer
	Parameters *parameters.ParsedParameters
}

ParsedLayer 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 NewParsedLayer added in v0.4.36 

func NewParsedLayer(layer ParameterLayer, options ...ParsedLayerOption) (*ParsedLayer, error)

func (*ParsedLayer) Clone added in v0.4.36 

func (ppl *ParsedLayer) Clone() *ParsedLayer

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

func (*ParsedLayer) GetParameter added in v0.4.36 

func (ppl *ParsedLayer) GetParameter(k string) (interface{}, bool)

func (*ParsedLayer) InitializeStruct added in v0.4.36 

func (ppl *ParsedLayer) InitializeStruct(s interface{}) error

func (*ParsedLayer) MergeParameters added in v0.4.36 

func (ppl *ParsedLayer) MergeParameters(other *ParsedLayer)

MergeParameters merges the other ParsedLayer into this one, overwriting any existing values. This doesn't replace the actual Layer pointer.

type ParsedLayerOption added in v0.4.36 

type ParsedLayerOption func(*ParsedLayer) error

func WithParsedParameterValue added in v0.4.36 

func WithParsedParameterValue(
	key string, value interface{},
	options ...parameters.ParseStepOption,
) ParsedLayerOption

func WithParsedParameters added in v0.4.36 

func WithParsedParameters(pds *parameters.ParsedParameters) ParsedLayerOption

type ParsedLayers added in v0.4.36 

type ParsedLayers struct {
	*orderedmap.OrderedMap[string, *ParsedLayer]
}

func NewParsedLayers added in v0.4.36 

func NewParsedLayers(options ...ParsedLayersOption) *ParsedLayers

func (*ParsedLayers) Clone added in v0.5.9 

func (p *ParsedLayers) Clone() *ParsedLayers

func (*ParsedLayers) ForEach added in v0.4.36 

func (p *ParsedLayers) ForEach(fn func(k string, v *ParsedLayer))

func (*ParsedLayers) ForEachE added in v0.4.36 

func (p *ParsedLayers) ForEachE(fn func(k string, v *ParsedLayer) error) error

func (*ParsedLayers) GetAllParsedParameters added in v0.4.36 

func (p *ParsedLayers) GetAllParsedParameters() *parameters.ParsedParameters

GetAllParsedParameters returns a new instance of parameters.ParsedParameters that merges the parameters from all ParsedLayers. The returned parameters are a deep clone of the parameters.

func (*ParsedLayers) GetDataMap added in v0.4.36 

func (p *ParsedLayers) GetDataMap() map[string]interface{}

GetDataMap is useful when rendering out templates using all passed in layers.

func (*ParsedLayers) GetDefaultParameterLayer added in v0.4.36 

func (p *ParsedLayers) GetDefaultParameterLayer() *ParsedLayer

func (*ParsedLayers) GetOrCreate added in v0.4.36 

func (p *ParsedLayers) GetOrCreate(layer ParameterLayer) *ParsedLayer

func (*ParsedLayers) GetParameter added in v0.4.36 

func (p *ParsedLayers) GetParameter(slug string, key string) (*parameters.ParsedParameter, bool)

func (*ParsedLayers) InitializeStruct added in v0.4.36 

func (p *ParsedLayers) InitializeStruct(layerKey string, dst interface{}) error

InitializeStruct initializes a struct with values from a ParsedLayer specified by the key. If the key is "default", it creates a fresh empty default layer for defaults and initializes the struct with it. If the layer specified by the key is not found, it returns an error. The struct must be passed by reference as the s parameter.

type ParsedLayersOption added in v0.4.36 

type ParsedLayersOption func(*ParsedLayers)

func WithParsedLayer added in v0.4.36 

func WithParsedLayer(slug string, v *ParsedLayer) ParsedLayersOption

type WhitelistParameterLayer added in v0.4.36 

type WhitelistParameterLayer struct {
	ParameterLayer
	WhitelistedParameters map[string]interface{}
}

func NewWhitelistParameterLayer added in v0.4.36 

func NewWhitelistParameterLayer(layer ParameterLayer, whitelistedParameters map[string]interface{}) *WhitelistParameterLayer

func (*WhitelistParameterLayer) GetParameterDefinitions added in v0.4.36 

func (l *WhitelistParameterLayer) GetParameterDefinitions() *parameters.ParameterDefinitions

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.