parameters

package
v0.4.11 Latest Latest
Warning

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

 Go to latest Published: Sep 19, 2023 License: MIT Imports: 24 Imported by: 66

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AddArgumentsToCobraCommand 

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

AddArgumentsToCobraCommand adds each ParameterDefinition from `arguments` as positional arguments to the provided `cmd` cobra command. Argument ordering, optionality, and multiplicity constraints are respected:

  • Required arguments (argument.Required == true) should come before the optional.
  • Only one list argument (either ParameterTypeStringList or ParameterTypeIntegerList) is allowed and it should be the last one.

Any violation of these conditions yields an error. This function processes each argument, checks their default values for validity, which if invalid, triggers an error return.

It computes the minimum and maximum number of arguments the command can take based on the required, optional, and list arguments. If everything is successful, it assigns an argument validator (either MinimumNArgs or RangeArgs) to the cobra command's Args attribute.

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, ignoreRequired bool) (*orderedmap.OrderedMap[string, interface{}], error)

GatherArguments parses positional string arguments into a map of values.

It takes the command-line arguments, the expected argument definitions, and a boolean indicating whether to only include explicitly provided arguments, not the default values of missing arguments.

Only the last parameter definitions can be a list parameter type.

Required arguments missing from the input will result in an error. Arguments with default values can be included based on the onlyProvided flag.

The result is a map with argument names as keys and parsed values. Argument order is maintained.

Any extra arguments not defined will result in an error. Parsing errors for individual arguments will also return errors.

func GatherFlagsFromCobraCommand 

func GatherFlagsFromCobraCommand(cmd *cobra.Command, params []*ParameterDefinition, onlyProvided bool, ignoreRequired 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 added in v0.2.18 

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

func GatherParametersFromMap added in v0.2.54 

func GatherParametersFromMap(m map[string]interface{}, ps map[string]*ParameterDefinition, onlyProvided bool) (map[string]interface{}, error)

func GenerateUseString added in v0.4.9 

func GenerateUseString(cmd *cobra.Command, arguments []*ParameterDefinition) string

GenerateUseString creates a string representation of the 'Use' field for a given cobra command and a list of parameter definitions. The first word of the existing 'Use' field is treated as the verb for the command. The resulting string briefly describes how to use the command respecting the following conventions:

  • Required parameters are enclosed in '<>'.
  • Optional parameters are enclosed in '[]'.
  • Optional parameters that accept multiple input (ParameterTypeStringList or ParameterTypeIntegerList) are followed by '...'.
  • If a parameter has a default value, it is specified after parameter name like 'parameter (default: value)'.

For example:

  • If there is a required parameter 'name', and an optional parameter 'age' with a default value of '30', the resulting string will be: 'verb <name> [age (default: 30)]'.
  • If there is a required parameter 'name', and an optional parameter 'colors' of type ParameterTypeStringList, the resulting Use string will be: 'verb <name> [colors...]'

func InitializeParameterDefaultsFromParameters added in v0.2.18 

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

func InitializeParameterDefinitionsFromStruct added in v0.2.13 

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

IsListParameter returns if the parameter has to be parsed from a list of strings, not if its value is actually a string.

func ParseDate 

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

func RenderValue added in v0.2.46 

func RenderValue(type_ ParameterType, value interface{}) (string, error)

RenderValue renders the given value to string so that it can be parsed as a cobra command line flag. TODO(manuel, 2023-09-09) Refactor rendering of values to strings that can be parsed. This is only applicable to parsing using cobra, but really we now have many more ways of parsing a flag out of a string, among which GET query and FORM input parameters.

func StructToMap added in v0.4.8 

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

Types

type FileData added in v0.4.11 

type FileData struct {
	Content          string
	ParsedContent    interface{}
	ParseError       error
	RawContent       []byte
	StringContent    string
	IsList           bool
	IsObject         bool
	BaseName         string
	Extension        string
	FileType         FileType
	Path             string
	RelativePath     string
	AbsolutePath     string
	Size             int64
	LastModifiedTime time.Time
	Permissions      os.FileMode
	IsDirectory      bool
}

func GetFileData added in v0.4.11 

func GetFileData(filename string) (*FileData, error)

type FileType added in v0.4.11 

type FileType string
const (
	Unknown FileType = "Unknown"
	JSON    FileType = "JSON"
	YAML    FileType = "YAML"
	CSV     FileType = "CSV"
	TEXT    FileType = "TEXT"
)

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 LoadParameterDefinitionsFromYAML added in v0.2.84 

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

LoadParameterDefinitionsFromYAML loads a map of ParameterDefinitions from a YAML file. It checks that default values are valid. It returns the ParameterDefinitions as a map indexed by name, and as a list.

func NewParameterDefinition 

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

func (*ParameterDefinition) CheckParameterDefaultValueValidity 

func (p *ParameterDefinition) CheckParameterDefaultValueValidity() error

CheckParameterDefaultValueValidity checks if the ParameterDefinition's Default is valid. This is used when validating loading from a YAML file or setting up cobra flag definitions.

func (*ParameterDefinition) CheckValueValidity added in v0.2.54 

func (p *ParameterDefinition) CheckValueValidity(v interface{}) error

CheckValueValidity checks if the given value is valid for the ParameterDefinition.

func (*ParameterDefinition) Copy 

func (p *ParameterDefinition) Copy() *ParameterDefinition

func (*ParameterDefinition) InitializeValueToEmptyValue added in v0.4.9 

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

InitializeValueToEmptyValue initializes the given value to the empty value of the type of the parameter.

func (*ParameterDefinition) IsEqualToDefault added in v0.2.55 

func (p *ParameterDefinition) IsEqualToDefault(i interface{}) bool

func (*ParameterDefinition) ParseFromReader added in v0.2.16 

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

ParseFromReader parses a single element for the type from the reader. In the case of parameters taking multiple files, this needs to be called for each file and merged at the caller level.

func (*ParameterDefinition) ParseParameter 

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

func (*ParameterDefinition) SetDefaultFromValue added in v0.2.13 

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.

func (*ParameterDefinition) SetValueFromInterface added in v0.4.9 

func (p *ParameterDefinition) SetValueFromInterface(value reflect.Value, v interface{}) error

SetValueFromInterface assigns the given value to the given reflect.Value.

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"
	ParameterTypeStringFromFiles ParameterType = "stringFromFiles"

	// ParameterTypeFile and ParameterTypeFileList are a more elaborate version that loads and parses
	// the file content and returns a list of FileData objects (or a single object in the case
	// of ParameterTypeFile).
	ParameterTypeFile     ParameterType = "file"
	ParameterTypeFileList ParameterType = "fileList"

	ParameterTypeObjectListFromFile  ParameterType = "objectListFromFile"
	ParameterTypeObjectListFromFiles ParameterType = "objectListFromFiles"
	ParameterTypeObjectFromFile      ParameterType = "objectFromFile"
	ParameterTypeStringListFromFile  ParameterType = "stringListFromFile"
	ParameterTypeStringListFromFiles ParameterType = "stringListFromFiles"

	// 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"
	ParameterTypeChoiceList  ParameterType = "choiceList"
)

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.