Package io.github.qishr.cascara.common.util
Class ParseResult
java.lang.Object
io.github.qishr.cascara.common.util.CommandLine.ParseResult
Enclosing Class:
io.github.qishr.cascara.common.util.CommandLine
public static class ParseResult
Encapsulates the result of parsing an array of command line arguments.
Nested Class Summary
| Modifier and Type | Class | Description |
|---|---|---|
| public static | io.github.qishr.cascara.common.util.CommandLine.ParseResult.Builder | Builds immutable ParseResult instances. |
| public static | io.github.qishr.cascara.common.util.CommandLine.ParseResult.GroupMatch | A group's multiplicity specifies how many matches of a group may appear on the command line. |
| public static | io.github.qishr.cascara.common.util.CommandLine.ParseResult.GroupMatchContainer | Provides information about an ArgGroup that was matched on the command line. |
Method Summary
| Modifier and Type | Method | Description |
|---|---|---|
| public static Builder | builder(CommandSpec commandSpec) | Creates and returns a new ParseResult.Builder for the specified command spec. |
| public List<GroupMatchContainer> | findMatches(ArgGroupSpec group) | Returns the matches for the specified argument group. |
| public List<GroupMatch> | getGroupMatches() | Returns the top-level container for the ArgGroupSpec match or matches found. |
| public OptionSpec | matchedOption(char shortName) | Returns the option with the specified short name, or null if no option with that name was matched on the command line. |
| public OptionSpec | matchedOption(String name) | Returns the option with the specified name, or null if no option with that name was matched on the command line. |
| public PositionalParamSpec | matchedPositional(int position) | Returns the first PositionalParamSpec that matched an argument at the specified position, or null if no positional parameters were matched at that position. |
| public List<PositionalParamSpec> | matchedPositionals(int position) | Returns all PositionalParamSpec objects that matched an argument at the specified position, or an empty list if no positional parameters were matched at that position. |
| public CommandSpec | commandSpec() | Returns the CommandSpec for the matched command. |
| public boolean | hasMatchedOption(char shortName) | Returns whether an option whose aliases include the specified short name was matched on the command line. |
| public boolean | hasMatchedOption(String name) | Returns whether an option whose aliases include the specified name was matched on the command line. |
| public boolean | hasMatchedOption(OptionSpec option) | Returns whether the specified option was matched on the command line. |
| public boolean | hasMatchedPositional(int position) | Returns whether a positional parameter was matched at the specified position. |
| public boolean | hasMatchedPositional(PositionalParamSpec positional) | Returns whether the specified positional parameter was matched on the command line. |
| public Set<OptionSpec> | matchedOptionsSet() | Returns a set of matched options. |
| public List<OptionSpec> | matchedOptions() | Returns a list of matched options, in order they were matched on the command line. |
| public Set<PositionalParamSpec> | matchedPositionalsSet() | Returns a set of matched positional parameters. |
| public List<PositionalParamSpec> | matchedPositionals() | Returns a list of matched positional parameters, in order they were matched on the command line. |
| public List<ArgSpec> | matchedArgs() | Returns a list of matched options and positional parameters, in order they were matched on the command line. |
| public List<String> | unmatched() | Returns a list of command line arguments that did not match any options or positional parameters. |
| public List<String> | originalArgs() | Returns the original command line arguments that were passed to the CommandLine#parseArgs(String...) method, before @-file expansion. |
| public List<String> | expandedArgs() | Returns the command line arguments after @-files were expanded; these are the arguments that were actually parsed. |
| public List<Exception> | errors() | If ParserSpec#collectErrors is true, returns the list of exceptions that were encountered during parsing, otherwise, returns an empty list. |
| public T | matchedOptionValue(char shortName, T defaultValue) | Returns the command line argument value of the option with the specified name, converted to the type of the option, or the specified default value if no option with the specified name was matched. |
| public T | matchedOptionValue(String name, T defaultValue) | Returns the command line argument value of the option with the specified name, converted to the type of the option, or the specified default value if no option with the specified name was matched. |
| public T | matchedPositionalValue(int position, T defaultValue) | Returns the command line argument value of the positional parameter at the specified position, converted to the type of the positional parameter, or the specified default value if no positional parameter was matched at that position. |
| public boolean | hasSubcommand() | Returns true if a subcommand was matched on the command line, false otherwise. |
| public ParseResult | subcommand() | Returns the ParseResult for the last subcommand of this command that was matched on the command line, or null if no subcommand was matched. |
| public List<ParseResult> | subcommands() | Returns a list with the ParseResult objects for each subcommand of this command that was matched on the command line or an empty list if no subcommands were matched. |
| public boolean | isUsageHelpRequested() | Returns true if one of the options that was matched on the command line is a OptionSpec#usageHelp() option. |
| public boolean | isVersionHelpRequested() | Returns true if one of the options that was matched on the command line is a OptionSpec#versionHelp() option. |
| public List<CommandLine> | asCommandLineList() | Returns this ParseResult as a list of CommandLine objects, one for each matched command/subcommand. |
Method Details
builder
public static Builder builder(CommandSpec commandSpec)
Creates and returns a new ParseResult.Builder for the specified command spec.
findMatches
public List<GroupMatchContainer> findMatches(ArgGroupSpec group)
Returns the matches for the specified argument group.
Since:
4.0
getGroupMatches
public List<GroupMatch> getGroupMatches()
Returns the top-level container for the ArgGroupSpec match or matches found.
If the user input was a valid combination of group arguments, the returned list should contain a single GroupMatch. Details of the GroupMatchContainer encountered on the command line can be obtained via its GroupMatch#matchedSubgroups() method. The top-level match returned by this method contains no matched arguments.
If the returned list contains more than one GroupMatch, the user input was invalid:
the maximum multiplicity of a group was exceeded, and the parser created an extra
match to capture the values. Usually this results in a ParameterException
being thrown by the parse method, unless the parser is configured to collect errors.
Since:
4.0
matchedOption
public OptionSpec matchedOption(char shortName)
Returns the option with the specified short name, or null if no option with that name was matched
on the command line.
Use OptionSpec#getValue() on the returned OptionSpec to get the matched value (or values),
converted to the type of the option. Alternatively, use OptionSpec#stringValues()
to get the matched String values after they were split into parts, or
OptionSpec#originalStringValues() to get the original String values that were
matched on the command line, before any processing.
To get the default value of an option that was
hasMatchedOption.hasMatchedOption on the command line, use
parseResult.commandSpec().findOption(shortName).getValue().
See Also:
matchedOption
public OptionSpec matchedOption(String name)
Returns the option with the specified name, or null if no option with that name was matched on the command line.
Use OptionSpec#getValue() on the returned OptionSpec to get the matched value (or values),
converted to the type of the option. Alternatively, use OptionSpec#stringValues()
to get the matched String values after they were split into parts, or
OptionSpec#originalStringValues() to get the original String values that were
matched on the command line, before any processing.
To get the default value of an option that was
hasMatchedOption.hasMatchedOption on the command line, use
parseResult.commandSpec().findOption(String).getValue().
Parameters:
name - used to search the matched options. May be an alias of the option name that was actually specified on the command line.
The specified name may include option name prefix characters or not.
See Also:
matchedPositional
public PositionalParamSpec matchedPositional(int position)
Returns the first PositionalParamSpec that matched an argument at the specified position, or null if no positional parameters were matched at that position.
matchedPositionals
public List<PositionalParamSpec> matchedPositionals(int position)
Returns all PositionalParamSpec objects that matched an argument at the specified position, or an empty list if no positional parameters were matched at that position.
commandSpec
public CommandSpec commandSpec()
Returns the CommandSpec for the matched command.
hasMatchedOption
public boolean hasMatchedOption(char shortName)
Returns whether an option whose aliases include the specified short name was matched on the command line.
Parameters:
shortName - used to search the matched options. May be an alias of the option name that was actually specified on the command line.
hasMatchedOption
public boolean hasMatchedOption(String name)
Returns whether an option whose aliases include the specified name was matched on the command line.
Parameters:
name - used to search the matched options. May be an alias of the option name that was actually specified on the command line.
The specified name may include option name prefix characters or not.
hasMatchedOption
public boolean hasMatchedOption(OptionSpec option)
Returns whether the specified option was matched on the command line.
hasMatchedPositional
public boolean hasMatchedPositional(int position)
Returns whether a positional parameter was matched at the specified position.
hasMatchedPositional
public boolean hasMatchedPositional(PositionalParamSpec positional)
Returns whether the specified positional parameter was matched on the command line.
matchedOptionsSet
public Set<OptionSpec> matchedOptionsSet()
Returns a set of matched options.
Since:
4.0
matchedOptions
public List<OptionSpec> matchedOptions()
Returns a list of matched options, in order they were matched on the command line.The returned list may contain the same OptionSpec multiple times, if the option was matched multiple times on the command line.
matchedPositionalsSet
public Set<PositionalParamSpec> matchedPositionalsSet()
Returns a set of matched positional parameters.
Since:
4.0
matchedPositionals
public List<PositionalParamSpec> matchedPositionals()
Returns a list of matched positional parameters, in order they were matched on the command line.The returned list may contain the same PositionalParamSpec multiple times, if the parameter was matched multiple times on the command line.
matchedArgs
public List<ArgSpec> matchedArgs()
Returns a list of matched options and positional parameters, in order they were matched on the command line.The returned list may contain an OptionSpec or PositionalParamSpec multiple times, if the option or parameter was matched multiple times on the command line.
Since:
4.0
unmatched
public List<String> unmatched()
Returns a list of command line arguments that did not match any options or positional parameters.
originalArgs
public List<String> originalArgs()
Returns the original command line arguments that were passed to the CommandLine#parseArgs(String...) method, before @-file expansion.
See Also:
expandedArgs
public List<String> expandedArgs()
Returns the command line arguments after @-files were expanded; these are the arguments that were actually parsed.
Since:
4.4
See Also:
errors
public List<Exception> errors()
If ParserSpec#collectErrors is true, returns the list of exceptions that were encountered during parsing, otherwise, returns an empty list.
Since:
3.2
matchedOptionValue
public T matchedOptionValue(char shortName, T defaultValue)
Returns the command line argument value of the option with the specified name, converted to the type of the option, or the specified default value if no option with the specified name was matched.
matchedOptionValue
public T matchedOptionValue(String name, T defaultValue)
Returns the command line argument value of the option with the specified name, converted to the type of the option, or the specified default value if no option with the specified name was matched.
matchedPositionalValue
public T matchedPositionalValue(int position, T defaultValue)
Returns the command line argument value of the positional parameter at the specified position, converted to the type of the positional parameter, or the specified default value if no positional parameter was matched at that position.
hasSubcommand
public boolean hasSubcommand()
Returns true if a subcommand was matched on the command line, false otherwise.
subcommand
public ParseResult subcommand()
Returns the ParseResult for the last subcommand of this command that was matched on the command line, or null if no subcommand was matched.
subcommands
public List<ParseResult> subcommands()
Returns a list with the ParseResult objects for each subcommand of this command
that was matched on the command line or an empty list if no subcommands were matched.The returned list can only contain multiple values if this command's CommandSpec#subcommandsRepeatable() attribute is true.
Since:
4.2
isUsageHelpRequested
public boolean isUsageHelpRequested()
Returns true if one of the options that was matched on the command line is a OptionSpec#usageHelp() option.
isVersionHelpRequested
public boolean isVersionHelpRequested()
Returns true if one of the options that was matched on the command line is a OptionSpec#versionHelp() option.
asCommandLineList
public List<CommandLine> asCommandLineList()
Returns this ParseResult as a list of CommandLine objects, one for each matched command/subcommand.Note that for repeatable subcommands, there may be multiple commands at each level of the hierarchy in the returned list.
Since:
3.0