-
- All Superinterfaces:
ArgumentContainer
- All Known Subinterfaces:
Subparser
- All Known Implementing Classes:
ArgumentParserImpl
,SubparserImpl
public interface ArgumentParser extends ArgumentContainer
This interface defines behavior of ArgumentParser.
The typical usage is set description using
description(String)
and add arguments usingArgumentContainer.addArgument(String...)
. To add sub-command, first calladdSubparsers()
to obtainSubparsers
object.Subparsers
object provides necessary methods to add sub-commands. To make a conceptual group of arguments, first calladdArgumentGroup(String)
to createArgumentGroup
object. And add argument to that group usingArgumentContainer.addArgument(String...)
. Similarly, to add the mutually exclusive group of arguments, useaddMutuallyExclusiveGroup(String)
to createMutuallyExclusiveGroup
object. To parse command-line arguments, callparseArgs(String[])
or several overloaded methods.
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description ArgumentGroup
addArgumentGroup(java.lang.String title)
Creates newArgumentGroup
object and adds to this parser and returns the object.MutuallyExclusiveGroup
addMutuallyExclusiveGroup()
Creates new mutually exclusive group,MutuallyExclusiveGroup
object, without title and adds to this parser and returns the object.MutuallyExclusiveGroup
addMutuallyExclusiveGroup(java.lang.String title)
Creates new mutually exclusive group,MutuallyExclusiveGroup
object, and adds to this parser and returns the object.Subparsers
addSubparsers()
ReturnsSubparsers
.ArgumentParser
defaultHelp(boolean defaultHelp)
If defaultHelp istrue
, the default values of arguments are printed in help message.ArgumentParser
description(java.lang.String description)
Sets the description for the arguments of this container.ArgumentParser
epilog(java.lang.String epilog)
Sets the text to display after the argument help.java.lang.String
formatHelp()
Returns help message.java.lang.String
formatUsage()
Returns a brief description of how the program should be invoked on the command line.java.lang.String
formatVersion()
Returns version string.ArgumentParserConfiguration
getConfig()
Get the configuration of this argument parser.java.lang.Object
getDefault(java.lang.String dest)
Returns default value of givendest
.void
handleError(ArgumentParserException e)
Prints usage and error message.void
handleError(ArgumentParserException e, java.io.PrintWriter writer)
Prints usage and error message to the given writer.Namespace
parseArgs(java.lang.String[] args)
Parses command line arguments.void
parseArgs(java.lang.String[] args, java.lang.Object userData)
Parses command line arguments.void
parseArgs(java.lang.String[] args, java.util.Map<java.lang.String,java.lang.Object> attrs)
Parses command line arguments.void
parseArgs(java.lang.String[] args, java.util.Map<java.lang.String,java.lang.Object> attrs, java.lang.Object userData)
Parses command line arguments.Namespace
parseArgsOrFail(java.lang.String[] args)
Parses command line arguments, handling any errors.Namespace
parseKnownArgs(java.lang.String[] args, java.util.List<java.lang.String> unknown)
Just likeparseArgs(String[])
, but parses only known arguments without throwing exception for unrecognized arguments.void
parseKnownArgs(java.lang.String[] args, java.util.List<java.lang.String> unknown, java.lang.Object userData)
Just likeparseArgs(String[], Object)
, but parses only known arguments without throwing exception for unrecognized arguments.void
parseKnownArgs(java.lang.String[] args, java.util.List<java.lang.String> unknown, java.util.Map<java.lang.String,java.lang.Object> attrs)
Just likeparseArgs(String[], Map)
, but parses only known arguments without throwing exception for unrecognized arguments.void
parseKnownArgs(java.lang.String[] args, java.util.List<java.lang.String> unknown, java.util.Map<java.lang.String,java.lang.Object> attrs, java.lang.Object userData)
Just likeparseArgs(String[], Map, Object)
, but parses only known arguments without throwing exception for unrecognized arguments.Namespace
parseKnownArgsOrFail(java.lang.String[] args, java.util.List<java.lang.String> unknown)
Just likeparseArgsOrFail(String[])
, but parses only known arguments without throwing exception for unrecognized arguments.void
printHelp()
Prints help message in stdout.void
printHelp(java.io.PrintWriter writer)
Prints help message in writer.void
printUsage()
Print a brief description of how the program should be invoked on the command line in stdout.void
printUsage(java.io.PrintWriter writer)
Print a brief description of how the program should be invoked on the command line in writer.void
printVersion()
Prints version string in stdout.void
printVersion(java.io.PrintWriter writer)
Prints version string in writer.ArgumentParser
setDefault(java.lang.String dest, java.lang.Object value)
Sets parser-level default value of attributedest
.ArgumentParser
setDefaults(java.util.Map<java.lang.String,java.lang.Object> attrs)
Sets parser-level default values fromattrs
.ArgumentParser
usage(java.lang.String usage)
Sets the text to display as usage line.ArgumentParser
version(java.lang.String version)
Sets version string.-
Methods inherited from interface net.sourceforge.argparse4j.inf.ArgumentContainer
addArgument
-
-
-
-
Method Detail
-
addArgumentGroup
ArgumentGroup addArgumentGroup(java.lang.String title)
Creates new
ArgumentGroup
object and adds to this parser and returns the object.The
title
is printed in help message as a title of this group.ArgumentGroup
provides a way to conceptually group up command line arguments.- Parameters:
title
- The title printed in help message.- Returns:
ArgumentGroup
object.
-
addMutuallyExclusiveGroup
MutuallyExclusiveGroup addMutuallyExclusiveGroup()
Creates new mutually exclusive group,
MutuallyExclusiveGroup
object, without title and adds to this parser and returns the object.- Returns:
MutuallyExclusiveGroup
object.
-
addMutuallyExclusiveGroup
MutuallyExclusiveGroup addMutuallyExclusiveGroup(java.lang.String title)
Creates new mutually exclusive group,
MutuallyExclusiveGroup
object, and adds to this parser and returns the object.The arguments added to this group are mutually exclusive; if more than one argument belong to the group are specified, an error will be reported. The
title
is printed in help message as a title of this group.- Parameters:
title
- The title printed in help message.- Returns:
- The
MutuallyExclusiveGroup
object.
-
addSubparsers
Subparsers addSubparsers()
Returns
Subparsers
.The method name is rather controversial because repeated call of this method does not add new
Subparsers
object. Instead, this method always returns sameSubparsers
object.Subparsers
object provides a way to add sub-commands.- Returns:
Subparsers
object.
-
usage
ArgumentParser usage(java.lang.String usage)
Sets the text to display as usage line. By default, the usage line is calculated from the arguments this object contains.
If the given usage contains
${prog}
string, it will be replaced with the program name given inArgumentParsers.newArgumentParser(String)
.- Parameters:
usage
- usage text- Returns:
- this
-
description
ArgumentParser description(java.lang.String description)
Description copied from interface:ArgumentContainer
Sets the description for the arguments of this container.- Specified by:
description
in interfaceArgumentContainer
- Parameters:
description
- The description of this container.- Returns:
- this
-
epilog
ArgumentParser epilog(java.lang.String epilog)
Sets the text to display after the argument help.- Parameters:
epilog
- The text to display after the argument help.- Returns:
- this
-
version
ArgumentParser version(java.lang.String version)
Sets version string. It will be displayed
printVersion()
.If the given usage contains
${prog}
string, it will be replaced with the program name given inArgumentParsers.newArgumentParser(String)
. This processed text will be printed without text-wrapping.- Parameters:
version
- The version string.- Returns:
- this
-
defaultHelp
ArgumentParser defaultHelp(boolean defaultHelp)
If defaultHelp is
true
, the default values of arguments are printed in help message.By default, the default values are not printed in help message.
- Parameters:
defaultHelp
- Switch to display the default value in help message.- Returns:
- this
-
printHelp
void printHelp()
Prints help message in stdout.
-
printHelp
void printHelp(java.io.PrintWriter writer)
Prints help message in writer.- Parameters:
writer
- Writer to print message.
-
formatHelp
java.lang.String formatHelp()
Returns help message.- Returns:
- The help message.
-
printUsage
void printUsage()
Print a brief description of how the program should be invoked on the command line in stdout.
-
printUsage
void printUsage(java.io.PrintWriter writer)
Print a brief description of how the program should be invoked on the command line in writer.- Parameters:
writer
- Writer to print message.
-
formatUsage
java.lang.String formatUsage()
Returns a brief description of how the program should be invoked on the command line.- Returns:
- Usage text.
-
printVersion
void printVersion()
Prints version string in stdout.
-
printVersion
void printVersion(java.io.PrintWriter writer)
Prints version string in writer.- Parameters:
writer
- Writer to print version string.
-
formatVersion
java.lang.String formatVersion()
Returns version string.- Returns:
- The version string.
-
setDefault
ArgumentParser setDefault(java.lang.String dest, java.lang.Object value)
Sets parser-level default value of attribute
dest
.The parser-level defaults always override argument-level defaults.
- Parameters:
dest
- The attribute name.value
- The default value.- Returns:
- this
-
setDefaults
ArgumentParser setDefaults(java.util.Map<java.lang.String,java.lang.Object> attrs)
Sets parser-level default values from
attrs
.All key-value pair in
attrs
are registered to parser-level defaults. The parser-level defaults always override argument-level defaults.- Parameters:
attrs
- The parser-level default values to add.- Returns:
- this
-
getDefault
java.lang.Object getDefault(java.lang.String dest)
Returns default value of given
dest
.Returns default value set by
Argument.setDefault(Object)
,setDefault(String, Object)
orsetDefaults(Map)
. Please note that while parser-level defaults always override argument-level defaults while parsing, this method examines argument-level defaults first. If no default value is found, then check parser-level defaults. If no default value is found, returnsnull
.- Parameters:
dest
- The attribute name of default value to get.- Returns:
- The default value of given dest.
-
parseArgsOrFail
Namespace parseArgsOrFail(java.lang.String[] args)
Parses command line arguments, handling any errors.
This is a shortcut method that combines
parseArgs(java.lang.String[])
andhandleError(net.sourceforge.argparse4j.inf.ArgumentParserException)
. If the arguments can be successfully parsed, the resulted attributes are returned as aNamespace
object. Otherwise, the program exits with a1
return code.- Parameters:
args
- Command line arguments.- Returns:
Namespace
object.
-
parseArgs
Namespace parseArgs(java.lang.String[] args) throws ArgumentParserException
Parses command line arguments.
The resulted attributes are returned as
Namespace
object. This method must not alter the status of this parser and can be called multiple times.- Parameters:
args
- Command line arguments.- Returns:
Namespace
object.- Throws:
ArgumentParserException
- If an error occurred.
-
parseArgs
void parseArgs(java.lang.String[] args, java.util.Map<java.lang.String,java.lang.Object> attrs) throws ArgumentParserException
Parses command line arguments.
Unlike
parseArgs(String[])
, which returnsNamespace
object, this method stores attributes in givenattrs
.- Parameters:
args
- Command line arguments.attrs
- Map object to store attributes.- Throws:
ArgumentParserException
- If an error occurred.
-
parseArgs
void parseArgs(java.lang.String[] args, java.lang.Object userData) throws ArgumentParserException
Parses command line arguments.
Unlike
parseArgs(String[])
, which returnsNamespace
object, this method stores attributes in givenuserData
. The location to store value is designated usingArg
annotations. User don't have to specifyArg
for all attributes: the missing attributes are just skipped. This method performs simpleList
to generic array conversion. For example, user can assignList<Integer>
attribute to generic arrayint[]
.- Parameters:
args
- Command line arguments.userData
- Object to store attributes.- Throws:
ArgumentParserException
- If an error occurred.
-
parseArgs
void parseArgs(java.lang.String[] args, java.util.Map<java.lang.String,java.lang.Object> attrs, java.lang.Object userData) throws ArgumentParserException
Parses command line arguments.
This is a combination of
parseArgs(String[], Map)
andparseArgs(String[], Object)
. The all attributes will be stored inattrs
. The attributes specified inArg
annotations will be also stored inuserData
.- Parameters:
args
- Command line arguments.attrs
- Map to store attributes.userData
- Object to store attributes.- Throws:
ArgumentParserException
- If an error occurred.
-
parseKnownArgsOrFail
Namespace parseKnownArgsOrFail(java.lang.String[] args, java.util.List<java.lang.String> unknown)
Just like
parseArgsOrFail(String[])
, but parses only known arguments without throwing exception for unrecognized arguments. Ifunknown
is not null, unrecognized arguments will be stored in it.- Parameters:
args
- Command line arguments.unknown
- Output variable to store unrecognized arguments, or null- Returns:
Namespace
object.- Since:
- 0.7.0
-
parseKnownArgs
Namespace parseKnownArgs(java.lang.String[] args, java.util.List<java.lang.String> unknown) throws ArgumentParserException
Just like
parseArgs(String[])
, but parses only known arguments without throwing exception for unrecognized arguments. Ifunknown
is not null, unrecognized arguments will be stored in it.- Parameters:
args
- Command line arguments.unknown
- Output variable to store unrecognized arguments, or null- Returns:
Namespace
object.- Throws:
ArgumentParserException
- If an error occurred.- Since:
- 0.7.0
-
parseKnownArgs
void parseKnownArgs(java.lang.String[] args, java.util.List<java.lang.String> unknown, java.util.Map<java.lang.String,java.lang.Object> attrs) throws ArgumentParserException
Just like
parseArgs(String[], Map)
, but parses only known arguments without throwing exception for unrecognized arguments. Ifunknown
is not null, unrecognized arguments will be stored in it.- Parameters:
args
- Command line arguments.unknown
- Output variable to store unrecognized arguments, or nullattrs
- Map object to store attributes.- Throws:
ArgumentParserException
- If an error occurred.- Since:
- 0.7.0
-
parseKnownArgs
void parseKnownArgs(java.lang.String[] args, java.util.List<java.lang.String> unknown, java.lang.Object userData) throws ArgumentParserException
Just like
parseArgs(String[], Object)
, but parses only known arguments without throwing exception for unrecognized arguments. Ifunknown
is not null, unrecognized arguments will be stored in it.- Parameters:
args
- Command line arguments.unknown
- Output variable to store unrecognized arguments, or nulluserData
- Object to store attributes.- Throws:
ArgumentParserException
- If an error occurred.- Since:
- 0.7.0
-
parseKnownArgs
void parseKnownArgs(java.lang.String[] args, java.util.List<java.lang.String> unknown, java.util.Map<java.lang.String,java.lang.Object> attrs, java.lang.Object userData) throws ArgumentParserException
Just like
parseArgs(String[], Map, Object)
, but parses only known arguments without throwing exception for unrecognized arguments. Ifunknown
is not null, unrecognized arguments will be stored in it.- Parameters:
args
- Command line arguments.unknown
- Output variable to store unrecognized arguments, or nullattrs
- Map to store attributes.userData
- Object to store attributes.- Throws:
ArgumentParserException
- If an error occurred.- Since:
- 0.7.0
-
handleError
void handleError(ArgumentParserException e)
Prints usage and error message.
Please note that this method does not terminate the program.
- Parameters:
e
- Error thrown byparseArgs(String[])
.
-
handleError
void handleError(ArgumentParserException e, java.io.PrintWriter writer)
Prints usage and error message to the given writer.
Please note that this method does not terminate the program.
- Parameters:
e
- Error thrown byparseArgs(String[])
.writer
- The writer to which to write error messages- Since:
- 0.8.0
-
getConfig
ArgumentParserConfiguration getConfig()
Get the configuration of this argument parser.
- Returns:
- The argument parser configuration.
- Since:
- 0.8.0
-
-