/*
* 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();
}
}
}