[GRASS-dev] Re: [GRASS GIS] #1031: More specific parameter information in command line help

[GRASS GIS]

#1031: More specific parameter information in command line help
--------------------------+-------------------------------------------------
  Reporter:  huhabla      |       Owner:  grass-dev at lists.osgeo.org
      Type:  enhancement  |      Status:  new                      
  Priority:  minor        |   Milestone:  7.0.0                    
 Component:  libgis       |     Version:  svn-trunk                
Resolution:               |    Keywords:  parser, help             
  Platform:  All          |         Cpu:  All                      
--------------------------+-------------------------------------------------
Comment (by glynn):

 Replying to [comment:10 martinl]:

 > > I've been suggesting that the "type system" should be re-worked since
 roughly forever. I would have hoped that the wxGUI development would
 produce some feedback, but so far that hasn't happened.
 >
 > Can you elaborate a bit on your suggestion?

 Currently, the "type" is defined by a combination of fields:

 type, required, multiple, options, key_desc, gisprompt.

 The type field defines a base type: string, integer or floating-point.
 gis_prompt may refine the base type to a more specific type. options
 replaces the base type with an enumeration type. required==NO converts the
 type to a "Maybe" type. multiple=YES converts the type to a list type
 (except that the GUI treats it as a set if the "options" field is set).
 key_desc converts the type to a tuple type if the description contains
 commas.

 My preference would be for a structured type system as is commonly found
 in high-level languages, where base types can be combined using
 constructors.

 Essentially, all of the above fields would be replaced by a single type
 field, whose value would be a pointer to an arbitrarily complex structure,
 with a set of functions for creating types. Off the top of my head, you
 would need:

 {{{
 // Base types:
 T_integer()
 T_integer_subrange(int first, int last, int step)
 T_integer_enumeration(int count, int val0, [, int val1, ...])
 T_real()
 T_real_subrange(double first, bool first_inclusive, double last, bool
 last_inclusive)
 T_string()
 T_string_enumeration(count, char* val0, [, char* val1, ...])
 T_string_enumeration_with_descs(count, char* val0, char *desc0, [, char*
 val1, char* desc1, ...])
 T_element(enum Element element, enum Age age)

 // Composite types:
 T_optional(Type* base)
 T_tuple(int count, Type* type0 [, Type* type1, ...])
 T_record(int count, char* name0, Type* type0 [, char* name1, Type* type1,
 ...])
 T_list(Type* type, bool allow_empty, bool allow_duplicates, bool
 order_matters)
 T_union(int count, Type* type0, Type* type1 [, Type* type2, ...])
 }}}

 So e.g.:

 {{{
 opt->type = T_union(2,
         T_integer_subrange(1, 99, 2),
         T_string_enumeration(2, "all", "none"));
 }}}

 would allow the option value to be any odd integer between 1 and 99
 inclusive or the strings "all" or "none".

 Variadic functions could either use a prefixed count or a NULL terminator
 (but the latter won't work for numbers).

 You would also need dependent base types, e.g. "column name within the
 database table associated with the map specified by the input= option".

 When it comes to parsing, you could implement such types using a generic
 mechanism using a callback function to enumerate or validate allowed
 values; however, we need to think about how this interacts with the GUI.

 One possibility would be:

 T_dependent(Type* (*callback)(int argc, char**argv), char* opt0 [, char*
 opt1, ...])

 The parser would provide an option to expand an option's type given a
 partial list of option values, e.g.

 {{{
 d.vect --expand=rgb_column map=inmap
 }}}

 would convert the rgb_column= option's dependent type to a fixed
 enumeration of the available columns for the specified input map.

 The alternative is to simply add each case as a separate base type, i.e.:

 {{{
 T_database_column(char* driver_opt, char* database_opt, char* table_opt)
 T_map_database_column(char* map_opt)
 }}}

 The --interface description would simply report the information verbatim
 and the GUI would be responsible for enumeration.

-- 
Ticket URL: <http://trac.osgeo.org/grass/ticket/1031#comment:13>
GRASS GIS <http://grass.osgeo.org>