GRASS GIS 7 Programmer's Manual  7.9.dev(2021)-e5379bbd7
parser_rest.c
Go to the documentation of this file.
1 /*!
2  \file lib/gis/parser_rest.c
3 
4  \brief GIS Library - Argument parsing functions (reStructuredText output)
5 
6  (C) 2012 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 Luca Delucchi
12 */
13 #include <stdio.h>
14 #include <string.h>
15 
16 #include <grass/gis.h>
17 #include <grass/glocale.h>
18 
19 #include "parser_local_proto.h"
20 
21 
22 static void print_escaped_for_rest(FILE * f, const char *str);
23 static void print_escaped_for_rest_options(FILE * f, const char *str);
24 
25 
26 /*!
27  \brief Print module usage description in reStructuredText format.
28 */
29 void G__usage_rest(void)
30 {
31  struct Option *opt;
32  struct Flag *flag;
33  const char *type;
34  int new_prompt = 0;
35  unsigned int s;
36 
37  new_prompt = G__uses_new_gisprompt();
38 
39  if (!st->pgm_name)
40  st->pgm_name = G_program_name();
41  if (!st->pgm_name)
42  st->pgm_name = "??";
43 
44  fprintf(stdout, "=================");
45  for (s = 0; s <= strlen(st->pgm_name); s++) {
46  fprintf(stdout, "=");
47  }
48  fprintf(stdout, "\n");
49  fprintf(stdout, "%s - GRASS GIS manual\n", st->pgm_name);
50  fprintf(stdout, "=================");
51  for (s = 0; s <= strlen(st->pgm_name); s++) {
52  fprintf(stdout, "=");
53  }
54  fprintf(stdout, "\n\n");
55 
56  fprintf(stdout,".. figure:: grass_logo.png\n");
57  fprintf(stdout," :align: center\n");
58  fprintf(stdout," :alt: GRASS logo\n\n");
59 
60  fprintf(stdout,"%s\n----\n", _("NAME"));
61  fprintf(stdout, "**%s**", st->pgm_name);
62 
63  if (st->module_info.label || st->module_info.description)
64  fprintf(stdout, " - ");
65 
66  if (st->module_info.label)
67  fprintf(stdout, "%s\n\n", st->module_info.label);
68 
69  if (st->module_info.description)
70  fprintf(stdout, "%s\n", st->module_info.description);
71 
72 
73  fprintf(stdout, "\n%s\n----------------------\n", _("KEYWORDS"));
74  if (st->module_info.keywords) {
75  G__print_keywords(stdout, NULL);
76  fprintf(stdout, "\n");
77  }
78  fprintf(stdout, "\n%s\n----------------------\n", _("SYNOPSIS"));
79  fprintf(stdout, "**%s**\n\n", st->pgm_name);
80  fprintf(stdout, "**%s** --help\n\n", st->pgm_name);
81 
82  fprintf(stdout, "**%s**", st->pgm_name);
83 
84 
85 
86  /* print short version first */
87  if (st->n_flags) {
88  flag = &st->first_flag;
89  fprintf(stdout, " [**-");
90  while (flag != NULL) {
91  fprintf(stdout, "%c", flag->key);
92  flag = flag->next_flag;
93  }
94  fprintf(stdout, "**] ");
95  }
96  else
97  fprintf(stdout, " ");
98 
99  if (st->n_opts) {
100  opt = &st->first_option;
101 
102  while (opt != NULL) {
103  if (opt->key_desc != NULL)
104  type = opt->key_desc;
105  else
106  switch (opt->type) {
107  case TYPE_INTEGER:
108  type = "integer";
109  break;
110  case TYPE_DOUBLE:
111  type = "float";
112  break;
113  case TYPE_STRING:
114  type = "string";
115  break;
116  default:
117  type = "string";
118  break;
119  }
120  if (!opt->required)
121  fprintf(stdout, " [");
122  fprintf(stdout, "**%s** = *%s*", opt->key, type);
123  if (opt->multiple) {
124  fprintf(stdout, " [, *%s* ,...]", type);
125  }
126  if (!opt->required)
127  fprintf(stdout, "] ");
128 
129  opt = opt->next_opt;
130  fprintf(stdout, " ");
131  }
132  }
133  if (new_prompt)
134  fprintf(stdout, " [-- **overwrite**] ");
135 
136  fprintf(stdout, " [-- **verbose**] ");
137  fprintf(stdout, " [-- **quiet**] ");
138 
139  fprintf(stdout, "\n");
140 
141 
142  /* now long version */
143  fprintf(stdout, "\n");
144  if (st->n_flags || new_prompt) {
145  flag = &st->first_flag;
146  fprintf(stdout, "%s:\n~~~~~~\n", _("Flags"));
147  while (st->n_flags && flag != NULL) {
148  fprintf(stdout, "**-%c**\n", flag->key);
149 
150  if (flag->label) {
151  fprintf(stdout, " %s", flag->label);
152  }
153 
154  if (flag->description) {
155  fprintf(stdout, " %s", flag->description);
156  }
157 
158  flag = flag->next_flag;
159  fprintf(stdout, "\n");
160  }
161  if (new_prompt) {
162  fprintf(stdout, "-- **overwrite**\n");
163  fprintf(stdout, " %s\n",
164  _("Allow output files to overwrite existing files"));
165  }
166 
167  fprintf(stdout, "-- **verbose**\n");
168  fprintf(stdout, " %s\n", _("Verbose module output"));
169 
170  fprintf(stdout, "-- **quiet**\n");
171  fprintf(stdout, " %s\n", _("Quiet module output"));
172 
173  fprintf(stdout, "\n");
174  }
175 
176  fprintf(stdout, "\n");
177  if (st->n_opts) {
178  opt = &st->first_option;
179  fprintf(stdout, "%s:\n~~~~~~~~~~~\n", _("Parameters"));
180 
181  while (opt != NULL) {
182  /* TODO: make this a enumeration type? */
183  if (opt->key_desc != NULL)
184  type = opt->key_desc;
185  else
186  switch (opt->type) {
187  case TYPE_INTEGER:
188  type = "integer";
189  break;
190  case TYPE_DOUBLE:
191  type = "float";
192  break;
193  case TYPE_STRING:
194  type = "string";
195  break;
196  default:
197  type = "string";
198  break;
199  }
200  fprintf(stdout, "**%s** = *%s*", opt->key, type);
201  if (opt->multiple) {
202  fprintf(stdout, " [, *%s* ,...]", type);
203  }
204  /* fprintf(stdout, "*"); */
205  if (opt->required) {
206  fprintf(stdout, " **[required]**");
207  }
208  fprintf(stdout, "\n\n");
209  if (opt->label) {
210  fprintf(stdout, "\t");
211  print_escaped_for_rest(stdout, opt->label);
212  /* fprintf(stdout, " %s\n", opt->label); */
213  fprintf(stdout, "\n\n");
214  }
215  if (opt->description) {
216  fprintf(stdout, "\t");
217  print_escaped_for_rest(stdout, opt->description);
218  /* fprintf(stdout, " %s\n", opt->description); */
219  fprintf(stdout, "\n\n");
220  }
221 
222  if (opt->options) {
223  fprintf(stdout, "\t%s: *", _("Options"));
224  print_escaped_for_rest_options(stdout, opt->options);
225  /* fprintf(stdout, "%s", opt->options);*/
226  fprintf(stdout, "*\n\n");
227  }
228 
229  if (opt->def) {
230  fprintf(stdout, "\t%s:", _("Default"));
231  /* TODO check if value is empty
232  if (!opt->def.empty()){ */
233  fprintf(stdout, " *");
234  print_escaped_for_rest(stdout, opt->def);
235  /* fprintf(stdout,"%s", opt->def); */
236  fprintf(stdout, "*\n\n");
237  /* } */
238  fprintf(stdout, "\n\n");
239  }
240 
241  if (opt->descs) {
242  int i = 0;
243 
244  while (opt->opts[i]) {
245  if (opt->descs[i]) {
246  fprintf(stdout, "\t\t**");
247  print_escaped_for_rest(stdout, opt->opts[i]);
248  /*fprintf(stdout,"%s", opt->opts[i]); */
249  fprintf(stdout, "** : ");
250  print_escaped_for_rest(stdout, opt->descs[i]);
251  /* fprintf(stdout, "%s\n", opt->descs[i]); */
252  fprintf(stdout, "\n\n");
253  }
254  i++;
255  }
256  }
257 
258  opt = opt->next_opt;
259  fprintf(stdout, "\n");
260  }
261  fprintf(stdout, "\n");
262  }
263 
264 }
265 
266 
267 /*!
268  * \brief Format text for reStructuredText output
269  */
270 #define do_escape(c,escaped) case c: fputs(escaped,f);break
271  void print_escaped_for_rest(FILE * f, const char *str)
272  {
273  const char *s;
274 
275  for (s = str; *s; s++) {
276  switch (*s) {
277  do_escape('\n', "\n\n");
278  default:
279  fputc(*s, f);
280  }
281  }
282  }
283 
284  void print_escaped_for_rest_options(FILE * f, const char *str)
285  {
286  const char *s;
287 
288  for (s = str; *s; s++) {
289  switch (*s) {
290  do_escape('\n', "\n\n");
291  default:
292  fputc(*s, f);
293  }
294  }
295  }
296 
297 #undef do_escape
int G__uses_new_gisprompt(void)
Definition: parser.c:874
const char ** opts
Definition: gis.h:538
const char * G_program_name(void)
Return module name.
Definition: progrm_nme.c:28
#define TYPE_DOUBLE
Definition: gis.h:161
#define do_escape(c, escaped)
Format text for reStructuredText output.
Definition: parser_rest.c:270
void G__usage_rest(void)
Print module usage description in reStructuredText format.
Definition: parser_rest.c:29
#define TYPE_STRING
Definition: gis.h:162
#define NULL
Definition: ccmath.h:32
const char * def
Definition: gis.h:545
const char * description
Definition: gis.h:541
#define TYPE_INTEGER
Definition: gis.h:160
int type
Definition: gis.h:534
struct state * st
Definition: parser.c:104
int multiple
Definition: gis.h:536
Structure that stores flag info.
Definition: gis.h:560
char key
Definition: gis.h:562
int required
Definition: gis.h:535
struct Flag * next_flag
Definition: gis.h:569
const char * label
Definition: gis.h:566
const char * label
Definition: gis.h:540
const char ** descs
Definition: gis.h:543
Structure that stores option information.
Definition: gis.h:531
#define _(str)
Definition: glocale.h:10
const char * description
Definition: gis.h:567
const char * key
Definition: gis.h:533
void G__print_keywords(FILE *fd, void(*format)(FILE *, const char *))
Print list of keywords (internal use only)
Definition: parser.c:910
const char * options
Definition: gis.h:537
const char * key_desc
Definition: gis.h:539
struct Option * next_opt
Definition: gis.h:547