eu.tneitzel.argparse4j.inf.ArgumentParser Maven / Gradle / Ivy
Show all versions of argparse4j Show documentation
/*
* Copyright (C) 2011 Tatsuhiro Tsujikawa
*
* Permission is hereby granted, free of charge, to any person
* obtaining a copy of this software and associated documentation
* files (the "Software"), to deal in the Software without
* restriction, including without limitation the rights to use, copy,
* modify, merge, publish, distribute, sublicense, and/or sell copies
* of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be
* included in all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
* NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
* BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
* ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
* CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
* SOFTWARE.
*/
package eu.tneitzel.argparse4j.inf;
import java.io.PrintWriter;
import java.util.List;
import java.util.Map;
import eu.tneitzel.argparse4j.ArgumentParsers;
import eu.tneitzel.argparse4j.annotation.Arg;
/**
*
* This interface defines behavior of ArgumentParser.
*
*
* The typical usage is set description using {@link #description(String)} and
* add arguments using {@link #addArgument(String...)}. To add sub-command,
* first call {@link #addSubparsers()} to obtain {@link Subparsers} object.
* {@link Subparsers} object provides necessary methods to add sub-commands. To
* make a conceptual group of arguments, first call
* {@link #addArgumentGroup(String)} to create {@link ArgumentGroup} object. And
* add argument to that group using {@link ArgumentGroup#addArgument(String...)}
* . Similarly, to add the mutually exclusive group of arguments, use
* {@link #addMutuallyExclusiveGroup(String)} to create
* {@link MutuallyExclusiveGroup} object. To parse command-line arguments, call
* {@link #parseArgs(String[])} or several overloaded methods.
*
*/
public interface ArgumentParser extends ArgumentContainer {
/**
*
* Creates new {@link ArgumentGroup} object and adds to this parser and
* returns the object.
*
*
* The {@code title} is printed in help message as a title of this group.
* {@link ArgumentGroup} provides a way to conceptually group up command
* line arguments.
*
*
* @param title
* The title printed in help message.
* @return {@link ArgumentGroup} object.
*/
ArgumentGroup addArgumentGroup(String title);
/**
*
* Returns an already existing {@link 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.
*
*
* @param title
* The title of the group to look for.
* @return {@link ArgumentGroup} object.
*/
ArgumentGroup getArgumentGroup(String title);
/**
*
* Returns an already existing {@link 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.
*
*
* @param title
* The title of the group to look for.
* @return {@link ArgumentGroup} object.
*/
ArgumentGroup getOrCreateArgumentGroup(String title);
/**
*
* Creates new mutually exclusive group, {@link MutuallyExclusiveGroup}
* object, without title and adds to this parser and returns the object.
*
*
* @return {@link MutuallyExclusiveGroup} object.
*/
MutuallyExclusiveGroup addMutuallyExclusiveGroup();
/**
*
* Creates new mutually exclusive group, {@link 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 {@code title} is printed in help message as a title of this
* group.
*
*
* @param title
* The title printed in help message.
* @return The {@link MutuallyExclusiveGroup} object.
*/
MutuallyExclusiveGroup addMutuallyExclusiveGroup(String title);
/**
*
* Returns {@link Subparsers}.
*
*
* The method name is rather controversial because repeated call of this
* method does not add new {@link Subparsers} object. Instead, this method
* always returns same {@link Subparsers} object. {@link Subparsers} object
* provides a way to add sub-commands.
*
*
* @return {@link Subparsers} object.
*/
Subparsers addSubparsers();
/**
*
* 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
* {@link ArgumentParsers#newArgumentParser(String)}.
*
*
* @param usage
* usage text
* @return this
*/
ArgumentParser usage(String usage);
@Override
ArgumentParser description(String description);
/**
* Sets the text to display after the argument help.
*
* @param epilog
* The text to display after the argument help.
* @return this
*/
ArgumentParser epilog(String epilog);
/**
*
* Sets version string. It will be displayed {@link #printVersion()}.
*
*
* If the given usage contains ${prog} string, it will be replaced
* with the program name given in
* {@link ArgumentParsers#newArgumentParser(String)}. This processed text
* will be printed without text-wrapping.
*
*
* @param version
* The version string.
* @return this
*/
ArgumentParser version(String version);
/**
*
* If defaultHelp is {@code true}, the default values of arguments are
* printed in help message.
*
*
* By default, the default values are not printed in help message.
*
*
* @param defaultHelp
* Switch to display the default value in help message.
* @return this
*/
ArgumentParser defaultHelp(boolean defaultHelp);
/**
* Prints help message in stdout.
*/
void printHelp();
/**
* Prints help message in writer.
*
* @param writer
* Writer to print message.
*/
void printHelp(PrintWriter writer);
/**
* Returns help message.
*
* @return The help message.
*/
String formatHelp();
/**
* Print a brief description of how the program should be invoked on the
* command line in stdout.
*/
void printUsage();
/**
* Print a brief description of how the program should be invoked on the
* command line in writer.
*
* @param writer
* Writer to print message.
*/
void printUsage(PrintWriter writer);
/**
* Returns a brief description of how the program should be invoked on the
* command line.
*
* @return Usage text.
*/
String formatUsage();
/**
* Prints version string in stdout.
*/
void printVersion();
/**
* Prints version string in writer.
*
* @param writer
* Writer to print version string.
*/
void printVersion(PrintWriter writer);
/**
* Returns version string.
*
* @return The version string.
*/
String formatVersion();
/**
*
* Sets parser-level default value of attribute {@code dest}.
*
*
* The parser-level defaults always override argument-level defaults.
*
*
* @param dest
* The attribute name.
* @param value
* The default value.
* @return this
*/
ArgumentParser setDefault(String dest, Object value);
/**
*
* Sets parser-level default values from {@code attrs}.
*
*
* All key-value pair in {@code attrs} are registered to parser-level
* defaults. The parser-level defaults always override argument-level
* defaults.
*
*
* @param attrs
* The parser-level default values to add.
* @return this
*/
ArgumentParser setDefaults(Map attrs);
/**
*
* Returns default value of given {@code dest}.
*
*
* Returns default value set by {@link Argument#setDefault(Object)},
* {@link ArgumentParser#setDefault(String, Object)} or
* {@link #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
* {@code null}.
*
*
* @param dest
* The attribute name of default value to get.
* @return The default value of given dest.
*/
Object getDefault(String dest);
/**
*
* Parses command line arguments, handling any errors.
*
*
* This is a shortcut method that combines {@link #parseArgs} and
* {@link #handleError }. If the arguments can be successfully parsed, the
* resulted attributes are returned as a {@link Namespace} object.
* Otherwise, the program exits with a 1 return code.
*
*
*
* @param args
* Command line arguments.
* @return {@link Namespace} object.
*/
Namespace parseArgsOrFail(String[] args);
/**
*
* Parses command line arguments.
*
*
* The resulted attributes are returned as {@link Namespace} object. This
* method must not alter the status of this parser and can be called
* multiple times.
*
*
* @param args
* Command line arguments.
* @return {@link Namespace} object.
* @throws ArgumentParserException
* If an error occurred.
*/
Namespace parseArgs(String[] args) throws ArgumentParserException;
/**
*
* Parses command line arguments.
*
*
* Unlike {@link #parseArgs(String[])}, which returns {@link Namespace}
* object, this method stores attributes in given {@code attrs}.
*
*
* @param args
* Command line arguments.
* @param attrs
* Map object to store attributes.
* @throws ArgumentParserException
* If an error occurred.
*/
void parseArgs(String[] args, Map attrs)
throws ArgumentParserException;
/**
*
* Parses command line arguments.
*
*
* Unlike {@link #parseArgs(String[])}, which returns {@link Namespace}
* object, this method stores attributes in given {@code userData}. The
* location to store value is designated using {@link Arg} annotations. User
* don't have to specify {@link Arg} for all attributes: the missing
* attributes are just skipped. This method performs simple {@link List} to
* generic array conversion. For example, user can assign
* {@code List} attribute to generic array {@code int[]}.
*
*
* @param args
* Command line arguments.
* @param userData
* Object to store attributes.
* @throws ArgumentParserException
* If an error occurred.
*/
void parseArgs(String[] args, Object userData)
throws ArgumentParserException;
/**
*
* Parses command line arguments.
*
*
* This is a combination of {@link #parseArgs(String[], Map)} and
* {@link #parseArgs(String[], Object)}. The all attributes will be stored
* in {@code attrs}. The attributes specified in {@link Arg} annotations
* will be also stored in {@code userData}.
*
*
* @param args
* Command line arguments.
* @param attrs
* Map to store attributes.
* @param userData
* Object to store attributes.
* @throws ArgumentParserException
* If an error occurred.
*/
void parseArgs(String[] args, Map attrs, Object userData)
throws ArgumentParserException;
/**
*
* Just like {@link #parseArgsOrFail(String[])}, but parses only known
* arguments without throwing exception for unrecognized arguments. If
* {@code unknown} is not null, unrecognized arguments will be stored in it.
*
*
* @param args
* Command line arguments.
* @param unknown
* Output variable to store unrecognized arguments, or null
* @return {@link Namespace} object.
* @since 0.7.0
*/
Namespace parseKnownArgsOrFail(String[] args, List unknown);
/**
*
* Just like {@link #parseArgs(String[])}, but parses only known arguments
* without throwing exception for unrecognized arguments. If {@code unknown}
* is not null, unrecognized arguments will be stored in it.
*
*
* @param args
* Command line arguments.
* @param unknown
* Output variable to store unrecognized arguments, or null
* @return {@link Namespace} object.
* @throws ArgumentParserException
* If an error occurred.
* @since 0.7.0
*/
Namespace parseKnownArgs(String[] args, List unknown)
throws ArgumentParserException;
/**
*
* Just like {@link #parseArgs(String[], Map)}, but parses only known
* arguments without throwing exception for unrecognized arguments. If
* {@code unknown} is not null, unrecognized arguments will be stored in it.
*
*
* @param args
* Command line arguments.
* @param unknown
* Output variable to store unrecognized arguments, or null
* @param attrs
* Map object to store attributes.
* @throws ArgumentParserException
* If an error occurred.
* @since 0.7.0
*/
void parseKnownArgs(String[] args, List unknown,
Map attrs) throws ArgumentParserException;
/**
*
* Just like {@link #parseArgs(String[], Object)}, but parses only known
* arguments without throwing exception for unrecognized arguments. If
* {@code unknown} is not null, unrecognized arguments will be stored in it.
*
*
* @param args
* Command line arguments.
* @param unknown
* Output variable to store unrecognized arguments, or null
* @param userData
* Object to store attributes.
* @throws ArgumentParserException
* If an error occurred.
* @since 0.7.0
*/
void parseKnownArgs(String[] args, List unknown, Object userData)
throws ArgumentParserException;
/**
*
* Just like {@link #parseArgs(String[], Map, Object)}, but parses only
* known arguments without throwing exception for unrecognized arguments. If
* {@code unknown} is not null, unrecognized arguments will be stored in it.
*
*
* @param args
* Command line arguments.
* @param unknown
* Output variable to store unrecognized arguments, or null
* @param attrs
* Map to store attributes.
* @param userData
* Object to store attributes.
* @throws ArgumentParserException
* If an error occurred.
* @since 0.7.0
*/
void parseKnownArgs(String[] args, List unknown,
Map attrs, Object userData)
throws ArgumentParserException;
/**
*
* Prints usage and error message.
*
*
* Please note that this method does not terminate the program.
*
*
* @param e
* Error thrown by {@link #parseArgs(String[])}.
*/
void handleError(ArgumentParserException e);
/**
*
* Prints usage and error message to the given writer.
*
*
* Please note that this method does not terminate the program.
*
*
* @param e
* Error thrown by {@link #parseArgs(String[])}.
* @param writer
* The writer to which to write error messages
* @since 0.8.0
*/
void handleError(ArgumentParserException e, PrintWriter writer);
/**
*
* Get the configuration of this argument parser.
*
*
* @return The argument parser configuration.
* @since 0.8.0
*/
ArgumentParserConfiguration getConfig();
}