Geografic-Information-System/general/g.message/g.message.html

<h2>DESCRIPTION</h2>

<p>This program is to be used in Shell/Perl/Python scripts, so the author does not
need to use the <tt>echo</tt> program. The advantage of <em>g.message</em> is
that it formats messages just like other GRASS modules do and that its
functionality is influenced by the <tt>GRASS_VERBOSE</tt> and
<tt>GRASS_MESSAGE_FORMAT</tt> environment variables.

<p>
The program can be used for standard informative messages as well as warnings 
(<b>-w</b> flag) and fatal errors (<b>-e</b> flag). For debugging
purposes, the <b>-d</b> flag will cause <em>g.message</em> to print a debugging
message at the given level.


<h2>NOTES</h2>

Messages containing "<tt>=</tt>" must use the full <b>message=</b> syntax so
the parser doesn't get confused.
<p>
If you want a long message (multi-line) to be dealt with as a single
paragraph, use a single call to <em>g.message</em> with text split in the
script using the backslash as the last character. (In shell scripts don't
close the "quote")
<p>
A blank line may be obtained with
<div class="code"><pre>
g.message message=""
</pre></div>
<p>
Redundant whitespace will be stripped away.
<p>
It's advisable to single quote the messages that are to be printed literally.
It prevents a number of characters (most notably, space and the dollar sign
'<tt>$</tt>') from being treated specifically by the shell.
<p>
When it is necessary to include, for example, a variable's value as part of
the message, the double quotes may be used, which do not deprive the
dollar sign of its special variable-expansion powers.
<p>
While it is known that the interactive Bash instances may treat the
exclamation mark '<tt>!</tt>' character specifically (making single quoting
of it necessary), it shouldn't be the case for the non-interactive
instances of Bash. Nonetheless, to avoid context-based confusion later on
you are enouraged to single-quote messages that do not require
<tt>$VARIABLE</tt> expansion.

<h3>Usage in Python scripts</h3>

<a href="http://grass.osgeo.org/grass70/manuals/libpython/">GRASS
Python Scripting Library</a> defines special wrappers
for <em>g.message</em>.

<ul>
  <li><tt>debug()</tt> for <tt>g.message -d</tt>
  <li><tt>error()</tt> for <tt>g.message -e</tt>
  <li><tt>fatal()</tt> for <tt>g.message -e</tt> + <tt>exit()</tt>
  <li><tt>info()</tt> for <tt>g.message -i</tt>
  <li><tt>message()</tt> for <tt>g.message</tt>
  <li><tt>verbose()</tt> for <tt>g.message -v</tt>
  <li><tt>warning()</tt> for <tt>g.message -w</tt>
</ul>

<p>
Note: The Python shell in the <em>wxGUI</em> can be used for entering the
following sample code:
<p>

<div class="code"><pre>
import grass.script as gcore

gcore.warning("This is a warning")
</pre></div>

is identical with

<div class="code"><pre>
g.message -w message="This is a warning"
</pre></div>

<h3>VERBOSITY LEVELS</h3>
Controlled by the "<tt>GRASS_VERBOSE</tt>" environment variable. Typically this
is set using the <b>--quiet</b> or <b>--verbose</b> command line options.
<ul>
<li>0 - only errors and warnings are printed 
<li>1 - progress messages are printed 
<li>2 - all module messages are printed 
<li>3 - additional verbose messages are printed
</ul>

<h3>DEBUG LEVELS</h3>
Controlled by the "<tt>DEBUG</tt>" GRASS <i>gisenv</i> variable (set with
<em><a href="g.gisenv.html">g.gisenv</a></em>).
<br>
Recommended levels:
<ul>
<li>1 - message is printed once or few times per module
<li>3 - each row (raster) or line (vector)
<li>5 - each cell (raster) or point (vector) 
</ul>

<h2>SEE ALSO</h2>
<em>
<a href="variables.html">GRASS variables and environment variables</a><br>
<a href="g.gisenv.html">g.gisenv</a>,
<a href="g.parser.html">g.parser</a>
</em>

<h2>AUTHOR</h2>

Jachym Cepicky

<p>
<i>Last changed: $Date$</i>