commons-issues mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Emmanuel Bourg (JIRA)" <>
Subject [jira] Commented: (CLI-196) Annotation based option specification
Date Tue, 13 Jul 2010 21:59:50 GMT


Emmanuel Bourg commented on CLI-196:

I18n could probably be implemented by adding a descriptionKey attribute as an alternative
to the description attribute. The resource bundle would be specified by an annotation at the
class level.

For the reference, the annotation based declaration has been implemented by Cedric Beust in
JCommander :

> Annotation based option specification
> -------------------------------------
>                 Key: CLI-196
>                 URL:
>             Project: Commons CLI
>          Issue Type: New Feature
>          Components: CLI-1.x
>            Reporter: Kevin Holloway
>            Priority: Minor
> This is a proposal for an alternative way of specifying command line options, using annotations.
 It's implementation wraps Commons CLI code and uses reflection.
> From a user perspective, the following is a example of a mythical program that takes
three arguments:
> -utc, reports the date in terms of UTC.
> -offset <integer>, adds an offset to the reference date.
> -reference <amount>, the reference amount (whatever that is).
> The Java code for the options is as follows:
> {code}
> public class XyzOptions {
>   private boolean utc;
>   private int offset;
>   private BigDecimal reference;
>   @Option (name="utc", description="Reports the date in terms of UTC")
>   void setUTC (boolean utc) {
>     this.utc = utc;
>   }
>   @Option (name="offset", description="Adds an offset to the reference date")
>   void setOffset (int offset) {
>     this.offset = offset;
>   }
>   @Option (name="reference", required=true, description="The reference amount")
>   void setReferenceAmount (BigDecimal amount) {
>     this.reference = amount;
>   }
>   // get methods omitted
> }
> {code}
> @Option is an annotation that provides CLI option details.  The @Option annotates set
methods of the options class.
> The Java code that uses these options is as follows:
> {code}
> public static void main (String[] args) {
>   XyzOptions options = CommandLine.parse(args, XyzOptions.class, "dateCommand");
>   // the program options can then be accessed using get methods or field access on the
options object.
> }
> {code}
> The "CommandLine" class is the class that builds the CLI Options instance using the @Option
annotations and reflection.  
> The @Option annotation allows the following to be specified:
> * name.  The short name of the option.
> * longForm.  The long form of the option.
> * description.  The description of the option.  This is the description that appears
in the help text.
> * required.  true if this option is required.  This defaults to false, meaning the option
is optional.
> * argOptional.  true if the option argument is optional.  This defaults to false, meaning
the option argument is mandatory.
> The remaining information is obtained by reflection on the set method parameter.
> * If the set method parameter is boolean or Boolean, the option is assumed to take no
argument.  It is a simple switch.
> * If the set method parameter takes any other type, the option is assumed to take an
argument of that type.
> ** If the parameter type is String, the option argument is used as-is.
> ** If the parameter type is a primitive type (or the class equivalent), the option argument
is converted to that type and passed to the set method.
> ** If the parameter type is something else (such as BigDecimal), the command line parser
looks for a class constructor that takes a String argument.  If this is found, and instance
of the object is created an passed to the set method.  Any class that has a constructor that
takes a single String argument can be used.
> Option arguments can be validated in the set methods.  For example, if a File needs to
be a directory, the set method could be as follows:
> {code}
>   @Option (name="dir", description="The output directory")
>   void setOutputDir (File file) {
>     if (!file.isDirectory()) {
>       throw new IllegalArgumentException ("'dir' option must specify a directory");
>     }
>     this.file = file;
> }
> {code}
> The code for what is described here is available if anyone wants it.
> This is the idea.  There are some issues to resolve, but the first question is: does
anyone think it worth pursuing this?

This message is automatically generated by JIRA.
You can reply to this email to add a comment to the issue online.

View raw message