eu.tneitzel.argparse4j.inf

Interface ArgumentParser

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 using ArgumentContainer.addArgument(String...). To add sub-command, first call addSubparsers() to obtain Subparsers object. Subparsers object provides necessary methods to add sub-commands. To make a conceptual group of arguments, first call addArgumentGroup(String) to create ArgumentGroup object. And add argument to that group using ArgumentContainer.addArgument(String...) . Similarly, to add the mutually exclusive group of arguments, use addMutuallyExclusiveGroup(String) to create MutuallyExclusiveGroup object. To parse command-line arguments, call parseArgs(String[]) or several overloaded methods.

Method Summary

Modifier and Type	Method and Description
ArgumentGroup	addArgumentGroup(String title) Creates new ArgumentGroup 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(String title) Creates new mutually exclusive group, MutuallyExclusiveGroup object, and adds to this parser and returns the object.
Subparsers	addSubparsers() Returns Subparsers.
ArgumentParser	defaultHelp(boolean defaultHelp) If defaultHelp is true, the default values of arguments are printed in help message.
ArgumentParser	description(String description) Sets the description for the arguments of this container.
ArgumentParser	epilog(String epilog) Sets the text to display after the argument help.
String	formatHelp() Returns help message.
String	formatUsage() Returns a brief description of how the program should be invoked on the command line.
String	formatVersion() Returns version string.
ArgumentGroup	getArgumentGroup(String title) Returns an already existing ArgumentGroup object that was added to the parser.
ArgumentParserConfiguration	getConfig() Get the configuration of this argument parser.
Object	getDefault(String dest) Returns default value of given dest.
ArgumentGroup	getOrCreateArgumentGroup(String title) Returns an already existing ArgumentGroup object that was added to the parser.
void	handleError(ArgumentParserException e) Prints usage and error message.
void	handleError(ArgumentParserException e, PrintWriter writer) Prints usage and error message to the given writer.
Namespace	parseArgs(String[] args) Parses command line arguments.
void	parseArgs(String[] args, Map<String,Object> attrs) Parses command line arguments.
void	parseArgs(String[] args, Map<String,Object> attrs, Object userData) Parses command line arguments.
void	parseArgs(String[] args, Object userData) Parses command line arguments.
Namespace	parseArgsOrFail(String[] args) Parses command line arguments, handling any errors.
Namespace	parseKnownArgs(String[] args, List<String> unknown) Just like parseArgs(String[]), but parses only known arguments without throwing exception for unrecognized arguments.
void	parseKnownArgs(String[] args, List<String> unknown, Map<String,Object> attrs) Just like parseArgs(String[], Map), but parses only known arguments without throwing exception for unrecognized arguments.
void	parseKnownArgs(String[] args, List<String> unknown, Map<String,Object> attrs, Object userData) Just like parseArgs(String[], Map, Object), but parses only known arguments without throwing exception for unrecognized arguments.
void	parseKnownArgs(String[] args, List<String> unknown, Object userData) Just like parseArgs(String[], Object), but parses only known arguments without throwing exception for unrecognized arguments.
Namespace	parseKnownArgsOrFail(String[] args, List<String> unknown) Just like parseArgsOrFail(String[]), but parses only known arguments without throwing exception for unrecognized arguments.
void	printHelp() Prints help message in stdout.
void	printHelp(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(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(PrintWriter writer) Prints version string in writer.
ArgumentParser	setDefault(String dest, Object value) Sets parser-level default value of attribute dest.
ArgumentParser	setDefaults(Map<String,Object> attrs) Sets parser-level default values from attrs.
ArgumentParser	usage(String usage) Sets the text to display as usage line.
ArgumentParser	version(String version) Sets version string.

Methods inherited from interface eu.tneitzel.argparse4j.inf.ArgumentContainer

addArgument

Method Detail

addArgumentGroup

ArgumentGroup addArgumentGroup(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.

getArgumentGroup

ArgumentGroup getArgumentGroup(String title)

Returns an already existing ArgumentGroup object that was added to the parser. Groups are looked up by name. If no group with the specified name is found, null is returned.

Parameters:

title - The title of the group to look for.

Returns:

ArgumentGroup object.

getOrCreateArgumentGroup

ArgumentGroup getOrCreateArgumentGroup(String title)

Returns an already existing ArgumentGroup object that was added to the parser. Groups are looked up by name. If no group with the specified name is found, a new one is created.

Parameters:

title - The title of the group to look for.

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(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 same Subparsers object. Subparsers object provides a way to add sub-commands.

Returns:

Subparsers object.

usage

ArgumentParser usage(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 in ArgumentParsers.newArgumentParser(String).

Parameters:

usage - usage text

Returns:

this

description

ArgumentParser description(String description)

Description copied from interface: ArgumentContainer

Sets the description for the arguments of this container.

Specified by:

description in interface ArgumentContainer

Parameters:

description - The description of this container.

Returns:

this

epilog

ArgumentParser epilog(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(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 in ArgumentParsers.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(PrintWriter writer)

Prints help message in writer.

Parameters:

writer - Writer to print message.

formatHelp

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(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

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(PrintWriter writer)

Prints version string in writer.

Parameters:

writer - Writer to print version string.

formatVersion

String formatVersion()

Returns version string.

Returns:

The version string.

setDefault

ArgumentParser setDefault(String dest,
                          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(Map<String,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

Object getDefault(String dest)

Returns default value of given dest.

Returns default value set by Argument.setDefault(Object), setDefault(String, Object) or setDefaults(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, returns null.

Parameters:

dest - The attribute name of default value to get.

Returns:

The default value of given dest.

parseArgsOrFail

Namespace parseArgsOrFail(String[] args)

Parses command line arguments, handling any errors.

This is a shortcut method that combines parseArgs(java.lang.String[]) and handleError(eu.tneitzel.argparse4j.inf.ArgumentParserException). If the arguments can be successfully parsed, the resulted attributes are returned as a Namespace object. Otherwise, the program exits with a 1 return code.

Parameters:

args - Command line arguments.

Returns:

Namespace object.

parseArgs

Namespace parseArgs(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(String[] args,
               Map<String,Object> attrs)
        throws ArgumentParserException

Parses command line arguments.

Unlike parseArgs(String[]), which returns Namespace object, this method stores attributes in given attrs.

Parameters:

args - Command line arguments.

attrs - Map object to store attributes.

Throws:

ArgumentParserException - If an error occurred.

parseArgs

void parseArgs(String[] args,
               Object userData)
        throws ArgumentParserException

Parses command line arguments.

Unlike parseArgs(String[]), which returns Namespace object, this method stores attributes in given userData. The location to store value is designated using Arg annotations. User don't have to specify Arg for all attributes: the missing attributes are just skipped. This method performs simple List to generic array conversion. For example, user can assign List<Integer> attribute to generic array int[].

Parameters:

args - Command line arguments.

userData - Object to store attributes.

Throws:

ArgumentParserException - If an error occurred.

parseArgs

void parseArgs(String[] args,
               Map<String,Object> attrs,
               Object userData)
        throws ArgumentParserException

Parses command line arguments.

This is a combination of parseArgs(String[], Map) and parseArgs(String[], Object). The all attributes will be stored in attrs. The attributes specified in Arg annotations will be also stored in userData.

Parameters:

args - Command line arguments.

attrs - Map to store attributes.

userData - Object to store attributes.

Throws:

ArgumentParserException - If an error occurred.

parseKnownArgsOrFail

Namespace parseKnownArgsOrFail(String[] args,
                               List<String> unknown)

Just like parseArgsOrFail(String[]), but parses only known arguments without throwing exception for unrecognized arguments. If unknown 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(String[] args,
                         List<String> unknown)
                  throws ArgumentParserException

Just like parseArgs(String[]), but parses only known arguments without throwing exception for unrecognized arguments. If unknown 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(String[] args,
                    List<String> unknown,
                    Map<String,Object> attrs)
             throws ArgumentParserException

Just like parseArgs(String[], Map), but parses only known arguments without throwing exception for unrecognized arguments. If unknown is not null, unrecognized arguments will be stored in it.

Parameters:

args - Command line arguments.

unknown - Output variable to store unrecognized arguments, or null

attrs - Map object to store attributes.

Throws:

ArgumentParserException - If an error occurred.

Since:

0.7.0

parseKnownArgs

void parseKnownArgs(String[] args,
                    List<String> unknown,
                    Object userData)
             throws ArgumentParserException

Just like parseArgs(String[], Object), but parses only known arguments without throwing exception for unrecognized arguments. If unknown is not null, unrecognized arguments will be stored in it.

Parameters:

args - Command line arguments.

unknown - Output variable to store unrecognized arguments, or null

userData - Object to store attributes.

Throws:

ArgumentParserException - If an error occurred.

Since:

0.7.0

parseKnownArgs

void parseKnownArgs(String[] args,
                    List<String> unknown,
                    Map<String,Object> attrs,
                    Object userData)
             throws ArgumentParserException

Just like parseArgs(String[], Map, Object), but parses only known arguments without throwing exception for unrecognized arguments. If unknown is not null, unrecognized arguments will be stored in it.

Parameters:

args - Command line arguments.

unknown - Output variable to store unrecognized arguments, or null

attrs - 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 by parseArgs(String[]).

handleError

void handleError(ArgumentParserException e,
                 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 by parseArgs(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