/*
* Copyright (C) 2011 Google Inc.
*
* 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 com.google.caliper.options;
import static com.google.common.base.Preconditions.checkArgument;
import com.google.caliper.util.DisplayUsageException;
import com.google.caliper.util.InvalidCommandException;
import com.google.caliper.util.Parser;
import com.google.caliper.util.Parsers;
import com.google.common.base.Throwables;
import com.google.common.collect.ImmutableList;
import com.google.common.collect.ImmutableMap;
import com.google.common.collect.Iterators;
import com.google.common.collect.Lists;
import com.google.common.primitives.Primitives;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
import java.lang.reflect.Field;
import java.lang.reflect.InvocationTargetException;
import java.lang.reflect.Method;
import java.lang.reflect.Modifier;
import java.lang.reflect.Type;
import java.text.ParseException;
import java.util.Iterator;
import java.util.List;
// based on r135 of OptionParser.java from vogar
// NOTE: this class is still pretty messy but will be cleaned up further and possibly offered to
// Guava.
/**
* 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.
*
* The fields corresponding to options are updated as their options are processed. Any remaining
* positional arguments are returned as an ImmutableList<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" }) String outputFile;
*
* }
*
* 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)
*/
final class CommandLineParser<T> {
/**
* Annotates a field or method in an options class to signify that parsed values should be
* injected.
*/
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.FIELD, ElementType.METHOD})
public @interface Option {
/**
* The names for this option, such as { "-h", "--help" }. Names must start with one or two '-'s.
* An option must have at least one name.
*/
String[] value();
}
/**
* Annotates a single method in an options class to receive any "leftover" arguments. The method
* must accept {@code ImmutableList<String>} or a supertype. The method will be invoked even if
* the list is empty.
*/
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.FIELD, ElementType.METHOD})
public @interface Leftovers {}
public static <T> CommandLineParser<T> forClass(Class<? extends T> c) {
return new CommandLineParser<T>(c);
}
private final InjectionMap injectionMap;
private T injectee;
// TODO(kevinb): make a helper object that can be mutated during processing
private final List<PendingInjection> pendingInjections = Lists.newArrayList();
/**
* Constructs a new command-line parser that will inject values into {@code injectee}.
*
* @throws IllegalArgumentException if {@code injectee} contains multiple options using the same
* name
*/
private CommandLineParser(Class<? extends T> c) {
this.injectionMap = InjectionMap.forClass(c);
}
/**
* 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 void parseAndInject(String[] args, T injectee) throws InvalidCommandException {
this.injectee = injectee;
pendingInjections.clear();
Iterator<String> argsIter = Iterators.forArray(args);
ImmutableList.Builder<String> builder = ImmutableList.builder();
while (argsIter.hasNext()) {
String arg = argsIter.next();
if (arg.equals("--")) {
break; // "--" marks the end of options and the beginning of positional arguments.
} else if (arg.startsWith("--")) {
parseLongOption(arg, argsIter);
} else if (arg.startsWith("-")) {
parseShortOptions(arg, argsIter);
} else {
builder.add(arg);
// allow positional arguments to mix with options since many linux commands do
}
}
for (PendingInjection pi : pendingInjections) {
pi.injectableOption.inject(pi.value, injectee);
}
ImmutableList<String> leftovers = builder.addAll(argsIter).build();
invokeMethod(injectee, injectionMap.leftoversMethod, leftovers);
}
// Private stuff from here on down
private abstract static class InjectableOption {
abstract boolean isBoolean();
abstract void inject(String valueText, Object injectee) throws InvalidCommandException;
boolean delayedInjection() {
return false;
}
}
private static class InjectionMap {
public static InjectionMap forClass(Class<?> injectedClass) {
ImmutableMap.Builder<String, InjectableOption> builder = ImmutableMap.builder();
InjectableOption helpOption = new InjectableOption() {
@Override boolean isBoolean() {
return true;
}
@Override void inject(String valueText, Object injectee) throws DisplayUsageException {
throw new DisplayUsageException();
}
};
builder.put("-h", helpOption);
builder.put("--help", helpOption);
Method leftoverMethod = null;
for (Field field : injectedClass.getDeclaredFields()) {
checkArgument(!field.isAnnotationPresent(Leftovers.class),
"Sorry, @Leftovers only works for methods at present"); // TODO(kevinb)
Option option = field.getAnnotation(Option.class);
if (option != null) {
InjectableOption injectable = FieldOption.create(field);
for (String optionName : option.value()) {
builder.put(optionName, injectable);
}
}
}
for (Method method : injectedClass.getDeclaredMethods()) {
if (method.isAnnotationPresent(Leftovers.class)) {
checkArgument(!isStaticOrAbstract(method),
"@Leftovers method cannot be static or abstract");
checkArgument(!method.isAnnotationPresent(Option.class),
"method has both @Option and @Leftovers");
checkArgument(leftoverMethod == null, "Two methods have @Leftovers");
method.setAccessible(true);
leftoverMethod = method;
// TODO: check type is a supertype of ImmutableList<String>
}
Option option = method.getAnnotation(Option.class);
if (option != null) {
InjectableOption injectable = MethodOption.create(method);
for (String optionName : option.value()) {
builder.put(optionName, injectable);
}
}
}
ImmutableMap<String, InjectableOption> optionMap = builder.build();
return new InjectionMap(optionMap, leftoverMethod);
}
final ImmutableMap<String, InjectableOption> optionMap;
final Method leftoversMethod;
InjectionMap(ImmutableMap<String, InjectableOption> optionMap, Method leftoversMethod) {
this.optionMap = optionMap;
this.leftoversMethod = leftoversMethod;
}
InjectableOption getInjectableOption(String optionName) throws InvalidCommandException {
InjectableOption injectable = optionMap.get(optionName);
if (injectable == null) {
throw new InvalidCommandException("Invalid option: %s", optionName);
}
return injectable;
}
}
private static class FieldOption extends InjectableOption {
private static InjectableOption create(Field field) {
field.setAccessible(true);
Type type = field.getGenericType();
if (type instanceof Class) {
return new FieldOption(field, (Class<?>) type);
}
throw new IllegalArgumentException("can't inject parameterized types etc.");
}
private Field field;
private boolean isBoolean;
private Parser<?> parser;
private FieldOption(Field field, Class<?> c) {
this.field = field;
this.isBoolean = c == boolean.class || c == Boolean.class;
try {
this.parser = Parsers.conventionalParser(Primitives.wrap(c));
} catch (NoSuchMethodException e) {
throw new IllegalArgumentException("No suitable String-conversion method");
}
}
@Override boolean isBoolean() {
return isBoolean;
}
@Override void inject(String valueText, Object injectee) throws InvalidCommandException {
Object value = convert(parser, valueText);
try {
field.set(injectee, value);
} catch (IllegalAccessException impossible) {
throw new AssertionError(impossible);
}
}
}
private static class MethodOption extends InjectableOption {
private static InjectableOption create(Method method) {
checkArgument(!isStaticOrAbstract(method),
"@Option methods cannot be static or abstract");
Class<?>[] classes = method.getParameterTypes();
checkArgument(classes.length == 1, "Method does not have exactly one argument: " + method);
return new MethodOption(method, classes[0]);
}
private Method method;
private boolean isBoolean;
private Parser<?> parser;
private MethodOption(Method method, Class<?> c) {
this.method = method;
this.isBoolean = c == boolean.class || c == Boolean.class;
try {
this.parser = Parsers.conventionalParser(Primitives.wrap(c));
} catch (NoSuchMethodException e) {
throw new IllegalArgumentException("No suitable String-conversion method");
}
method.setAccessible(true);
}
@Override boolean isBoolean() {
return isBoolean;
}
@Override boolean delayedInjection() {
return true;
}
@Override void inject(String valueText, Object injectee) throws InvalidCommandException {
invokeMethod(injectee, method, convert(parser, valueText));
}
}
private static Object convert(Parser<?> parser, String valueText) throws InvalidCommandException {
Object value;
try {
value = parser.parse(valueText);
} catch (ParseException e) {
throw new InvalidCommandException("wrong datatype: " + e.getMessage());
}
return value;
}
private void parseLongOption(String arg, Iterator<String> args) throws InvalidCommandException {
String name = arg.replaceFirst("^--no-", "--");
String value = null;
// Support "--name=value" as well as "--name value".
int equalsIndex = name.indexOf('=');
if (equalsIndex != -1) {
value = name.substring(equalsIndex + 1);
name = name.substring(0, equalsIndex);
}
InjectableOption injectable = injectionMap.getInjectableOption(name);
if (value == null) {
value = injectable.isBoolean()
? Boolean.toString(!arg.startsWith("--no-"))
: grabNextValue(args, name);
}
injectNowOrLater(injectable, value);
}
private void injectNowOrLater(InjectableOption injectable, String value)
throws InvalidCommandException {
if (injectable.delayedInjection()) {
pendingInjections.add(new PendingInjection(injectable, value));
} else {
injectable.inject(value, injectee);
}
}
private static class PendingInjection {
InjectableOption injectableOption;
String value;
private PendingInjection(InjectableOption injectableOption, String value) {
this.injectableOption = injectableOption;
this.value = 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 parseShortOptions(String arg, Iterator<String> args) throws InvalidCommandException {
for (int i = 1; i < arg.length(); ++i) {
String name = "-" + arg.charAt(i);
InjectableOption injectable = injectionMap.getInjectableOption(name);
String value;
if (injectable.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; // delayed "break"
// otherwise the next arg
} else {
value = grabNextValue(args, name);
}
}
injectNowOrLater(injectable, value);
}
}
private static void invokeMethod(Object injectee, Method method, Object value)
throws InvalidCommandException {
try {
method.invoke(injectee, value);
} catch (IllegalAccessException impossible) {
throw new AssertionError(impossible);
} catch (InvocationTargetException e) {
Throwable cause = e.getCause();
Throwables.propagateIfPossible(cause, InvalidCommandException.class);
throw new RuntimeException(e);
}
}
private String grabNextValue(Iterator<String> args, String name)
throws InvalidCommandException {
if (args.hasNext()) {
return args.next();
} else {
throw new InvalidCommandException("option '" + name + "' requires an argument");
}
}
private static boolean isStaticOrAbstract(Method method) {
int modifiers = method.getModifiers();
return Modifier.isStatic(modifiers) || Modifier.isAbstract(modifiers);
}
}