src/vogar/OptionParser.java - platform/external/vogar - Git at Google

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