r.what: file output parameter added (from r.stats) incl. example

git-svn-id: https://svn.osgeo.org/grass/grass/trunk@58253 15284696-431f-4ddb-bdfa-cd5b030d7da7

raster/r.what/main.c

@@ -51,6 +51,7 @@ int main(int argc, char *argv[])
 {
     int i, j;
     int nfiles;
+    char *name;
     int fd[NFILES];
     struct Categories cats[NFILES];
     struct Cell_head window;
@@ -70,7 +71,7 @@ int main(int argc, char *argv[])
     char buffer[1024];
     char **ptr;
     struct _opt {
-        struct Option *input, *cache, *null, *coords, *fs, *points;
+        struct Option *input, *cache, *null, *coords, *fs, *points, *output;
     } opt;
     struct _flg {
 	struct Flag *label, *cache, *cat_int, *color, *header;
@@ -100,6 +101,7 @@ int main(int argc, char *argv[])
     module->description =
 	_("Queries raster maps on their category values and category labels.");
 
+    /* TODO: should be G_OPT_R_INPUTS for consistency but needs overall change where used */
     opt.input = G_define_standard_option(G_OPT_R_MAPS);
     opt.input->description = _("Name of existing raster map(s) to query");
 
@@ -121,6 +123,11 @@ int main(int argc, char *argv[])
     opt.null->description = _("Char string to represent no data cell");
     opt.null->guisection = _("Print");
     
+    opt.output = G_define_standard_option(G_OPT_F_OUTPUT);
+    opt.output->required = NO;
+    opt.output->description =
+	_("Name for output file (if omitted or \"-\" output to stdout)");
+
     opt.fs = G_define_standard_option(G_OPT_F_SEP);
     opt.fs->guisection = _("Print");
 
@@ -161,6 +168,13 @@ int main(int argc, char *argv[])
     if (G_parser(argc, argv))
 	exit(EXIT_FAILURE);
 
+    name = opt.output->answer;
+    if (name != NULL && strcmp(name, "-") != 0) {
+	if (NULL == freopen(name, "w", stdout)) {
+	    G_fatal_error(_("Unable to open file <%s> for writing"), name);
+	}
+    }
+
     tty = isatty(0);
 
     fs = G_option_to_separator(opt.fs);

raster/r.what/r.what.html

@@ -56,6 +56,27 @@ r.what map=boundary_county_500m points=comm_colleges
 ...
 </pre></div>
 
+
+<h3>Input coordinates given as a vector points map, output into CSV file</h3>
+
+Coordinates can be read from exising vector points map by
+specifing <b>points</b> option. Other features than points or
+centroids are ignored. The output is stored in a CSV file including header
+row. Example: query North Carolina county number for each community college:
+
+<div class="code"><pre>
+g.region rast=boundary_county_500m -p
+r.what map=boundary_county_500m points=comm_colleges \
+       separator=comma output=result.csv -n
+       
+cat result.csv 
+easting,northing,site_name,boundary_county_500m
+145096.859150,154534.264884,,39
+616341.437150,146049.750884,,51
+410595.719150,174301.828884,,71
+...
+</pre></div>
+
 <h3>Input from a text file containing coordinates</h3>
 
 The contents of an ASCII text file can be redirected to <em>r.what</em>
@@ -134,7 +155,6 @@ The maximum number of raster map layers that can be queried at one time is 400.
 <h2>TODO</h2>
 
 <ul>
-  <li>Add <b>file</b> option</li>
   <li>Fix <b>400 maps</b> limit</li>
 </ul>