parameters

package
v0.4.33 Latest Latest
Warning

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

 Go to latest Published: Dec 12, 2023 License: MIT Imports: 25 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.

The required argument checks that all the required parameter definitions are present. The provided argument only checks that the provided flags are passed. Prefix is prepended to all flag names.

func GatherFlagsFromStringList added in v0.4.12 

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

GatherFlagsFromStringList is a function that parses command line flags according to a list of parameter definitions. It returns a map of parameter names to parsed values.

### Usage

The function takes two arguments:

- `args`: a slice of strings representing the command line arguments. - `params`: a slice of `*ParameterDefinition` representing the parameter definitions.

The function returns a map where the keys are the parameter names and the values are the parsed values. If a flag is not recognized or its value cannot be parsed, an error is returned.

### Internals

The function first creates a map of possible flag names from the list of parameter definitions. It then iterates over the command line arguments. If an argument starts with `--` or `-`, it is considered a flag. The function then checks if the flag is recognized by looking it up in the map of flag names. If the flag is recognized, its value is collected.

The system sets the flag to "true" automatically if it's a boolean flag. If a flag repeats, the system collects all its values in a slice. Once the system has collected all flags and their raw values, it parses the raw values based on the parameter definitions.

The `ParseParameter` method of the corresponding `ParameterDefinition` performs the parsing. This method receives a slice of strings and returns the parsed value and an error. The system stores the parsed values in the result map.

### Example

Here is an example of how to use the function:

```go 

params := []*ParameterDefinition{
   {Name: "verbose", ShortFlag: "v", Type: ParameterTypeBool},
   {Name: "output", ShortFlag: "o", Type: ParameterTypeString},
}

args := []string{"--verbose", "-o", "file.txt"} result, args, err := GatherFlagsFromStringList(args, params, false, false, "") 

if err != nil {
   log.Fatal(err)
}

fmt.Println(result) // prints: map[verbose:true output:file.txt] ```

In this example, the function parses the `--verbose` and `-o` flags according to the provided parameter definitions. The `--verbose` flag is a boolean flag and is set to "true". The `-o` flag is a string flag and its value is "file.txt".

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)

GatherParametersFromMap gathers parameter values from a map based on the provided ParameterDefinitions.

For each ParameterDefinition, it checks if a matching value is present in the map:

- If the parameter is missing and required, an error is returned. - If the parameter is missing and optional, the default value is used. - If the value is provided, it is validated against the definition.

Values are looked up by parameter name, as well as short flag if provided.

The returned map contains the gathered parameter values, with defaults filled in for any missing optional parameters.

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 GlazedStructToMap added in v0.4.30 

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

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)

ParseDate parses a string into a time.Time based on predefined date formats.

It first tries parsing with dateparse.ParseAny using standard formats. If that fails, it tries naturaldate.Parse which handles relative natural language dates.

If both parsing attempts fail, an error is returned. The reference time passed to naturaldate.Parse defaults to time.Now().

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.

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)

func (*FileData) PrettyPrint added in v0.4.32 

func (fd *FileData) PrettyPrint() string

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)

ParseParameter parses command line arguments according to the given ParameterDefinition. It returns the parsed parameter value and a non-nil error if parsing failed.

The function takes a list of strings that can be gathered from the command line arguments. This is because cobra for example allows slice flags to be passed by reusing the same flag multiple times (or by parsing comma-separated values).

If the parameter is required and not provided, an error is returned. If the parameter is optional and not provided, the default value is returned.

The ParameterDefinition specifies the expected type and how to parse the arguments:

  • ParameterTypeString: parsed from a single string value
  • ParameterTypeInteger, ParameterTypeFloat, ParameterTypeBool: parsed from a single value
  • ParameterTypeStringList, ParameterTypeIntegerList, ParameterTypeFloatList: parsed from multiple values
  • ParameterTypeFile: load file contents into a FileData struct
  • ParameterTypeFileList: load multiple files into []*FileData
  • ParameterTypeChoice, ParameterTypeChoiceList: validated against allowed choices
  • ParameterTypeKeyValue: parsed from colon separated strings or files
  • ParameterTypeObjectListFromFile, ParameterTypeObjectListFromFiles: deserialized object lists from JSON/YAML files
  • ParameterTypeObjectFromFile: deserialized a single object from a JSON/YAML file
  • ParameterTypeStringFromFile, ParameterTypeStringFromFiles: load file contents as strings
  • ParameterTypeStringListFromFile, ParameterTypeStringListFromFiles: load file lines as a string list

The parsing logic depends on the Type in the ParameterDefinition.

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.