[mkgmap-dev] complete list of all mkgmap options

Tue Aug 4 11:57:29 BST 2009

Sounds good to me!

Maybe there is an open source  framework we could use: 
http://www.cyclopsgroup.org/projects/jcli/

Best wishes
Christian

Chris Miller schrieb:
> Something we've done at my current job is to write a CLI framework that makes 
> managing command line params very very easy. I think this project could benefit 
> greatly from this approach due to its large number of (frequently changing?) 
> parameters. Unfortunately I can't contribute our code, however I can describe 
> in detail what we did and help with the implementation. Basically each application 
> that uses command line params defines an interface that looks something like 
> this:
>
> public interface MkGMapParams {
>   @Option(defaultValue = "0", description = "The Family ID for the generated 
> map")
>   int getFamilyId();
>
>   @Option(defaultValue = Option.REQUIRED, description = "The Product ID for 
> the generated map")
>   int getProductId();
>
>   @Option(defaultValue = Option.OPTIONAL, description = "The country the 
> map represents")
>   String getCountryName();
>
>   @Option(description = "Specify this to make cycleways")
>   boolean isMakeCycleways();
>
>   enum MyEnum { One, Two }
>   @Option(name = "custom-enum", defaultValue = "One", description = "My custom 
> enum")
>   MyEnum getEnum();
>   // etc
> }
>
> To parse the parameters in code, we basically just make a call to our parser 
> as follows:
>
> MkGMapParams params = CliParser.parse(MkGMapParams.class, arguments);   // 
> where arguments is a String... parameter
>
> That's it, the 'params' object now has all our command line params, parsed 
> into the correct type. If any of the parsing failed, error(s) explaining 
> what was wrong, along with a list of valid options and descriptions, are 
> displayed to the user.
>
> Some valid usage examples:
> java -jar mkgmap --product-id 99 --country-name bhutan --make-cycleways
> java -jar mkgmap --product-id 99 --custom-enum Two
>
> Some invalid usage examples:
> java -jar mkgmap --family-id 99 --country-name bhutan --make-cycleways   
>  (fails because --product-id is a required parameter)
> java -jar mkgmap --product-id 99 --enum One    (fails because the 'enum' 
> parameter must be specified as --custom-enum, not --enum)
> java -jar mkgmap --product-id abc    (fails because --product-id is not an 
> integer)
> java -jar mkgmap --product-id 11 --family-id --make-cycleways  (fails because 
> no value was specified for --family-id)
>
>
> Here's how it works under the hood:
>
> We have a converter interface defined as follows:
>
> interface Converter<T> {
>   T convert(String param) throws Exception;         // Convert from the string 
> provided on the command line to a typesafe object.
>   List<String> getValidValues() throws Exception;  // Provide a list of valid 
> options (optional). eg a list of enum values.
>   String getDefaultValue() throws Exception;        // Returns the default 
> value (or null if the parameter is required).
> }
>
> We then have a map from type to converter class, eg:
>
> defaultConverters.put(String.class, StringConverter.class);
> defaultConverters.put(Integer.class, IntegerConverter.class);
> defaultConverters.put(Integer.type, IntegerConverter.class);
>
> We then use reflection (and the annotation info) to examine the interface 
> and determine what the valid parameters are, whether they're required, what 
> type they are etc. For each parameter we parse we convert the string to the 
> appropriate type using the above map. Once that's done and no errors were 
> found, we use Proxy.newProxyInstance() to create an instance of the parameter 
> interface for the client application.
>
> Note that we have a lot of additional functionality too like list handling, 
> custom converters, inter-parameter dependency handling, custom validation, 
> Guice support etc but the above is the guts of it. I hope it doesn't sound 
> like too much work - it's really not! The best thing is it will force people 
> to clearly define their parameters in the MkGMapParams interface since that's 
> the only thing that'll be available anywhere beyond the main() method. It's 
> very easy to use once the scaffolding is in place and it makes for nice centralised 
> management of params and user friendly help and error messages.
>
> Chris
>
>
>
> _______________________________________________
> mkgmap-dev mailing list
> mkgmap-dev at lists.mkgmap.org.uk
> http://www.mkgmap.org.uk/mailman/listinfo/mkgmap-dev
>   