Documentation
¶
Index ¶
- type ArgumentsParser
- func (ap *ArgumentsParser) ArgumentIsPresent(argumentName string) bool
- func (ap *ArgumentsParser) Get(argumentFlag string) (interface{}, error)
- func (ap *ArgumentsParser) NewArgumentGroup(name string) (*argumentgroup.ArgumentGroup, error)
- func (ap *ArgumentsParser) NewBoolArgument(ptr *bool, shortName, longName string, defaultValue bool, help string) error
- func (ap *ArgumentsParser) NewDependentArgumentGroup(name string) (*argumentgroup.ArgumentGroup, error)
- func (ap *ArgumentsParser) NewIntArgument(ptr *int, shortName, longName string, defaultValue int, required bool, ...) error
- func (ap *ArgumentsParser) NewIntPositionalArgument(ptr *int, name string, help string) error
- func (ap *ArgumentsParser) NewIntRangeArgument(ptr *int, shortName, longName string, defaultValue int, rangeStart int, ...) error
- func (ap *ArgumentsParser) NewListOfIntsArgument(ptr *[]int, shortName, longName string, defaultValue []int, required bool, ...) error
- func (ap *ArgumentsParser) NewListOfStringsArgument(ptr *[]string, shortName, longName string, defaultValue []string, ...) error
- func (ap *ArgumentsParser) NewMapOfHttpHeadersArgument(ptr *map[string]string, shortName, longName string, ...) error
- func (ap *ArgumentsParser) NewNotRequiredMutuallyExclusiveArgumentGroup(name string) (*argumentgroup.ArgumentGroup, error)
- func (ap *ArgumentsParser) NewRequiredMutuallyExclusiveArgumentGroup(name string) (*argumentgroup.ArgumentGroup, error)
- func (ap *ArgumentsParser) NewStringArgument(ptr *string, shortName, longName string, defaultValue string, required bool, ...) error
- func (ap *ArgumentsParser) NewStringPositionalArgument(ptr *string, name string, help string) error
- func (ap *ArgumentsParser) NewTcpPortArgument(ptr *int, shortName, longName string, defaultValue int, required bool, ...) error
- func (ap *ArgumentsParser) Parse()
- func (ap *ArgumentsParser) ParseFrom(index int)
- func (ap *ArgumentsParser) PrintArgumentTree()
- func (ap *ArgumentsParser) Register(arg arguments.Argument) error
- func (ap *ArgumentsParser) RegisterPositional(newPositionalArgument positionals.PositionalArgument) error
- func (ap *ArgumentsParser) Usage()
- func (ap *ArgumentsParser) UsageFrom(index int)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ArgumentsParser ¶
type ArgumentsParser struct {
Banner string
ShowBannerOnHelp bool
ShowBannerOnRun bool
PositionalArguments []positionals.PositionalArgument
DefaultGroup *argumentgroup.ArgumentGroup
Groups map[string]*argumentgroup.ArgumentGroup
// contains filtered or unexported fields
}
ArgumentsParser is responsible for parsing command-line arguments for a program. It handles both positional and named arguments, supports argument groups, and provides usage information. The parser maintains a mapping of argument names to their corresponding values and manages required arguments.
Fields:
Banner (string): A banner string that is printed before running the argument parsing.
This is typically used to display the program name or purpose.
PositionalArguments ([]*positionals.PositionalArgument): A slice of pointers to positional arguments
that the parser will manage.
DefaultGroup (*argumentgroup.ArgumentGroup): A pointer to the default argument group for organizing
arguments, if applicable.
shortNameToArgument (map[string]arguments.Argument): A map that associates short flag names (e.g., "-v")
with their corresponding argument structures.
longNameToArgument (map[string]arguments.Argument): A map that associates long flag names (e.g., "--verbose")
with their corresponding argument structures.
requiredArguments ([]arguments.Argument): A slice of pointers to required arguments that must be provided
by the user for the program to run successfully.
allArguments ([]arguments.Argument): A slice containing all arguments (both positional and named) that
the parser manages.
Groups (map[string]*argumentgroup.ArgumentGroup): A map of named subgroups to organize related arguments
into logical categories for better structure and readability.
func (*ArgumentsParser) ArgumentIsPresent ¶
func (ap *ArgumentsParser) ArgumentIsPresent(argumentName string) bool
ArgumentIsPresent checks if a given argument is present in the parsed arguments. It supports both short (e.g., -e) and long (e.g., --example) argument names.
Parameters:
- argumentName: The name of the argument to check. It should start with a dash ('-') for short arguments or two dashes ('--') for long arguments.
Returns: - bool: true if the argument is present; false otherwise.
The function first verifies that the argument name has a valid length and starts with a dash. It then checks if the argument is in the `longNameToArgument` map for long arguments or `shortNameToArgument` map for short arguments, returning true if found and false if not.
func (*ArgumentsParser) Get ¶
func (ap *ArgumentsParser) Get(argumentFlag string) (interface{}, error)
Get retrieves the value of the argument specified by its short or long name.
Parameters:
- name: The name of the argument to retrieve. This can be either the short name (single character) or the long name (string) of the argument.
Returns: - The value of the argument as an interface{} if the argument is found. - An error if the argument maps are not initialized or if the argument with the specified name is not found.
The function first checks if the argument maps (shortNameToArgument and longNameToArgument) are initialized. If they are not, it returns an error indicating that the argument maps are not initialized. It then looks up the argument by its short name in the shortNameToArgument map. If the argument is not found, it looks up the argument by its long name in the longNameToArgument map. If the argument is still not found, it returns an error indicating that the argument with the specified name is not found. If the argument is found, it returns the value of the argument.
func (*ArgumentsParser) NewArgumentGroup ¶
func (ap *ArgumentsParser) NewArgumentGroup(name string) (*argumentgroup.ArgumentGroup, error)
NewArgumentGroup creates a new argument group with the specified name and adds it to the list of child groups.
Parameters: - name: The name of the new argument group.
Returns: A pointer to the newly created ArgumentGroup struct, which can be used to add arguments to the group.
The function initializes a new ArgumentGroup with the provided name, appends it to the SubGroups slice, and returns a pointer to the newly added ArgumentGroup. This allows for further configuration and addition of arguments to the group.
func (*ArgumentsParser) NewBoolArgument ¶
func (ap *ArgumentsParser) NewBoolArgument(ptr *bool, shortName, longName string, defaultValue bool, help string) error
NewBoolArgument initializes a new BoolArgument and registers it with the ArgumentsParser. It sets up the argument with the provided short and long names, default value, and help message.
Parameters: - ptr: A pointer to the boolean variable where the argument's value will be stored. - shortName: The short flag (e.g., "-b") used to specify the boolean argument. It can be empty if no short flag is defined. - longName: The long flag (e.g., "--bool") used to specify the boolean argument. It can be empty if no long flag is defined. - defaultValue: The boolean value to be used if the argument is not provided by the user. - help: A description of what this argument represents, displayed in help/usage information.
Returns: - An error if the argument registration fails, otherwise nil.
func (*ArgumentsParser) NewDependentArgumentGroup ¶
func (ap *ArgumentsParser) NewDependentArgumentGroup(name string) (*argumentgroup.ArgumentGroup, error)
NewRequiredMutuallyExclusiveArgumentGroup creates a new argument group with the specified name and adds it to the list of child groups. This group enforces that exactly one of the arguments within it must be set; if none or more than one are provided, an error will be thrown.
Parameters: - name: The name of the new argument group.
Returns: A pointer to the newly created ArgumentGroup struct, which can be used to add arguments to the group, or an error if a group with the same name already exists.
The function initializes a new ArgumentGroup with the provided name and the type ARGUMENT_GROUP_TYPE_REQUIRED_MUTUALLY_EXCLUSIVE. It adds the group to the Groups map and returns a pointer to the newly added ArgumentGroup. This allows for further configuration and addition of arguments to the group, ensuring that only one of the arguments is set during parsing.
func (*ArgumentsParser) NewIntArgument ¶
func (ap *ArgumentsParser) NewIntArgument(ptr *int, shortName, longName string, defaultValue int, required bool, help string) error
NewIntArgument initializes a new IntArgument and registers it with the ArgumentsParser. It sets up the argument with the provided short and long names, default value, requirement status, and help message.
Parameters: - ptr: A pointer to the integer variable where the argument's value will be stored. - shortName: The short flag (e.g., "-n") used to specify the integer argument. It can be empty if no short flag is defined. - longName: The long flag (e.g., "--number") used to specify the integer argument. It can be empty if no long flag is defined. - defaultValue: The integer value to be used if the argument is not provided by the user. - required: Indicates whether the argument must be specified by the user. - help: A description of what this argument represents, displayed in help/usage information.
Returns: - An error if the argument registration fails, otherwise nil.
func (*ArgumentsParser) NewIntPositionalArgument ¶
func (ap *ArgumentsParser) NewIntPositionalArgument(ptr *int, name string, help string) error
NewIntArgument registers a new int argument with the argument parser.
Parameters: - ptr: A pointer to the int variable where the argument value will be stored. - shortName: The short name (single character) of the argument, prefixed with a dash (e.g., "-u"). - longName: The long name of the argument, prefixed with two dashes (e.g., "--username"). - defaultValue: The default value of the argument if it is not provided by the user. - help: A description of the argument, which will be displayed in the help message.
The function creates a new StringArgument with the provided parameters and adds it to the argument group.
func (*ArgumentsParser) NewIntRangeArgument ¶
func (ap *ArgumentsParser) NewIntRangeArgument(ptr *int, shortName, longName string, defaultValue int, rangeStart int, rangeStop int, required bool, help string) error
NewIntRangeArgument initializes a new IntRangeArgument and registers it with the ArgumentsParser. It sets up the argument with the provided short and long names, default value, range boundaries, requirement status, and help message.
Parameters: - ptr: A pointer to the integer variable where the argument's value will be stored. - shortName: The short flag (e.g., "-r") used to specify the argument. It can be empty if no short flag is defined. - longName: The long flag (e.g., "--range") used to specify the argument. It can be empty if no long flag is defined. - defaultValue: The integer to be used if the argument is not provided by the user. - rangeStart: The minimum allowable value for the integer argument. - rangeStop: The maximum allowable value for the integer argument. - required: Indicates whether the argument must be specified by the user. - help: A description of what this argument represents, displayed in help/usage information.
Returns: - An error if the argument registration fails, otherwise nil.
func (*ArgumentsParser) NewListOfIntsArgument ¶
func (ap *ArgumentsParser) NewListOfIntsArgument(ptr *[]int, shortName, longName string, defaultValue []int, required bool, help string) error
NewListOfIntsArgument registers a new list of integers argument with the argument parser.
Parameters: - ptr: A pointer to the slice of int variables where the argument values will be stored. - shortName: The short name (single character) of the argument, prefixed with a dash (e.g., "-n"). - longName: The long name of the argument, prefixed with two dashes (e.g., "--numbers"). - defaultValue: The default list of integers if the argument is not provided by the user. - required: A boolean indicating if the argument is mandatory. - help: A description of the argument, which will be displayed in the help message.
The function creates a new ListOfIntsArgument with the provided parameters and adds it to the argument group.
func (*ArgumentsParser) NewListOfStringsArgument ¶
func (ap *ArgumentsParser) NewListOfStringsArgument(ptr *[]string, shortName, longName string, defaultValue []string, required bool, help string) error
NewListOfStringsArgument registers a new list of strings argument with the argument parser.
Parameters: - ptr: A pointer to the slice of string variables where the argument values will be stored. - shortName: The short name (single character) of the argument, prefixed with a dash (e.g., "-s"). - longName: The long name of the argument, prefixed with two dashes (e.g., "--strings"). - defaultValue: The default list of strings if the argument is not provided by the user. - required: A boolean indicating if the argument is mandatory. - help: A description of the argument, which will be displayed in the help message.
The function creates a new ListOfStringsArgument with the provided parameters and adds it to the argument group.
func (*ArgumentsParser) NewMapOfHttpHeadersArgument ¶
func (ap *ArgumentsParser) NewMapOfHttpHeadersArgument(ptr *map[string]string, shortName, longName string, defaultValue map[string]string, required bool, help string) error
NewMapOfHttpHeadersArgument registers a new list of HTTP headers argument with the argument parser.
Parameters: - ptr: A pointer to the slice of string variables where the argument values will be stored. - shortName: The short name (single character) of the argument, prefixed with a dash (e.g., "-H"). - longName: The long name of the argument, prefixed with two dashes (e.g., "--header"). - required: A boolean indicating if the argument is mandatory. - help: A description of the argument, which will be displayed in the help message.
The function creates a new MapOfHttpHeadersArgument with the provided parameters and adds it to the argument group. Each header should be passed in the format "Key: Value".
func (*ArgumentsParser) NewNotRequiredMutuallyExclusiveArgumentGroup ¶
func (ap *ArgumentsParser) NewNotRequiredMutuallyExclusiveArgumentGroup(name string) (*argumentgroup.ArgumentGroup, error)
NewNotRequiredMutuallyExclusiveArgumentGroup creates a new argument group with the specified name and adds it to the list of child groups. This group allows at most one of the arguments within it to be set, but it is not mandatory to provide any.
Parameters: - name: The name of the new argument group.
Returns: A pointer to the newly created ArgumentGroup struct, which can be used to add arguments to the group, or an error if a group with the same name already exists.
The function initializes a new ArgumentGroup with the provided name and the type ARGUMENT_GROUP_TYPE_NOT_REQUIRED_MUTUALLY_EXCLUSIVE. It appends the group to the Groups map and returns a pointer to the newly added ArgumentGroup. This allows for further configuration and addition of arguments to the group.
func (*ArgumentsParser) NewRequiredMutuallyExclusiveArgumentGroup ¶
func (ap *ArgumentsParser) NewRequiredMutuallyExclusiveArgumentGroup(name string) (*argumentgroup.ArgumentGroup, error)
NewRequiredMutuallyExclusiveArgumentGroup creates a new argument group with the specified name and adds it to the list of child groups. This group enforces that exactly one of the arguments within it must be set; if none or more than one are provided, an error will be thrown.
Parameters: - name: The name of the new argument group.
Returns: A pointer to the newly created ArgumentGroup struct, which can be used to add arguments to the group, or an error if a group with the same name already exists.
The function initializes a new ArgumentGroup with the provided name and the type ARGUMENT_GROUP_TYPE_REQUIRED_MUTUALLY_EXCLUSIVE. It adds the group to the Groups map and returns a pointer to the newly added ArgumentGroup. This allows for further configuration and addition of arguments to the group, ensuring that only one of the arguments is set during parsing.
func (*ArgumentsParser) NewStringArgument ¶
func (ap *ArgumentsParser) NewStringArgument(ptr *string, shortName, longName string, defaultValue string, required bool, help string) error
NewStringArgument initializes a new StringArgument and registers it with the ArgumentsParser. It sets up the argument with the provided short and long names, default value, requirement status, and help message.
Parameters: - ptr: A pointer to the string variable where the argument's value will be stored. - shortName: The short flag (e.g., "-s") used to specify the string argument. It can be empty if no short flag is defined. - longName: The long flag (e.g., "--string") used to specify the string argument. It can be empty if no long flag is defined. - defaultValue: The string value to be used if the argument is not provided by the user. - required: Indicates whether the argument must be specified by the user. - help: A description of what this argument represents, displayed in help/usage information.
Returns: - An error if the argument registration fails, otherwise nil.
func (*ArgumentsParser) NewStringPositionalArgument ¶
func (ap *ArgumentsParser) NewStringPositionalArgument(ptr *string, name string, help string) error
NewStringArgument registers a new string argument with the argument parser.
Parameters: - ptr: A pointer to the string variable where the argument value will be stored. - shortName: The short name (single character) of the argument, prefixed with a dash (e.g., "-u"). - longName: The long name of the argument, prefixed with two dashes (e.g., "--username"). - defaultValue: The default value of the argument if it is not provided by the user. - help: A description of the argument, which will be displayed in the help message.
The function creates a new StringArgument with the provided parameters and adds it to the argument group.
func (*ArgumentsParser) NewTcpPortArgument ¶
func (ap *ArgumentsParser) NewTcpPortArgument(ptr *int, shortName, longName string, defaultValue int, required bool, help string) error
NewTcpPortArgument initializes a new TcpPortArgument and registers it with the ArgumentsParser. It sets up the argument with the provided short and long names, default value, requirement status, and help message.
Parameters: - ptr: A pointer to the integer variable where the argument's value will be stored. - shortName: The short flag (e.g., "-p") used to specify the TCP port argument. It can be empty if no short flag is defined. - longName: The long flag (e.g., "--port") used to specify the TCP port argument. It can be empty if no long flag is defined. - defaultValue: The TCP port number to be used if the argument is not provided by the user. - required: Indicates whether the argument must be specified by the user. - help: A description of what this argument represents, displayed in help/usage information.
Returns: - An error if the argument registration fails, otherwise nil.
func (*ArgumentsParser) Parse ¶
func (ap *ArgumentsParser) Parse()
Parse parses the arguments and returns the parsed arguments.
Returns: - A map of parsed arguments.
func (*ArgumentsParser) ParseFrom ¶
func (ap *ArgumentsParser) ParseFrom(index int)
Parse processes the command-line arguments and sets the values for the defined arguments. This method handles both positional and named arguments, supports flags with values specified using "=", and checks for missing or unexpected arguments. It also provides a usage message if the "-h" or "--help" flags are present.
Behavior:
- Populates maps for quick lookup of arguments based on their short and long names.
- Splits input arguments on "=" to allow for flags like "--key=value".
- Detects the presence of help flags ("-h" or "--help") and displays usage information.
- Separates positional arguments from named arguments based on the order of inputs.
- Validates that all required positional and named arguments are provided and parses them.
- Displays error messages for missing or extra arguments and exits if any errors are detected.
Note:
This method terminates the program if it encounters errors or if help is requested.
Example Usage:
- `./program positional1 positional2 --name=example`
Errors:
If required arguments are missing or extra positional arguments are found, error messages will be displayed, and the program will exit with a non-zero status.
func (*ArgumentsParser) PrintArgumentTree ¶
func (ap *ArgumentsParser) PrintArgumentTree()
PrintArgumentTree prints the argument tree for the ArgumentsParser.
The function prints the banner, the list of arguments, and the subgroups in a tree-like structure. Each level of indentation is represented by " │ ". The output includes the banner, the names of the arguments, and the names of the subgroups within the ArgumentsParser.
func (*ArgumentsParser) Register ¶
func (ap *ArgumentsParser) Register(arg arguments.Argument) error
Register adds a new argument to the ArgumentsParser's default group. It ensures that the short and long names for the argument are unique and prevents duplicate registrations.
Parameters: - arg: An instance of the arguments.Argument interface representing the argument to be registered.
Returns: - An error if the argument's short or long name conflicts with an existing argument, otherwise nil.
func (*ArgumentsParser) RegisterPositional ¶
func (ap *ArgumentsParser) RegisterPositional(newPositionalArgument positionals.PositionalArgument) error
Register registers a new argument with the argument group if it does not already exist.
Parameters: - arg: The argument to be registered.
The function checks if the argument's short name and long name are already present in the ShortNameToArgument and LongNameToArgument maps. If not, it adds the argument to these maps and appends it to the Arguments slice.
func (*ArgumentsParser) Usage ¶
func (ap *ArgumentsParser) Usage()
Usage prints the usage information for the command-line arguments.
func (*ArgumentsParser) UsageFrom ¶
func (ap *ArgumentsParser) UsageFrom(index int)
Usage prints the usage information for the command-line arguments.
The function first prints the banner, followed by the usage string, which includes the name of the executable. It then iterates through all the arguments in the DefaultGroup and prints their short name, long name, and help description. The arguments are formatted using the padding format calculated by the computePaddingFormat function.
After printing the arguments in the DefaultGroup, the function iterates over the named subgroups in the Groups map. For each subgroup, it prints the group name and the arguments within that group, including their short name, long name, and help description. The subgroup arguments are also formatted using the padding format calculated by the computePaddingFormat function.
The function ensures that the usage information is displayed in a clear and organized manner, making it easy for users to understand the available command-line arguments and their descriptions.
Source Files