Asterisk XML Documentation API. More...
#include "asterisk/xml.h"
Go to the source code of this file.
Enumerations | |
enum | ast_doc_src { AST_XML_DOC, AST_STATIC_DOC } |
From where the documentation come from, this structure is useful for use it inside application/functions/manager actions structure. More... | |
Functions | |
char * | ast_xmldoc_build_arguments (const char *type, const char *name, const char *module) |
Generate the [arguments] tag based on type of node ('application', 'function' or 'agi') and name. | |
char * | ast_xmldoc_build_description (const char *type, const char *name, const char *module) |
Generate description documentation from XML. | |
char * | ast_xmldoc_build_seealso (const char *type, const char *name, const char *module) |
Parse the <see-also> node content. | |
char * | ast_xmldoc_build_synopsis (const char *type, const char *name, const char *module) |
Generate synopsis documentation from XML. | |
char * | ast_xmldoc_build_syntax (const char *type, const char *name, const char *module) |
Get the syntax for a specified application or function. | |
char * | ast_xmldoc_printable (const char *bwinput, int withcolors) |
Colorize and put delimiters (instead of tags) to the xmldoc output. |
Asterisk XML Documentation API.
Definition in file xmldoc.h.
enum ast_doc_src |
From where the documentation come from, this structure is useful for use it inside application/functions/manager actions structure.
AST_XML_DOC |
From XML documentation |
AST_STATIC_DOC |
From application/function registration |
Definition at line 28 of file xmldoc.h.
00028 { 00029 AST_XML_DOC, /*!< From XML documentation */ 00030 AST_STATIC_DOC /*!< From application/function registration */ 00031 };
char* ast_xmldoc_build_arguments | ( | const char * | type, | |
const char * | name, | |||
const char * | module | |||
) |
Generate the [arguments] tag based on type of node ('application', 'function' or 'agi') and name.
type | 'application', 'function' or 'agi' ? | |
name | Name of the application or function to build the 'arguments' tag. | |
module | The module the item is in (optional, can be NULL) |
NULL | on error. | |
Output | buffer with the [arguments] tag content. |
Definition at line 1757 of file xmldoc.c.
References ast_free, ast_str_buffer(), ast_str_create(), ast_str_strlen(), ast_str_truncate(), ast_strdup, ast_strlen_zero(), ast_xml_node_get_children(), ast_xml_node_get_name(), ast_xml_node_get_next(), xmldoc_get_node(), and xmldoc_parse_parameter().
Referenced by acf_retrieve_docs(), ast_manager_register2(), and ast_register_application2().
01758 { 01759 struct ast_xml_node *node; 01760 struct ast_str *ret = ast_str_create(128); 01761 char *retstr = NULL; 01762 01763 if (ast_strlen_zero(type) || ast_strlen_zero(name)) { 01764 ast_free(ret); 01765 return NULL; 01766 } 01767 01768 node = xmldoc_get_node(type, name, module, documentation_language); 01769 01770 if (!node || !ast_xml_node_get_children(node)) { 01771 ast_free(ret); 01772 return NULL; 01773 } 01774 01775 /* Find the syntax field. */ 01776 for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) { 01777 if (!strcasecmp(ast_xml_node_get_name(node), "syntax")) { 01778 break; 01779 } 01780 } 01781 01782 if (!node || !ast_xml_node_get_children(node)) { 01783 /* We couldn't find the syntax node. */ 01784 ast_free(ret); 01785 return NULL; 01786 } 01787 01788 for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) { 01789 xmldoc_parse_parameter(node, "", &ret); 01790 } 01791 01792 if (ast_str_strlen(ret) > 0) { 01793 /* remove last '\n' */ 01794 char *buf = ast_str_buffer(ret); 01795 if (buf[ast_str_strlen(ret) - 1] == '\n') { 01796 ast_str_truncate(ret, -1); 01797 } 01798 retstr = ast_strdup(ast_str_buffer(ret)); 01799 } 01800 ast_free(ret); 01801 01802 return retstr; 01803 }
char* ast_xmldoc_build_description | ( | const char * | type, | |
const char * | name, | |||
const char * | module | |||
) |
Generate description documentation from XML.
type | The source of documentation (application, function, etc). | |
name | The name of the application, function, etc. | |
module | The module the item is in (optional, can be NULL) |
NULL | on error. | |
A | malloc'ed string with the formatted description. |
Definition at line 1896 of file xmldoc.c.
References xmldoc_build_field().
Referenced by acf_retrieve_docs(), ast_agi_register(), ast_manager_register2(), and ast_register_application2().
01897 { 01898 return xmldoc_build_field(type, name, module, "description", 0); 01899 }
char* ast_xmldoc_build_seealso | ( | const char * | type, | |
const char * | name, | |||
const char * | module | |||
) |
Parse the <see-also> node content.
type | 'application', 'function' or 'agi'. | |
name | Application or functions name. | |
module | The module the item is in (optional, can be NULL) |
NULL | on error. | |
Content | of the see-also node. |
Definition at line 1457 of file xmldoc.c.
References ast_free, ast_str_append(), ast_str_buffer(), ast_str_create(), ast_strdup, ast_strlen_zero(), ast_xml_free_attr(), ast_xml_free_text(), ast_xml_get_attribute(), ast_xml_get_text(), ast_xml_node_get_children(), ast_xml_node_get_name(), ast_xml_node_get_next(), first, and xmldoc_get_node().
Referenced by acf_retrieve_docs(), ast_agi_register(), ast_manager_register2(), and ast_register_application2().
01458 { 01459 struct ast_str *outputstr; 01460 char *output; 01461 struct ast_xml_node *node; 01462 const char *typename; 01463 const char *content; 01464 int first = 1; 01465 01466 if (ast_strlen_zero(type) || ast_strlen_zero(name)) { 01467 return NULL; 01468 } 01469 01470 /* get the application/function root node. */ 01471 node = xmldoc_get_node(type, name, module, documentation_language); 01472 if (!node || !ast_xml_node_get_children(node)) { 01473 return NULL; 01474 } 01475 01476 /* Find the <see-also> node. */ 01477 for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) { 01478 if (!strcasecmp(ast_xml_node_get_name(node), "see-also")) { 01479 break; 01480 } 01481 } 01482 01483 if (!node || !ast_xml_node_get_children(node)) { 01484 /* we couldnt find a <see-also> node. */ 01485 return NULL; 01486 } 01487 01488 /* prepare the output string. */ 01489 outputstr = ast_str_create(128); 01490 if (!outputstr) { 01491 return NULL; 01492 } 01493 01494 /* get into the <see-also> node. */ 01495 for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) { 01496 if (strcasecmp(ast_xml_node_get_name(node), "ref")) { 01497 continue; 01498 } 01499 01500 /* parse the <ref> node. 'type' attribute is required. */ 01501 typename = ast_xml_get_attribute(node, "type"); 01502 if (!typename) { 01503 continue; 01504 } 01505 content = ast_xml_get_text(node); 01506 if (!content) { 01507 ast_xml_free_attr(typename); 01508 continue; 01509 } 01510 if (!strcasecmp(typename, "application")) { 01511 ast_str_append(&outputstr, 0, "%s%s()", (first ? "" : ", "), content); 01512 } else if (!strcasecmp(typename, "function")) { 01513 ast_str_append(&outputstr, 0, "%s%s", (first ? "" : ", "), content); 01514 } else if (!strcasecmp(typename, "astcli")) { 01515 ast_str_append(&outputstr, 0, "%s<astcli>%s</astcli>", (first ? "" : ", "), content); 01516 } else { 01517 ast_str_append(&outputstr, 0, "%s%s", (first ? "" : ", "), content); 01518 } 01519 first = 0; 01520 ast_xml_free_text(content); 01521 ast_xml_free_attr(typename); 01522 } 01523 01524 output = ast_strdup(ast_str_buffer(outputstr)); 01525 ast_free(outputstr); 01526 01527 return output; 01528 }
char* ast_xmldoc_build_synopsis | ( | const char * | type, | |
const char * | name, | |||
const char * | module | |||
) |
Generate synopsis documentation from XML.
type | The source of documentation (application, function, etc). | |
name | The name of the application, function, etc. | |
module | The module the item is in (optional, can be NULL) |
NULL | on error. | |
A | malloc'ed string with the synopsis. |
Definition at line 1891 of file xmldoc.c.
References xmldoc_build_field().
Referenced by acf_retrieve_docs(), ast_agi_register(), ast_manager_register2(), and ast_register_application2().
01892 { 01893 return xmldoc_build_field(type, name, module, "synopsis", 1); 01894 }
char* ast_xmldoc_build_syntax | ( | const char * | type, | |
const char * | name, | |||
const char * | module | |||
) |
Get the syntax for a specified application or function.
type | Application, Function or AGI ? | |
name | Name of the application or function. | |
module | The module the item is in (optional, can be NULL) |
NULL | on error. | |
The | generated syntax in a ast_malloc'ed string. |
Definition at line 1152 of file xmldoc.c.
References ast_xml_node_get_children(), ast_xml_node_get_name(), ast_xml_node_get_next(), COMMAND_SYNTAX, FUNCTION_SYNTAX, MANAGER_SYNTAX, xmldoc_get_node(), xmldoc_get_syntax_cmd(), xmldoc_get_syntax_fun(), xmldoc_get_syntax_manager(), and xmldoc_get_syntax_type().
Referenced by acf_retrieve_docs(), ast_agi_register(), ast_manager_register2(), and ast_register_application2().
01153 { 01154 struct ast_xml_node *node; 01155 char *syntax = NULL; 01156 01157 node = xmldoc_get_node(type, name, module, documentation_language); 01158 if (!node) { 01159 return NULL; 01160 } 01161 01162 for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) { 01163 if (!strcasecmp(ast_xml_node_get_name(node), "syntax")) { 01164 break; 01165 } 01166 } 01167 01168 if (node) { 01169 switch (xmldoc_get_syntax_type(type)) { 01170 case FUNCTION_SYNTAX: 01171 syntax = xmldoc_get_syntax_fun(node, name, "parameter", 1, 1); 01172 break; 01173 case COMMAND_SYNTAX: 01174 syntax = xmldoc_get_syntax_cmd(node, name, 1); 01175 break; 01176 case MANAGER_SYNTAX: 01177 syntax = xmldoc_get_syntax_manager(node, name); 01178 break; 01179 default: 01180 syntax = xmldoc_get_syntax_fun(node, name, "parameter", 1, 1); 01181 } 01182 } 01183 return syntax; 01184 }
char* ast_xmldoc_printable | ( | const char * | bwinput, | |
int | withcolors | |||
) |
Colorize and put delimiters (instead of tags) to the xmldoc output.
bwinput | Not colorized input with tags. | |
withcolors | Result output with colors. |
NULL | on error. | |
New | malloced buffer colorized and with delimiters. |
Definition at line 315 of file xmldoc.c.
References ARRAY_LEN, ast_copy_string(), ast_free, ast_opt_light_background, ast_str_append(), ast_str_buffer(), ast_str_create(), ast_term_color_code(), COLOR_CYAN, colorized_tags, len(), term_end(), and xmldoc_string_wrap().
Referenced by handle_cli_agi_show(), handle_show_function(), handle_showmancmd(), print_app_docs(), and write_htmldump().
00316 { 00317 struct ast_str *colorized; 00318 char *wrapped = NULL; 00319 int i, c, len, colorsection; 00320 char *tmp; 00321 size_t bwinputlen; 00322 static const int base_fg = COLOR_CYAN; 00323 00324 if (!bwinput) { 00325 return NULL; 00326 } 00327 00328 bwinputlen = strlen(bwinput); 00329 00330 if (!(colorized = ast_str_create(256))) { 00331 return NULL; 00332 } 00333 00334 if (withcolors) { 00335 ast_term_color_code(&colorized, base_fg, 0); 00336 if (!colorized) { 00337 return NULL; 00338 } 00339 } 00340 00341 for (i = 0; i < bwinputlen; i++) { 00342 colorsection = 0; 00343 /* Check if we are at the beginning of a tag to be colorized. */ 00344 for (c = 0; c < ARRAY_LEN(colorized_tags); c++) { 00345 if (strncasecmp(bwinput + i, colorized_tags[c].inittag, strlen(colorized_tags[c].inittag))) { 00346 continue; 00347 } 00348 00349 if (!(tmp = strcasestr(bwinput + i + strlen(colorized_tags[c].inittag), colorized_tags[c].endtag))) { 00350 continue; 00351 } 00352 00353 len = tmp - (bwinput + i + strlen(colorized_tags[c].inittag)); 00354 00355 /* Setup color */ 00356 if (withcolors) { 00357 if (ast_opt_light_background) { 00358 /* Turn off *bright* colors */ 00359 ast_term_color_code(&colorized, colorized_tags[c].colorfg & 0x7f, 0); 00360 } else { 00361 /* Turn on *bright* colors */ 00362 ast_term_color_code(&colorized, colorized_tags[c].colorfg | 0x80, 0); 00363 } 00364 if (!colorized) { 00365 return NULL; 00366 } 00367 } 00368 00369 /* copy initial string replace */ 00370 ast_str_append(&colorized, 0, "%s", colorized_tags[c].init); 00371 if (!colorized) { 00372 return NULL; 00373 } 00374 { 00375 char buf[len + 1]; 00376 ast_copy_string(buf, bwinput + i + strlen(colorized_tags[c].inittag), sizeof(buf)); 00377 ast_str_append(&colorized, 0, "%s", buf); 00378 } 00379 if (!colorized) { 00380 return NULL; 00381 } 00382 00383 /* copy the ending string replace */ 00384 ast_str_append(&colorized, 0, "%s", colorized_tags[c].end); 00385 if (!colorized) { 00386 return NULL; 00387 } 00388 00389 /* Continue with the last color. */ 00390 if (withcolors) { 00391 ast_term_color_code(&colorized, base_fg, 0); 00392 if (!colorized) { 00393 return NULL; 00394 } 00395 } 00396 00397 i += len + strlen(colorized_tags[c].endtag) + strlen(colorized_tags[c].inittag) - 1; 00398 colorsection = 1; 00399 break; 00400 } 00401 00402 if (!colorsection) { 00403 ast_str_append(&colorized, 0, "%c", bwinput[i]); 00404 if (!colorized) { 00405 return NULL; 00406 } 00407 } 00408 } 00409 00410 if (withcolors) { 00411 ast_str_append(&colorized, 0, "%s", term_end()); 00412 if (!colorized) { 00413 return NULL; 00414 } 00415 } 00416 00417 /* Wrap the text, notice that string wrap will avoid cutting an ESC sequence. */ 00418 wrapped = xmldoc_string_wrap(ast_str_buffer(colorized), xmldoc_text_columns, xmldoc_max_diff); 00419 00420 ast_free(colorized); 00421 00422 return wrapped; 00423 }