/*
|
* Copyright (C) 2010 The Android Open Source Project
|
*
|
* Licensed under the Apache License, Version 2.0 (the "License");
|
* you may not use this file except in compliance with the License.
|
* You may obtain a copy of the License at
|
*
|
* http://www.apache.org/licenses/LICENSE-2.0
|
*
|
* Unless required by applicable law or agreed to in writing, software
|
* distributed under the License is distributed on an "AS IS" BASIS,
|
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
* See the License for the specific language governing permissions and
|
* limitations under the License.
|
*/
|
|
package vogar;
|
|
import com.google.common.collect.Lists;
|
import java.io.File;
|
import java.io.IOException;
|
import java.lang.reflect.Field;
|
import java.lang.reflect.ParameterizedType;
|
import java.lang.reflect.Type;
|
import java.util.ArrayList;
|
import java.util.Arrays;
|
import java.util.Collection;
|
import java.util.HashMap;
|
import java.util.Iterator;
|
import java.util.List;
|
import java.util.Map;
|
import vogar.util.Strings;
|
|
/**
|
* Parses command line options.
|
*
|
* Strings in the passed-in String[] are parsed left-to-right. Each
|
* String is classified as a short option (such as "-v"), a long
|
* option (such as "--verbose"), an argument to an option (such as
|
* "out.txt" in "-f out.txt"), or a non-option positional argument.
|
*
|
* A simple short option is a "-" followed by a short option
|
* character. If the option requires an argument (which is true of any
|
* non-boolean option), it may be written as a separate parameter, but
|
* need not be. That is, "-f out.txt" and "-fout.txt" are both
|
* acceptable.
|
*
|
* It is possible to specify multiple short options after a single "-"
|
* as long as all (except possibly the last) do not require arguments.
|
*
|
* A long option begins with "--" followed by several characters. If
|
* the option requires an argument, it may be written directly after
|
* the option name, separated by "=", or as the next argument. (That
|
* is, "--file=out.txt" or "--file out.txt".)
|
*
|
* A boolean long option '--name' automatically gets a '--no-name'
|
* companion. Given an option "--flag", then, "--flag", "--no-flag",
|
* "--flag=true" and "--flag=false" are all valid, though neither
|
* "--flag true" nor "--flag false" are allowed (since "--flag" by
|
* itself is sufficient, the following "true" or "false" is
|
* interpreted separately). You can use "yes" and "no" as synonyms for
|
* "true" and "false".
|
*
|
* Each String not starting with a "-" and not a required argument of
|
* a previous option is a non-option positional argument, as are all
|
* successive Strings. Each String after a "--" is a non-option
|
* positional argument.
|
*
|
* Parsing of numeric fields such byte, short, int, long, float, and
|
* double fields is supported. This includes both unboxed and boxed
|
* versions (e.g. int vs Integer). If there is a problem parsing the
|
* argument to match the desired type, a runtime exception is thrown.
|
*
|
* File option fields are supported by simply wrapping the string
|
* argument in a File object without testing for the existance of the
|
* file.
|
*
|
* Parameterized Collection fields such as List<File> and Set<String>
|
* are supported as long as the parameter type is otherwise supported
|
* by the option parser. The collection field should be initialized
|
* with an appropriate collection instance.
|
*
|
* Enum types are supported. Input may be in either CONSTANT_CASE or
|
* lower_case.
|
*
|
* The fields corresponding to options are updated as their options
|
* are processed. Any remaining positional arguments are returned as a
|
* List<String>.
|
*
|
* Here's a simple example:
|
*
|
* // This doesn't need to be a separate class, if your application doesn't warrant it.
|
* // Non-@Option fields will be ignored.
|
* class Options {
|
* @Option(names = { "-q", "--quiet" })
|
* boolean quiet = false;
|
*
|
* // Boolean options require a long name if it's to be possible to explicitly turn them off.
|
* // Here the user can use --no-color.
|
* @Option(names = { "--color" })
|
* boolean color = true;
|
*
|
* @Option(names = { "-m", "--mode" })
|
* String mode = "standard; // Supply a default just by setting the field.
|
*
|
* @Option(names = { "-p", "--port" })
|
* int portNumber = 8888;
|
*
|
* // There's no need to offer a short name for rarely-used options.
|
* @Option(names = { "--timeout" })
|
* double timeout = 1.0;
|
*
|
* @Option(names = { "-o", "--output-file" })
|
* File output;
|
*
|
* // Multiple options are added to the collection.
|
* // The collection field itself must be non-null.
|
* @Option(names = { "-i", "--input-file" })
|
* List<File> inputs = new ArrayList<File>();
|
*
|
* }
|
*
|
* class Main {
|
* public static void main(String[] args) {
|
* Options options = new Options();
|
* List<String> inputFilenames = new OptionParser(options).parse(args);
|
* for (String inputFilename : inputFilenames) {
|
* if (!options.quiet) {
|
* ...
|
* }
|
* ...
|
* }
|
* }
|
* }
|
*
|
* See also:
|
*
|
* the getopt(1) man page
|
* Python's "optparse" module (http://docs.python.org/library/optparse.html)
|
* the POSIX "Utility Syntax Guidelines" (http://www.opengroup.org/onlinepubs/000095399/basedefs/xbd_chap12.html#tag_12_02)
|
* the GNU "Standards for Command Line Interfaces" (http://www.gnu.org/prep/standards/standards.html#Command_002dLine-Interfaces)
|
*/
|
public class OptionParser {
|
private static final HashMap<Class<?>, Handler> handlers = new HashMap<Class<?>, Handler>();
|
static {
|
handlers.put(boolean.class, new BooleanHandler());
|
handlers.put(Boolean.class, new BooleanHandler());
|
|
handlers.put(byte.class, new ByteHandler());
|
handlers.put(Byte.class, new ByteHandler());
|
handlers.put(short.class, new ShortHandler());
|
handlers.put(Short.class, new ShortHandler());
|
handlers.put(int.class, new IntegerHandler());
|
handlers.put(Integer.class, new IntegerHandler());
|
handlers.put(long.class, new LongHandler());
|
handlers.put(Long.class, new LongHandler());
|
|
handlers.put(float.class, new FloatHandler());
|
handlers.put(Float.class, new FloatHandler());
|
handlers.put(double.class, new DoubleHandler());
|
handlers.put(Double.class, new DoubleHandler());
|
|
handlers.put(String.class, new StringHandler());
|
handlers.put(File.class, new FileHandler());
|
}
|
Handler getHandler(Type type) {
|
if (type instanceof ParameterizedType) {
|
ParameterizedType parameterizedType = (ParameterizedType) type;
|
Class rawClass = (Class<?>) parameterizedType.getRawType();
|
if (!Collection.class.isAssignableFrom(rawClass)) {
|
throw new RuntimeException("cannot handle non-collection parameterized type " + type);
|
}
|
Type actualType = parameterizedType.getActualTypeArguments()[0];
|
if (!(actualType instanceof Class)) {
|
throw new RuntimeException("cannot handle nested parameterized type " + type);
|
}
|
return getHandler(actualType);
|
}
|
if (type instanceof Class) {
|
Class<?> classType = (Class) type;
|
if (Collection.class.isAssignableFrom(classType)) {
|
// could handle by just having a default of treating
|
// contents as String but consciously decided this
|
// should be an error
|
throw new RuntimeException(
|
"cannot handle non-parameterized collection " + type + ". " +
|
"use a generic Collection to specify a desired element type");
|
}
|
if (classType.isEnum()) {
|
return new EnumHandler(classType);
|
}
|
return handlers.get(classType);
|
}
|
throw new RuntimeException("cannot handle unknown field type " + type);
|
}
|
|
private final Object optionSource;
|
private final HashMap<String, Field> optionMap;
|
private final Map<Field, Object> defaultOptionMap;
|
|
/**
|
* Constructs a new OptionParser for setting the @Option fields of 'optionSource'.
|
*/
|
public OptionParser(Object optionSource) {
|
this.optionSource = optionSource;
|
this.optionMap = makeOptionMap();
|
this.defaultOptionMap = new HashMap<Field, Object>();
|
}
|
|
public static String[] readFile(File configFile) {
|
if (!configFile.exists()) {
|
return new String[0];
|
}
|
|
List<String> configFileLines;
|
try {
|
configFileLines = Strings.readFileLines(configFile);
|
} catch (IOException e) {
|
throw new RuntimeException(e);
|
}
|
|
List<String> argsList = Lists.newArrayList();
|
for (String rawLine : configFileLines) {
|
String line = rawLine.trim();
|
|
// allow comments and blank lines
|
if (line.startsWith("#") || line.isEmpty()) {
|
continue;
|
}
|
int space = line.indexOf(' ');
|
if (space == -1) {
|
argsList.add(line);
|
} else {
|
argsList.add(line.substring(0, space));
|
argsList.add(line.substring(space + 1).trim());
|
}
|
}
|
|
return argsList.toArray(new String[argsList.size()]);
|
}
|
|
/**
|
* Parses the command-line arguments 'args', setting the @Option fields of the 'optionSource' provided to the constructor.
|
* Returns a list of the positional arguments left over after processing all options.
|
*/
|
public List<String> parse(String[] args) {
|
return parseOptions(Arrays.asList(args).iterator());
|
}
|
|
private List<String> parseOptions(Iterator<String> args) {
|
final List<String> leftovers = new ArrayList<String>();
|
|
// Scan 'args'.
|
while (args.hasNext()) {
|
final String arg = args.next();
|
if (arg.equals("--")) {
|
// "--" marks the end of options and the beginning of positional arguments.
|
break;
|
} else if (arg.startsWith("--")) {
|
// A long option.
|
parseLongOption(arg, args);
|
} else if (arg.startsWith("-")) {
|
// A short option.
|
parseGroupedShortOptions(arg, args);
|
} else {
|
// The first non-option marks the end of options.
|
leftovers.add(arg);
|
break;
|
}
|
}
|
|
// Package up the leftovers.
|
while (args.hasNext()) {
|
leftovers.add(args.next());
|
}
|
return leftovers;
|
}
|
|
private Field fieldForArg(String name) {
|
final Field field = optionMap.get(name);
|
if (field == null) {
|
throw new RuntimeException("unrecognized option '" + name + "'");
|
}
|
return field;
|
}
|
|
private void parseLongOption(String arg, Iterator<String> args) {
|
String name = arg.replaceFirst("^--no-", "--");
|
String value = null;
|
|
// Support "--name=value" as well as "--name value".
|
final int equalsIndex = name.indexOf('=');
|
if (equalsIndex != -1) {
|
value = name.substring(equalsIndex + 1);
|
name = name.substring(0, equalsIndex);
|
}
|
|
final Field field = fieldForArg(name);
|
final Handler handler = getHandler(field.getGenericType());
|
if (value == null) {
|
if (handler.isBoolean()) {
|
value = arg.startsWith("--no-") ? "false" : "true";
|
} else {
|
value = grabNextValue(args, name, field);
|
}
|
}
|
setValue(field, arg, handler, value);
|
}
|
|
// Given boolean options a and b, and non-boolean option f, we want to allow:
|
// -ab
|
// -abf out.txt
|
// -abfout.txt
|
// (But not -abf=out.txt --- POSIX doesn't mention that either way, but GNU expressly forbids it.)
|
private void parseGroupedShortOptions(String arg, Iterator<String> args) {
|
for (int i = 1; i < arg.length(); ++i) {
|
final String name = "-" + arg.charAt(i);
|
final Field field = fieldForArg(name);
|
final Handler handler = getHandler(field.getGenericType());
|
String value;
|
if (handler.isBoolean()) {
|
value = "true";
|
} else {
|
// We need a value. If there's anything left, we take the rest of this "short option".
|
if (i + 1 < arg.length()) {
|
value = arg.substring(i + 1);
|
i = arg.length() - 1;
|
} else {
|
value = grabNextValue(args, name, field);
|
}
|
}
|
setValue(field, arg, handler, value);
|
}
|
}
|
|
@SuppressWarnings("unchecked")
|
private void setValue(Field field, String arg, Handler handler, String valueText) {
|
|
Object value = handler.translate(valueText);
|
if (value == null) {
|
final String type = field.getType().getSimpleName().toLowerCase();
|
throw new RuntimeException("couldn't convert '" + valueText + "' to a " + type + " for option '" + arg + "'");
|
}
|
try {
|
field.setAccessible(true);
|
// record the original value of the field so it can be reset
|
if (!defaultOptionMap.containsKey(field)) {
|
defaultOptionMap.put(field, field.get(optionSource));
|
}
|
if (Collection.class.isAssignableFrom(field.getType())) {
|
Collection collection = (Collection) field.get(optionSource);
|
collection.add(value);
|
} else {
|
field.set(optionSource, value);
|
}
|
} catch (IllegalAccessException ex) {
|
throw new RuntimeException("internal error", ex);
|
}
|
}
|
|
/**
|
* Resets optionSource's fields to their defaults
|
*/
|
public void reset() {
|
for (Map.Entry<Field, Object> entry : defaultOptionMap.entrySet()) {
|
try {
|
entry.getKey().set(optionSource, entry.getValue());
|
} catch (IllegalAccessException e) {
|
throw new RuntimeException(e);
|
}
|
}
|
}
|
|
// Returns the next element of 'args' if there is one. Uses 'name' and 'field' to construct a helpful error message.
|
private String grabNextValue(Iterator<String> args, String name, Field field) {
|
if (!args.hasNext()) {
|
final String type = field.getType().getSimpleName().toLowerCase();
|
throw new RuntimeException("option '" + name + "' requires a " + type + " argument");
|
}
|
return args.next();
|
}
|
|
// Cache the available options and report any problems with the options themselves right away.
|
private HashMap<String, Field> makeOptionMap() {
|
final HashMap<String, Field> optionMap = new HashMap<String, Field>();
|
final Class<?> optionClass = optionSource.getClass();
|
for (Field field : optionClass.getDeclaredFields()) {
|
if (field.isAnnotationPresent(Option.class)) {
|
final Option option = field.getAnnotation(Option.class);
|
final String[] names = option.names();
|
if (names.length == 0) {
|
throw new RuntimeException("found an @Option with no name!");
|
}
|
for (String name : names) {
|
if (optionMap.put(name, field) != null) {
|
throw new RuntimeException("found multiple @Options sharing the name '" + name + "'");
|
}
|
}
|
if (getHandler(field.getGenericType()) == null) {
|
throw new RuntimeException("unsupported @Option field type '" + field.getType() + "'");
|
}
|
}
|
}
|
return optionMap;
|
}
|
|
static abstract class Handler {
|
// Only BooleanHandler should ever override this.
|
boolean isBoolean() {
|
return false;
|
}
|
|
/**
|
* Returns an object of appropriate type for the given Handle, corresponding to 'valueText'.
|
* Returns null on failure.
|
*/
|
abstract Object translate(String valueText);
|
}
|
|
static class BooleanHandler extends Handler {
|
@Override boolean isBoolean() {
|
return true;
|
}
|
|
Object translate(String valueText) {
|
if (valueText.equalsIgnoreCase("true") || valueText.equalsIgnoreCase("yes")) {
|
return Boolean.TRUE;
|
} else if (valueText.equalsIgnoreCase("false") || valueText.equalsIgnoreCase("no")) {
|
return Boolean.FALSE;
|
}
|
return null;
|
}
|
}
|
|
static class ByteHandler extends Handler {
|
Object translate(String valueText) {
|
try {
|
return Byte.parseByte(valueText);
|
} catch (NumberFormatException ex) {
|
return null;
|
}
|
}
|
}
|
|
static class ShortHandler extends Handler {
|
Object translate(String valueText) {
|
try {
|
return Short.parseShort(valueText);
|
} catch (NumberFormatException ex) {
|
return null;
|
}
|
}
|
}
|
|
static class IntegerHandler extends Handler {
|
Object translate(String valueText) {
|
try {
|
return Integer.parseInt(valueText);
|
} catch (NumberFormatException ex) {
|
return null;
|
}
|
}
|
}
|
|
static class LongHandler extends Handler {
|
Object translate(String valueText) {
|
try {
|
return Long.parseLong(valueText);
|
} catch (NumberFormatException ex) {
|
return null;
|
}
|
}
|
}
|
|
static class FloatHandler extends Handler {
|
Object translate(String valueText) {
|
try {
|
return Float.parseFloat(valueText);
|
} catch (NumberFormatException ex) {
|
return null;
|
}
|
}
|
}
|
|
static class DoubleHandler extends Handler {
|
Object translate(String valueText) {
|
try {
|
return Double.parseDouble(valueText);
|
} catch (NumberFormatException ex) {
|
return null;
|
}
|
}
|
}
|
|
static class StringHandler extends Handler {
|
Object translate(String valueText) {
|
return valueText;
|
}
|
}
|
|
@SuppressWarnings("unchecked") // creating an instance with a non-enum type is an error!
|
static class EnumHandler extends Handler {
|
private final Class<?> enumType;
|
|
public EnumHandler(Class<?> enumType) {
|
this.enumType = enumType;
|
}
|
|
Object translate(String valueText) {
|
try {
|
return Enum.valueOf((Class) enumType, valueText.toUpperCase());
|
} catch (IllegalArgumentException e) {
|
return null;
|
}
|
}
|
}
|
|
static class FileHandler extends Handler {
|
Object translate(String valueText) {
|
return new File(valueText).getAbsoluteFile();
|
}
|
}
|
}
|
