[GRASS-dev] Interface description flag

[Glynn Clements]

Tyler Smith wrote:

> However, I also have utility functions that provide completion of
> vector and raster map names. I don't understand the output of
> --interface-description well enough to know if there's a way to
> automatically identify parameters that should be completed with a
> vector name lookup. For example, all of the following combinations are
> completed by a vector map file:
> 
> v.convert input= d.vect map= r.volume centroids= v.split input=
> 
> I notice that each of them has the following item in their <parameter> tag:
> 
> <gisprompt age="old" element="dig" prompt="vector" />
> 
> The age and element values differ, but all four have prompt="vector".
> 
> Can I use this to identify parameters that take a vector file name?

You should use the element field to identify options whose arguments
are vector or raster map names.

> That is, is the value of <gisprompt prompt="vector"> present for all
> commands that should be completed by a vector map name, and is this
> value absent from all other parameters?

The value of the "prompt" field is human-readable text (it dates back
to before the GUI, when running a command without options would result
in interactive prompts on the terminal).

The "element" field is machine-readable; it identifies the type of
entity to which the option refers (and, indirectly, the subdirectory
of the mapset directory where the data is stored; see the
etc/element_list file for the mapping between element names and
subdirectories).

If the "age" field is "old", then the file (or directory)
<mapset>/<element>/<name> must exist or an error is generated. If the
"age" field is "new", then <mapset>/<element>/<name> must not exist
unless the --overwrite option is given, or an error is generated.

So the "element" field can be assumed to reliably identify when an
option value must the name of a map (or similar entity, e.g. imagery
group, named region, icon, etc).

-- 
Glynn Clements <glynn at gclements.plus.com>