diff --git a/src/main/java/com/google/devtools/common/options/Converter.java b/src/main/java/com/google/devtools/common/options/Converter.java
new file mode 100644
index 0000000..867ef82
--- /dev/null
+++ b/src/main/java/com/google/devtools/common/options/Converter.java
@@ -0,0 +1,33 @@
+// Copyright 2014 Google Inc. All rights reserved.
+//
+// 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.devtools.common.options;
+
+/**
+ * A converter is a little helper object that can take a String and
+ * turn it into an instance of type T (the type parameter to the converter).
+ */
+public interface Converter<T> {
+
+  /**
+   * Convert a string into type T.
+   */
+  T convert(String input) throws OptionsParsingException;
+
+  /**
+   * The type description appears in usage messages. E.g.: "a string",
+   * "a path", etc.
+   */
+  String getTypeDescription();
+
+}
diff --git a/src/main/java/com/google/devtools/common/options/Converters.java b/src/main/java/com/google/devtools/common/options/Converters.java
new file mode 100644
index 0000000..e8c69ec
--- /dev/null
+++ b/src/main/java/com/google/devtools/common/options/Converters.java
@@ -0,0 +1,326 @@
+// Copyright 2014 Google Inc. All rights reserved.
+//
+// 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.devtools.common.options;
+
+import com.google.common.base.Splitter;
+import com.google.common.collect.ImmutableList;
+import com.google.common.collect.Maps;
+
+import java.util.Iterator;
+import java.util.List;
+import java.util.Map;
+import java.util.logging.Level;
+import java.util.regex.Pattern;
+import java.util.regex.PatternSyntaxException;
+
+/**
+ * Some convenient converters used by blaze. Note: These are specific to
+ * blaze.
+ */
+public final class Converters {
+
+  /**
+   * Join a list of words as in English.  Examples:
+   * "nothing"
+   * "one"
+   * "one or two"
+   * "one and two"
+   * "one, two or three".
+   * "one, two and three".
+   * The toString method of each element is used.
+   */
+  static String joinEnglishList(Iterable<?> choices) {
+    StringBuilder buf = new StringBuilder();
+    for (Iterator<?> ii = choices.iterator(); ii.hasNext(); ) {
+      Object choice = ii.next();
+      if (buf.length() > 0) {
+        buf.append(ii.hasNext() ? ", " : " or ");
+      }
+      buf.append(choice);
+    }
+    return buf.length() == 0 ? "nothing" : buf.toString();
+  }
+
+  public static class SeparatedOptionListConverter
+      implements Converter<List<String>> {
+
+    private final String separatorDescription;
+    private final Splitter splitter;
+
+    protected SeparatedOptionListConverter(char separator,
+                                           String separatorDescription) {
+      this.separatorDescription = separatorDescription;
+      this.splitter = Splitter.on(separator);
+    }
+
+    @Override
+    public List<String> convert(String input) {
+      return input.equals("")
+          ? ImmutableList.<String>of()
+          : ImmutableList.copyOf(splitter.split(input));
+    }
+
+    @Override
+    public String getTypeDescription() {
+      return separatorDescription + "-separated list of options";
+    }
+  }
+
+  public static class CommaSeparatedOptionListConverter
+      extends SeparatedOptionListConverter {
+    public CommaSeparatedOptionListConverter() {
+      super(',', "comma");
+    }
+  }
+
+  public static class ColonSeparatedOptionListConverter extends SeparatedOptionListConverter {
+    public ColonSeparatedOptionListConverter() {
+      super(':', "colon");
+    }
+  }
+
+  public static class LogLevelConverter implements Converter<Level> {
+
+    public static Level[] LEVELS = new Level[] {
+      Level.OFF, Level.SEVERE, Level.WARNING, Level.INFO, Level.FINE,
+      Level.FINER, Level.FINEST
+    };
+
+    @Override
+    public Level convert(String input) throws OptionsParsingException {
+      try {
+        int level = Integer.parseInt(input);
+        return LEVELS[level];
+      } catch (NumberFormatException e) {
+        throw new OptionsParsingException("Not a log level: " + input);
+      } catch (ArrayIndexOutOfBoundsException e) {
+        throw new OptionsParsingException("Not a log level: " + input);
+      }
+    }
+
+    @Override
+    public String getTypeDescription() {
+      return "0 <= an integer <= " + (LEVELS.length - 1);
+    }
+
+  }
+
+  /**
+   * Checks whether a string is part of a set of strings.
+   */
+  public static class StringSetConverter implements Converter<String> {
+
+    // TODO(bazel-team): if this class never actually contains duplicates, we could s/List/Set/
+    // here.
+    private final List<String> values;
+
+    public StringSetConverter(String... values) {
+      this.values = ImmutableList.copyOf(values);
+    }
+
+    @Override
+    public String convert(String input) throws OptionsParsingException {
+      if (values.contains(input)) {
+        return input;
+      }
+
+      throw new OptionsParsingException("Not one of " + values);
+    }
+
+    @Override
+    public String getTypeDescription() {
+      return joinEnglishList(values);
+    }
+  }
+
+  /**
+   * Checks whether a string is a valid regex pattern and compiles it.
+   */
+  public static class RegexPatternConverter implements Converter<Pattern> {
+
+    @Override
+    public Pattern convert(String input) throws OptionsParsingException {
+      try {
+        return Pattern.compile(input);
+      } catch (PatternSyntaxException e) {
+        throw new OptionsParsingException("Not a valid regular expression: " + e.getMessage());
+      }
+    }
+
+    @Override
+    public String getTypeDescription() {
+      return "a valid Java regular expression";
+    }
+  }
+
+  /**
+   * Limits the length of a string argument.
+   */
+  public static class LengthLimitingConverter implements Converter<String> {
+    private final int maxSize;
+
+    public LengthLimitingConverter(int maxSize) {
+      this.maxSize = maxSize;
+    }
+
+    @Override
+    public String convert(String input) throws OptionsParsingException {
+      if (input.length() > maxSize) {
+        throw new OptionsParsingException("Input must be " + getTypeDescription());
+      }
+      return input;
+    }
+
+    @Override
+    public String getTypeDescription() {
+      return "a string <= " + maxSize + " characters";
+    }
+  }
+
+  /**
+   * Checks whether an integer is in the given range.
+   */
+  public static class RangeConverter implements Converter<Integer> {
+    final int minValue;
+    final int maxValue;
+
+    public RangeConverter(int minValue, int maxValue) {
+      this.minValue = minValue;
+      this.maxValue = maxValue;
+    }
+
+    @Override
+    public Integer convert(String input) throws OptionsParsingException {
+      try {
+        Integer value = Integer.parseInt(input);
+        if (value < minValue) {
+          throw new OptionsParsingException("'" + input + "' should be >= " + minValue);
+        } else if (value < minValue || value > maxValue) {
+          throw new OptionsParsingException("'" + input + "' should be <= " + maxValue);
+        }
+        return value;
+      } catch (NumberFormatException e) {
+        throw new OptionsParsingException("'" + input + "' is not an int");
+      }
+    }
+
+    @Override
+    public String getTypeDescription() {
+      if (minValue == Integer.MIN_VALUE) {
+        if (maxValue == Integer.MAX_VALUE) {
+          return "an integer";
+        } else {
+          return "an integer, <= " + maxValue;
+        }
+      } else if (maxValue == Integer.MAX_VALUE) {
+        return "an integer, >= " + minValue;
+      } else {
+        return "an integer in "
+            + (minValue < 0 ? "(" + minValue + ")" : minValue) + "-" + maxValue + " range";
+      }
+    }
+  }
+
+  /**
+   * A converter for variable assignments from the parameter list of a blaze
+   * command invocation. Assignments are expected to have the form "name=value",
+   * where names and values are defined to be as permissive as possible.
+   */
+  public static class AssignmentConverter implements Converter<Map.Entry<String, String>> {
+
+    @Override
+    public Map.Entry<String, String> convert(String input)
+        throws OptionsParsingException {
+      int pos = input.indexOf("=");
+      if (pos <= 0) {
+        throw new OptionsParsingException("Variable definitions must be in the form of a "
+            + "'name=value' assignment");
+      }
+      String name = input.substring(0, pos);
+      String value = input.substring(pos + 1);
+      return Maps.immutableEntry(name, value);
+    }
+
+    @Override
+    public String getTypeDescription() {
+      return "a 'name=value' assignment";
+    }
+
+  }
+
+  /**
+   * A converter for variable assignments from the parameter list of a blaze
+   * command invocation. Assignments are expected to have the form "name[=value]",
+   * where names and values are defined to be as permissive as possible and value
+   * part can be optional (in which case it is considered to be null).
+   */
+  public static class OptionalAssignmentConverter implements Converter<Map.Entry<String, String>> {
+
+    @Override
+    public Map.Entry<String, String> convert(String input)
+        throws OptionsParsingException {
+      int pos = input.indexOf("=");
+      if (pos == 0 || input.length() == 0) {
+        throw new OptionsParsingException("Variable definitions must be in the form of a "
+            + "'name=value' or 'name' assignment");
+      } else if (pos < 0) {
+        return Maps.immutableEntry(input, null);
+      }
+      String name = input.substring(0, pos);
+      String value = input.substring(pos + 1);
+      return Maps.immutableEntry(name, value);
+    }
+
+    @Override
+    public String getTypeDescription() {
+      return "a 'name=value' assignment with an optional value part";
+    }
+
+  }
+
+  public static class HelpVerbosityConverter extends EnumConverter<OptionsParser.HelpVerbosity> {
+    public HelpVerbosityConverter() {
+      super(OptionsParser.HelpVerbosity.class, "--help_verbosity setting");
+    }
+  }
+
+  /**
+   * A converter for boolean values. This is already one of the defaults, so clients
+   * should not typically need to add this.
+   */
+  public static class BooleanConverter implements Converter<Boolean> {
+    @Override
+    public Boolean convert(String input) throws OptionsParsingException {
+      if (input == null) {
+        return false;
+      }
+      input = input.toLowerCase();
+      if (input.equals("true") || input.equals("1") || input.equals("yes") ||
+          input.equals("t") || input.equals("y")) {
+        return true;
+      }
+      if (input.equals("false") || input.equals("0") || input.equals("no") ||
+          input.equals("f") || input.equals("n")) {
+        return false;
+      }
+      throw new OptionsParsingException("'" + input + "' is not a boolean");
+    }
+
+    @Override
+    public String getTypeDescription() {
+      return "a boolean";
+    }
+  }
+
+}
diff --git a/src/main/java/com/google/devtools/common/options/DuplicateOptionDeclarationException.java b/src/main/java/com/google/devtools/common/options/DuplicateOptionDeclarationException.java
new file mode 100644
index 0000000..b4e572e
--- /dev/null
+++ b/src/main/java/com/google/devtools/common/options/DuplicateOptionDeclarationException.java
@@ -0,0 +1,26 @@
+// Copyright 2014 Google Inc. All rights reserved.
+//
+// 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.devtools.common.options;
+
+/**
+ * Indicates that an option is declared in more than one class.
+ */
+public class DuplicateOptionDeclarationException extends RuntimeException {
+
+  DuplicateOptionDeclarationException(String message) {
+    super(message);
+  }
+
+}
diff --git a/src/main/java/com/google/devtools/common/options/EnumConverter.java b/src/main/java/com/google/devtools/common/options/EnumConverter.java
new file mode 100644
index 0000000..f65241a
--- /dev/null
+++ b/src/main/java/com/google/devtools/common/options/EnumConverter.java
@@ -0,0 +1,74 @@
+// Copyright 2014 Google Inc. All rights reserved.
+//
+// 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.devtools.common.options;
+
+import java.util.Arrays;
+
+/**
+ * A converter superclass for converters that parse enums.
+ *
+ * Just subclass this class, creating a zero aro argument constructor that
+ * calls {@link #EnumConverter(Class, String)}.
+ *
+ * This class compares the input string to the string returned by the toString()
+ * method of each enum member in a case-insensitive way. Usually, this is the
+ * name of the symbol, but beware if you override toString()!
+ */
+public abstract class EnumConverter<T extends Enum<T>>
+    implements Converter<T> {
+
+  private final Class<T> enumType;
+  private final String typeName;
+
+  /**
+   * Creates a new enum converter. You *must* implement a zero-argument
+   * constructor that delegates to this constructor, passing in the appropriate
+   * parameters.
+   *
+   * @param enumType The type of your enumeration; usually a class literal
+   *                 like MyEnum.class
+   * @param typeName The intuitive name of your enumeration, for example, the
+   *                 type name for CompilationMode might be "compilation mode".
+   */
+  protected EnumConverter(Class<T> enumType, String typeName) {
+    this.enumType = enumType;
+    this.typeName = typeName;
+  }
+
+  /**
+   * Implements {@link #convert(String)}.
+   */
+  @Override
+  public final T convert(String input) throws OptionsParsingException {
+    for (T value : enumType.getEnumConstants()) {
+      if (value.toString().equalsIgnoreCase(input)) {
+        return value;
+      }
+    }
+    throw new OptionsParsingException("Not a valid " + typeName + ": '"
+                                      + input + "' (should be "
+                                      + getTypeDescription() + ")");
+  }
+
+  /**
+   * Implements {@link #getTypeDescription()}.
+   */
+  @Override
+  public final String getTypeDescription() {
+    return Converters.joinEnglishList(
+        Arrays.asList(enumType.getEnumConstants())).toLowerCase();
+  }
+
+}
diff --git a/src/main/java/com/google/devtools/common/options/GenericTypeHelper.java b/src/main/java/com/google/devtools/common/options/GenericTypeHelper.java
new file mode 100644
index 0000000..2240860
--- /dev/null
+++ b/src/main/java/com/google/devtools/common/options/GenericTypeHelper.java
@@ -0,0 +1,133 @@
+// Copyright 2014 Google Inc. All rights reserved.
+//
+// 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.devtools.common.options;
+
+import com.google.common.annotations.VisibleForTesting;
+import com.google.common.primitives.Primitives;
+import com.google.common.reflect.TypeToken;
+
+import java.lang.reflect.Method;
+import java.lang.reflect.ParameterizedType;
+import java.lang.reflect.Type;
+import java.lang.reflect.TypeVariable;
+
+/**
+ * A helper class for {@link OptionsParserImpl} to help checking the return type
+ * of a {@link Converter} against the type of a field or the element type of a
+ * list.
+ *
+ * <p>This class has to go through considerable contortion to get the correct result
+ * from the Java reflection system, unfortunately. If the generic reflection part
+ * had been better designed, some of this would not be necessary.
+ */
+class GenericTypeHelper {
+
+  /**
+   * Returns the raw type of t, if t is either a raw or parameterized type.
+   * Otherwise, this method throws an {@link AssertionError}.
+   */
+  @VisibleForTesting
+  static Class<?> getRawType(Type t) {
+    if (t instanceof Class<?>) {
+      return (Class<?>) t;
+    } else if (t instanceof ParameterizedType) {
+      return (Class<?>) ((ParameterizedType) t).getRawType();
+    } else {
+      throw new AssertionError("A known concrete type is not concrete");
+    }
+  }
+
+  /**
+   * If type is a parameterized type, searches the given type variable in the list
+   * of declared type variables, and then returns the corresponding actual type.
+   * Returns null if the type variable is not defined by type.
+   */
+  private static Type matchTypeVariable(Type type, TypeVariable<?> variable) {
+    if (type instanceof ParameterizedType) {
+      Class<?> rawInterfaceType = getRawType(type);
+      TypeVariable<?>[] typeParameters = rawInterfaceType.getTypeParameters();
+      for (int i = 0; i < typeParameters.length; i++) {
+        if (variable.equals(typeParameters[i])) {
+          return ((ParameterizedType) type).getActualTypeArguments()[i];
+        }
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Resolves the return type of a method, in particular if the generic return
+   * type ({@link Method#getGenericReturnType()}) is a type variable
+   * ({@link TypeVariable}), by checking all super-classes and directly
+   * implemented interfaces.
+   *
+   * <p>The method m must be defined by the given type or by its raw class type.
+   *
+   * @throws AssertionError if the generic return type could not be resolved
+   */
+  // TODO(bazel-team): also check enclosing classes and indirectly implemented
+  // interfaces, which can also contribute type variables. This doesn't happen
+  // in the existing use cases.
+  public static Type getActualReturnType(Type type, Method method) {
+    Type returnType = method.getGenericReturnType();
+    if (returnType instanceof Class<?>) {
+      return returnType;
+    } else if (returnType instanceof ParameterizedType) {
+      return returnType;
+    } else if (returnType instanceof TypeVariable<?>) {
+      TypeVariable<?> variable = (TypeVariable<?>) returnType;
+      while (type != null) {
+        Type candidate = matchTypeVariable(type, variable);
+        if (candidate != null) {
+          return candidate;
+        }
+
+        Class<?> rawType = getRawType(type);
+        for (Type interfaceType : rawType.getGenericInterfaces()) {
+          candidate = matchTypeVariable(interfaceType, variable);
+          if (candidate != null) {
+            return candidate;
+          }
+        }
+
+        type = rawType.getGenericSuperclass();
+      }
+    }
+    throw new AssertionError("The type " + returnType
+        + " is not a Class, ParameterizedType, or TypeVariable");
+  }
+
+  /**
+   * Determines if a value of a particular type (from) is assignable to a field of
+   * a particular type (to). Also allows assigning wrapper types to primitive
+   * types.
+   *
+   * <p>The checks done here should be identical to the checks done by
+   * {@link java.lang.reflect.Field#set}. I.e., if this method returns true, a
+   * subsequent call to {@link java.lang.reflect.Field#set} should succeed.
+   */
+  public static boolean isAssignableFrom(Type to, Type from) {
+    if (to instanceof Class<?>) {
+      Class<?> toClass = (Class<?>) to;
+      if (toClass.isPrimitive()) {
+        return Primitives.wrap(toClass).equals(from);
+      }
+    }
+    return TypeToken.of(to).isAssignableFrom(from);
+  }
+
+  private GenericTypeHelper() {
+    // Prevents Java from creating a public constructor.
+  }
+}
diff --git a/src/main/java/com/google/devtools/common/options/Option.java b/src/main/java/com/google/devtools/common/options/Option.java
new file mode 100644
index 0000000..e244736
--- /dev/null
+++ b/src/main/java/com/google/devtools/common/options/Option.java
@@ -0,0 +1,127 @@
+// Copyright 2014 Google Inc. All rights reserved.
+//
+// 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.devtools.common.options;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * An interface for annotating fields in classes (derived from OptionsBase)
+ * that are options.
+ */
+@Target(ElementType.FIELD)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface Option {
+
+  /**
+   * The name of the option ("--name").
+   */
+  String name();
+
+  /**
+   * The single-character abbreviation of the option ("-abbrev").
+   */
+  char abbrev() default '\0';
+
+  /**
+   * A help string for the usage information.
+   */
+  String help() default "";
+
+  /**
+   * The default value for the option. This method should only be invoked
+   * directly by the parser implementation. Any access to default values
+   * should go via the parser to allow for application specific defaults.
+   *
+   * <p>There are two reasons this is a string.  Firstly, it ensures that
+   * explicitly specifying this option at its default value (as printed in the
+   * usage message) has the same behavior as not specifying the option at all;
+   * this would be very hard to achieve if the default value was an instance of
+   * type T, since we'd need to ensure that {@link #toString()} and {@link
+   * #converter} were dual to each other.  The second reason is more mundane
+   * but also more restrictive: annotation values must be compile-time
+   * constants.
+   *
+   * <p>If an option's defaultValue() is the string "null", the option's
+   * converter will not be invoked to interpret it; a null reference will be
+   * used instead.  (It would be nice if defaultValue could simply return null,
+   * but bizarrely, the Java Language Specification does not consider null to
+   * be a compile-time constant.)  This special interpretation of the string
+   * "null" is only applicable when computing the default value; if specified
+   * on the command-line, this string will have its usual literal meaning.
+   */
+  String defaultValue();
+
+  /**
+   * A string describing the category of options that this belongs to. {@link
+   * OptionsParser#describeOptions} prints options of the same category grouped
+   * together.
+   */
+  String category() default "misc";
+
+  /**
+   * The converter that we'll use to convert this option into an object or
+   * a simple type. The default is to use the builtin converters.
+   * Custom converters must implement the {@link Converter} interface.
+   */
+  @SuppressWarnings({"unchecked", "rawtypes"})
+  // Can't figure out how to coerce Converter.class into Class<? extends Converter<?>>
+  Class<? extends Converter> converter() default Converter.class;
+
+  /**
+   * A flag indicating whether the option type should be allowed to occur
+   * multiple times in a single option list.
+   *
+   * <p>If the command can occur multiple times, then the attribute value
+   * <em>must</em> be a list type {@code List<T>}, and the result type of the
+   * converter for this option must either match the parameter {@code T} or
+   * {@code List<T>}. In the latter case the individual lists are concatenated
+   * to form the full options value.
+   */
+  boolean allowMultiple() default false;
+
+  /**
+   * If the option is actually an abbreviation for other options, this field will
+   * contain the strings to expand this option into. The original option is dropped
+   * and the replacement used in its stead. It is recommended that such an option be
+   * of type {@link Void}.
+   *
+   * An expanded option overrides previously specified options of the same name,
+   * even if it is explicitly specified. This is the original behavior and can
+   * be surprising if the user is not aware of it, which has led to several
+   * requests to change this behavior. This was discussed in the blaze team and
+   * it was decided that it is not a strong enough case to change the behavior.
+   */
+  String[] expansion() default {};
+
+  /**
+   * If the option requires that additional options be implicitly appended, this field
+   * will contain the additional options. Implicit dependencies are parsed at the end
+   * of each {@link OptionsParser#parse} invocation, and override options specified in
+   * the same call. However, they can be overridden by options specified in a later
+   * call or by options with a higher priority.
+   *
+   * @see OptionPriority
+   */
+  String[] implicitRequirements() default {};
+
+  /**
+   * If this field is a non-empty string, the option is deprecated, and a
+   * deprecation warning is added to the list of warnings when such an option
+   * is used.
+   */
+  String deprecationWarning() default "";
+}
diff --git a/src/main/java/com/google/devtools/common/options/OptionPriority.java b/src/main/java/com/google/devtools/common/options/OptionPriority.java
new file mode 100644
index 0000000..6e90008
--- /dev/null
+++ b/src/main/java/com/google/devtools/common/options/OptionPriority.java
@@ -0,0 +1,58 @@
+// Copyright 2014 Google Inc. All rights reserved.
+//
+// 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.devtools.common.options;
+
+/**
+ * The priority of option values, in order of increasing priority.
+ *
+ * <p>In general, new values for options can only override values with a lower or
+ * equal priority. Option values provided in annotations in an options class are
+ * implicitly at the priority {@code DEFAULT}.
+ *
+ * <p>The ordering of the priorities is the source-code order. This is consistent
+ * with the automatically generated {@code compareTo} method as specified by the
+ * Java Language Specification. DO NOT change the source-code order of these
+ * values, or you will break code that relies on the ordering.
+ */
+public enum OptionPriority {
+
+  /**
+   * The priority of values specified in the {@link Option} annotation. This
+   * should never be specified in calls to {@link OptionsParser#parse}.
+   */
+  DEFAULT,
+
+  /**
+   * Overrides default options at runtime, while still allowing the values to be
+   * overridden manually.
+   */
+  COMPUTED_DEFAULT,
+
+  /**
+   * For options coming from a configuration file or rc file.
+   */
+  RC_FILE,
+
+  /**
+   * For options coming from the command line.
+   */
+  COMMAND_LINE,
+
+  /**
+   * This priority can be used to unconditionally override any user-provided options.
+   * This should be used rarely and with caution!
+   */
+  SOFTWARE_REQUIREMENT;
+
+}
diff --git a/src/main/java/com/google/devtools/common/options/Options.java b/src/main/java/com/google/devtools/common/options/Options.java
new file mode 100644
index 0000000..171be2e
--- /dev/null
+++ b/src/main/java/com/google/devtools/common/options/Options.java
@@ -0,0 +1,104 @@
+// Copyright 2014 Google Inc. All rights reserved.
+//
+// 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.devtools.common.options;
+
+import java.util.Arrays;
+import java.util.List;
+
+/**
+ * Interface for parsing options from a single options specification class.
+ *
+ * The {@link Options#parse(Class, String...)} method in this class has no clear
+ * use case. Instead, use the {@link OptionsParser} class directly, as in this
+ * code snippet:
+ *
+ * <pre>
+ * OptionsParser parser = OptionsParser.newOptionsParser(FooOptions.class);
+ * try {
+ *   parser.parse(FooOptions.class, args);
+ * } catch (OptionsParsingException e) {
+ *   System.err.print("Error parsing options: " + e.getMessage());
+ *   System.err.print(options.getUsage());
+ *   System.exit(1);
+ * }
+ * FooOptions foo = parser.getOptions(FooOptions.class);
+ * List&lt;String&gt; otherArguments = parser.getResidue();
+ * </pre>
+ *
+ * Using this class in this case actually results in more code.
+ *
+ * @see OptionsParser for parsing options from multiple options specification classes.
+ */
+public class Options<O extends OptionsBase> {
+
+  /**
+   * Parse the options provided in args, given the specification in
+   * optionsClass.
+   */
+  public static <O extends OptionsBase> Options<O> parse(Class<O> optionsClass, String... args)
+      throws OptionsParsingException {
+    OptionsParser parser = OptionsParser.newOptionsParser(optionsClass);
+    parser.parse(OptionPriority.COMMAND_LINE, null, Arrays.asList(args));
+    List<String> remainingArgs = parser.getResidue();
+    return new Options<O>(parser.getOptions(optionsClass),
+                          remainingArgs.toArray(new String[0]));
+  }
+
+  /**
+   * Returns an options object at its default values.  The returned object may
+   * be freely modified by the caller, by assigning its fields.
+   */
+  public static <O extends OptionsBase> O getDefaults(Class<O> optionsClass) {
+    try {
+      return parse(optionsClass, new String[0]).getOptions();
+    } catch (OptionsParsingException e) {
+      String message = "Error while parsing defaults: " + e.getMessage();
+      throw new AssertionError(message);
+    }
+  }
+
+  /**
+   * Returns a usage string (renders the help information, the defaults, and
+   * of course the option names).
+   */
+  public static String getUsage(Class<? extends OptionsBase> optionsClass) {
+    StringBuilder usage = new StringBuilder();
+    OptionsUsage.getUsage(optionsClass, usage);
+    return usage.toString();
+  }
+
+  private O options;
+  private String[] remainingArgs;
+
+  private Options(O options, String[] remainingArgs) {
+    this.options = options;
+    this.remainingArgs = remainingArgs;
+  }
+
+  /**
+   * Returns an instance of options class O.
+   */
+  public O getOptions() {
+    return options;
+  }
+
+  /**
+   * Returns the arguments that we didn't parse.
+   */
+  public String[] getRemainingArgs() {
+    return remainingArgs;
+  }
+
+}
diff --git a/src/main/java/com/google/devtools/common/options/OptionsBase.java b/src/main/java/com/google/devtools/common/options/OptionsBase.java
new file mode 100644
index 0000000..ed9f215
--- /dev/null
+++ b/src/main/java/com/google/devtools/common/options/OptionsBase.java
@@ -0,0 +1,118 @@
+// Copyright 2014 Google Inc. All rights reserved.
+//
+// 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.devtools.common.options;
+
+import com.google.common.escape.CharEscaperBuilder;
+import com.google.common.escape.Escaper;
+
+import java.util.List;
+import java.util.Map;
+import java.util.Map.Entry;
+
+/**
+ * Base class for all options classes.  Extend this class, adding public
+ * instance fields annotated with @Option.  Then you can create instances
+ * either programmatically:
+ *
+ * <pre>
+ *   X x = Options.getDefaults(X.class);
+ *   x.host = "localhost";
+ *   x.port = 80;
+ * </pre>
+ *
+ * or from an array of command-line arguments:
+ *
+ * <pre>
+ *   OptionsParser parser = OptionsParser.newOptionsParser(X.class);
+ *   parser.parse("--host", "localhost", "--port", "80");
+ *   X x = parser.getOptions(X.class);
+ * </pre>
+ *
+ * <p>Subclasses of OptionsBase <b>must</b> be constructed reflectively,
+ * i.e. using not {@code new MyOptions}, but one of the two methods above
+ * instead.  (Direct construction creates an empty instance, not containing
+ * default values.  This leads to surprising behavior and often
+ * NullPointerExceptions, etc.)
+ */
+public abstract class OptionsBase {
+
+  private static final Escaper ESCAPER = new CharEscaperBuilder()
+      .addEscape('\\', "\\\\").addEscape('"', "\\\"").toEscaper();
+
+  /**
+   * Subclasses must provide a default (no argument) constructor.
+   */
+  protected OptionsBase() {
+    // There used to be a sanity check here that checks the stack trace of this constructor
+    // invocation; unfortunately, that makes the options construction about 10x slower. So be
+    // careful with how you construct options classes.
+  }
+
+  /**
+   * Returns this options object in the form of a (new) mapping from option
+   * names, including inherited ones, to option values.  If the public fields
+   * are mutated, this will be reflected in subsequent calls to {@code asMap}.
+   * Mutation of this map by the caller does not affect this options object.
+   */
+  public final Map<String, Object> asMap() {
+    return OptionsParserImpl.optionsAsMap(this);
+  }
+
+  @Override
+  public final String toString() {
+    return getClass().getName() + asMap();
+  }
+
+  /**
+   * Returns a string that uniquely identifies the options. This value is
+   * intended for analysis caching.
+   */
+  public final String cacheKey() {
+    StringBuilder result = new StringBuilder(getClass().getName()).append("{");
+
+    for (Entry<String, Object> entry : asMap().entrySet()) {
+      result.append(entry.getKey()).append("=");
+
+      Object value = entry.getValue();
+      // This special case is needed because List.toString() prints the same
+      // ("[]") for an empty list and for a list with a single empty string.
+      if (value instanceof List<?> && ((List<?>) value).isEmpty()) {
+        result.append("EMPTY");
+      } else if (value == null) {
+        result.append("NULL");
+      } else {
+        result
+            .append('"')
+            .append(ESCAPER.escape(value.toString()))
+            .append('"');
+      }
+      result.append(", ");
+    }
+
+    return result.append("}").toString();
+  }
+
+  @Override
+  public final boolean equals(Object that) {
+    return that != null &&
+        this.getClass() == that.getClass() &&
+        this.asMap().equals(((OptionsBase) that).asMap());
+  }
+
+  @Override
+  public final int hashCode() {
+    return this.getClass().hashCode() + asMap().hashCode();
+  }
+}
diff --git a/src/main/java/com/google/devtools/common/options/OptionsClassProvider.java b/src/main/java/com/google/devtools/common/options/OptionsClassProvider.java
new file mode 100644
index 0000000..1868e23
--- /dev/null
+++ b/src/main/java/com/google/devtools/common/options/OptionsClassProvider.java
@@ -0,0 +1,29 @@
+// Copyright 2014 Google Inc. All rights reserved.
+//
+// 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.devtools.common.options;
+
+/**
+ * A read-only interface for options parser results, which only allows to query the options of
+ * a specific class, but not e.g. the residue any other information pertaining to the command line.
+ */
+public interface OptionsClassProvider {
+  /**
+   * Returns the options instance for the given {@code optionsClass}, that is,
+   * the parsed options, or null if it is not among those available.
+   *
+   * <p>The returned options should be treated by library code as immutable and
+   * a provider is permitted to return the same options instance multiple times.
+   */
+  <O extends OptionsBase> O getOptions(Class<O> optionsClass);
+}
diff --git a/src/main/java/com/google/devtools/common/options/OptionsData.java b/src/main/java/com/google/devtools/common/options/OptionsData.java
new file mode 100644
index 0000000..e9b6574
--- /dev/null
+++ b/src/main/java/com/google/devtools/common/options/OptionsData.java
@@ -0,0 +1,264 @@
+// Copyright 2014 Google Inc. All rights reserved.
+//
+// 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.devtools.common.options;
+
+import com.google.common.collect.ImmutableList;
+import com.google.common.collect.ImmutableMap;
+import com.google.common.collect.Lists;
+import com.google.common.collect.Maps;
+
+import java.lang.reflect.Constructor;
+import java.lang.reflect.Field;
+import java.lang.reflect.Method;
+import java.lang.reflect.Modifier;
+import java.lang.reflect.ParameterizedType;
+import java.lang.reflect.Type;
+import java.util.Collection;
+import java.util.Collections;
+import java.util.List;
+import java.util.Map;
+
+import javax.annotation.concurrent.Immutable;
+
+/**
+ * An immutable selection of options data corresponding to a set of options
+ * classes. The data is collected using reflection, which can be expensive.
+ * Therefore this class can be used internally to cache the results.
+ */
+@Immutable
+final class OptionsData {
+
+  /**
+   * These are the options-declaring classes which are annotated with
+   * {@link Option} annotations.
+   */
+  private final Map<Class<? extends OptionsBase>, Constructor<?>> optionsClasses;
+
+  /** Maps option name to Option-annotated Field. */
+  private final Map<String, Field> nameToField;
+
+  /** Maps option abbreviation to Option-annotated Field. */
+  private final Map<Character, Field> abbrevToField;
+
+  /**
+   * For each options class, contains a list of all Option-annotated fields in
+   * that class.
+   */
+  private final Map<Class<? extends OptionsBase>, List<Field>> allOptionsFields;
+
+  /**
+   * Mapping from each Option-annotated field to the default value for that
+   * field.
+   */
+  private final Map<Field, Object> optionDefaults;
+
+  /**
+   * Mapping from each Option-annotated field to the proper converter.
+   *
+   * @see OptionsParserImpl#findConverter
+   */
+  private final Map<Field, Converter<?>> converters;
+
+  private OptionsData(Map<Class<? extends OptionsBase>, Constructor<?>> optionsClasses,
+                      Map<String, Field> nameToField,
+                      Map<Character, Field> abbrevToField,
+                      Map<Class<? extends OptionsBase>, List<Field>> allOptionsFields,
+                      Map<Field, Object> optionDefaults,
+                      Map<Field, Converter<?>> converters) {
+    this.optionsClasses = ImmutableMap.copyOf(optionsClasses);
+    this.allOptionsFields = ImmutableMap.copyOf(allOptionsFields);
+    this.nameToField = ImmutableMap.copyOf(nameToField);
+    this.abbrevToField = ImmutableMap.copyOf(abbrevToField);
+    // Can't use an ImmutableMap here because of null values.
+    this.optionDefaults = Collections.unmodifiableMap(optionDefaults);
+    this.converters = ImmutableMap.copyOf(converters);
+  }
+
+  public Collection<Class<? extends OptionsBase>> getOptionsClasses() {
+    return optionsClasses.keySet();
+  }
+
+  @SuppressWarnings("unchecked") // The construction ensures that the case is always valid.
+  public <T extends OptionsBase> Constructor<T> getConstructor(Class<T> clazz) {
+    return (Constructor<T>) optionsClasses.get(clazz);
+  }
+
+  public Field getFieldFromName(String name) {
+    return nameToField.get(name);
+  }
+
+  public Iterable<Map.Entry<String, Field>> getAllNamedFields() {
+    return nameToField.entrySet();
+  }
+
+  public Field getFieldForAbbrev(char abbrev) {
+    return abbrevToField.get(abbrev);
+  }
+
+  public List<Field> getFieldsForClass(Class<? extends OptionsBase> optionsClass) {
+    return allOptionsFields.get(optionsClass);
+  }
+
+  public Object getDefaultValue(Field field) {
+    return optionDefaults.get(field);
+  }
+
+  public Converter<?> getConverter(Field field) {
+    return converters.get(field);
+  }
+
+  private static List<Field> getAllAnnotatedFields(Class<? extends OptionsBase> optionsClass) {
+    List<Field> allFields = Lists.newArrayList();
+    for (Field field : optionsClass.getFields()) {
+      if (field.isAnnotationPresent(Option.class)) {
+        allFields.add(field);
+      }
+    }
+    if (allFields.isEmpty()) {
+      throw new IllegalStateException(optionsClass + " has no public @Option-annotated fields");
+    }
+    return ImmutableList.copyOf(allFields);
+  }
+
+  private static Object retrieveDefaultFromAnnotation(Field optionField) {
+    Option annotation = optionField.getAnnotation(Option.class);
+    // If an option can be specified multiple times, its default value is a new empty list.
+    if (annotation.allowMultiple()) {
+      return Collections.emptyList();
+    }
+    String defaultValueString = OptionsParserImpl.getDefaultOptionString(optionField);
+    try {
+      return OptionsParserImpl.isSpecialNullDefault(defaultValueString, optionField)
+          ? null
+          : OptionsParserImpl.findConverter(optionField).convert(defaultValueString);
+    } catch (OptionsParsingException e) {
+      throw new IllegalStateException("OptionsParsingException while "
+          + "retrieving default for " + optionField.getName() + ": "
+          + e.getMessage());
+    }
+  }
+
+  static OptionsData of(Collection<Class<? extends OptionsBase>> classes) {
+    Map<Class<? extends OptionsBase>, Constructor<?>> constructorBuilder = Maps.newHashMap();
+    Map<Class<? extends OptionsBase>, List<Field>> allOptionsFieldsBuilder = Maps.newHashMap();
+    Map<String, Field> nameToFieldBuilder = Maps.newHashMap();
+    Map<Character, Field> abbrevToFieldBuilder = Maps.newHashMap();
+    Map<Field, Object> optionDefaultsBuilder = Maps.newHashMap();
+    Map<Field, Converter<?>> convertersBuilder = Maps.newHashMap();
+
+    // Read all Option annotations:
+    for (Class<? extends OptionsBase> parsedOptionsClass : classes) {
+      try {
+        Constructor<? extends OptionsBase> constructor =
+            parsedOptionsClass.getConstructor(new Class[0]);
+        constructorBuilder.put(parsedOptionsClass, constructor);
+      } catch (NoSuchMethodException e) {
+        throw new IllegalArgumentException(parsedOptionsClass
+            + " lacks an accessible default constructor");
+      }
+      List<Field> fields = getAllAnnotatedFields(parsedOptionsClass);
+      allOptionsFieldsBuilder.put(parsedOptionsClass, fields);
+
+      for (Field field : fields) {
+        Option annotation = field.getAnnotation(Option.class);
+
+        // Check that the field type is a List, and that the converter
+        // type matches the element type of the list.
+        Type fieldType = field.getGenericType();
+        if (annotation.allowMultiple()) {
+          if (!(fieldType instanceof ParameterizedType)) {
+            throw new AssertionError("Type of multiple occurrence option must be a List<...>");
+          }
+          ParameterizedType pfieldType = (ParameterizedType) fieldType;
+          if (pfieldType.getRawType() != List.class) {
+            // Throw an assertion, because this indicates an undetected type
+            // error in the code.
+            throw new AssertionError("Type of multiple occurrence option must be a List<...>");
+          }
+          fieldType = pfieldType.getActualTypeArguments()[0];
+        }
+
+        // Get the converter return type.
+        @SuppressWarnings("rawtypes")
+        Class<? extends Converter> converter = annotation.converter();
+        if (converter == Converter.class) {
+          Converter<?> actualConverter = OptionsParserImpl.DEFAULT_CONVERTERS.get(fieldType);
+          if (actualConverter == null) {
+            throw new AssertionError("Cannot find converter for field of type "
+                + field.getType() + " named " + field.getName()
+                + " in class " + field.getDeclaringClass().getName());
+          }
+          converter = actualConverter.getClass();
+        }
+        if (Modifier.isAbstract(converter.getModifiers())) {
+          throw new AssertionError("The converter type (" + converter
+              + ") must be a concrete type");
+        }
+        Type converterResultType;
+        try {
+          Method convertMethod = converter.getMethod("convert", String.class);
+          converterResultType = GenericTypeHelper.getActualReturnType(converter, convertMethod);
+        } catch (NoSuchMethodException e) {
+          throw new AssertionError("A known converter object doesn't implement the convert"
+              + " method");
+        }
+
+        if (annotation.allowMultiple()) {
+          if (GenericTypeHelper.getRawType(converterResultType) == List.class) {
+            Type elementType =
+                ((ParameterizedType) converterResultType).getActualTypeArguments()[0];
+            if (!GenericTypeHelper.isAssignableFrom(fieldType, elementType)) {
+              throw new AssertionError("If the converter return type of a multiple occurance " +
+                  "option is a list, then the type of list elements (" + fieldType + ") must be " +
+                  "assignable from the converter list element type (" + elementType + ")");
+            }
+          } else {
+            if (!GenericTypeHelper.isAssignableFrom(fieldType, converterResultType)) {
+              throw new AssertionError("Type of list elements (" + fieldType +
+                  ") for multiple occurrence option must be assignable from the converter " +
+                  "return type (" + converterResultType + ")");
+            }
+          }
+        } else {
+          if (!GenericTypeHelper.isAssignableFrom(fieldType, converterResultType)) {
+            throw new AssertionError("Type of field (" + fieldType +
+                ") must be assignable from the converter " +
+                "return type (" + converterResultType + ")");
+          }
+        }
+
+        if (annotation.name() == null) {
+          throw new AssertionError(
+              "Option cannot have a null name");
+        }
+        if (nameToFieldBuilder.put(annotation.name(), field) != null) {
+          throw new DuplicateOptionDeclarationException(
+              "Duplicate option name: --" + annotation.name());
+        }
+        if (annotation.abbrev() != '\0') {
+          if (abbrevToFieldBuilder.put(annotation.abbrev(), field) != null) {
+            throw new DuplicateOptionDeclarationException(
+                  "Duplicate option abbrev: -" + annotation.abbrev());
+          }
+        }
+        optionDefaultsBuilder.put(field, retrieveDefaultFromAnnotation(field));
+
+        convertersBuilder.put(field, OptionsParserImpl.findConverter(field));
+      }
+    }
+    return new OptionsData(constructorBuilder, nameToFieldBuilder, abbrevToFieldBuilder,
+        allOptionsFieldsBuilder, optionDefaultsBuilder, convertersBuilder);
+  }
+}
diff --git a/src/main/java/com/google/devtools/common/options/OptionsParser.java b/src/main/java/com/google/devtools/common/options/OptionsParser.java
new file mode 100644
index 0000000..9564daa
--- /dev/null
+++ b/src/main/java/com/google/devtools/common/options/OptionsParser.java
@@ -0,0 +1,526 @@
+// Copyright 2014 Google Inc. All rights reserved.
+//
+// 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.devtools.common.options;
+
+import com.google.common.base.Function;
+import com.google.common.base.Functions;
+import com.google.common.base.Joiner;
+import com.google.common.base.Preconditions;
+import com.google.common.collect.ImmutableList;
+import com.google.common.collect.Lists;
+import com.google.common.collect.Maps;
+
+import java.lang.reflect.Field;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.Collection;
+import java.util.Collections;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * A parser for options. Typical use case in a main method:
+ *
+ * <pre>
+ * OptionsParser parser = OptionsParser.newOptionsParser(FooOptions.class, BarOptions.class);
+ * parser.parseAndExitUponError(args);
+ * FooOptions foo = parser.getOptions(FooOptions.class);
+ * BarOptions bar = parser.getOptions(BarOptions.class);
+ * List&lt;String&gt; otherArguments = parser.getResidue();
+ * </pre>
+ *
+ * <p>FooOptions and BarOptions would be options specification classes, derived
+ * from OptionsBase, that contain fields annotated with @Option(...).
+ *
+ * <p>Alternatively, rather than calling
+ * {@link #parseAndExitUponError(OptionPriority, String, String[])},
+ * client code may call {@link #parse(OptionPriority,String,List)}, and handle
+ * parser exceptions usage messages themselves.
+ *
+ * <p>This options parsing implementation has (at least) one design flaw. It
+ * allows both '--foo=baz' and '--foo baz' for all options except void, boolean
+ * and tristate options. For these, the 'baz' in '--foo baz' is not treated as
+ * a parameter to the option, making it is impossible to switch options between
+ * void/boolean/tristate and everything else without breaking backwards
+ * compatibility.
+ *
+ * @see Options a simpler class which you can use if you only have one options
+ * specification class
+ */
+public class OptionsParser implements OptionsProvider {
+
+  /**
+   * A cache for the parsed options data. Both keys and values are immutable, so
+   * this is always safe. Only access this field through the {@link
+   * #getOptionsData} method for thread-safety! The cache is very unlikely to
+   * grow to a significant amount of memory, because there's only a fixed set of
+   * options classes on the classpath.
+   */
+  private static final Map<ImmutableList<Class<? extends OptionsBase>>, OptionsData> optionsData =
+      Maps.newHashMap();
+
+  private static synchronized OptionsData getOptionsData(
+      ImmutableList<Class<? extends OptionsBase>> optionsClasses) {
+    OptionsData result = optionsData.get(optionsClasses);
+    if (result == null) {
+      result = OptionsData.of(optionsClasses);
+      optionsData.put(optionsClasses, result);
+    }
+    return result;
+  }
+
+  /**
+   * Returns all the annotated fields for the given class, including inherited
+   * ones.
+   */
+  static Collection<Field> getAllAnnotatedFields(Class<? extends OptionsBase> optionsClass) {
+    OptionsData data = getOptionsData(ImmutableList.<Class<? extends OptionsBase>>of(optionsClass));
+    return data.getFieldsForClass(optionsClass);
+  }
+
+  /**
+   * @see #newOptionsParser(Iterable)
+   */
+  public static OptionsParser newOptionsParser(Class<? extends OptionsBase> class1) {
+    return newOptionsParser(ImmutableList.<Class<? extends OptionsBase>>of(class1));
+  }
+
+  /**
+   * @see #newOptionsParser(Iterable)
+   */
+  public static OptionsParser newOptionsParser(Class<? extends OptionsBase> class1,
+                                               Class<? extends OptionsBase> class2) {
+    return newOptionsParser(ImmutableList.of(class1, class2));
+  }
+
+  /**
+   * Create a new {@link OptionsParser}.
+   */
+  public static OptionsParser newOptionsParser(
+      Iterable<Class<? extends OptionsBase>> optionsClasses) {
+    return new OptionsParser(getOptionsData(ImmutableList.copyOf(optionsClasses)));
+  }
+
+  /**
+   * Canonicalizes a list of options using the given option classes. The
+   * contract is that if the returned set of options is passed to an options
+   * parser with the same options classes, then that will have the same effect
+   * as using the original args (which are passed in here), except for cosmetic
+   * differences.
+   */
+  public static List<String> canonicalize(
+      Collection<Class<? extends OptionsBase>> optionsClasses, List<String> args)
+      throws OptionsParsingException {
+    OptionsParser parser = new OptionsParser(optionsClasses);
+    parser.setAllowResidue(false);
+    parser.parse(args);
+    return parser.impl.asCanonicalizedList();
+  }
+
+  private final OptionsParserImpl impl;
+  private final List<String> residue = new ArrayList<String>();
+  private boolean allowResidue = true;
+
+  OptionsParser(Collection<Class<? extends OptionsBase>> optionsClasses) {
+    this(OptionsData.of(optionsClasses));
+  }
+
+  OptionsParser(OptionsData optionsData) {
+    impl = new OptionsParserImpl(optionsData);
+  }
+
+  /**
+   * Indicates whether or not the parser will allow a non-empty residue; that
+   * is, iff this value is true then a call to one of the {@code parse}
+   * methods will throw {@link OptionsParsingException} unless
+   * {@link #getResidue()} is empty after parsing.
+   */
+  public void setAllowResidue(boolean allowResidue) {
+    this.allowResidue = allowResidue;
+  }
+
+  /**
+   * Indicates whether or not the parser will allow long options with a
+   * single-dash, instead of the usual double-dash, too, eg. -example instead of just --example.
+   */
+  public void setAllowSingleDashLongOptions(boolean allowSingleDashLongOptions) {
+    this.impl.setAllowSingleDashLongOptions(allowSingleDashLongOptions);
+  }
+
+  public void parseAndExitUponError(String[] args) {
+    parseAndExitUponError(OptionPriority.COMMAND_LINE, "unknown", args);
+  }
+
+  /**
+   * A convenience function for use in main methods. Parses the command line
+   * parameters, and exits upon error. Also, prints out the usage message
+   * if "--help" appears anywhere within {@code args}.
+   */
+  public void parseAndExitUponError(OptionPriority priority, String source, String[] args) {
+    try {
+      parse(priority, source, Arrays.asList(args));
+    } catch (OptionsParsingException e) {
+      System.err.println("Error parsing command line: " + e.getMessage());
+      System.err.println("Try --help.");
+      System.exit(2);
+    }
+    for (String arg : args) {
+      if (arg.equals("--help")) {
+        System.out.println(describeOptions(Collections.<String, String>emptyMap(),
+                                           HelpVerbosity.LONG));
+        System.exit(0);
+      }
+    }
+  }
+
+  /**
+   * The name and value of an option with additional metadata describing its
+   * priority, source, whether it was set via an implicit dependency, and if so,
+   * by which other option.
+   */
+  public static class OptionValueDescription {
+    private final String name;
+    private final Object value;
+    private final OptionPriority priority;
+    private final String source;
+    private final String implicitDependant;
+    private final String expandedFrom;
+
+    public OptionValueDescription(String name, Object value,
+        OptionPriority priority, String source, String implicitDependant, String expandedFrom) {
+      this.name = name;
+      this.value = value;
+      this.priority = priority;
+      this.source = source;
+      this.implicitDependant = implicitDependant;
+      this.expandedFrom = expandedFrom;
+    }
+
+    public String getName() {
+      return name;
+    }
+
+    public Object getValue() {
+      return value;
+    }
+
+    public OptionPriority getPriority() {
+      return priority;
+    }
+
+    public String getSource() {
+      return source;
+    }
+
+    public String getImplicitDependant() {
+      return implicitDependant;
+    }
+
+    public boolean isImplicitDependency() {
+      return implicitDependant != null;
+    }
+
+    public String getExpansionParent() {
+      return expandedFrom;
+    }
+
+    public boolean isExpansion() {
+      return expandedFrom != null;
+    }
+
+    @Override
+    public String toString() {
+      StringBuilder result = new StringBuilder();
+      result.append("option '").append(name).append("' ");
+      result.append("set to '").append(value).append("' ");
+      result.append("with priority ").append(priority);
+      if (source != null) {
+        result.append(" and source '").append(source).append("'");
+      }
+      if (implicitDependant != null) {
+        result.append(" implicitly by ");
+      }
+      return result.toString();
+    }
+  }
+
+  /**
+   * The name and unparsed value of an option with additional metadata describing its
+   * priority, source, whether it was set via an implicit dependency, and if so,
+   * by which other option.
+   *
+   * <p>Note that the unparsed value and the source parameters can both be null.
+   */
+  public static class UnparsedOptionValueDescription {
+    private final String name;
+    private final Field field;
+    private final String unparsedValue;
+    private final OptionPriority priority;
+    private final String source;
+    private final boolean explicit;
+
+    public UnparsedOptionValueDescription(String name, Field field, String unparsedValue,
+        OptionPriority priority, String source, boolean explicit) {
+      this.name = name;
+      this.field = field;
+      this.unparsedValue = unparsedValue;
+      this.priority = priority;
+      this.source = source;
+      this.explicit = explicit;
+    }
+
+    public String getName() {
+      return name;
+    }
+
+    Field getField() {
+      return field;
+    }
+
+    public boolean isBooleanOption() {
+      return field.getType().equals(boolean.class);
+    }
+
+    private DocumentationLevel documentationLevel() {
+      Option option = field.getAnnotation(Option.class);
+      return OptionsParser.documentationLevel(option.category());
+    }
+
+    public boolean isDocumented() {
+      return documentationLevel() == DocumentationLevel.DOCUMENTED;
+    }
+
+    public boolean isHidden() {
+      return documentationLevel() == DocumentationLevel.HIDDEN;
+    }
+
+    boolean isExpansion() {
+      Option option = field.getAnnotation(Option.class);
+      return option.expansion().length > 0;
+    }
+
+    boolean isImplicitRequirement() {
+      Option option = field.getAnnotation(Option.class);
+      return option.implicitRequirements().length > 0;
+    }
+
+    boolean allowMultiple() {
+      Option option = field.getAnnotation(Option.class);
+      return option.allowMultiple();
+    }
+
+    public String getUnparsedValue() {
+      return unparsedValue;
+    }
+
+    OptionPriority getPriority() {
+      return priority;
+    }
+
+    public String getSource() {
+      return source;
+    }
+
+    public boolean isExplicit() {
+      return explicit;
+    }
+
+    @Override
+    public String toString() {
+      StringBuilder result = new StringBuilder();
+      result.append("option '").append(name).append("' ");
+      result.append("set to '").append(unparsedValue).append("' ");
+      result.append("with priority ").append(priority);
+      if (source != null) {
+        result.append(" and source '").append(source).append("'");
+      }
+      return result.toString();
+    }
+  }
+
+  /**
+   * The verbosity with which option help messages are displayed: short (just
+   * the name), medium (name, type, default, abbreviation), and long (full
+   * description).
+   */
+  public enum HelpVerbosity { LONG, MEDIUM, SHORT }
+
+  /**
+   * The level of documentation. Only documented options are output as part of
+   * the help.
+   *
+   * <p>We use 'hidden' so that options that form the protocol between the
+   * client and the server are not logged.
+   */
+  enum DocumentationLevel {
+    DOCUMENTED, UNDOCUMENTED, HIDDEN
+  }
+
+  /**
+   * Returns a description of all the options this parser can digest.
+   * In addition to {@link Option} annotations, this method also
+   * interprets {@link OptionsUsage} annotations which give an intuitive short
+   * description for the options.
+   *
+   * @param categoryDescriptions a mapping from category names to category
+   *   descriptions.  Options of the same category (see {@link
+   *   Option#category}) will be grouped together, preceded by the description
+   *   of the category.
+   * @param helpVerbosity if {@code long}, the options will be described
+   *   verbosely, including their types, defaults and descriptions.  If {@code
+   *   medium}, the descriptions are omitted, and if {@code short}, the options
+   *   are just enumerated.
+   */
+  public String describeOptions(Map<String, String> categoryDescriptions,
+                                HelpVerbosity helpVerbosity) {
+    StringBuilder desc = new StringBuilder();
+    if (!impl.getOptionsClasses().isEmpty()) {
+
+      List<Field> allFields = Lists.newArrayList();
+      for (Class<? extends OptionsBase> optionsClass : impl.getOptionsClasses()) {
+        allFields.addAll(impl.getAnnotatedFieldsFor(optionsClass));
+      }
+      Collections.sort(allFields, OptionsUsage.BY_CATEGORY);
+      String prevCategory = null;
+
+      for (Field optionField : allFields) {
+        String category = optionField.getAnnotation(Option.class).category();
+        if (!category.equals(prevCategory)) {
+          prevCategory = category;
+          String description = categoryDescriptions.get(category);
+          if (description == null) {
+            description = "Options category '" + category + "'";
+          }
+          if (documentationLevel(category) == DocumentationLevel.DOCUMENTED) {
+            desc.append("\n").append(description).append(":\n");
+          }
+        }
+
+        if (documentationLevel(prevCategory) == DocumentationLevel.DOCUMENTED) {
+          OptionsUsage.getUsage(optionField, desc, helpVerbosity);
+        }
+      }
+    }
+    return desc.toString().trim();
+  }
+
+  /**
+   * Returns a description of the option value set by the last previous call to
+   * {@link #parse(OptionPriority, String, List)} that successfully set the given
+   * option. If the option is of type {@link List}, the description will
+   * correspond to any one of the calls, but not necessarily the last.
+   */
+  public OptionValueDescription getOptionValueDescription(String name) {
+    return impl.getOptionValueDescription(name);
+  }
+
+  static DocumentationLevel documentationLevel(String category) {
+    if ("undocumented".equals(category)) {
+      return DocumentationLevel.UNDOCUMENTED;
+    } else if ("hidden".equals(category)) {
+      return DocumentationLevel.HIDDEN;
+    } else {
+      return DocumentationLevel.DOCUMENTED;
+    }
+  }
+
+  /**
+   * A convenience method, equivalent to
+   * {@code parse(OptionPriority.COMMAND_LINE, null, Arrays.asList(args))}.
+   */
+  public void parse(String... args) throws OptionsParsingException {
+    parse(OptionPriority.COMMAND_LINE, (String) null, Arrays.asList(args));
+  }
+
+  /**
+   * A convenience method, equivalent to
+   * {@code parse(OptionPriority.COMMAND_LINE, null, args)}.
+   */
+  public void parse(List<String> args) throws OptionsParsingException {
+    parse(OptionPriority.COMMAND_LINE, (String) null, args);
+  }
+
+  /**
+   * Parses {@code args}, using the classes registered with this parser.
+   * {@link #getOptions(Class)} and {@link #getResidue()} return the results.
+   * May be called multiple times; later options override existing ones if they
+   * have equal or higher priority. The source of options is a free-form string
+   * that can be used for debugging. Strings that cannot be parsed as options
+   * accumulates as residue, if this parser allows it.
+   *
+   * @see OptionPriority
+   */
+  public void parse(OptionPriority priority, String source,
+      List<String> args) throws OptionsParsingException {
+    parseWithSourceFunction(priority, Functions.constant(source), args);
+  }
+
+  /**
+   * Parses {@code args}, using the classes registered with this parser.
+   * {@link #getOptions(Class)} and {@link #getResidue()} return the results. May be called
+   * multiple times; later options override existing ones if they have equal or higher priority.
+   * The source of options is given as a function that maps option names to the source of the
+   * option. Strings that cannot be parsed as options accumulates as* residue, if this parser
+   * allows it.
+   */
+  public void parseWithSourceFunction(OptionPriority priority,
+      Function<? super String, String> sourceFunction, List<String> args)
+      throws OptionsParsingException {
+    Preconditions.checkNotNull(priority);
+    Preconditions.checkArgument(priority != OptionPriority.DEFAULT);
+    residue.addAll(impl.parse(priority, sourceFunction, args));
+    if (!allowResidue && !residue.isEmpty()) {
+      String errorMsg = "Unrecognized arguments: " + Joiner.on(' ').join(residue);
+      throw new OptionsParsingException(errorMsg);
+    }
+  }
+
+  @Override
+  public List<String> getResidue() {
+    return ImmutableList.copyOf(residue);
+  }
+
+  /**
+   * Returns a list of warnings about problems encountered by previous parse calls.
+   */
+  public List<String> getWarnings() {
+    return impl.getWarnings();
+  }
+
+  @Override
+  public <O extends OptionsBase> O getOptions(Class<O> optionsClass) {
+    return impl.getParsedOptions(optionsClass);
+  }
+
+  @Override
+  public boolean containsExplicitOption(String name) {
+    return impl.containsExplicitOption(name);
+  }
+
+  @Override
+  public List<UnparsedOptionValueDescription> asListOfUnparsedOptions() {
+    return impl.asListOfUnparsedOptions();
+  }
+
+  @Override
+  public List<UnparsedOptionValueDescription> asListOfExplicitOptions() {
+    return impl.asListOfExplicitOptions();
+  }
+
+  @Override
+  public List<OptionValueDescription> asListOfEffectiveOptions() {
+    return impl.asListOfEffectiveOptions();
+  }
+}
diff --git a/src/main/java/com/google/devtools/common/options/OptionsParserImpl.java b/src/main/java/com/google/devtools/common/options/OptionsParserImpl.java
new file mode 100644
index 0000000..e339dcd
--- /dev/null
+++ b/src/main/java/com/google/devtools/common/options/OptionsParserImpl.java
@@ -0,0 +1,722 @@
+// Copyright 2014 Google Inc. All rights reserved.
+//
+// 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.devtools.common.options;
+
+import com.google.common.base.Function;
+import com.google.common.base.Functions;
+import com.google.common.base.Joiner;
+import com.google.common.base.Preconditions;
+import com.google.common.base.Predicate;
+import com.google.common.collect.ArrayListMultimap;
+import com.google.common.collect.ImmutableList;
+import com.google.common.collect.Iterables;
+import com.google.common.collect.ListMultimap;
+import com.google.common.collect.Lists;
+import com.google.common.collect.Maps;
+import com.google.devtools.common.options.OptionsParser.OptionValueDescription;
+import com.google.devtools.common.options.OptionsParser.UnparsedOptionValueDescription;
+
+import java.lang.reflect.Constructor;
+import java.lang.reflect.Field;
+import java.lang.reflect.ParameterizedType;
+import java.lang.reflect.Type;
+import java.util.Arrays;
+import java.util.Collection;
+import java.util.Collections;
+import java.util.Comparator;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * The implementation of the options parser. This is intentionally package
+ * private for full flexibility. Use {@link OptionsParser} or {@link Options}
+ * if you're a consumer.
+ */
+class OptionsParserImpl {
+
+  /**
+   * A bunch of default converters in case the user doesn't specify a
+   * different one in the field annotation.
+   */
+  static final Map<Class<?>, Converter<?>> DEFAULT_CONVERTERS = Maps.newHashMap();
+
+  static {
+    DEFAULT_CONVERTERS.put(String.class, new Converter<String>() {
+      @Override
+      public String convert(String input) {
+        return input;
+      }
+      @Override
+      public String getTypeDescription() {
+        return "a string";
+      }});
+    DEFAULT_CONVERTERS.put(int.class, new Converter<Integer>() {
+      @Override
+      public Integer convert(String input) throws OptionsParsingException {
+        try {
+          return Integer.decode(input);
+        } catch (NumberFormatException e) {
+          throw new OptionsParsingException("'" + input + "' is not an int");
+        }
+      }
+      @Override
+      public String getTypeDescription() {
+        return "an integer";
+      }});
+    DEFAULT_CONVERTERS.put(double.class, new Converter<Double>() {
+      @Override
+      public Double convert(String input) throws OptionsParsingException {
+        try {
+          return Double.parseDouble(input);
+        } catch (NumberFormatException e) {
+          throw new OptionsParsingException("'" + input + "' is not a double");
+        }
+      }
+      @Override
+      public String getTypeDescription() {
+        return "a double";
+      }});
+    DEFAULT_CONVERTERS.put(boolean.class, new Converters.BooleanConverter());
+    DEFAULT_CONVERTERS.put(TriState.class, new Converter<TriState>() {
+      @Override
+      public TriState convert(String input) throws OptionsParsingException {
+        if (input == null) {
+          return TriState.AUTO;
+        }
+        input = input.toLowerCase();
+        if (input.equals("auto")) {
+          return TriState.AUTO;
+        }
+        if (input.equals("true") || input.equals("1") || input.equals("yes") ||
+            input.equals("t") || input.equals("y")) {
+          return TriState.YES;
+        }
+        if (input.equals("false") || input.equals("0") || input.equals("no") ||
+            input.equals("f") || input.equals("n")) {
+          return TriState.NO;
+        }
+        throw new OptionsParsingException("'" + input + "' is not a boolean");
+      }
+      @Override
+      public String getTypeDescription() {
+        return "a tri-state (auto, yes, no)";
+      }});
+    DEFAULT_CONVERTERS.put(Void.class, new Converter<Void>() {
+      @Override
+      public Void convert(String input) throws OptionsParsingException {
+        if (input == null) {
+          return null;  // expected input, return is unused so null is fine.
+        }
+        throw new OptionsParsingException("'" + input + "' unexpected");
+      }
+      @Override
+      public String getTypeDescription() {
+        return "";
+      }});
+    DEFAULT_CONVERTERS.put(long.class, new Converter<Long>() {
+      @Override
+      public Long convert(String input) throws OptionsParsingException {
+        try {
+          return Long.decode(input);
+        } catch (NumberFormatException e) {
+          throw new OptionsParsingException("'" + input + "' is not a long");
+        }
+      }
+      @Override
+      public String getTypeDescription() {
+        return "a long integer";
+      }});
+  }
+
+  /**
+   * For every value, this class keeps track of its priority, its free-form source
+   * description, whether it was set as an implicit dependency, and the value.
+   */
+  private static final class ParsedOptionEntry {
+    private final Object value;
+    private final OptionPriority priority;
+    private final String source;
+    private final String implicitDependant;
+    private final String expandedFrom;
+    private final boolean allowMultiple;
+
+    ParsedOptionEntry(Object value,
+        OptionPriority priority, String source, String implicitDependant, String expandedFrom,
+        boolean allowMultiple) {
+      this.value = value;
+      this.priority = priority;
+      this.source = source;
+      this.implicitDependant = implicitDependant;
+      this.expandedFrom = expandedFrom;
+      this.allowMultiple = allowMultiple;
+    }
+
+    // Need to suppress unchecked warnings, because the "multiple occurrence"
+    // options use unchecked ListMultimaps due to limitations of Java generics.
+    @SuppressWarnings({"unchecked", "rawtypes"})
+    Object getValue() {
+      if (allowMultiple) {
+        // Sort the results by option priority and return them in a new list.
+        // The generic type of the list is not known at runtime, so we can't
+        // use it here. It was already checked in the constructor, so this is
+        // type-safe.
+        List result = Lists.newArrayList();
+        ListMultimap realValue = (ListMultimap) value;
+        for (OptionPriority priority : OptionPriority.values()) {
+          // If there is no mapping for this key, this check avoids object creation (because
+          // ListMultimap has to return a new object on get) and also an unnecessary addAll call.
+          if (realValue.containsKey(priority)) {
+            result.addAll(realValue.get(priority));
+          }
+        }
+        return result;
+      }
+      return value;
+    }
+
+    // Need to suppress unchecked warnings, because the "multiple occurrence"
+    // options use unchecked ListMultimaps due to limitations of Java generics.
+    @SuppressWarnings({"unchecked", "rawtypes"})
+    void addValue(OptionPriority addedPriority, Object addedValue) {
+      Preconditions.checkState(allowMultiple);
+      ListMultimap optionValueList = (ListMultimap) value;
+      if (addedValue instanceof List<?>) {
+        for (Object element : (List<?>) addedValue) {
+          optionValueList.put(addedPriority, element);
+        }
+      } else {
+        optionValueList.put(addedPriority, addedValue);
+      }
+    }
+
+    OptionValueDescription asOptionValueDescription(String fieldName) {
+      return new OptionValueDescription(fieldName, getValue(), priority,
+          source, implicitDependant, expandedFrom);
+    }
+  }
+
+  private final OptionsData optionsData;
+
+  /**
+   * We store the results of parsing the arguments in here. It'll look like
+   * <pre>
+   *   Field("--host") -> "www.google.com"
+   *   Field("--port") -> 80
+   * </pre>
+   * This map is modified by repeated calls to
+   * {@link #parse(OptionPriority,Function,List)}.
+   */
+  private final Map<Field, ParsedOptionEntry> parsedValues = Maps.newHashMap();
+
+  /**
+   * We store the pre-parsed, explicit options for each priority in here.
+   * We use partially preparsed options, which can be different from the original
+   * representation, e.g. "--nofoo" becomes "--foo=0".
+   */
+  private final List<UnparsedOptionValueDescription> unparsedValues =
+      Lists.newArrayList();
+
+  private final List<String> warnings = Lists.newArrayList();
+  
+  private boolean allowSingleDashLongOptions = false;
+
+  /**
+   * Create a new parser object
+   */
+  OptionsParserImpl(OptionsData optionsData) {
+    this.optionsData = optionsData;
+  }
+
+  /**
+   * Indicates whether or not the parser will allow long options with a
+   * single-dash, instead of the usual double-dash, too, eg. -example instead of just --example.
+   */
+  void setAllowSingleDashLongOptions(boolean allowSingleDashLongOptions) {
+    this.allowSingleDashLongOptions = allowSingleDashLongOptions;
+  }
+  
+  /**
+   * The implementation of {@link OptionsBase#asMap}.
+   */
+  static Map<String, Object> optionsAsMap(OptionsBase optionsInstance) {
+    Map<String, Object> map = Maps.newHashMap();
+    for (Field field : OptionsParser.getAllAnnotatedFields(optionsInstance.getClass())) {
+      try {
+        String name = field.getAnnotation(Option.class).name();
+        Object value = field.get(optionsInstance);
+        map.put(name, value);
+      } catch (IllegalAccessException e) {
+        throw new IllegalStateException(e); // unreachable
+      }
+    }
+    return map;
+  }
+
+  List<Field> getAnnotatedFieldsFor(Class<? extends OptionsBase> clazz) {
+    return optionsData.getFieldsForClass(clazz);
+  }
+
+  /**
+   * Implements {@link OptionsParser#asListOfUnparsedOptions()}.
+   */
+  List<UnparsedOptionValueDescription> asListOfUnparsedOptions() {
+    List<UnparsedOptionValueDescription> result = Lists.newArrayList(unparsedValues);
+    // It is vital that this sort is stable so that options on the same priority are not reordered.
+    Collections.sort(result, new Comparator<UnparsedOptionValueDescription>() {
+      @Override
+      public int compare(UnparsedOptionValueDescription o1,
+          UnparsedOptionValueDescription o2) {
+        return o1.getPriority().compareTo(o2.getPriority());
+      }
+    });
+    return result;
+  }
+
+  /**
+   * Implements {@link OptionsParser#asListOfExplicitOptions()}.
+   */
+  List<UnparsedOptionValueDescription> asListOfExplicitOptions() {
+    List<UnparsedOptionValueDescription> result = Lists.newArrayList(Iterables.filter(
+      unparsedValues,
+      new Predicate<UnparsedOptionValueDescription>() {
+        @Override
+        public boolean apply(UnparsedOptionValueDescription input) {
+          return input.isExplicit();
+        }
+    }));
+    // It is vital that this sort is stable so that options on the same priority are not reordered.
+    Collections.sort(result, new Comparator<UnparsedOptionValueDescription>() {
+      @Override
+      public int compare(UnparsedOptionValueDescription o1,
+          UnparsedOptionValueDescription o2) {
+        return o1.getPriority().compareTo(o2.getPriority());
+      }
+    });
+    return result;
+  }
+
+  /**
+   * Implements {@link OptionsParser#canonicalize}.
+   */
+  List<String> asCanonicalizedList() {
+    List<UnparsedOptionValueDescription> processed = Lists.newArrayList(unparsedValues);
+    Collections.sort(processed, new Comparator<UnparsedOptionValueDescription>() {
+      // This Comparator sorts implicit requirement options to the end, keeping their existing
+      // order, and sorts the other options alphabetically.
+      @Override
+      public int compare(UnparsedOptionValueDescription o1,
+          UnparsedOptionValueDescription o2) {
+        if (o1.isImplicitRequirement()) {
+          return o2.isImplicitRequirement() ? 0 : 1;
+        }
+        if (o2.isImplicitRequirement()) {
+          return -1;
+        }
+        return o1.getName().compareTo(o2.getName());
+      }
+    });
+
+    List<String> result = Lists.newArrayList();
+    for (int i = 0; i < processed.size(); i++) {
+      UnparsedOptionValueDescription value = processed.get(i);
+      // Skip an option if the next option is the same, but only if the option does not allow
+      // multiple values.
+      if (!value.allowMultiple()) {
+        if ((i < processed.size() - 1) && value.getName().equals(processed.get(i + 1).getName())) {
+          continue;
+        }
+      }
+
+      // Ignore expansion options.
+      if (value.isExpansion()) {
+        continue;
+      }
+
+      result.add("--" + value.getName() + "=" + value.getUnparsedValue());
+    }
+    return result;
+  }
+
+  /**
+   * Implements {@link OptionsParser#asListOfEffectiveOptions()}.
+   */
+  List<OptionValueDescription> asListOfEffectiveOptions() {
+    List<OptionValueDescription> result = Lists.newArrayList();
+    for (Map.Entry<String,Field> mapEntry : optionsData.getAllNamedFields()) {
+      String fieldName = mapEntry.getKey();
+      Field field = mapEntry.getValue();
+      ParsedOptionEntry entry = parsedValues.get(field);
+      if (entry == null) {
+        Object value = optionsData.getDefaultValue(field);
+        result.add(new OptionValueDescription(fieldName, value, OptionPriority.DEFAULT,
+            null, null, null));
+      } else {
+        result.add(entry.asOptionValueDescription(fieldName));
+      }
+    }
+    return result;
+  }
+
+  Collection<Class<?  extends OptionsBase>> getOptionsClasses() {
+    return optionsData.getOptionsClasses();
+  }
+
+  private void maybeAddDeprecationWarning(Field field) {
+    Option option = field.getAnnotation(Option.class);
+    // Continue to support the old behavior for @Deprecated options.
+    String warning = option.deprecationWarning();
+    if (!warning.equals("") || (field.getAnnotation(Deprecated.class) != null)) {
+      warnings.add("Option '" + option.name() + "' is deprecated"
+          + (warning.equals("") ? "" : ": " + warning));
+    }
+  }
+
+  // Warnings should not end with a '.' because the internal reporter adds one automatically.
+  private void setValue(Field field, String name, Object value,
+      OptionPriority priority, String source, String implicitDependant, String expandedFrom) {
+    ParsedOptionEntry entry = parsedValues.get(field);
+    if (entry != null) {
+      // Override existing option if the new value has higher or equal priority.
+      if (priority.compareTo(entry.priority) >= 0) {
+        // Output warnings:
+        if ((implicitDependant != null) && (entry.implicitDependant != null)) {
+          if (!implicitDependant.equals(entry.implicitDependant)) {
+            warnings.add("Option '" + name + "' is implicitly defined by both option '" +
+                entry.implicitDependant + "' and option '" + implicitDependant + "'");
+          }
+        } else if ((implicitDependant != null) && priority.equals(entry.priority)) {
+          warnings.add("Option '" + name + "' is implicitly defined by option '" +
+              implicitDependant + "'; the implicitly set value overrides the previous one");
+        } else if (entry.implicitDependant != null) {
+          warnings.add("A new value for option '" + name + "' overrides a previous " +
+              "implicit setting of that option by option '" + entry.implicitDependant + "'");
+        } else if ((priority == entry.priority) &&
+            ((entry.expandedFrom == null) && (expandedFrom != null))) {
+          // Create a warning if an expansion option overrides an explicit option:
+          warnings.add("The option '" + expandedFrom + "' was expanded and now overrides a "
+              + "previous explicitly specified option '" + name + "'");
+        }
+
+        // Record the new value:
+        parsedValues.put(field,
+            new ParsedOptionEntry(value, priority, source, implicitDependant, expandedFrom, false));
+      }
+    } else {
+      parsedValues.put(field,
+          new ParsedOptionEntry(value, priority, source, implicitDependant, expandedFrom, false));
+      maybeAddDeprecationWarning(field);
+    }
+  }
+
+  private void addListValue(Field field, String name, Object value,
+      OptionPriority priority, String source, String implicitDependant, String expandedFrom) {
+    ParsedOptionEntry entry = parsedValues.get(field);
+    if (entry == null) {
+      entry = new ParsedOptionEntry(ArrayListMultimap.create(), priority, source,
+          implicitDependant, expandedFrom, true);
+      parsedValues.put(field, entry);
+      maybeAddDeprecationWarning(field);
+    }
+    entry.addValue(priority, value);
+  }
+
+  private Object getValue(Field field) {
+    ParsedOptionEntry entry = parsedValues.get(field);
+    return entry == null ? null : entry.getValue();
+  }
+
+  OptionValueDescription getOptionValueDescription(String name) {
+    Field field = optionsData.getFieldFromName(name);
+    if (field == null) {
+      throw new IllegalArgumentException("No such option '" + name + "'");
+    }
+    ParsedOptionEntry entry = parsedValues.get(field);
+    if (entry == null) {
+      return null;
+    }
+    return entry.asOptionValueDescription(name);
+  }
+
+  boolean containsExplicitOption(String name) {
+    Field field = optionsData.getFieldFromName(name);
+    if (field == null) {
+      throw new IllegalArgumentException("No such option '" + name + "'");
+    }
+    return parsedValues.get(field) != null;
+  }
+
+  /**
+   * Parses the args, and returns what it doesn't parse. May be called multiple
+   * times, and may be called recursively. In each call, there may be no
+   * duplicates, but separate calls may contain intersecting sets of options; in
+   * that case, the arg seen last takes precedence.
+   */
+  List<String> parse(OptionPriority priority, Function<? super String, String> sourceFunction,
+      List<String> args) throws OptionsParsingException {
+    return parse(priority, sourceFunction, null, null, args);
+  }
+
+  /**
+   * Parses the args, and returns what it doesn't parse. May be called multiple
+   * times, and may be called recursively. Calls may contain intersecting sets
+   * of options; in that case, the arg seen last takes precedence.
+   *
+   * <p>The method uses the invariant that if an option has neither an implicit
+   * dependant nor an expanded from value, then it must have been explicitly
+   * set.
+   */
+  private List<String> parse(OptionPriority priority,
+      final Function<? super String, String> sourceFunction, String implicitDependant,
+      String expandedFrom, List<String> args) throws OptionsParsingException {
+    List<String> unparsedArgs = Lists.newArrayList();
+    LinkedHashMap<String,List<String>> implicitRequirements = Maps.newLinkedHashMap();
+    for (int pos = 0; pos < args.size(); pos++) {
+      String arg = args.get(pos);
+      if (!arg.startsWith("-")) {
+        unparsedArgs.add(arg);
+        continue;  // not an option arg
+      }
+      if (arg.equals("--")) {  // "--" means all remaining args aren't options
+        while (++pos < args.size()) {
+          unparsedArgs.add(args.get(pos));
+        }
+        break;
+      }
+
+      String value = null;
+      Field field;
+      boolean booleanValue = true;
+
+      if (arg.length() == 2) { // -l  (may be nullary or unary)
+        field = optionsData.getFieldForAbbrev(arg.charAt(1));
+        booleanValue = true;
+
+      } else if (arg.length() == 3 && arg.charAt(2) == '-') { // -l-  (boolean)
+        field = optionsData.getFieldForAbbrev(arg.charAt(1));
+        booleanValue = false;
+
+      } else if (allowSingleDashLongOptions // -long_option
+          || arg.startsWith("--")) { // or --long_option
+        int equalsAt = arg.indexOf('=');
+        int nameStartsAt = arg.startsWith("--") ? 2 : 1;
+        String name =
+            equalsAt == -1 ? arg.substring(nameStartsAt) : arg.substring(nameStartsAt, equalsAt);
+        if (name.trim().equals("")) {
+          throw new OptionsParsingException("Invalid options syntax: " + arg, arg);
+        }
+        value = equalsAt == -1 ? null : arg.substring(equalsAt + 1);
+        field = optionsData.getFieldFromName(name);
+
+        // look for a "no"-prefixed option name: "no<optionname>";
+        // (Undocumented: we also allow --no_foo.  We're generous like that.)
+        if (field == null && name.startsWith("no")) {
+          String realname = name.substring(name.startsWith("no_") ? 3 : 2);
+          field = optionsData.getFieldFromName(realname);
+          booleanValue = false;
+          if (field != null) {
+            // TODO(bazel-team): Add tests for these cases.
+            if (!OptionsParserImpl.isBooleanField(field)) {
+              throw new OptionsParsingException(
+                  "Illegal use of 'no' prefix on non-boolean option: " + arg, arg);
+            }
+            if (value != null) {
+              throw new OptionsParsingException(
+                  "Unexpected value after boolean option: " + arg, arg);
+            }
+            // "no<optionname>" signifies a boolean option w/ false value
+            value = "0";
+          }
+        }
+
+      } else {
+        throw new OptionsParsingException("Invalid options syntax: " + arg, arg);
+      }
+
+      if (field == null) {
+        throw new OptionsParsingException("Unrecognized option: " + arg, arg);
+      }
+      
+      if (value == null) {
+        // special case boolean to supply value based on presence of "no" prefix
+        if (OptionsParserImpl.isBooleanField(field)) {
+          value = booleanValue ? "1" : "0";
+        } else if (field.getType().equals(Void.class)) {
+          // this is expected, Void type options have no args
+        } else if (pos != args.size() - 1) {
+          value = args.get(++pos);  // "--flag value" form
+        } else {
+          throw new OptionsParsingException("Expected value after " + arg);
+        }
+      }
+
+      Option option = field.getAnnotation(Option.class);
+      final String originalName = option.name();
+      if (implicitDependant == null) {
+        // Log explicit options and expanded options in the order they are parsed (can be sorted
+        // later). Also remember whether they were expanded or not. This information is needed to
+        // correctly canonicalize flags.
+        unparsedValues.add(new UnparsedOptionValueDescription(originalName, field, value,
+            priority, sourceFunction.apply(originalName), expandedFrom == null));
+      }
+
+      // Handle expansion options.
+      if (option.expansion().length > 0) {
+        Function<Object, String> expansionSourceFunction = Functions.<String>constant(
+            "expanded from option --" + originalName + " from " +
+            sourceFunction.apply(originalName));
+        maybeAddDeprecationWarning(field);
+        List<String> unparsed = parse(priority, expansionSourceFunction, null, originalName,
+            ImmutableList.copyOf(option.expansion()));
+        if (!unparsed.isEmpty()) {
+          // Throw an assertion, because this indicates an error in the code that specified the
+          // expansion for the current option.
+          throw new AssertionError("Unparsed options remain after parsing expansion of " +
+            arg + ":" + Joiner.on(' ').join(unparsed));
+        }
+      } else {
+        Converter<?> converter = optionsData.getConverter(field);
+        Object convertedValue;
+        try {
+          convertedValue = converter.convert(value);
+        } catch (OptionsParsingException e) {
+          // The converter doesn't know the option name, so we supply it here by
+          // re-throwing:
+          throw new OptionsParsingException("While parsing option " + arg
+                                            + ": " + e.getMessage(), e);
+        }
+
+        // ...but allow duplicates of single-use options across separate calls to
+        // parse(); latest wins:
+        if (!option.allowMultiple()) {
+          setValue(field, originalName, convertedValue,
+              priority, sourceFunction.apply(originalName), implicitDependant, expandedFrom);
+        } else {
+          // But if it's a multiple-use option, then just accumulate the
+          // values, in the order in which they were seen.
+          // Note: The type of the list member is not known; Java introspection
+          // only makes it available in String form via the signature string
+          // for the field declaration.
+          addListValue(field, originalName, convertedValue,
+              priority, sourceFunction.apply(originalName), implicitDependant, expandedFrom);
+        }
+      }
+
+      // Collect any implicit requirements.
+      if (option.implicitRequirements().length > 0) {
+        implicitRequirements.put(option.name(), Arrays.asList(option.implicitRequirements()));
+      }
+    }
+
+    // Now parse any implicit requirements that were collected.
+    // TODO(bazel-team): this should happen when the option is encountered.
+    if (!implicitRequirements.isEmpty()) {
+      for (Map.Entry<String,List<String>> entry : implicitRequirements.entrySet()) {
+        Function<Object, String> requirementSourceFunction = Functions.<String>constant(
+            "implicit requirement of option --" + entry.getKey() + " from " +
+            sourceFunction.apply(entry.getKey()));
+
+        List<String> unparsed = parse(priority, requirementSourceFunction, entry.getKey(), null,
+            entry.getValue());
+        if (!unparsed.isEmpty()) {
+          // Throw an assertion, because this indicates an error in the code that specified in the
+          // implicit requirements for the option(s).
+          throw new AssertionError("Unparsed options remain after parsing implicit options:"
+              + Joiner.on(' ').join(unparsed));
+        }
+      }
+    }
+
+    return unparsedArgs;
+  }
+
+  /**
+   * Gets the result of parsing the options.
+   */
+  <O extends OptionsBase> O getParsedOptions(Class<O> optionsClass) {
+    // Create the instance:
+    O optionsInstance;
+    try {
+      Constructor<O> constructor = optionsData.getConstructor(optionsClass);
+      if (constructor == null) {
+        return null;
+      }
+      optionsInstance = constructor.newInstance(new Object[0]);
+    } catch (Exception e) {
+      throw new IllegalStateException(e);
+    }
+
+    // Set the fields
+    for (Field field : optionsData.getFieldsForClass(optionsClass)) {
+      Object value = getValue(field);
+      if (value == null) {
+        value = optionsData.getDefaultValue(field);
+      }
+      try {
+        field.set(optionsInstance, value);
+      } catch (IllegalAccessException e) {
+        throw new IllegalStateException(e);
+      }
+    }
+    return optionsInstance;
+  }
+
+  List<String> getWarnings() {
+    return ImmutableList.copyOf(warnings);
+  }
+
+  static String getDefaultOptionString(Field optionField) {
+    Option annotation = optionField.getAnnotation(Option.class);
+    return annotation.defaultValue();
+  }
+
+  static boolean isBooleanField(Field field) {
+    return field.getType().equals(boolean.class) || field.getType().equals(TriState.class);
+  }
+
+  static boolean isSpecialNullDefault(String defaultValueString, Field optionField) {
+    return defaultValueString.equals("null") && !optionField.getType().isPrimitive();
+  }
+
+  static Converter<?> findConverter(Field optionField) {
+    Option annotation = optionField.getAnnotation(Option.class);
+    if (annotation.converter() == Converter.class) {
+      Type type;
+      if (annotation.allowMultiple()) {
+        // The OptionParserImpl already checked that the type is List<T> for some T;
+        // here we extract the type T.
+        type = ((ParameterizedType) optionField.getGenericType()).getActualTypeArguments()[0];
+      } else {
+        type = optionField.getType();
+      }
+      Converter<?> converter = DEFAULT_CONVERTERS.get(type);
+      if (converter == null) {
+        throw new AssertionError("No converter found for "
+            + type + "; possible fix: add "
+            + "converter=... to @Option annotation for "
+            + optionField.getName());
+      }
+      return converter;
+    }
+    try {
+      Class<?> converter = annotation.converter();
+      Constructor<?> constructor = converter.getConstructor(new Class<?>[0]);
+      return (Converter<?>) constructor.newInstance(new Object[0]);
+    } catch (Exception e) {
+      throw new AssertionError(e);
+    }
+  }
+
+}
diff --git a/src/main/java/com/google/devtools/common/options/OptionsParsingException.java b/src/main/java/com/google/devtools/common/options/OptionsParsingException.java
new file mode 100644
index 0000000..9d2916a
--- /dev/null
+++ b/src/main/java/com/google/devtools/common/options/OptionsParsingException.java
@@ -0,0 +1,50 @@
+// Copyright 2014 Google Inc. All rights reserved.
+//
+// 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.devtools.common.options;
+
+/**
+ * An exception that's thrown when the {@link OptionsParser} fails.
+ *
+ * @see OptionsParser#parse(OptionPriority,String,java.util.List)
+ */
+public class OptionsParsingException extends Exception {
+  private final String invalidArgument;
+
+  public OptionsParsingException(String message) {
+    this(message, (String) null);
+  }
+
+  public OptionsParsingException(String message, String argument) {
+    super(message);
+    this.invalidArgument = argument;
+  }
+
+  public OptionsParsingException(String message, Throwable throwable) {
+    this(message, null, throwable);
+  }
+
+  public OptionsParsingException(String message, String argument, Throwable throwable) {
+    super(message, throwable);
+    this.invalidArgument = argument;
+  }
+
+  /**
+   * Gets the name of the invalid argument or {@code null} if the exception
+   * can not determine the exact invalid arguments
+   */
+  public String getInvalidArgument() {
+    return invalidArgument;
+  }
+}
diff --git a/src/main/java/com/google/devtools/common/options/OptionsProvider.java b/src/main/java/com/google/devtools/common/options/OptionsProvider.java
new file mode 100644
index 0000000..be399a7
--- /dev/null
+++ b/src/main/java/com/google/devtools/common/options/OptionsProvider.java
@@ -0,0 +1,67 @@
+// Copyright 2014 Google Inc. All rights reserved.
+//
+// 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.devtools.common.options;
+
+import com.google.devtools.common.options.OptionsParser.OptionValueDescription;
+import com.google.devtools.common.options.OptionsParser.UnparsedOptionValueDescription;
+
+import java.util.List;
+
+/**
+ * A read-only interface for options parser results, which does not allow any
+ * further parsing of options.
+ */
+public interface OptionsProvider extends OptionsClassProvider {
+
+  /**
+   * Returns an immutable copy of the residue, that is, the arguments that
+   * have not been parsed.
+   */
+  List<String> getResidue();
+
+  /**
+   * Returns if the named option was specified explicitly in a call to parse.
+   */
+  boolean containsExplicitOption(String string);
+
+  /**
+   * Returns a mutable copy of the list of all options that were specified
+   * either explicitly or implicitly. These options are sorted by priority, and
+   * by the order in which they were specified. If an option was specified
+   * multiple times, it is included in the result multiple times. Does not
+   * include the residue.
+   *
+   * <p>The returned list can be filtered if undocumented, hidden or implicit
+   * options should not be displayed.
+   */
+  List<UnparsedOptionValueDescription> asListOfUnparsedOptions();
+
+  /**
+   * Returns a list of all explicitly specified options, suitable for logging
+   * or for displaying back to the user. These options are sorted by priority,
+   * and by the order in which they were specified. If an option was
+   * explicitly specified multiple times, it is included in the result
+   * multiple times. Does not include the residue.
+   *
+   * <p>The list includes undocumented options.
+   */
+  public List<UnparsedOptionValueDescription> asListOfExplicitOptions();
+
+  /**
+   * Returns a list of all options, including undocumented ones, and their
+   * effective values. There is no guaranteed ordering for the result.
+   */
+  public List<OptionValueDescription> asListOfEffectiveOptions();
+}
diff --git a/src/main/java/com/google/devtools/common/options/OptionsUsage.java b/src/main/java/com/google/devtools/common/options/OptionsUsage.java
new file mode 100644
index 0000000..c48a532
--- /dev/null
+++ b/src/main/java/com/google/devtools/common/options/OptionsUsage.java
@@ -0,0 +1,156 @@
+// Copyright 2014 Google Inc. All rights reserved.
+//
+// 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.devtools.common.options;
+
+import static com.google.devtools.common.options.OptionsParserImpl.findConverter;
+
+import com.google.common.base.Splitter;
+import com.google.common.base.Strings;
+import com.google.common.collect.Lists;
+
+import java.lang.reflect.Field;
+import java.text.BreakIterator;
+import java.util.Collections;
+import java.util.Comparator;
+import java.util.List;
+
+/**
+ * A renderer for usage messages. For now this is very simple.
+ */
+class OptionsUsage {
+
+  private static final Splitter NEWLINE_SPLITTER = Splitter.on('\n');
+
+  /**
+   * Given an options class, render the usage string into the usage,
+   * which is passed in as an argument.
+   */
+  static void getUsage(Class<? extends OptionsBase> optionsClass, StringBuilder usage) {
+    List<Field> optionFields =
+        Lists.newArrayList(OptionsParser.getAllAnnotatedFields(optionsClass));
+    Collections.sort(optionFields, BY_NAME);
+    for (Field optionField : optionFields) {
+      getUsage(optionField, usage, OptionsParser.HelpVerbosity.LONG);
+    }
+  }
+
+  /**
+   * Paragraph-fill the specified input text, indenting lines to 'indent' and
+   * wrapping lines at 'width'.  Returns the formatted result.
+   */
+  static String paragraphFill(String in, int indent, int width) {
+    String indentString = Strings.repeat(" ", indent);
+    StringBuilder out = new StringBuilder();
+    String sep = "";
+    for (String paragraph : NEWLINE_SPLITTER.split(in)) {
+      BreakIterator boundary = BreakIterator.getLineInstance(); // (factory)
+      boundary.setText(paragraph);
+      out.append(sep).append(indentString);
+      int cursor = indent;
+      for (int start = boundary.first(), end = boundary.next();
+           end != BreakIterator.DONE;
+           start = end, end = boundary.next()) {
+        String word =
+            paragraph.substring(start, end); // (may include trailing space)
+        if (word.length() + cursor > width) {
+          out.append('\n').append(indentString);
+          cursor = indent;
+        }
+        out.append(word);
+        cursor += word.length();
+      }
+      sep = "\n";
+    }
+    return out.toString();
+  }
+
+  /**
+   * Append the usage message for a single option-field message to 'usage'.
+   */
+  static void getUsage(Field optionField, StringBuilder usage,
+                       OptionsParser.HelpVerbosity helpVerbosity) {
+    String flagName = getFlagName(optionField);
+    String typeDescription = getTypeDescription(optionField);
+    Option annotation = optionField.getAnnotation(Option.class);
+    usage.append("  --" + flagName);
+    if (helpVerbosity == OptionsParser.HelpVerbosity.SHORT) { // just the name
+      usage.append('\n');
+      return;
+    }
+    if (annotation.abbrev() != '\0') {
+      usage.append(" [-").append(annotation.abbrev()).append(']');
+    }
+    if (!typeDescription.equals("")) {
+      usage.append(" (" + typeDescription + "; ");
+      if (annotation.allowMultiple()) {
+        usage.append("may be used multiple times");
+      } else {
+        // Don't call the annotation directly (we must allow overrides to certain defaults)
+        String defaultValueString = OptionsParserImpl.getDefaultOptionString(optionField);
+        if (OptionsParserImpl.isSpecialNullDefault(defaultValueString, optionField)) {
+          usage.append("default: see description");
+        } else {
+          usage.append("default: \"" + defaultValueString + "\"");
+        }
+      }
+      usage.append(")");
+    }
+    usage.append("\n");
+    if (helpVerbosity == OptionsParser.HelpVerbosity.MEDIUM) { // just the name and type.
+      return;
+    }
+    if (!annotation.help().equals("")) {
+      usage.append(paragraphFill(annotation.help(), 4, 80)); // (indent, width)
+      usage.append('\n');
+    }
+    if (annotation.expansion().length > 0) {
+      StringBuilder expandsMsg = new StringBuilder("Expands to: ");
+      for (String exp : annotation.expansion()) {
+        expandsMsg.append(exp).append(" ");
+      }
+      usage.append(paragraphFill(expandsMsg.toString(), 4, 80)); // (indent, width)
+      usage.append('\n');
+    }
+  }
+
+  private static final Comparator<Field> BY_NAME = new Comparator<Field>() {
+    @Override
+    public int compare(Field left, Field right) {
+      return left.getName().compareTo(right.getName());
+    }
+  };
+
+  /**
+   * An ordering relation for option-field fields that first groups together
+   * options of the same category, then sorts by name within the category.
+   */
+  static final Comparator<Field> BY_CATEGORY = new Comparator<Field>() {
+    @Override
+    public int compare(Field left, Field right) {
+      int r = left.getAnnotation(Option.class).category().compareTo(
+              right.getAnnotation(Option.class).category());
+      return r == 0 ? BY_NAME.compare(left, right) : r;
+    }
+  };
+
+  private static String getTypeDescription(Field optionsField) {
+    return findConverter(optionsField).getTypeDescription();
+  }
+
+  static String getFlagName(Field field) {
+    String name = field.getAnnotation(Option.class).name();
+    return OptionsParserImpl.isBooleanField(field) ? "[no]" + name : name;
+  }
+
+}
diff --git a/src/main/java/com/google/devtools/common/options/TriState.java b/src/main/java/com/google/devtools/common/options/TriState.java
new file mode 100644
index 0000000..9e873ea
--- /dev/null
+++ b/src/main/java/com/google/devtools/common/options/TriState.java
@@ -0,0 +1,21 @@
+// Copyright 2014 Google Inc. All rights reserved.
+//
+// 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.devtools.common.options;
+
+/**
+ * Enum used to represent tri-state options (yes/no/auto).
+ */
+public enum TriState {
+  YES, NO, AUTO
+}