[GRASS-user] What exactly defines the "#% gisprompt:" in grass scripts?

[Glynn Clements]

Nikos Alexandris wrote:

> > > Where can I find a (very) detailed explanation about the following
> > > "definition" found in grass-scripts?
> > >
> > > #%  gisprompt: old,cell,raster
> > >
> > > What is the 1st (here = old), the 2nd (here = cell) and the 3rd (here =
> > > raster) part mean exactly?
> 
> Martin Landa:
> > http://download.osgeo.org/grass/grass7_progman/gislib.html#gisprompt_Member
> 
> IIUC, it is as follows:
> 
> 1st argument -> new (for new maps?), old (for existing maps?), output
> (for exported files?)
> 
> 2nd argument -> directory name within the grass-db
> 
> Q: is it always "cell" for raster maps? what about floating point maps?
> For example "grep -Fr "#% gisprompt" * | grep fcell" in grass_trunk
> source doesn't return anything. I've seen only "cell" entries.
> 
> 3rd argument -> type (e.g. raster, vector, color)
> 
> (Probably I don't understand it correctly)

The gisprompt field is used in several ways by different parts of
GRASS.

1. If any option has "new" as the first component, the --o (overwrite)
flag will be listed in the module's interface (--help output, manual
page, GUI dialog, etc).

2. If an option which has "new" as the first component is given, the
parser checks whether the entity (map, etc) already exists. The second
field is used to determine where to look for the file (i.e. if the
option has "new,cell,...", it will look in the "cell" directory).

IOW, the second field should be the name of one of the standard
subdirectories of the mapset, as listed in $GISBASE/etc/element_list.

3. If a module is run without arguments, and GRASS_UI_TERM is set
(indicating that terminal-based interaction should be used rather than
a GUI dialog), the gisprompt fields affect how the user is prompted
for values.

Specifically, the first field affects which of the G_ask_* functions
are used, while the second and third fields are passed as arguments. 
The second field will be used to select the type of elements to list
if the user enters "list", while the third field will typically be
incorporated into the prompt.

4. The gisprompt values are passed to any GUI code, both
self-contained dialogs generated by the parser for the --ui option,
and stand-alone GUIs (gis.m, wxGUI) which use the --tcltk or
--xml-description flags to obtain a machine-readable description of
the module's interface. How the GUI interprets this is up to the GUI.

Item #3 above is the original reason for the gisprompt field; the
others were added later. Also, option #3 isn't relevant to 7.0, which
has removed most of the terminal-based interaction.

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