parameters

Documentation

Index

• func AddArgumentsToCobraCommand(cmd *cobra.Command, arguments []*ParameterDefinition) error
• func AddFlagsToCobraCommand(flagSet *pflag.FlagSet, flags []*ParameterDefinition, prefix string) error
• func GatherArguments(args []string, arguments []*ParameterDefinition, onlyProvided bool) (map[string]interface{}, error)
• func GatherFlagsFromCobraCommand(cmd *cobra.Command, params []*ParameterDefinition, onlyProvided bool, ...) (map[string]interface{}, error)
• func GatherFlagsFromViper(params []*ParameterDefinition, onlyProvided bool, prefix string) (map[string]interface{}, error)
• func InitializeParameterDefaultsFromParameters(parameterDefinitions map[string]*ParameterDefinition, ...) error
• func InitializeParameterDefinitionsFromStruct(parameterDefinitions map[string]*ParameterDefinition, s interface{}) error
• func InitializeStructFromParameterDefinitions(s interface{}, parameterDefinitions map[string]*ParameterDefinition) error
• func InitializeStructFromParameters(s interface{}, ps map[string]interface{}) error
• func IsFileLoadingParameter(p ParameterType, v string) bool
• func IsListParameter(p ParameterType) bool
• func ParseDate(value string) (time.Time, error)
• type ParameterDefinition
  • func InitFlagsFromYaml(yamlContent []byte) (map[string]*ParameterDefinition, []*ParameterDefinition)
  • func NewParameterDefinition(name string, parameterType ParameterType, options ...ParameterDefinitionOption) *ParameterDefinition
  • func (p *ParameterDefinition) CheckParameterDefaultValueValidity() error
  • func (p *ParameterDefinition) Copy() *ParameterDefinition
  • func (p *ParameterDefinition) ParseFromReader(f io.Reader, name string) (interface{}, error)
  • func (p *ParameterDefinition) ParseParameter(v []string) (interface{}, error)
  • func (p *ParameterDefinition) SetDefaultFromInterface(i interface{}) error
  • func (p *ParameterDefinition) SetDefaultFromValue(value reflect.Value) error
  • func (p *ParameterDefinition) SetValueFromDefault(value reflect.Value) error
  • func (p *ParameterDefinition) String() string
• type ParameterDefinitionOption
  • func WithChoices(choices []string) ParameterDefinitionOption
  • func WithDefault(defaultValue interface{}) ParameterDefinitionOption
  • func WithHelp(help string) ParameterDefinitionOption
  • func WithRequired(required bool) ParameterDefinitionOption
  • func WithShortFlag(shortFlag string) ParameterDefinitionOption
• type ParameterType

Functions

func AddArgumentsToCobraCommand

func AddArgumentsToCobraCommand(cmd *cobra.Command, arguments []*ParameterDefinition) error

AddArgumentsToCobraCommand adds the arguments (not the flags) of a CommandDescription to a cobra command as positional arguments. An optional argument cannot be followed by a required argument. Similarly, a list of arguments cannot be followed by any argument (since we otherwise wouldn't know how many belong to the list and where to do the cut off).

func AddFlagsToCobraCommand

func AddFlagsToCobraCommand(
	flagSet *pflag.FlagSet,
	flags []*ParameterDefinition,
	prefix string,

) error

AddFlagsToCobraCommand takes the parameters from a CommandDescription and converts them to cobra flags, before adding them to the Flags() of a the passed cobra command.

TODO(manuel, 2023-02-12) We need to handle arbitrary defaults here

See https://github.com/go-go-golems/glazed/issues/132

Currently, usage of this functions just passes the defaults encoded in the metadata YAML files (for glazed flags at least), but really we want to override this on a per command basis easily without having to necessarily copy or mutate the parameters loaded from yaml.

One option would be to remove the defaults structs, and do the overloading by command with ParameterList manipulating functions, so that it is easy for the library user to override and further tweak the defaults.

Currently, that behaviour is encoded in the AddFieldsFilterFlags function itself.

What also needs to be considered is the bigger context that these declarative flags and arguments definitions are going to be used in a lot of different contexts, and might need to be overloaded and initialized in different ways.

For example: - REST API - CLI - GRPC service - TUI bubbletea UI - Web UI - declarative config files

--- 2023-02-12 - manuel

I went with the following solution:

One other option would be to pass this function a map with overloaded default, but while that feels easier and cleaner in the short term, I think it limits the concept of what it means for a library user to overload the defaults handling mechanism. This already becomes apparent in the FieldsFilterDefaults handling, where an empty list or a list containing "all" should be treated the same.

func GatherArguments

func GatherArguments(args []string, arguments []*ParameterDefinition, onlyProvided bool) (map[string]interface{}, error)

GatherArguments parses the positional arguments passed as a list of strings into a map of parsed values. If onlyProvided is true, then only arguments that are provided are returned (i.e. the default values are not included).

func GatherFlagsFromCobraCommand

func GatherFlagsFromCobraCommand(
	cmd *cobra.Command,
	params []*ParameterDefinition,
	onlyProvided bool,
	prefix string,
) (map[string]interface{}, error)

GatherFlagsFromCobraCommand gathers the flags from the cobra command, and parses them according to the parameter description passed in params. The result is a map of parameter names to parsed values. If onlyProvided is true, only parameters that are provided by the user are returned (i.e. not the default values). If a parameter cannot be parsed correctly, or is missing even though it is not optional, an error is returned.

func GatherFlagsFromViper

func GatherFlagsFromViper(
	params []*ParameterDefinition,
	onlyProvided bool,
	prefix string,
) (map[string]interface{}, error)

func InitializeParameterDefaultsFromParameters

func InitializeParameterDefaultsFromParameters(
	parameterDefinitions map[string]*ParameterDefinition,
	ps map[string]interface{},
) error

func InitializeParameterDefinitionsFromStruct

func InitializeParameterDefinitionsFromStruct(
	parameterDefinitions map[string]*ParameterDefinition,
	s interface{},
) error

InitializeParameterDefinitionsFromStruct initializes a map of parameter definitions from a struct. Each field in the struct annotated with tag `glazed.parameter` will be used to set the default value of the corresponding definition in `parameterDefinitions`. If no `ParameterDefinition` is found for a field, an error is returned. This is the inverse of InitializeStructFromParameterDefinitions.

func InitializeStructFromParameterDefinitions

func InitializeStructFromParameterDefinitions(
	s interface{},
	parameterDefinitions map[string]*ParameterDefinition,
) error

InitializeStructFromParameterDefinitions initializes a struct from a map of parameter definitions.

Each field in the struct annotated with tag `glazed.parameter` will be set to the default value of the corresponding `ParameterDefinition`. If no `ParameterDefinition` is found for a field, an error is returned.

func InitializeStructFromParameters

func InitializeStructFromParameters(s interface{}, ps map[string]interface{}) error

func IsFileLoadingParameter

func IsFileLoadingParameter(p ParameterType, v string) bool

IsFileLoadingParameter returns true if the parameter type is one that loads a file, when provided with the given value. This slightly odd API is because some types like ParameterTypeKeyValue can be either a string or a file. A beginning character of @ indicates a file.

func IsListParameter

func IsListParameter(p ParameterType) bool

func ParseDate

func ParseDate(value string) (time.Time, error)

Types

type ParameterDefinition

type ParameterDefinition struct {
	Name      string        `yaml:"name"`
	ShortFlag string        `yaml:"shortFlag,omitempty"`
	Type      ParameterType `yaml:"type"`
	Help      string        `yaml:"help,omitempty"`
	Default   interface{}   `yaml:"default,omitempty"`
	Choices   []string      `yaml:"choices,omitempty"`
	Required  bool          `yaml:"required,omitempty"`
}

ParameterDefinition is a declarative way of describing a command line parameter. A ParameterDefinition can be either a Flag or an Argument. Along with metadata (Name, Help) that is useful for help, it also specifies a Type, a Default value and if it is Required.

func InitFlagsFromYaml

func InitFlagsFromYaml(yamlContent []byte) (map[string]*ParameterDefinition, []*ParameterDefinition)

func NewParameterDefinition

func NewParameterDefinition(name string, parameterType ParameterType, options ...ParameterDefinitionOption) *ParameterDefinition

func (*ParameterDefinition) CheckParameterDefaultValueValidity

func (p *ParameterDefinition) CheckParameterDefaultValueValidity() error

func (*ParameterDefinition) Copy

func (p *ParameterDefinition) Copy() *ParameterDefinition

func (*ParameterDefinition) ParseFromReader

func (p *ParameterDefinition) ParseFromReader(f io.Reader, name string) (interface{}, error)

func (*ParameterDefinition) ParseParameter

func (p *ParameterDefinition) ParseParameter(v []string) (interface{}, error)

func (*ParameterDefinition) SetDefaultFromInterface

func (p *ParameterDefinition) SetDefaultFromInterface(i interface{}) error

func (*ParameterDefinition) SetDefaultFromValue

func (p *ParameterDefinition) SetDefaultFromValue(value reflect.Value) error

func (*ParameterDefinition) SetValueFromDefault

func (p *ParameterDefinition) SetValueFromDefault(value reflect.Value) error

SetValueFromDefault assigns the default value of the ParameterDefinition to the given value. If the Default value is nil, the value is set to the zero value of the type.

TODO(manuel, 2023-02-12) Not sure if the setting to the zero value of the type is the best idea, really.

func (*ParameterDefinition) String

func (p *ParameterDefinition) String() string

type ParameterDefinitionOption

type ParameterDefinitionOption func(*ParameterDefinition)

func WithChoices

func WithChoices(choices []string) ParameterDefinitionOption

func WithDefault

func WithDefault(defaultValue interface{}) ParameterDefinitionOption

func WithHelp

func WithHelp(help string) ParameterDefinitionOption

func WithRequired

func WithRequired(required bool) ParameterDefinitionOption

func WithShortFlag

func WithShortFlag(shortFlag string) ParameterDefinitionOption

type ParameterType

type ParameterType string

const (
	ParameterTypeString ParameterType = "string"

	ParameterTypeStringFromFile ParameterType = "stringFromFile"

	ParameterTypeObjectListFromFile ParameterType = "objectListFromFile"
	ParameterTypeObjectFromFile     ParameterType = "objectFromFile"
	ParameterTypeStringListFromFile ParameterType = "stringListFromFile"

	// ParameterTypeKeyValue signals either a string with comma separate key-value options,
	// or when beginning with @, a file with key-value options
	ParameterTypeKeyValue ParameterType = "keyValue"

	ParameterTypeInteger     ParameterType = "int"
	ParameterTypeFloat       ParameterType = "float"
	ParameterTypeBool        ParameterType = "bool"
	ParameterTypeDate        ParameterType = "date"
	ParameterTypeStringList  ParameterType = "stringList"
	ParameterTypeIntegerList ParameterType = "intList"
	ParameterTypeFloatList   ParameterType = "floatList"
	ParameterTypeChoice      ParameterType = "choice"
)