Module command line parser: Difference between revisions

From GRASS-Wiki
Jump to navigation Jump to search
(+ Overview table of parser standard options)
 
(26 intermediate revisions by 4 users not shown)
Line 1: Line 1:
GRASS's command line parser is used by just about all modules to check input values, create help pages and GUIs. With the help of the ''g.parser'' module your shell or Python scripts can automatically generate help page templates and fully functional GUI windows.
GRASS GIS's command line parser is used by just about all modules to check input values, create help pages and GUIs. With the help of the ''g.parser'' module your shell or Python scripts can automatically generate help page templates and fully functional GUI windows. (This is a frontend for the G_parser() function in the C API; see the [http://grass.osgeo.org/programming7/parser_8c.html programmer's manual] if you are interested in that)
 
* see the [http://grass.ibiblio.org/grass63/manuals/html63_user/g.parser.html g.parser help page]
 


== Command line parser ==
== Command line parser ==


* options take user input (name or number) and of the style:
* Options take user input (name or number) and of the style:
  '''option='''''answer''
  '''option='''''answer''
* flags are on/off switches and of the style
* flags are on/off switches and of the style
  '''-f'''
  '''-f'''


* Run time flags and options can be mixed in any order. Special options to display help and GUI templates should appear on their own.
* Options may be tested for correct numerical value and range. For example testing if the numerical answer falls within 0-100 percent.
* Options may be limited to a discrete set of answers. This results in a pulldown menu in the GUI and a strict answer from the command line.


* the first option= listed by --help may be skiped, for example:
* The first option= listed by --help may be skipped, for example:
  d.rast elevation.dem
  d.rast elevation.dem
* option names may be shortened up to the point where they collide.
 
Thus shortening option names in a module with color= and column= options would require at minimum colo= and colu=.
* Examples (works with any existing GRASS GIS command):
  r.in.ascii --script
  v.in.ascii --script
 
* Option names may be shortened up to the point where they collide. Thus shortening option names in a module with color= and column= options would require at minimum colo= and colu=.
for example:
for example:
  '''input=''' → '''in='''  and  '''output=''' → '''out='''
  '''input=''' → '''in='''  and  '''output=''' → '''out='''


* flags may be combined behind a single "-". for example:
* Flags may be combined behind a single "-". for example:
  '''-r -f -t'''  is the same as  '''-rtf'''
  '''-r -f -t'''  is the same as  '''-rtf'''


* All modules can take the command line options --ui to force a GUI window, --overwrite to allow/force overwritting of maps and files, --quiet to make modules less noisy, --verbose to make modules more noisy, and --script to generate a shell script wrapper template.
* --quiet, --verbose, and --overwrite may be abbreviated as --q, --v, --o.
* --help or just 'help' by itself on the command line prints concise module command line option help. This help page will also be printed if there was an error parsing the command options.


== GUI window parser ==
== GUI window parser ==
* If a module is called with no options or flags specified then a GUI window is launched, unless the environment variable GRASS_UI_TERM is set (to any value), in which case the command-line interactive parser is launched.
* If a module is called with options and flags specified, but with the --ui flag, then a GUI window is started with those options and flags already set to the given values. (useful for interactive scripts)


* Auto-created from <tt>--tcltk</tt> or <tt>--interface-description</tt> (for XML) command line options.
* Auto-created from <tt>--tcltk</tt> or <tt>--interface-description</tt> (for XML) command line options.
Line 29: Line 41:
* Quotes to protect "special characters" from the shell are not needed here. Quotes needed to denote SQL 'strings' are still needed.
* Quotes to protect "special characters" from the shell are not needed here. Quotes needed to denote SQL 'strings' are still needed.


== Help page template ==
== Interactive text based UI parser ==
 
If the environment variable <tt>GRASS_UI_TERM</tt> is set to any value, then an interactive question/answer text based UI is launched instead of the graphical UI window.
 
== Help page HTML template ==
 
* Auto-created with the <tt>--html-description</tt> command line option.
 
== Using the parser in own scripts and programs ==
 
To add parser (i.e. eventually also GUI functionality) into a self-written script is very simple. Just some specific lines need to be added to the script. The easiest approach is to look at an existing script shipped with GRASS GIS:
 
Material:
* List of [http://grass.osgeo.org/programming7/parser__standard__options_8c.html available options for parameters and flags]
* see also the {{cmd|g.parser}} help page
* Code examples:
** '''Shell scripts''':
*** [https://trac.osgeo.org/grass/browser/grass/branches/releasebranch_6_4/scripts/i.landsat.rgb/i.landsat.rgb#L21 imagery]
*** [https://trac.osgeo.org/grass/browser/grass/branches/releasebranch_6_4/scripts/r.blend/r.blend#L15 raster]
*** [https://trac.osgeo.org/grass/browser/grass/branches/releasebranch_6_4/scripts/v.db.join/v.db.join#L15 vector]
*** [https://trac.osgeo.org/grass/browser/grass/branches/releasebranch_6_4/scripts/r3.mapcalculator/r3.mapcalculator#L16 voxel]
*** [https://trac.osgeo.org/grass/browser/grass/branches/releasebranch_6_4/scripts/ other examples]
** '''Python scripts''':
*** [https://trac.osgeo.org/grass/browser/grass/trunk/scripts/i.landsat.rgb/i.landsat.rgb.py#L22 imagery]
*** [https://trac.osgeo.org/grass/browser/grass/trunk/scripts/r.rgb/r.rgb.py#L15 raster]
*** [https://trac.osgeo.org/grass/browser/grass/trunk/scripts/v.db.join/v.db.join.py#L16 vector]
*** [https://trac.osgeo.org/grass/browser/grass/trunk/scripts/r3.in.xyz/r3.in.xyz.py#L22 voxel]
*** [https://trac.osgeo.org/grass/browser/grass/trunk/scripts other examples]
** '''C/C++ code''':
*** [https://trac.osgeo.org/grass/browser/grass/trunk/db/db.tables/main.c#L64 database]
*** [https://trac.osgeo.org/grass/browser/grass/trunk/display/d.rast/main.c#L42 display]
*** [https://trac.osgeo.org/grass/browser/grass/trunk/general/g.list/main.c#L36 general]
*** [https://trac.osgeo.org/grass/browser/grass/trunk/imagery/i.segment/parse_args.c#L10 imagery]
*** [https://trac.osgeo.org/grass/browser/grass/trunk/raster/r.resamp.bspline/main.c#L64 raster]
*** [https://trac.osgeo.org/grass/browser/grass/trunk/vector/v.extrude/main.c#L37 vector]
*** [https://trac.osgeo.org/grass/browser/grass/trunk/raster3d/r3.gwflow/main.c#L50 voxel]
*** [https://trac.osgeo.org/grass/browser/grass/trunk/ other examples]
 
== Troubleshooting ==
 
Q: my python scripts are lacking the automatically generated flag for --overwrite in the GUI
 
A: You should be using standardized option G_OPT_R_INPUT, the definition can be found here:
http://grass.osgeo.org/programming7/parser__standard__options_8c_source.html
 
The key here is to specify 'new' in gisprompt, but only for output map. 'new' means that a new map will be created and parser then knows that it should check whether there is already a map of such name and if yes, require overwrite. Based on 'new', the overwrite flag is created.
 
== WPS process description ==
 
Starting with GRASS7, the WPS process description can be automatically generated with the option '--wps-process-description', see [[WPS]].
 
== Exceptions ==
 
Due to technical reasons some modules do not use the standard parser in ''GRASS 6''. These include:
* {{cmd|r.mapcalc}}
* {{cmd|g.parser}} itself
 
== API ==
 
=== C API ===
 
see http://grass.osgeo.org/programming7/parser_8c.html
 
=== Parser standard options ===
 
* see http://grass.osgeo.org/programming7/parser__standard__options_8c.html
* Overview table of [https://grass.osgeo.org/grass71/manuals/parser_standard_options.html parser standard options]


* auto-created with the --html-description command line option.
[[Category: FAQ]]
[[Category: Linking to other languages]]

Latest revision as of 18:04, 28 November 2015

GRASS GIS's command line parser is used by just about all modules to check input values, create help pages and GUIs. With the help of the g.parser module your shell or Python scripts can automatically generate help page templates and fully functional GUI windows. (This is a frontend for the G_parser() function in the C API; see the programmer's manual if you are interested in that)

Command line parser

  • Options take user input (name or number) and of the style:
option=answer
  • flags are on/off switches and of the style
-f
  • Run time flags and options can be mixed in any order. Special options to display help and GUI templates should appear on their own.
  • Options may be tested for correct numerical value and range. For example testing if the numerical answer falls within 0-100 percent.
  • Options may be limited to a discrete set of answers. This results in a pulldown menu in the GUI and a strict answer from the command line.
  • The first option= listed by --help may be skipped, for example:
d.rast elevation.dem
  • Examples (works with any existing GRASS GIS command):
 r.in.ascii --script
 v.in.ascii --script
  • Option names may be shortened up to the point where they collide. Thus shortening option names in a module with color= and column= options would require at minimum colo= and colu=.

for example:

input=in=   and   output=out=
  • Flags may be combined behind a single "-". for example:
-r -f -t   is the same as   -rtf
  • All modules can take the command line options --ui to force a GUI window, --overwrite to allow/force overwritting of maps and files, --quiet to make modules less noisy, --verbose to make modules more noisy, and --script to generate a shell script wrapper template.
  • --quiet, --verbose, and --overwrite may be abbreviated as --q, --v, --o.
  • --help or just 'help' by itself on the command line prints concise module command line option help. This help page will also be printed if there was an error parsing the command options.

GUI window parser

  • If a module is called with no options or flags specified then a GUI window is launched, unless the environment variable GRASS_UI_TERM is set (to any value), in which case the command-line interactive parser is launched.
  • If a module is called with options and flags specified, but with the --ui flag, then a GUI window is started with those options and flags already set to the given values. (useful for interactive scripts)
  • Auto-created from --tcltk or --interface-description (for XML) command line options.
  • Options may be grouped into tabs by the parser settings
  • Quotes to protect "special characters" from the shell are not needed here. Quotes needed to denote SQL 'strings' are still needed.

Interactive text based UI parser

If the environment variable GRASS_UI_TERM is set to any value, then an interactive question/answer text based UI is launched instead of the graphical UI window.

Help page HTML template

  • Auto-created with the --html-description command line option.

Using the parser in own scripts and programs

To add parser (i.e. eventually also GUI functionality) into a self-written script is very simple. Just some specific lines need to be added to the script. The easiest approach is to look at an existing script shipped with GRASS GIS:

Material:

Troubleshooting

Q: my python scripts are lacking the automatically generated flag for --overwrite in the GUI

A: You should be using standardized option G_OPT_R_INPUT, the definition can be found here: http://grass.osgeo.org/programming7/parser__standard__options_8c_source.html

The key here is to specify 'new' in gisprompt, but only for output map. 'new' means that a new map will be created and parser then knows that it should check whether there is already a map of such name and if yes, require overwrite. Based on 'new', the overwrite flag is created.

WPS process description

Starting with GRASS7, the WPS process description can be automatically generated with the option '--wps-process-description', see WPS.

Exceptions

Due to technical reasons some modules do not use the standard parser in GRASS 6. These include:

API

C API

see http://grass.osgeo.org/programming7/parser_8c.html

Parser standard options