GRASS GIS 7 Programmer's Manual  7.2.1(2017)-exported
parser_help.c
Go to the documentation of this file.
1 /*!
2  \file lib/gis/parser_help.c
3 
4  \brief GIS Library - Argument parsing functions (help)
5 
6  (C) 2001-2009, 2011 by the GRASS Development Team
7 
8  This program is free software under the GNU General Public License
9  (>=v2). Read the file COPYING that comes with GRASS for details.
10 
11  \author Original author CERL
12  \author Soeren Gebbert added Dec. 2009 WPS process_description document
13 */
14 
15 #include <stdio.h>
16 #include <string.h>
17 #include <stdlib.h>
18 
19 #include <grass/gis.h>
20 #include <grass/glocale.h>
21 
22 #include "parser_local_proto.h"
23 
24 static void usage(FILE *fp, int markers);
25 static void show_options(FILE *fp, int maxlen, const char *str);
26 static int show(FILE *fp, const char *item, int len);
27 
28 /*!
29  \brief Command line help/usage message.
30 
31  Calls to G_usage() allow the programmer to print the usage
32  message at any time. This will explain the allowed and required
33  command line input to the user. This description is given according
34  to the programmer's definitions for options and flags. This function
35  becomes useful when the user enters options and/or flags on the
36  command line that are syntactically valid to the parser, but
37  functionally invalid for the command (e.g. an invalid file name.)
38 
39  For example, the parser logic doesn't directly support grouping
40  options. If two options be specified together or not at all, the
41  parser must be told that these options are not required and the
42  programmer must check that if one is specified the other must be as
43  well. If this additional check fails, then G_parser() will succeed,
44  but the programmer can then call G_usage() to print the standard
45  usage message and print additional information about how the two
46  options work together.
47 */
48 void G_usage(void)
49 {
50  usage(stderr, 0);
51 }
52 
53 void G__usage_text(void)
54 {
55  usage(stdout, 1);
56 }
57 
58 static void usage(FILE *fp, int markers)
59 {
60  struct Option *opt;
61  struct Flag *flag;
62  char item[256];
63  const char *key_desc;
64  int maxlen;
65  int len, n;
66  int new_prompt = 0;
67 
68  new_prompt = G__uses_new_gisprompt();
69 
70  if (!st->pgm_name) /* v.dave && r.michael */
71  st->pgm_name = G_program_name();
72  if (!st->pgm_name)
73  st->pgm_name = "??";
74 
75  if (st->module_info.label || st->module_info.description) {
76  fprintf(fp, "\n");
77  if (markers)
78  fprintf(fp, "{{{DESCRIPTION}}}\n");
79  fprintf(fp, "%s\n", _("Description:"));
80  if (st->module_info.label)
81  fprintf(fp, " %s\n", st->module_info.label);
82  if (st->module_info.description)
83  fprintf(fp, " %s\n", st->module_info.description);
84  }
85  if (st->module_info.keywords) {
86  fprintf(fp, "\n");
87  if (markers)
88  fprintf(fp, "{{{KEYWORDS}}}\n");
89  fprintf(fp, "%s\n ", _("Keywords:"));
91  fprintf(fp, "\n");
92  }
93 
94  fprintf(fp, "\n");
95  if (markers)
96  fprintf(fp, "{{{USAGE}}}\n");
97  fprintf(fp, "%s\n ", _("Usage:"));
98 
99  len = show(fp, st->pgm_name, 1);
100 
101  /* Print flags */
102 
103  if (st->n_flags) {
104  item[0] = ' ';
105  item[1] = '[';
106  item[2] = '-';
107  flag = &st->first_flag;
108  for (n = 3; flag != NULL; n++, flag = flag->next_flag)
109  item[n] = flag->key;
110  item[n++] = ']';
111  item[n] = 0;
112  len = show(fp, item, len);
113  }
114 
115  maxlen = 0;
116  if (st->n_opts) {
117  opt = &st->first_option;
118  while (opt != NULL) {
119  if (opt->key_desc != NULL)
120  key_desc = opt->key_desc;
121  else if (opt->type == TYPE_STRING)
122  key_desc = "string";
123  else
124  key_desc = "value";
125 
126  if (!opt->key) {
127  fprintf(stderr, "\n%s\n", _("ERROR: Option key not defined"));
128  exit(EXIT_FAILURE);
129  }
130  n = strlen(opt->key);
131  if (n > maxlen)
132  maxlen = n;
133 
134  strcpy(item, " ");
135  if (!opt->required)
136  strcat(item, "[");
137  strcat(item, opt->key);
138  strcat(item, "=");
139  strcat(item, key_desc);
140  if (opt->multiple) {
141  strcat(item, "[,");
142  strcat(item, key_desc);
143  strcat(item, ",...]");
144  }
145  if (!opt->required)
146  strcat(item, "]");
147 
148  len = show(fp, item, len);
149 
150  opt = opt->next_opt;
151  }
152  }
153  if (new_prompt) {
154  strcpy(item, " [--overwrite]");
155  len = show(fp, item, len);
156  }
157 
158  strcpy(item, " [--help]");
159  len = show(fp, item, len);
160 
161  strcpy(item, " [--verbose]");
162  len = show(fp, item, len);
163 
164  strcpy(item, " [--quiet]");
165  len = show(fp, item, len);
166 
167  strcpy(item, " [--ui]");
168  len = show(fp, item, len);
169 
170  fprintf(fp, "\n");
171 
172  /* Print help info for flags */
173 
174  fprintf(fp, "\n");
175  if (markers)
176  fprintf(fp, "{{{FLAGS}}}\n");
177  fprintf(fp, "%s\n", _("Flags:"));
178 
179  if (st->n_flags) {
180  flag = &st->first_flag;
181  while (flag != NULL) {
182  fprintf(fp, " -%c ", flag->key);
183 
184  if (flag->label) {
185  fprintf(fp, "%s\n", flag->label);
186  if (flag->description)
187  fprintf(fp, " %s\n", flag->description);
188 
189  }
190  else if (flag->description) {
191  fprintf(fp, "%s\n", flag->description);
192  }
193 
194  flag = flag->next_flag;
195  }
196  }
197 
198  if (new_prompt)
199  fprintf(fp, " --o %s\n",
200  _("Allow output files to overwrite existing files"));
201 
202  fprintf(fp, " --h %s\n", _("Print usage summary"));
203  fprintf(fp, " --v %s\n", _("Verbose module output"));
204  fprintf(fp, " --q %s\n", _("Quiet module output"));
205  fprintf(fp, " --qq %s\n", _("Super quiet module output"));
206  fprintf(fp, " --ui %s\n", _("Force launching GUI dialog"));
207 
208  /* Print help info for options */
209 
210  if (st->n_opts) {
211  fprintf(fp, "\n");
212  if (markers)
213  fprintf(fp, "{{{PARAMETERS}}}\n");
214  fprintf(fp, "%s\n", _("Parameters:"));
215  opt = &st->first_option;
216  while (opt != NULL) {
217  fprintf(fp, " %*s ", maxlen, opt->key);
218 
219  if (opt->label) {
220  fprintf(fp, "%s\n", opt->label);
221  if (opt->description) {
222  fprintf(fp, " %*s %s\n",
223  maxlen, " ", opt->description);
224  }
225  }
226  else if (opt->description) {
227  fprintf(fp, "%s\n", opt->description);
228  }
229 
230  if (opt->options)
231  show_options(fp, maxlen, opt->options);
232  /*
233  fprintf (fp, " %*s options: %s\n", maxlen, " ",
234  _(opt->options)) ;
235  */
236  if (opt->def)
237  fprintf(fp, _(" %*s default: %s\n"), maxlen, " ",
238  opt->def);
239 
240  if (opt->descs) {
241  int i = 0;
242 
243  while (opt->opts[i]) {
244  if (opt->descs[i])
245  fprintf(fp, " %*s %s: %s\n",
246  maxlen, " ", opt->opts[i], opt->descs[i]);
247 
248  i++;
249  }
250  }
251 
252  opt = opt->next_opt;
253  }
254  }
255 }
256 
257 static void show_options(FILE *fp, int maxlen, const char *str)
258 {
259  char *buff = G_store(str);
260  char *p1, *p2;
261  int totlen, len;
262 
263  fprintf(fp, _(" %*s options: "), maxlen, " ");
264  totlen = maxlen + 13;
265  p1 = buff;
266  while ((p2 = strchr(p1, ','))) {
267  *p2 = '\0';
268  len = strlen(p1) + 1;
269  if ((len + totlen) > 76) {
270  totlen = maxlen + 13;
271  fprintf(fp, "\n %*s", maxlen + 13, " ");
272  }
273  fprintf(fp, "%s,", p1);
274  totlen += len;
275  p1 = p2 + 1;
276  }
277  len = strlen(p1);
278  if ((len + totlen) > 76)
279  fprintf(fp, "\n %*s", maxlen + 13, " ");
280  fprintf(fp, "%s\n", p1);
281 
282  G_free(buff);
283 }
284 
285 static int show(FILE *fp, const char *item, int len)
286 {
287  int n;
288 
289  n = strlen(item) + (len > 0);
290  if (n + len > 76) {
291  if (len)
292  fprintf(fp, "\n ");
293  len = 0;
294  }
295  fprintf(fp, "%s", item);
296  return n + len;
297 }
int G__uses_new_gisprompt(void)
Definition: parser.c:854
char * G_store(const char *s)
Copy string to allocated memory.
Definition: strings.c:86
#define NULL
Definition: ccmath.h:32
void G__usage_text(void)
Definition: parser_help.c:53
struct state * st
Definition: parser.c:103
const char * G_program_name(void)
Return module name.
Definition: progrm_nme.c:28
void G_usage(void)
Command line help/usage message.
Definition: parser_help.c:48
void G__print_keywords(FILE *fd, void(*format)(FILE *, const char *))
Print list of keywords (internal use only)
Definition: parser.c:890
void G_free(void *buf)
Free allocated memory.
Definition: alloc.c:149