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 1761 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().
01762 { 01763 struct ast_xml_node *node; 01764 struct ast_str *ret = ast_str_create(128); 01765 char *retstr = NULL; 01766 01767 if (ast_strlen_zero(type) || ast_strlen_zero(name)) { 01768 ast_free(ret); 01769 return NULL; 01770 } 01771 01772 node = xmldoc_get_node(type, name, module, documentation_language); 01773 01774 if (!node || !ast_xml_node_get_children(node)) { 01775 ast_free(ret); 01776 return NULL; 01777 } 01778 01779 /* Find the syntax field. */ 01780 for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) { 01781 if (!strcasecmp(ast_xml_node_get_name(node), "syntax")) { 01782 break; 01783 } 01784 } 01785 01786 if (!node || !ast_xml_node_get_children(node)) { 01787 /* We couldn't find the syntax node. */ 01788 ast_free(ret); 01789 return NULL; 01790 } 01791 01792 for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) { 01793 xmldoc_parse_parameter(node, "", &ret); 01794 } 01795 01796 if (ast_str_strlen(ret) > 0) { 01797 /* remove last '\n' */ 01798 char *buf = ast_str_buffer(ret); 01799 if (buf[ast_str_strlen(ret) - 1] == '\n') { 01800 ast_str_truncate(ret, -1); 01801 } 01802 retstr = ast_strdup(ast_str_buffer(ret)); 01803 } 01804 ast_free(ret); 01805 01806 return retstr; 01807 }
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 1899 of file xmldoc.c.
References xmldoc_build_field().
Referenced by acf_retrieve_docs(), ast_agi_register(), ast_manager_register2(), and ast_register_application2().
01900 { 01901 return xmldoc_build_field(type, name, module, "description", 0); 01902 }
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 1461 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().
01462 { 01463 struct ast_str *outputstr; 01464 char *output; 01465 struct ast_xml_node *node; 01466 const char *typename; 01467 const char *content; 01468 int first = 1; 01469 01470 if (ast_strlen_zero(type) || ast_strlen_zero(name)) { 01471 return NULL; 01472 } 01473 01474 /* get the application/function root node. */ 01475 node = xmldoc_get_node(type, name, module, documentation_language); 01476 if (!node || !ast_xml_node_get_children(node)) { 01477 return NULL; 01478 } 01479 01480 /* Find the <see-also> node. */ 01481 for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) { 01482 if (!strcasecmp(ast_xml_node_get_name(node), "see-also")) { 01483 break; 01484 } 01485 } 01486 01487 if (!node || !ast_xml_node_get_children(node)) { 01488 /* we couldnt find a <see-also> node. */ 01489 return NULL; 01490 } 01491 01492 /* prepare the output string. */ 01493 outputstr = ast_str_create(128); 01494 if (!outputstr) { 01495 return NULL; 01496 } 01497 01498 /* get into the <see-also> node. */ 01499 for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) { 01500 if (strcasecmp(ast_xml_node_get_name(node), "ref")) { 01501 continue; 01502 } 01503 01504 /* parse the <ref> node. 'type' attribute is required. */ 01505 typename = ast_xml_get_attribute(node, "type"); 01506 if (!typename) { 01507 continue; 01508 } 01509 content = ast_xml_get_text(node); 01510 if (!content) { 01511 ast_xml_free_attr(typename); 01512 continue; 01513 } 01514 if (!strcasecmp(typename, "application")) { 01515 ast_str_append(&outputstr, 0, "%s%s()", (first ? "" : ", "), content); 01516 } else if (!strcasecmp(typename, "function")) { 01517 ast_str_append(&outputstr, 0, "%s%s", (first ? "" : ", "), content); 01518 } else if (!strcasecmp(typename, "astcli")) { 01519 ast_str_append(&outputstr, 0, "%s<astcli>%s</astcli>", (first ? "" : ", "), content); 01520 } else { 01521 ast_str_append(&outputstr, 0, "%s%s", (first ? "" : ", "), content); 01522 } 01523 first = 0; 01524 ast_xml_free_text(content); 01525 ast_xml_free_attr(typename); 01526 } 01527 01528 output = ast_strdup(ast_str_buffer(outputstr)); 01529 ast_free(outputstr); 01530 01531 return output; 01532 }
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 1894 of file xmldoc.c.
References xmldoc_build_field().
Referenced by acf_retrieve_docs(), ast_agi_register(), ast_manager_register2(), and ast_register_application2().
01895 { 01896 return xmldoc_build_field(type, name, module, "synopsis", 1); 01897 }
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 1156 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().
01157 { 01158 struct ast_xml_node *node; 01159 char *syntax = NULL; 01160 01161 node = xmldoc_get_node(type, name, module, documentation_language); 01162 if (!node) { 01163 return NULL; 01164 } 01165 01166 for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) { 01167 if (!strcasecmp(ast_xml_node_get_name(node), "syntax")) { 01168 break; 01169 } 01170 } 01171 01172 if (node) { 01173 switch (xmldoc_get_syntax_type(type)) { 01174 case FUNCTION_SYNTAX: 01175 syntax = xmldoc_get_syntax_fun(node, name, "parameter", 1, 1); 01176 break; 01177 case COMMAND_SYNTAX: 01178 syntax = xmldoc_get_syntax_cmd(node, name, 1); 01179 break; 01180 case MANAGER_SYNTAX: 01181 syntax = xmldoc_get_syntax_manager(node, name); 01182 break; 01183 default: 01184 syntax = xmldoc_get_syntax_fun(node, name, "parameter", 1, 1); 01185 } 01186 } 01187 return syntax; 01188 }
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 }