20 #include "parser_local_proto.h"
22 static void print_python_short_flag(FILE *
file,
const char *key,
23 const char *label,
const char *description,
25 static void print_python_long_flag(FILE *
file,
const char *key,
26 const char *label,
const char *description,
28 static void print_python_option(FILE *
file,
const struct Option *opt,
29 const char *indent,
bool tools_api);
30 static void print_python_example(FILE *
file,
const char *python_function,
31 const char *output_format_default,
32 const char *indent,
bool tools_api);
33 static void print_python_tuple(FILE *
file,
const char *type,
int num_items);
35 void print_python_short_flag(FILE *
file,
const char *key,
const char *label,
36 const char *description,
const char *indent)
38 fprintf(
file,
"%s", indent);
40 fprintf(
file,
"**%s**", key);
41 fprintf(
file, MD_NEWLINE);
44 fprintf(
file,
"%s", indent);
47 fprintf(
file, MD_NEWLINE);
50 if (description !=
NULL) {
51 fprintf(
file,
"%s", indent);
57 void print_python_long_flag(FILE *
file,
const char *key,
const char *label,
58 const char *description,
const char *indent)
60 fprintf(
file,
"%s**%s** : bool, *optional*", indent, key);
61 fprintf(
file, MD_NEWLINE);
64 fprintf(
file,
"%s", indent);
67 fprintf(
file, MD_NEWLINE);
70 if (description !=
NULL) {
71 fprintf(
file,
"%s", indent);
74 fprintf(
file, MD_NEWLINE);
77 fprintf(
file,
"%s", indent);
79 const char *flag_default =
"*None*";
80 fprintf(
file,
"Default: %s", flag_default);
83 void print_python_tuple(FILE *
file,
const char *type,
int num_items)
85 fprintf(
file,
"tuple[%s", type);
86 for (
int i = 1; i < num_items; i++) {
87 fprintf(
file,
", %s", type);
92 void print_python_option(FILE *
file,
const struct Option *opt,
93 const char *indent,
bool tools_api)
114 char prompt_description[KEYLENGTH];
120 type =
"str | io.StringIO";
124 type =
"str | np.ndarray";
128 type =
"str | type(np.ndarray) | type(np.array) | "
129 "type(gs.array.array)";
134 fprintf(
file,
"%s**%s** : ", indent, opt->
key);
138 fprintf(
file,
"list[");
139 print_python_tuple(
file, type, tuple_items);
140 fprintf(
file,
"] | ");
141 print_python_tuple(
file, type, tuple_items);
142 fprintf(
file,
" | list[%s] | str", type);
145 if (strcmp(type,
"str")) {
150 fprintf(
file,
"%s | list[%s] | str", type, type);
153 fprintf(
file,
"%s | list[%s]", type, type);
157 else if (tuple_items) {
158 print_python_tuple(
file, type, tuple_items);
159 fprintf(
file,
" | list[%s] | str", type);
162 fprintf(
file,
"%s", type);
165 fprintf(
file,
", *required*");
168 fprintf(
file,
", *optional*");
171 fprintf(
file, MD_NEWLINE);
174 fprintf(
file,
"%s", indent);
180 fprintf(
file, MD_NEWLINE);
183 fprintf(
file,
"%s", indent);
188 fprintf(
file, MD_NEWLINE);
190 fprintf(
file,
"%s", indent);
192 fprintf(
file,
"%s: ",
_(
"Used as"));
195 if (strcmp(age,
"new") == 0)
196 fprintf(
file,
"output, ");
197 else if (strcmp(age,
"old") == 0)
198 fprintf(
file,
"input, ");
203 fprintf(
file,
"%s", prompt_description);
213 fprintf(
file, MD_NEWLINE);
215 fprintf(
file,
"%s", indent);
217 fprintf(
file,
"%s: *",
_(
"Allowed values"));
225 while (opt->
opts[i]) {
227 fprintf(
file, MD_NEWLINE);
229 fprintf(
file,
"%s", indent);
230 char *thumbnails =
NULL;
232 if (strcmp(opt->
gisprompt,
"old,colortable,colortable") ==
234 thumbnails =
"colortables";
235 else if (strcmp(opt->
gisprompt,
"old,barscale,barscale") ==
237 thumbnails =
"barscales";
239 "old,northarrow,northarrow") == 0)
240 thumbnails =
"northarrows";
244 fprintf(
file,
" ", opt->
opts[i],
245 thumbnails, opt->
opts[i]);
254 fprintf(
file,
"**: ");
261 if (opt->
def && opt->
def[0] !=
'\0') {
262 fprintf(
file, MD_NEWLINE);
264 fprintf(
file,
"%s", indent);
266 fprintf(
file,
"%s:",
_(
"Default"));
273 void print_python_example(FILE *
file,
const char *python_function,
274 const char *output_format_default,
const char *indent,
277 fprintf(
file,
"\n%sExample:\n", indent);
279 fprintf(
file,
"\n%s```python\n", indent);
280 bool first_parameter_printed =
false;
284 fprintf(
file,
"%stools = Tools()\n", indent);
285 fprintf(
file,
"%stools.%s(", indent, tool_name);
289 fprintf(
file,
"%sgs.%s(\"%s\"", indent, python_function,
st->pgm_name);
290 first_parameter_printed =
true;
293 const struct Option *first_required_rule_option =
299 opt = &
st->first_option;
301 while (opt !=
NULL) {
319 if (opt->
required || first_required_rule_option == opt ||
320 (strcmp(opt->
key,
"format") == 0 && output_format_default)) {
321 if (first_parameter_printed) {
324 fprintf(
file,
"%s=", opt->
key);
348 if (output_format_default && strcmp(opt->
key,
"format") == 0) {
349 fprintf(
file,
"\"%s\"", output_format_default);
353 fprintf(
file,
"%s", value);
356 fprintf(
file,
"\"%s\"", value);
364 fprintf(
file,
"0.0");
370 first_parameter_printed =
true;
376 fprintf(
file,
")\n%s```\n", indent);
385 bool output_format_option =
false;
386 const char *output_format_default =
NULL;
387 bool shell_eval_flag =
false;
388 const char *python_function =
NULL;
393 opt = &
st->first_option;
394 while (opt !=
NULL) {
395 if (strcmp(opt->
key,
"format") == 0) {
398 while (opt->
opts[i]) {
399 if (strcmp(opt->
opts[i],
"csv") == 0)
400 output_format_default =
"csv";
401 if (strcmp(opt->
opts[i],
"json") == 0) {
402 output_format_default =
"json";
408 if (output_format_default) {
409 output_format_option =
true;
417 flag = &
st->first_flag;
418 while (
st->n_flags && flag !=
NULL) {
419 if (flag->
key ==
'g') {
420 shell_eval_flag =
true;
426 bool first_parameter_printed =
false;
430 fprintf(
file,
"%s*grass.tools.Tools.%s*(", indent, tool_name);
434 if (output_format_option || (!new_prompt && shell_eval_flag)) {
435 python_function =
"parse_command";
441 python_function =
"run_command";
443 fprintf(
file,
"%s*grass.script.%s*(\"***%s***\",", indent,
444 python_function,
st->pgm_name);
446 first_parameter_printed =
true;
450 opt = &
st->first_option;
452 while (opt !=
NULL) {
453 if (first_parameter_printed) {
454 fprintf(
file,
"%s ", indent);
457 fprintf(
file,
"**%s**=*None*", opt->
key);
460 fprintf(
file,
"**%s**", opt->
key);
472 fprintf(
file,
"*\"");
474 fprintf(
file,
"\"*");
477 fprintf(
file,
",\n");
478 first_parameter_printed =
true;
484 flag = &
st->first_flag;
485 fprintf(
file,
"%s **flags**=*None*,\n", indent);
488 const char *flag_default =
"*None*";
490 fprintf(
file,
"%s **overwrite**=%s,\n", indent, flag_default);
492 fprintf(
file,
"%s **verbose**=%s,\n", indent, flag_default);
493 fprintf(
file,
"%s **quiet**=%s,\n", indent, flag_default);
494 fprintf(
file,
"%s **superquiet**=%s)\n", indent, flag_default);
496 print_python_example(
file, python_function, output_format_default, indent,
500 "\n%sThis grass.tools API is experimental in version 8.5 "
501 "and expected to be stable in version 8.6.\n",
517 opt = &
st->first_option;
518 while (opt !=
NULL) {
519 print_python_option(
file, opt, indent, tools_api);
521 fprintf(
file, MD_NEWLINE);
528 fprintf(
file,
"%s**flags** : str, *optional*", indent);
529 fprintf(
file, MD_NEWLINE);
531 fprintf(
file,
"%s", indent);
533 fprintf(
file,
"Allowed values: ");
534 flag = &
st->first_flag;
535 while (
st->n_flags && flag !=
NULL) {
536 fprintf(
file,
"*%s*", &flag->
key);
541 fprintf(
file, MD_NEWLINE);
543 flag = &
st->first_flag;
544 while (
st->n_flags && flag !=
NULL) {
547 fprintf(
file, MD_NEWLINE);
553 print_python_long_flag(
555 _(
"Allow output files to overwrite existing files"), indent);
556 fprintf(
file, MD_NEWLINE);
560 print_python_long_flag(
file,
"verbose",
NULL,
_(
"Verbose module output"),
562 fprintf(
file, MD_NEWLINE);
564 print_python_long_flag(
file,
"quiet",
NULL,
_(
"Quiet module output"),
566 fprintf(
file, MD_NEWLINE);
568 print_python_long_flag(
file,
"superquiet",
NULL,
569 _(
"Very quiet module output"), indent);
570 fprintf(
file, MD_NEWLINE);
576 fprintf(
file,
"\n%sReturns:\n\n", indent);
578 bool outputs_arrays =
false;
581 char prompt_description[KEYLENGTH];
583 opt = &
st->first_option;
584 while (opt !=
NULL) {
591 outputs_arrays =
true;
599 fprintf(
file,
"%s**result** : ", indent);
600 fprintf(
file,
"grass.tools.support.ToolResult");
601 if (outputs_arrays) {
602 fprintf(
file,
" | np.ndarray | tuple[np.ndarray]");
604 fprintf(
file,
" | None");
605 fprintf(
file, MD_NEWLINE);
606 fprintf(
file,
"\n%s", indent);
607 fprintf(
file,
"If the tool produces text as standard output, a "
608 "*ToolResult* object will be returned. "
609 "Otherwise, `None` will be returned.");
610 if (outputs_arrays) {
611 fprintf(
file,
" If an array type (e.g., *np.ndarray*) is used for one "
612 "of the raster outputs, "
613 "the result will be an array and will have the shape "
614 "corresponding to the computational region. "
615 "If an array type is used for more than one raster "
616 "output, the result will be a tuple of arrays.");
620 fprintf(
file,
"\n%sRaises:\n\n", indent);
622 "%s*grass.tools.ToolError*: When the tool ended with an error.\n",
void G_free(void *)
Free allocated memory.
void G_free_tokens(char **)
Free memory allocated to tokens.
char * G_strchg(char *, char, char)
Replace all occurrences of character in string bug with new.
int G_strncasecmp(const char *, const char *, int)
String compare ignoring case (upper or lower) - limited number of characters.
char * G_chop(char *)
Chop leading and trailing white spaces.
char * G_store(const char *)
Copy string to allocated memory.
char ** G_tokenize(const char *, const char *)
Tokenize string.
int G__uses_new_gisprompt(void)
void G__split_gisprompt(const char *gisprompt, char *age, char *element, char *desc)
const struct Option * G__first_required_option_from_rules(void)
void G__md_print_escaped(FILE *f, const char *str)
int G__option_num_tuple_items(const struct Option *opt)
Get number of tuple items if option is a tuple.
void G__md_print_escaped_for_options(FILE *f, const char *str)
void G__md_print_python_long_version(FILE *file, const char *indent, bool tools_api)
void G__md_print_python_short_version(FILE *file, const char *indent, bool tools_api)
Structure that stores flag info.
Structure that stores option information.