XML Documentation API. More...
#include "asterisk.h"
#include "asterisk/_private.h"
#include "asterisk/paths.h"
#include "asterisk/linkedlists.h"
#include "asterisk/strings.h"
#include "asterisk/config.h"
#include "asterisk/term.h"
#include "asterisk/xmldoc.h"
Go to the source code of this file.
Data Structures | |
struct | documentation_tree |
XML documentation tree. More... | |
struct | strcolorized_tags |
struct | strspecial_tags |
struct | strsyntaxtype |
Mapping between type of node and type of syntax to generate. More... | |
struct | xmldoc_tree |
Container of documentation trees. More... | |
Macros | |
#define | GOTONEXT(__rev, __a) (__rev ? ast_xml_node_get_prev(__a) : ast_xml_node_get_next(__a)) |
#define | ISLAST(__rev, __a) (__rev == 1 ? (ast_xml_node_get_prev(__a) ? 0 : 1) : (ast_xml_node_get_next(__a) ? 0 : 1)) |
#define | MP(__a) ((multiple ? __a : "")) |
Enumerations | |
enum | syntaxtype { FUNCTION_SYNTAX, MANAGER_SYNTAX, COMMAND_SYNTAX } |
Types of syntax that we are able to generate. 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. More... | |
char * | ast_xmldoc_build_description (const char *type, const char *name, const char *module) |
Generate description documentation from XML. More... | |
char * | ast_xmldoc_build_seealso (const char *type, const char *name, const char *module) |
Parse the <see-also> node content. More... | |
char * | ast_xmldoc_build_synopsis (const char *type, const char *name, const char *module) |
Generate synopsis documentation from XML. More... | |
char * | ast_xmldoc_build_syntax (const char *type, const char *name, const char *module) |
Get the syntax for a specified application or function. More... | |
int | ast_xmldoc_load_documentation (void) |
Load XML documentation. Provided by xmldoc.c. More... | |
char * | ast_xmldoc_printable (const char *bwinput, int withcolors) |
Colorize and put delimiters (instead of tags) to the xmldoc output. More... | |
static int | xmldoc_attribute_match (struct ast_xml_node *node, const char *attr, const char *value) |
static char * | xmldoc_build_field (const char *type, const char *name, const char *module, const char *var, int raw) |
Get the content of a field (synopsis, description, etc) from an asterisk document tree. More... | |
static int | xmldoc_foundspace_backward (const char *text, int currentpos, int maxdiff) |
static struct ast_str * | xmldoc_get_formatted (struct ast_xml_node *node, int raw_output, int raw_wrap) |
static struct ast_xml_node * | xmldoc_get_node (const char *type, const char *name, const char *module, const char *language) |
static char * | xmldoc_get_syntax_cmd (struct ast_xml_node *fixnode, const char *name, int printname) |
static char * | xmldoc_get_syntax_fun (struct ast_xml_node *rootnode, const char *rootname, const char *childname, int printparenthesis, int printrootname) |
static char * | xmldoc_get_syntax_manager (struct ast_xml_node *fixnode, const char *name) |
static enum syntaxtype | xmldoc_get_syntax_type (const char *type) |
static int | xmldoc_has_inside (struct ast_xml_node *fixnode, const char *what) |
static int | xmldoc_has_nodes (struct ast_xml_node *fixnode) |
static int | xmldoc_has_specialtags (struct ast_xml_node *fixnode) |
static int | xmldoc_parse_argument (struct ast_xml_node *fixnode, int insideparameter, const char *paramtabs, const char *tabs, struct ast_str **buffer) |
static char * | xmldoc_parse_cmd_enumlist (struct ast_xml_node *fixnode) |
static int | xmldoc_parse_enum (struct ast_xml_node *fixnode, const char *tabs, struct ast_str **buffer) |
static int | xmldoc_parse_enumlist (struct ast_xml_node *fixnode, const char *tabs, struct ast_str **buffer) |
static int | xmldoc_parse_option (struct ast_xml_node *fixnode, const char *tabs, struct ast_str **buffer) |
static void | xmldoc_parse_optionlist (struct ast_xml_node *fixnode, const char *tabs, struct ast_str **buffer) |
static int | xmldoc_parse_para (struct ast_xml_node *node, const char *tabs, const char *posttabs, struct ast_str **buffer) |
static void | xmldoc_parse_parameter (struct ast_xml_node *fixnode, const char *tabs, struct ast_str **buffer) |
static int | xmldoc_parse_specialtags (struct ast_xml_node *fixnode, const char *tabs, const char *posttabs, struct ast_str **buffer) |
static int | xmldoc_parse_variable (struct ast_xml_node *node, const char *tabs, struct ast_str **buffer) |
static int | xmldoc_parse_variablelist (struct ast_xml_node *node, const char *tabs, struct ast_str **buffer) |
static int | xmldoc_postbrlen (const char *postbr) |
static void | xmldoc_reverse_helper (int reverse, int *len, char **syntax, const char *fmt,...) |
static void | xmldoc_setpostbr (char *postbr, size_t len, const char *text) |
static void | xmldoc_string_cleanup (const char *text, struct ast_str **output, int lastspaces) |
static char * | xmldoc_string_wrap (const char *text, int columns, int maxdiff) |
static void | xmldoc_unload_documentation (void) |
Close and unload XML documentation. More... | |
static int | xmldoc_wait_nextspace (const char *text, int currentpos, int maxdiff) |
Variables | |
static struct strcolorized_tags | colorized_tags [] |
static const char | default_documentation_language [] = "en_US" |
Default documentation language. More... | |
static char | documentation_language [6] |
XML documentation language. More... | |
static struct strspecial_tags | special_tags [] |
static struct strsyntaxtype | stxtype [] |
static const int | xmldoc_max_diff = 5 |
This is a value that we will use to let the wrapping mechanism move the cursor backward and forward xmldoc_max_diff positions before cutting the middle of a word, trying to find a space or a . More... | |
static const int | xmldoc_text_columns = 74 |
Number of columns to print when showing the XML documentation with a 'core show application/function *' CLI command. Used in text wrapping. More... | |
static struct xmldoc_tree | xmldoc_tree = { .first = NULL, .last = NULL, .lock = { PTHREAD_RWLOCK_INITIALIZER , NULL, 1 } , } |
#define GOTONEXT | ( | __rev, | |
__a | |||
) | (__rev ? ast_xml_node_get_prev(__a) : ast_xml_node_get_next(__a)) |
Referenced by xmldoc_get_syntax_fun().
#define ISLAST | ( | __rev, | |
__a | |||
) | (__rev == 1 ? (ast_xml_node_get_prev(__a) ? 0 : 1) : (ast_xml_node_get_next(__a) ? 0 : 1)) |
Referenced by xmldoc_get_syntax_fun().
#define MP | ( | __a | ) | ((multiple ? __a : "")) |
Referenced by xmldoc_get_syntax_fun().
enum syntaxtype |
Types of syntax that we are able to generate.
Enumerator | |
---|---|
FUNCTION_SYNTAX | |
MANAGER_SYNTAX | |
COMMAND_SYNTAX |
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().
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().
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().
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().
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().
int ast_xmldoc_load_documentation | ( | void | ) |
Load XML documentation. Provided by xmldoc.c.
1 | on error. |
0 | on success. |
Definition at line 1963 of file xmldoc.c.
References ast_asprintf, ast_calloc, ast_config_AST_DATA_DIR, ast_config_destroy(), ast_config_load2(), ast_debug, ast_free, ast_log(), ast_malloc, ast_register_atexit(), AST_RWLIST_INSERT_TAIL, AST_RWLIST_UNLOCK, AST_RWLIST_WRLOCK, ast_strdup, ast_strlen_zero(), ast_variable_browse(), ast_xml_close(), ast_xml_get_root(), ast_xml_init(), ast_xml_node_get_name(), ast_xml_open(), CONFIG_STATUS_FILEINVALID, documentation_tree::doc, documentation_tree::filename, GLOB_ABORTED, LOG_ERROR, LOG_WARNING, MY_GLOB_FLAGS, ast_variable::name, ast_variable::next, ast_variable::value, var, and xmldoc_unload_documentation().
Referenced by main().
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(), strcasestr(), term_end(), and xmldoc_string_wrap().
Referenced by handle_cli_agi_show(), handle_show_function(), handle_showmancmd(), print_app_docs(), and write_htmldump().
|
static |
Definition at line 476 of file xmldoc.c.
References ast_xml_free_attr(), ast_xml_get_attribute(), and match().
Referenced by xmldoc_get_node().
|
static |
Get the content of a field (synopsis, description, etc) from an asterisk document tree.
type | Type of element (application, function, ...). |
name | Name of element (Dial, Echo, Playback, ...). |
var | Name of field to return (synopsis, description, etc). |
raw | Field only contains text, no other elements inside it. |
NULL | On error. |
Field | text content on success. |
Definition at line 1861 of file xmldoc.c.
References ast_free, ast_log(), ast_str_buffer(), ast_str_strlen(), ast_strdup, ast_strlen_zero(), ast_xml_find_element(), ast_xml_node_get_children(), LOG_ERROR, LOG_WARNING, xmldoc_get_formatted(), and xmldoc_get_node().
Referenced by ast_xmldoc_build_description(), and ast_xmldoc_build_synopsis().
|
static |
|
static |
Definition at line 1817 of file xmldoc.c.
References ast_skip_blanks(), ast_str_buffer(), ast_str_create(), ast_str_strlen(), ast_str_truncate(), ast_xml_free_text(), ast_xml_get_text(), ast_xml_node_get_children(), ast_xml_node_get_next(), xmldoc_parse_enumlist(), xmldoc_parse_para(), xmldoc_parse_specialtags(), xmldoc_parse_variablelist(), and xmldoc_string_cleanup().
Referenced by xmldoc_build_field().
|
static |
Definition at line 495 of file xmldoc.c.
References AST_LIST_TRAVERSE, AST_RWLIST_RDLOCK, AST_RWLIST_UNLOCK, ast_strlen_zero(), ast_xml_find_element(), ast_xml_get_root(), ast_xml_node_get_children(), ast_xml_node_get_next(), documentation_tree::doc, and xmldoc_attribute_match().
Referenced by ast_xmldoc_build_arguments(), ast_xmldoc_build_seealso(), ast_xmldoc_build_syntax(), and xmldoc_build_field().
|
static |
Definition at line 974 of file xmldoc.c.
References ast_free, ast_str_append(), ast_str_buffer(), ast_str_create(), ast_strdup, ast_true(), ast_xml_free_attr(), ast_xml_get_attribute(), ast_xml_node_get_children(), ast_xml_node_get_name(), ast_xml_node_get_next(), first, xmldoc_has_inside(), and xmldoc_parse_cmd_enumlist().
Referenced by ast_xmldoc_build_syntax(), and xmldoc_parse_cmd_enumlist().
|
static |
Definition at line 685 of file xmldoc.c.
References ast_asprintf, ast_free, ast_log(), ast_strdup, ast_strdupa, ast_strlen_zero(), ast_true(), ast_xml_free_attr(), ast_xml_get_attribute(), ast_xml_node_get_children(), ast_xml_node_get_name(), ast_xml_node_get_next(), GOTONEXT, ISLAST, len(), LOG_WARNING, MP, xmldoc_has_inside(), and xmldoc_reverse_helper().
Referenced by ast_xmldoc_build_syntax(), and xmldoc_parse_optionlist().
|
static |
Definition at line 1072 of file xmldoc.c.
References ast_free, ast_str_append(), ast_str_buffer(), ast_str_create(), ast_strdup, ast_true(), ast_xml_free_attr(), ast_xml_get_attribute(), ast_xml_node_get_children(), ast_xml_node_get_name(), and ast_xml_node_get_next().
Referenced by ast_xmldoc_build_syntax().
|
static |
Definition at line 1144 of file xmldoc.c.
References ARRAY_LEN, FUNCTION_SYNTAX, strsyntaxtype::stxtype, and stxtype.
Referenced by ast_xmldoc_build_syntax().
|
static |
Definition at line 624 of file xmldoc.c.
References ast_xml_node_get_children(), ast_xml_node_get_name(), and ast_xml_node_get_next().
Referenced by xmldoc_get_syntax_cmd(), xmldoc_get_syntax_fun(), xmldoc_parse_argument(), and xmldoc_parse_parameter().
|
static |
Definition at line 642 of file xmldoc.c.
References ast_xml_node_get_children(), ast_xml_node_get_name(), and ast_xml_node_get_next().
Referenced by xmldoc_parse_parameter().
|
static |
Definition at line 660 of file xmldoc.c.
References ARRAY_LEN, ast_xml_node_get_children(), ast_xml_node_get_name(), ast_xml_node_get_next(), and special_tags.
Referenced by xmldoc_parse_argument().
|
static |
Definition at line 1306 of file xmldoc.c.
References ast_str_append(), ast_xml_free_attr(), ast_xml_get_attribute(), ast_xml_node_get_children(), ast_xml_node_get_next(), xmldoc_has_inside(), xmldoc_has_specialtags(), xmldoc_parse_para(), and xmldoc_parse_specialtags().
Referenced by xmldoc_parse_option(), and xmldoc_parse_parameter().
|
static |
Definition at line 927 of file xmldoc.c.
References ast_free, ast_str_append(), ast_str_buffer(), ast_str_create(), ast_strdup, ast_xml_node_get_children(), ast_xml_node_get_name(), ast_xml_node_get_next(), first, and xmldoc_get_syntax_cmd().
Referenced by xmldoc_get_syntax_cmd().
|
static |
Definition at line 1541 of file xmldoc.c.
References ast_asprintf, ast_free, ast_xml_node_get_children(), ast_xml_node_get_next(), xmldoc_parse_enumlist(), xmldoc_parse_para(), and xmldoc_parse_specialtags().
Referenced by xmldoc_parse_enumlist().
|
static |
Definition at line 1573 of file xmldoc.c.
References ast_str_append(), ast_xml_free_attr(), ast_xml_get_attribute(), ast_xml_node_get_children(), ast_xml_node_get_name(), ast_xml_node_get_next(), and xmldoc_parse_enum().
Referenced by xmldoc_get_formatted(), xmldoc_parse_enum(), xmldoc_parse_option(), and xmldoc_parse_parameter().
|
static |
Definition at line 1609 of file xmldoc.c.
References ast_asprintf, ast_free, ast_str_append(), ast_xml_node_get_children(), ast_xml_node_get_name(), ast_xml_node_get_next(), xmldoc_parse_argument(), xmldoc_parse_enumlist(), xmldoc_parse_para(), xmldoc_parse_specialtags(), and xmldoc_parse_variablelist().
Referenced by xmldoc_parse_optionlist().
|
static |
Definition at line 1653 of file xmldoc.c.
References ast_free, ast_str_append(), ast_xml_free_attr(), ast_xml_get_attribute(), ast_xml_node_get_children(), ast_xml_node_get_name(), ast_xml_node_get_next(), xmldoc_get_syntax_fun(), and xmldoc_parse_option().
Referenced by xmldoc_parse_parameter().
|
static |
Definition at line 1202 of file xmldoc.c.
References ast_free, ast_str_append(), ast_str_buffer(), ast_xml_free_text(), ast_xml_get_text(), ast_xml_node_get_children(), ast_xml_node_get_name(), ast_xml_node_get_next(), and xmldoc_string_cleanup().
Referenced by xmldoc_get_formatted(), xmldoc_parse_argument(), xmldoc_parse_enum(), xmldoc_parse_option(), xmldoc_parse_parameter(), xmldoc_parse_specialtags(), xmldoc_parse_variable(), and xmldoc_parse_variablelist().
|
static |
Definition at line 1704 of file xmldoc.c.
References ast_asprintf, ast_free, ast_str_append(), ast_xml_free_attr(), ast_xml_get_attribute(), ast_xml_node_get_children(), ast_xml_node_get_name(), ast_xml_node_get_next(), xmldoc_has_inside(), xmldoc_has_nodes(), xmldoc_parse_argument(), xmldoc_parse_enumlist(), xmldoc_parse_optionlist(), xmldoc_parse_para(), and xmldoc_parse_specialtags().
Referenced by ast_xmldoc_build_arguments().
|
static |
Definition at line 1256 of file xmldoc.c.
References ARRAY_LEN, ast_str_append(), ast_strlen_zero(), ast_xml_node_get_children(), ast_xml_node_get_name(), ast_xml_node_get_next(), special_tags, and xmldoc_parse_para().
Referenced by xmldoc_get_formatted(), xmldoc_parse_argument(), xmldoc_parse_enum(), xmldoc_parse_option(), xmldoc_parse_parameter(), xmldoc_parse_variable(), and xmldoc_parse_variablelist().
|
static |
Definition at line 1353 of file xmldoc.c.
References ast_free, ast_str_append(), ast_str_buffer(), ast_str_strlen(), 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(), xmldoc_parse_para(), xmldoc_parse_specialtags(), and xmldoc_string_cleanup().
Referenced by xmldoc_parse_variablelist().
|
static |
Definition at line 1414 of file xmldoc.c.
References ast_asprintf, ast_free, ast_str_append(), ast_xml_free_attr(), ast_xml_get_attribute(), ast_xml_node_get_children(), ast_xml_node_get_name(), ast_xml_node_get_next(), xmldoc_parse_para(), xmldoc_parse_specialtags(), and xmldoc_parse_variable().
Referenced by xmldoc_get_formatted(), and xmldoc_parse_option().
|
static |
|
static |
Definition at line 575 of file xmldoc.c.
References ast_free, ast_realloc, and ast_vasprintf.
Referenced by xmldoc_get_syntax_fun().
|
static |
Definition at line 141 of file xmldoc.c.
References len().
Referenced by xmldoc_string_wrap().
|
static |
Definition at line 431 of file xmldoc.c.
References ast_log(), ast_str_append(), ast_str_create(), ast_str_trim_blanks(), and LOG_ERROR.
Referenced by xmldoc_get_formatted(), xmldoc_parse_para(), and xmldoc_parse_variable().
|
static |
Definition at line 238 of file xmldoc.c.
References ast_free, ast_log(), ast_str_append(), ast_str_buffer(), ast_str_create(), ast_str_truncate(), ast_strdup, ESC, LOG_WARNING, xmldoc_foundspace_backward(), xmldoc_postbrlen(), xmldoc_setpostbr(), and xmldoc_wait_nextspace().
Referenced by ast_xmldoc_printable().
|
static |
Close and unload XML documentation.
Definition at line 1948 of file xmldoc.c.
References ast_free, AST_RWLIST_REMOVE_HEAD, AST_RWLIST_UNLOCK, AST_RWLIST_WRLOCK, ast_xml_close(), ast_xml_finish(), documentation_tree::doc, and documentation_tree::filename.
Referenced by ast_xmldoc_load_documentation().
|
static |
|
static |
Referenced by ast_xmldoc_printable().
|
static |
|
static |
|
static |
Referenced by xmldoc_has_specialtags(), and xmldoc_parse_specialtags().
|
static |
Referenced by xmldoc_get_syntax_type().
|
static |
|
static |
|
static |