org.apache.commons.cli

Class DefaultParser

java.lang.Object

org.apache.commons.cli.DefaultParser

All Implemented Interfaces:

CommandLineParser

public class DefaultParser
extends Object
implements CommandLineParser

Default parser.

Since:

1.3

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	DefaultParser.Builder	A nested builder class to create DefaultParser instances using descriptive methods.
static class	DefaultParser.NonOptionAction	Enum representing possible actions that may be done when "non option" is discovered during parsing.

Field Summary

Fields

Modifier and Type	Field	Description
protected CommandLine	cmd	The command-line instance.
protected Option	currentOption	The last option parsed.
protected String	currentToken	The token currently processed.
protected List	expectedOpts	The required options and groups expected to be found when parsing the command line.
protected DefaultParser.NonOptionAction	nonOptionAction	Action to happen when "non option" token is discovered.
protected Options	options	The current options.
protected boolean	skipParsing	Flag indicating if tokens should no longer be analyzed and simply added as arguments of the command line.
protected boolean	stopAtNonOption	Deprecated. Use nonOptionAction instead. This field is unused, and left for binary compatibility reasons.

Constructor Summary

Constructors

Constructor	Description
DefaultParser()	Creates a new DefaultParser instance with partial matching enabled.
DefaultParser(boolean allowPartialMatching)	Create a new DefaultParser instance with the specified partial matching policy.

Method Summary

Modifier and Type	Method	Description
protected void	addArg(String token)	Adds token to command line CommandLine.addArg(String).
static DefaultParser.Builder	builder()	Creates a new DefaultParser.Builder to create an DefaultParser using descriptive methods.
protected void	checkRequiredOptions()	Throws a MissingOptionException if all of the required options are not present.
protected void	handleConcatenatedOptions(String token)	Breaks token into its constituent parts using the following algorithm.
protected void	handleUnknownToken(String token)	Handles an unknown token.
CommandLine	parse(Options options, Properties properties, DefaultParser.NonOptionAction nonOptionAction, String... arguments)	Parses the arguments according to the specified options and properties.
CommandLine	parse(Options options, String[] arguments)	Parses the arguments according to the specified options.
CommandLine	parse(Options options, String[] arguments, boolean stopAtNonOption)	Parses the arguments according to the specified options.
CommandLine	parse(Options options, String[] arguments, Properties properties)	Parses the arguments according to the specified options and properties.
CommandLine	parse(Options options, String[] arguments, Properties properties, boolean stopAtNonOption)	Parses the arguments according to the specified options and properties.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

cmd

protected CommandLine cmd

The command-line instance.

options

protected Options options

The current options.

stopAtNonOption

@Deprecated
protected boolean stopAtNonOption

Deprecated. Use nonOptionAction instead. This field is unused, and left for binary compatibility reasons.

Flag indicating how unrecognized tokens are handled. true to stop the parsing and add the remaining tokens to the args list. false to throw an exception.

nonOptionAction

protected DefaultParser.NonOptionAction nonOptionAction

Action to happen when "non option" token is discovered.

Since:

1.10.0

currentToken

protected String currentToken

The token currently processed.

currentOption

protected Option currentOption

The last option parsed.

skipParsing

protected boolean skipParsing

Flag indicating if tokens should no longer be analyzed and simply added as arguments of the command line.

expectedOpts

protected List expectedOpts

The required options and groups expected to be found when parsing the command line.

Constructor Detail

DefaultParser

public DefaultParser()

Creates a new DefaultParser instance with partial matching enabled.

By "partial matching" we mean that given the following code:

 final Options options = new Options();
 options.addOption(new Option("d", "debug", false, "Turn on debug."));
 options.addOption(new Option("e", "extract", false, "Turn on extract."));
 options.addOption(new Option("o", "option", true, "Turn on option with argument."));
 
 

with "partial matching" turned on, -de only matches the "debug" option. However, with "partial matching" disabled, -de would enable both debug as well as extract options.

DefaultParser

public DefaultParser(boolean allowPartialMatching)

Create a new DefaultParser instance with the specified partial matching policy.

By "partial matching" we mean that given the following code:

     final Options options = new Options();
     options.addOption(new Option("d", "debug", false, "Turn on debug."));
     options.addOption(new Option("e", "extract", false, "Turn on extract."));
     options.addOption(new Option("o", "option", true, "Turn on option with argument."));
 
 

with "partial matching" turned on, -de only matches the "debug" option. However, with "partial matching" disabled, -de would enable both debug as well as extract options.

Parameters:

allowPartialMatching - if partial matching of long options shall be enabled

Method Detail

builder

public static DefaultParser.Builder builder()

Creates a new DefaultParser.Builder to create an DefaultParser using descriptive methods.

Returns:

a new DefaultParser.Builder instance

Since:

1.5.0

addArg

protected void addArg(String token)

Adds token to command line CommandLine.addArg(String).

Parameters:

token - the unrecognized option/argument.

Since:

1.10.0

checkRequiredOptions

protected void checkRequiredOptions()
                             throws MissingOptionException

Throws a MissingOptionException if all of the required options are not present.

Throws:

MissingOptionException - if any of the required Options are not present.

handleConcatenatedOptions

protected void handleConcatenatedOptions(String token)
                                  throws ParseException

Breaks token into its constituent parts using the following algorithm.

• ignore the first character ("-")
• for each remaining character check if an Option exists with that id.
• if an Option does exist then add that character prepended with "-" to the list of processed tokens.
• if the Option can have an argument value and there are remaining characters in the token then add the remaining characters as a token to the list of processed tokens.
• if an Option does NOT exist AND stopAtNonOption IS set then add the special token "--" followed by the remaining characters and also the remaining tokens directly to the processed tokens list.
• if an Option does NOT exist AND stopAtNonOption IS NOT set then add that character prepended with "-".

Parameters:

token - The current token to be burst at the first non-Option encountered.

Throws:

ParseException - if there are any problems encountered while parsing the command line token.

handleUnknownToken

protected void handleUnknownToken(String token)
                           throws ParseException

Handles an unknown token. If the token starts with a dash an UnrecognizedOptionException is thrown. Otherwise the token is added to the arguments of the command line. If the stopAtNonOption flag is set, this stops the parsing and the remaining tokens are added as-is in the arguments of the command line.

Parameters:

token - the command line token to handle.

Throws:

ParseException - if parsing should fail.

Since:

1.10.0

parse

public CommandLine parse(Options options,
                         Properties properties,
                         DefaultParser.NonOptionAction nonOptionAction,
                         String... arguments)
                  throws ParseException

Parses the arguments according to the specified options and properties.

Parameters:

options - the specified Options

properties - command line option name-value pairs

nonOptionAction - see DefaultParser.NonOptionAction.

arguments - the command line arguments

Returns:

the list of atomic option and value tokens.

Throws:

ParseException - if there are any problems encountered while parsing the command line tokens.

Since:

1.10.0

parse

public CommandLine parse(Options options,
                         String[] arguments)
                  throws ParseException

Description copied from interface: CommandLineParser

Parses the arguments according to the specified options.

Specified by:

parse in interface CommandLineParser

Parameters:

options - the specified Options.

arguments - the command line arguments.

Returns:

the list of atomic option and value tokens.

Throws:

ParseException - if there are any problems encountered while parsing the command line tokens.

parse

public CommandLine parse(Options options,
                         String[] arguments,
                         boolean stopAtNonOption)
                  throws ParseException

Description copied from interface: CommandLineParser

Parses the arguments according to the specified options.

Specified by:

parse in interface CommandLineParser

Parameters:

options - the specified Options.

arguments - the command line arguments.

stopAtNonOption - if true an unrecognized argument stops the parsing and the remaining arguments are added to the CommandLines args list. If false an unrecognized argument triggers a ParseException.

Returns:

the list of atomic option and value tokens.

Throws:

ParseException - if there are any problems encountered while parsing the command line tokens.

See Also:

parse(Options, Properties, NonOptionAction, String[])

parse

public CommandLine parse(Options options,
                         String[] arguments,
                         Properties properties)
                  throws ParseException

Parses the arguments according to the specified options and properties.

Parameters:

options - the specified Options.

arguments - the command line arguments.

properties - command line option name-value pairs.

Returns:

the list of atomic option and value tokens.

Throws:

ParseException - if there are any problems encountered while parsing the command line tokens.

parse

public CommandLine parse(Options options,
                         String[] arguments,
                         Properties properties,
                         boolean stopAtNonOption)
                  throws ParseException

Parses the arguments according to the specified options and properties.

Parameters:

options - the specified Options.

arguments - the command line arguments.

properties - command line option name-value pairs.

stopAtNonOption - if true an unrecognized argument stops the parsing and the remaining arguments are added to the CommandLines args list. If false an unrecognized argument triggers a ParseException.

Returns:

the list of atomic option and value tokens.

Throws:

ParseException - if there are any problems encountered while parsing the command line tokens.

See Also:

parse(Options, Properties, NonOptionAction, String[])