Asterisk - The Open Source Telephony Project  21.4.1
Data Structures | Macros | Enumerations | Functions | Variables
xmldoc.c File Reference

XML Documentation API. More...

#include "asterisk.h"
#include "asterisk/_private.h"
#include "asterisk/paths.h"
#include "asterisk/linkedlists.h"
#include "asterisk/config.h"
#include "asterisk/term.h"
#include "asterisk/astobj2.h"
#include "asterisk/xmldoc.h"
#include "asterisk/cli.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, MANAGER_EVENT_SYNTAX, CONFIG_INFO_SYNTAX,
  CONFIG_FILE_SYNTAX, CONFIG_OPTION_SYNTAX, CONFIG_OBJECT_SYNTAX, COMMAND_SYNTAX
}
 Types of syntax that we are able to generate.
 

Functions

static char * _ast_xmldoc_build_arguments (struct ast_xml_node *node)
 
static char * _ast_xmldoc_build_description (struct ast_xml_node *node)
 
static char * _ast_xmldoc_build_seealso (struct ast_xml_node *node)
 
static char * _ast_xmldoc_build_synopsis (struct ast_xml_node *node)
 
static char * _ast_xmldoc_build_syntax (struct ast_xml_node *root_node, const char *type, const char *name)
 
static char * _xmldoc_build_field (struct ast_xml_node *node, const char *var, int raw)
 
static struct ast_xml_doc_itemast_xml_doc_item_alloc (const char *name, const char *type)
 
static int ast_xml_doc_item_cmp (void *obj, void *arg, int flags)
 
static void ast_xml_doc_item_destructor (void *obj)
 
static int ast_xml_doc_item_hash (const void *obj, const int flags)
 
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...
 
struct ao2_containerast_xmldoc_build_documentation (const char *type)
 Build the documentation for a particular source type. More...
 
struct ast_xml_doc_itemast_xmldoc_build_final_response (const char *type, const char *name, const char *module)
 Generate the [final response] tag based on type of node ('application', 'function' or 'agi') and name. More...
 
struct ast_xml_doc_itemast_xmldoc_build_list_responses (const char *type, const char *name, const char *module)
 Generate the [list responses] tag based on type of node ('application', 'function' or 'agi') and name. 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...
 
struct ast_xml_xpath_results * ast_xmldoc_query (const char *fmt,...)
 Execute an XPath query on the loaded XML documentation. More...
 
int ast_xmldoc_regenerate_doc_item (struct ast_xml_doc_item *item)
 Regenerate the documentation for a particular item. More...
 
static void build_config_docs (struct ast_xml_node *cur, struct ast_xml_doc_item_list *root)
 
static char * handle_dump_docs (struct ast_cli_entry *e, int cmd, struct ast_cli_args *a)
 
static char * handle_reload_docs (struct ast_cli_entry *e, int cmd, struct ast_cli_args *a)
 
static int xmldoc_attribute_match (struct ast_xml_node *node, const char *attr, const char *value)
 
static struct ast_xml_doc_itemxmldoc_build_documentation_item (struct ast_xml_node *node, const char *name, const char *type)
 
static char * xmldoc_build_field (const char *type, const char *name, const char *module, const char *var, int raw)
 
static struct ast_xml_doc_itemxmldoc_build_final_response (struct ast_xml_node *manager_action)
 
static struct ast_xml_doc_itemxmldoc_build_list_responses (struct ast_xml_node *manager_action)
 
static struct ast_strxmldoc_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_config_object (struct ast_xml_node *fixnode, const char *name)
 
static char * xmldoc_get_syntax_config_option (struct ast_xml_node *fixnode, const char *name)
 
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, const char *manager_type)
 
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_load_documentation (int first_time)
 
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_common_elements (struct ast_xml_node *node, const char *tabs, const char *posttabs, struct ast_str **buffer)
 
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_example (struct ast_xml_node *fixnode, struct ast_str **buffer)
 
static int xmldoc_parse_info (struct ast_xml_node *node, const char *tabs, const char *posttabs, 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_purge_documentation (void)
 
static int xmldoc_reload_documentation (void)
 
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, int maintain_newlines)
 
static char * xmldoc_string_wrap (const char *text, int columns)
 
static void xmldoc_unload_documentation (void)
 Close and unload XML documentation.
 

Variables

static struct ast_cli_entry cli_dump_xmldocs = { .handler = handle_dump_docs , .summary = "Dump the XML docs to the specified file" ,}
 
static struct ast_cli_entry cli_reload_xmldocs = { .handler = handle_reload_docs , .summary = "Reload the XML docs" ,}
 
static const struct strcolorized_tags colorized_tags []
 
static const char default_documentation_language [] = "en_US"
 Default documentation language.
 
static char documentation_language [6]
 XML documentation language.
 
static const struct strspecial_tags special_tags []
 
static struct strsyntaxtype stxtype []
 
static const int xmldoc_text_columns = 79
 Number of columns to print when showing the XML documentation with a 'core show application/function *' CLI command. Used in text wrapping.
 
static struct xmldoc_tree xmldoc_tree = { .first = NULL, .last = NULL, .lock = { PTHREAD_RWLOCK_INITIALIZER , NULL, {1, 0} } , }
 

Detailed Description

XML Documentation API.

Author
Eliel C. Sardanons (LU1ALY) eliel.nosp@m.s@gm.nosp@m.ail.c.nosp@m.om

libxml2 http://www.xmlsoft.org/

Definition in file xmldoc.c.

Function Documentation

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.

Parameters
type'application', 'function' or 'agi' ?
nameName of the application or function to build the 'arguments' tag.
moduleThe module the item is in (optional, can be NULL)
Return values
NULLon error.
Outputbuffer with the [arguments] tag content.

Definition at line 2084 of file xmldoc.c.

References AST_RWLIST_RDLOCK, AST_RWLIST_UNLOCK, ast_xml_node_get_children(), and documentation_language.

Referenced by ast_manager_register2(), and ast_register_application2().

2085 {
2086  struct ast_xml_node *node;
2087  char *arguments;
2088 
2089  if (ast_strlen_zero(type) || ast_strlen_zero(name)) {
2090  return NULL;
2091  }
2092 
2094  node = xmldoc_get_node(type, name, module, documentation_language);
2095 
2096  if (!node || !ast_xml_node_get_children(node)) {
2098  return NULL;
2099  }
2100 
2101  arguments = _ast_xmldoc_build_arguments(node);
2103  return arguments;
2104 }
Definition: test_heap.c:38
#define AST_RWLIST_RDLOCK(head)
Read locks a list.
Definition: linkedlists.h:78
static char documentation_language[6]
XML documentation language.
Definition: xmldoc.c:51
#define AST_RWLIST_UNLOCK(head)
Attempts to unlock a read/write based list.
Definition: linkedlists.h:151
Container of documentation trees.
Definition: xmldoc.c:74
struct ast_xml_node * ast_xml_node_get_children(struct ast_xml_node *node)
Get the node's children.
Definition: xml.c:395
char* ast_xmldoc_build_description ( const char *  type,
const char *  name,
const char *  module 
)

Generate description documentation from XML.

Parameters
typeThe source of documentation (application, function, etc).
nameThe name of the application, function, etc.
moduleThe module the item is in (optional, can be NULL)
Return values
NULLon error.
Amalloc'ed string with the formatted description.

Definition at line 2271 of file xmldoc.c.

Referenced by ast_manager_register2(), and ast_register_application2().

2272 {
2273  return xmldoc_build_field(type, name, module, "description", 0);
2274 }
struct ao2_container* ast_xmldoc_build_documentation ( const char *  type)

Build the documentation for a particular source type.

Parameters
typeThe source of the documentation items (application, function, etc.)
Return values
NULLon error
Anao2_container populated with ast_xml_doc instances for each item that exists for the specified source type
Since
11

Definition at line 2684 of file xmldoc.c.

References AO2_ALLOC_OPT_LOCK_MUTEX, ao2_container_alloc_hash, ao2_link, AST_LIST_FIRST, AST_LIST_HEAD_INIT, AST_LIST_INSERT_TAIL, AST_LIST_TRAVERSE, AST_RWLIST_RDLOCK, AST_RWLIST_UNLOCK, ast_xml_free_attr(), ast_xml_get_attribute(), ast_xml_get_root(), ast_xml_node_get_children(), ast_xml_node_get_name(), ast_xml_node_get_next(), documentation_tree::doc, and RAII_VAR.

Referenced by aco_init().

2685 {
2686  struct ao2_container *docs;
2687  struct ast_xml_node *node = NULL, *instance = NULL;
2688  struct documentation_tree *doctree;
2689  const char *name;
2690 
2692  ast_xml_doc_item_hash, NULL, ast_xml_doc_item_cmp);
2693  if (!docs) {
2694  ast_log(AST_LOG_ERROR, "Failed to create container for xml document item instances\n");
2695  return NULL;
2696  }
2697 
2699  AST_LIST_TRAVERSE(&xmldoc_tree, doctree, entry) {
2700  /* the core xml documents have priority over thirdparty document. */
2701  node = ast_xml_get_root(doctree->doc);
2702  if (!node) {
2703  break;
2704  }
2705 
2706  for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
2707  struct ast_xml_doc_item *item = NULL;
2708 
2709  /* Ignore empty nodes or nodes that aren't of the type requested */
2710  if (!ast_xml_node_get_children(node) || strcasecmp(ast_xml_node_get_name(node), type)) {
2711  continue;
2712  }
2713  name = ast_xml_get_attribute(node, "name");
2714  if (!name) {
2715  continue;
2716  }
2717 
2718  switch (xmldoc_get_syntax_type(type)) {
2719  case MANAGER_EVENT_SYNTAX:
2720  {
2721  struct ast_xml_doc_item_list root;
2722 
2723  AST_LIST_HEAD_INIT(&root);
2724  for (instance = ast_xml_node_get_children(node); instance; instance = ast_xml_node_get_next(instance)) {
2725  struct ast_xml_doc_item *temp;
2726  if (!ast_xml_node_get_children(instance) || strcasecmp(ast_xml_node_get_name(instance), "managerEventInstance")) {
2727  continue;
2728  }
2729  temp = xmldoc_build_documentation_item(instance, name, type);
2730  if (!temp) {
2731  break;
2732  }
2733  AST_LIST_INSERT_TAIL(&root, temp, next);
2734  }
2735  item = AST_LIST_FIRST(&root);
2736  break;
2737  }
2738  case CONFIG_INFO_SYNTAX:
2739  {
2740  RAII_VAR(const char *, name, ast_xml_get_attribute(node, "name"), ast_xml_free_attr);
2741 
2742  if (!ast_xml_node_get_children(node) || strcasecmp(ast_xml_node_get_name(node), "configInfo")) {
2743  break;
2744  }
2745 
2746  item = xmldoc_build_documentation_item(node, name, "configInfo");
2747  if (item) {
2748  struct ast_xml_doc_item_list root;
2749 
2750  AST_LIST_HEAD_INIT(&root);
2751  AST_LIST_INSERT_TAIL(&root, item, next);
2752  build_config_docs(node, &root);
2753  }
2754  break;
2755  }
2756  default:
2757  item = xmldoc_build_documentation_item(node, name, type);
2758  }
2759  ast_xml_free_attr(name);
2760 
2761  if (item) {
2762  ao2_link(docs, item);
2763  ao2_t_ref(item, -1, "Dispose of creation ref");
2764  }
2765  }
2766  }
2768 
2769  return docs;
2770 }
Definition: test_heap.c:38
XML documentation tree.
Definition: xmldoc.c:54
#define AST_LIST_FIRST(head)
Returns the first entry contained in a list.
Definition: linkedlists.h:421
#define AST_RWLIST_RDLOCK(head)
Read locks a list.
Definition: linkedlists.h:78
struct ast_xml_node * ast_xml_get_root(struct ast_xml_doc *doc)
Get the document root node.
Definition: xml.c:230
The struct to be used as the head of an ast_xml_doc_item list when being manipulated.
Definition: xmldoc.h:45
const char * ast_xml_get_attribute(struct ast_xml_node *node, const char *attrname)
Get a node attribute by name.
Definition: xml.c:267
void ast_xml_free_attr(const char *attribute)
Free an attribute returned by ast_xml_get_attribute()
Definition: xml.c:253
const ast_string_field type
Definition: xmldoc.h:74
struct ast_xml_doc * doc
Definition: xmldoc.c:56
#define AST_LIST_INSERT_TAIL(head, elm, field)
Appends a list entry to the tail of a list.
Definition: linkedlists.h:731
#define ao2_container_alloc_hash(ao2_options, container_options, n_buckets, hash_fn, sort_fn, cmp_fn)
Allocate and initialize a hash container with the desired number of buckets.
Definition: astobj2.h:1303
#define AST_LIST_TRAVERSE(head, var, field)
Loops over (traverses) the entries in a list.
Definition: linkedlists.h:491
#define AST_LIST_HEAD_INIT(head)
Initializes a list head structure.
Definition: linkedlists.h:626
Definition: search.h:40
Struct that contains the XML documentation for a particular item. Note that this is an ao2 ref counte...
Definition: xmldoc.h:56
#define AST_RWLIST_UNLOCK(head)
Attempts to unlock a read/write based list.
Definition: linkedlists.h:151
Generic container type.
Container of documentation trees.
Definition: xmldoc.c:74
struct ast_xml_node * ast_xml_node_get_next(struct ast_xml_node *node)
Get the next node in the same level.
Definition: xml.c:400
#define RAII_VAR(vartype, varname, initval, dtor)
Declare a variable that will call a destructor function when it goes out of scope.
Definition: utils.h:941
struct ast_xml_node * ast_xml_node_get_children(struct ast_xml_node *node)
Get the node's children.
Definition: xml.c:395
const char * ast_xml_node_get_name(struct ast_xml_node *node)
Get the name of a node.
Definition: xml.c:390
#define ao2_link(container, obj)
Add an object to a container.
Definition: astobj2.h:1532
struct ast_xml_doc_item* ast_xmldoc_build_final_response ( const char *  type,
const char *  name,
const char *  module 
)

Generate the [final response] tag based on type of node ('application', 'function' or 'agi') and name.

Parameters
type'application', 'function' or 'agi'
nameName of the application or function to build the 'responses' tag.
moduleThe module the item is in (optional, can be NULL)
Returns
An XMLDoc item list with the [final response] tag content.
Since
13.0.0

Definition at line 2554 of file xmldoc.c.

References AST_RWLIST_RDLOCK, AST_RWLIST_UNLOCK, ast_xml_node_get_children(), and documentation_language.

Referenced by ast_manager_register2().

2555 {
2556  struct ast_xml_node *node;
2557  static struct ast_xml_doc_item *response;
2558 
2559  if (ast_strlen_zero(type) || ast_strlen_zero(name)) {
2560  return NULL;
2561  }
2562 
2564  node = xmldoc_get_node(type, name, module, documentation_language);
2565 
2566  if (!node || !ast_xml_node_get_children(node)) {
2568  return NULL;
2569  }
2570 
2571  response = xmldoc_build_final_response(node);
2573  return response;
2574 }
Definition: test_heap.c:38
#define AST_RWLIST_RDLOCK(head)
Read locks a list.
Definition: linkedlists.h:78
const ast_string_field type
Definition: xmldoc.h:74
static char documentation_language[6]
XML documentation language.
Definition: xmldoc.c:51
const ast_string_field name
Definition: xmldoc.h:74
Struct that contains the XML documentation for a particular item. Note that this is an ao2 ref counte...
Definition: xmldoc.h:56
#define AST_RWLIST_UNLOCK(head)
Attempts to unlock a read/write based list.
Definition: linkedlists.h:151
Container of documentation trees.
Definition: xmldoc.c:74
struct ast_xml_node * ast_xml_node_get_children(struct ast_xml_node *node)
Get the node's children.
Definition: xml.c:395
struct ast_xml_doc_item* ast_xmldoc_build_list_responses ( const char *  type,
const char *  name,
const char *  module 
)

Generate the [list responses] tag based on type of node ('application', 'function' or 'agi') and name.

Parameters
type'application', 'function' or 'agi'
nameName of the application or function to build the 'responses' tag.
moduleThe module the item is in (optional, can be NULL)
Returns
An XMLDoc item list with the [list responses] tag content.
Since
13.0.0

Definition at line 2484 of file xmldoc.c.

References AST_RWLIST_RDLOCK, AST_RWLIST_UNLOCK, ast_xml_node_get_children(), and documentation_language.

Referenced by ast_manager_register2().

2485 {
2486  struct ast_xml_node *node;
2487  struct ast_xml_doc_item *responses;
2488 
2489  if (ast_strlen_zero(type) || ast_strlen_zero(name)) {
2490  return NULL;
2491  }
2492 
2494  node = xmldoc_get_node(type, name, module, documentation_language);
2495 
2496  if (!node || !ast_xml_node_get_children(node)) {
2498  return NULL;
2499  }
2500 
2501  responses = xmldoc_build_list_responses(node);
2503  return responses;
2504 }
Definition: test_heap.c:38
#define AST_RWLIST_RDLOCK(head)
Read locks a list.
Definition: linkedlists.h:78
const ast_string_field type
Definition: xmldoc.h:74
static char documentation_language[6]
XML documentation language.
Definition: xmldoc.c:51
const ast_string_field name
Definition: xmldoc.h:74
Struct that contains the XML documentation for a particular item. Note that this is an ao2 ref counte...
Definition: xmldoc.h:56
#define AST_RWLIST_UNLOCK(head)
Attempts to unlock a read/write based list.
Definition: linkedlists.h:151
Container of documentation trees.
Definition: xmldoc.c:74
struct ast_xml_node * ast_xml_node_get_children(struct ast_xml_node *node)
Get the node's children.
Definition: xml.c:395
char* ast_xmldoc_build_seealso ( const char *  type,
const char *  name,
const char *  module 
)

Parse the <see-also> node content.

Parameters
type'application', 'function' or 'agi'.
nameApplication or functions name.
moduleThe module the item is in (optional, can be NULL)
Return values
NULLon error.
Contentof the see-also node.

Definition at line 1702 of file xmldoc.c.

References AST_RWLIST_RDLOCK, AST_RWLIST_UNLOCK, ast_xml_node_get_children(), and documentation_language.

Referenced by ast_manager_register2(), and ast_register_application2().

1703 {
1704  char *output;
1705  struct ast_xml_node *node;
1706 
1707  if (ast_strlen_zero(type) || ast_strlen_zero(name)) {
1708  return NULL;
1709  }
1710 
1711  /* get the application/function root node. */
1713  node = xmldoc_get_node(type, name, module, documentation_language);
1714  if (!node || !ast_xml_node_get_children(node)) {
1716  return NULL;
1717  }
1718 
1719  output = _ast_xmldoc_build_seealso(node);
1721 
1722  return output;
1723 }
Definition: test_heap.c:38
#define AST_RWLIST_RDLOCK(head)
Read locks a list.
Definition: linkedlists.h:78
static char documentation_language[6]
XML documentation language.
Definition: xmldoc.c:51
#define AST_RWLIST_UNLOCK(head)
Attempts to unlock a read/write based list.
Definition: linkedlists.h:151
Container of documentation trees.
Definition: xmldoc.c:74
struct ast_xml_node * ast_xml_node_get_children(struct ast_xml_node *node)
Get the node's children.
Definition: xml.c:395
char* ast_xmldoc_build_synopsis ( const char *  type,
const char *  name,
const char *  module 
)

Generate synopsis documentation from XML.

Parameters
typeThe source of documentation (application, function, etc).
nameThe name of the application, function, etc.
moduleThe module the item is in (optional, can be NULL)
Return values
NULLon error.
Amalloc'ed string with the synopsis.

Definition at line 2248 of file xmldoc.c.

Referenced by ast_manager_register2(), and ast_register_application2().

2249 {
2250  return xmldoc_build_field(type, name, module, "synopsis", 1);
2251 }
char* ast_xmldoc_build_syntax ( const char *  type,
const char *  name,
const char *  module 
)

Get the syntax for a specified application or function.

Parameters
typeApplication, Function or AGI ?
nameName of the application or function.
moduleThe module the item is in (optional, can be NULL)
Return values
NULLon error.
Thegenerated syntax in a ast_malloc'ed string.

Definition at line 1252 of file xmldoc.c.

References AST_RWLIST_RDLOCK, AST_RWLIST_UNLOCK, and documentation_language.

Referenced by ast_manager_register2(), and ast_register_application2().

1253 {
1254  struct ast_xml_node *node;
1255  char *syntax;
1256 
1258  node = xmldoc_get_node(type, name, module, documentation_language);
1259  if (!node) {
1261  return NULL;
1262  }
1263 
1264  syntax = _ast_xmldoc_build_syntax(node, type, name);
1266  return syntax;
1267 }
Definition: test_heap.c:38
#define AST_RWLIST_RDLOCK(head)
Read locks a list.
Definition: linkedlists.h:78
static char documentation_language[6]
XML documentation language.
Definition: xmldoc.c:51
#define AST_RWLIST_UNLOCK(head)
Attempts to unlock a read/write based list.
Definition: linkedlists.h:151
Container of documentation trees.
Definition: xmldoc.c:74
int ast_xmldoc_load_documentation ( void  )

Load XML documentation. Provided by xmldoc.c.

Return values
1on error.
0on success.

Definition at line 3047 of file xmldoc.c.

3048 {
3049  return xmldoc_load_documentation(1);
3050 }
char* ast_xmldoc_printable ( const char *  bwinput,
int  withcolors 
)

Colorize and put delimiters (instead of tags) to the xmldoc output.

Parameters
bwinputNot colorized input with tags.
withcolorsResult output with colors.
Return values
NULLon error.
Newmalloced buffer colorized and with delimiters.

Definition at line 241 of file xmldoc.c.

References ast_copy_string(), ast_str_append(), ast_str_buffer(), ast_str_create, ast_term_color_code(), ast_term_reset(), and xmldoc_text_columns.

242 {
243  struct ast_str *colorized;
244  char *wrapped = NULL;
245  int i, c, len, colorsection;
246  char *tmp;
247  size_t bwinputlen;
248  static const int base_fg = COLOR_CYAN;
249 
250  if (!bwinput) {
251  return NULL;
252  }
253 
254  bwinputlen = strlen(bwinput);
255 
256  if (!(colorized = ast_str_create(256))) {
257  return NULL;
258  }
259 
260  if (withcolors) {
261  ast_term_color_code(&colorized, base_fg, 0);
262  if (!colorized) {
263  return NULL;
264  }
265  }
266 
267  for (i = 0; i < bwinputlen; i++) {
268  colorsection = 0;
269  /* Check if we are at the beginning of a tag to be colorized. */
270  for (c = 0; c < ARRAY_LEN(colorized_tags); c++) {
271  if (strncasecmp(bwinput + i, colorized_tags[c].inittag, strlen(colorized_tags[c].inittag))) {
272  continue;
273  }
274 
275  if (!(tmp = strcasestr(bwinput + i + strlen(colorized_tags[c].inittag), colorized_tags[c].endtag))) {
276  continue;
277  }
278 
279  len = tmp - (bwinput + i + strlen(colorized_tags[c].inittag));
280 
281  /* Setup color */
282  if (withcolors) {
283  if (ast_opt_light_background) {
284  /* Turn off *bright* colors */
285  ast_term_color_code(&colorized, colorized_tags[c].colorfg & 0x7f, 0);
286  } else {
287  /* Turn on *bright* colors */
288  ast_term_color_code(&colorized, colorized_tags[c].colorfg | 0x80, 0);
289  }
290  if (!colorized) {
291  return NULL;
292  }
293  }
294 
295  /* copy initial string replace */
296  ast_str_append(&colorized, 0, "%s", colorized_tags[c].init);
297  if (!colorized) {
298  return NULL;
299  }
300  {
301  char buf[len + 1];
302  ast_copy_string(buf, bwinput + i + strlen(colorized_tags[c].inittag), sizeof(buf));
303  ast_str_append(&colorized, 0, "%s", buf);
304  }
305  if (!colorized) {
306  return NULL;
307  }
308 
309  /* copy the ending string replace */
310  ast_str_append(&colorized, 0, "%s", colorized_tags[c].end);
311  if (!colorized) {
312  return NULL;
313  }
314 
315  /* Continue with the last color. */
316  if (withcolors) {
317  ast_term_color_code(&colorized, base_fg, 0);
318  if (!colorized) {
319  return NULL;
320  }
321  }
322 
323  i += len + strlen(colorized_tags[c].endtag) + strlen(colorized_tags[c].inittag) - 1;
324  colorsection = 1;
325  break;
326  }
327 
328  if (!colorsection) {
329  ast_str_append(&colorized, 0, "%c", bwinput[i]);
330  if (!colorized) {
331  return NULL;
332  }
333  }
334  }
335 
336  if (withcolors) {
337  ast_str_append(&colorized, 0, "%s", ast_term_reset());
338  if (!colorized) {
339  return NULL;
340  }
341  }
342 
343  /* Wrap the text, notice that string wrap will avoid cutting an ESC sequence. */
344  wrapped = xmldoc_string_wrap(ast_str_buffer(colorized), xmldoc_text_columns);
345 
346  ast_free(colorized);
347 
348  return wrapped;
349 }
char * ast_str_buffer(const struct ast_str *buf)
Returns the string buffer within the ast_str buf.
Definition: strings.h:761
int ast_term_color_code(struct ast_str **str, int fgcolor, int bgcolor)
Append a color sequence to an ast_str.
Definition: term.c:296
int ast_str_append(struct ast_str **buf, ssize_t max_len, const char *fmt,...)
Append to a thread local dynamic string.
Definition: strings.h:1139
Support for dynamic strings.
Definition: strings.h:623
static const int xmldoc_text_columns
Number of columns to print when showing the XML documentation with a 'core show application/function ...
Definition: xmldoc.c:48
const char * ast_term_reset(void)
Returns the terminal reset code.
Definition: term.c:357
void ast_copy_string(char *dst, const char *src, size_t size)
Size-limited null-terminating string copy.
Definition: strings.h:425
#define ast_str_create(init_len)
Create a malloc'ed dynamic length string.
Definition: strings.h:659
struct ast_xml_xpath_results* ast_xmldoc_query ( const char *  fmt,
  ... 
)

Execute an XPath query on the loaded XML documentation.

Parameters
fmtThe XPath query string to execute
...Variable printf style format arguments
Return values
AnXPath results object on success
NULLif no match found
Since
12

Definition at line 2576 of file xmldoc.c.

References AST_DYNSTR_BUILD_FAILED, AST_LIST_TRAVERSE, AST_RWLIST_RDLOCK, AST_RWLIST_UNLOCK, ast_str_buffer(), ast_str_create, ast_str_set_va(), ast_xml_query(), documentation_tree::doc, and RAII_VAR.

Referenced by load_modules().

2577 {
2578  struct ast_xml_xpath_results *results = NULL;
2579  struct documentation_tree *doctree;
2580  RAII_VAR(struct ast_str *, xpath_str, ast_str_create(128), ast_free);
2581  va_list ap;
2582  int res;
2583 
2584  if (!xpath_str) {
2585  return NULL;
2586  }
2587 
2588  va_start(ap, fmt);
2589  res = ast_str_set_va(&xpath_str, 0, fmt, ap);
2590  va_end(ap);
2591  if (res == AST_DYNSTR_BUILD_FAILED) {
2592  return NULL;
2593  }
2594 
2596  AST_LIST_TRAVERSE(&xmldoc_tree, doctree, entry) {
2597  if (!(results = ast_xml_query(doctree->doc, ast_str_buffer(xpath_str)))) {
2598  continue;
2599  }
2600  break;
2601  }
2603 
2604  return results;
2605 }
XML documentation tree.
Definition: xmldoc.c:54
char * ast_str_buffer(const struct ast_str *buf)
Returns the string buffer within the ast_str buf.
Definition: strings.h:761
#define AST_RWLIST_RDLOCK(head)
Read locks a list.
Definition: linkedlists.h:78
int ast_str_set_va(struct ast_str **buf, ssize_t max_len, const char *fmt, va_list ap)
Set a dynamic string from a va_list.
Definition: strings.h:1030
struct ast_xml_doc * doc
Definition: xmldoc.c:56
struct ast_xml_xpath_results * ast_xml_query(struct ast_xml_doc *doc, const char *xpath_str)
Execute an XPath query on an XML document.
Definition: xml.c:441
Support for dynamic strings.
Definition: strings.h:623
#define AST_LIST_TRAVERSE(head, var, field)
Loops over (traverses) the entries in a list.
Definition: linkedlists.h:491
Definition: search.h:40
#define AST_RWLIST_UNLOCK(head)
Attempts to unlock a read/write based list.
Definition: linkedlists.h:151
Container of documentation trees.
Definition: xmldoc.c:74
#define RAII_VAR(vartype, varname, initval, dtor)
Declare a variable that will call a destructor function when it goes out of scope.
Definition: utils.h:941
#define ast_str_create(init_len)
Create a malloc'ed dynamic length string.
Definition: strings.h:659
int ast_xmldoc_regenerate_doc_item ( struct ast_xml_doc_item item)

Regenerate the documentation for a particular item.

Parameters
itemThe documentation item to regenerate
Return values
-1on error
0on success
Since
12

Definition at line 2635 of file xmldoc.c.

References ast_xml_doc_item::arguments, ast_str_set(), ast_xml_free_attr(), ast_xml_get_attribute(), ast_xml_doc_item::description, ast_xml_doc_item::name, ast_xml_doc_item::node, ast_xml_doc_item::seealso, ast_xml_doc_item::synopsis, ast_xml_doc_item::syntax, and ast_xml_doc_item::type.

2636 {
2637  const char *name;
2638  char *syntax;
2639  char *seealso;
2640  char *arguments;
2641  char *synopsis;
2642  char *description;
2643 
2644  if (!item || !item->node) {
2645  return -1;
2646  }
2647 
2648  name = ast_xml_get_attribute(item->node, "name");
2649  if (!name) {
2650  return -1;
2651  }
2652 
2653  syntax = _ast_xmldoc_build_syntax(item->node, item->type, name);
2654  seealso = _ast_xmldoc_build_seealso(item->node);
2655  arguments = _ast_xmldoc_build_arguments(item->node);
2656  synopsis = _ast_xmldoc_build_synopsis(item->node);
2657  description = _ast_xmldoc_build_description(item->node);
2658 
2659  if (syntax) {
2660  ast_str_set(&item->syntax, 0, "%s", syntax);
2661  }
2662  if (seealso) {
2663  ast_str_set(&item->seealso, 0, "%s", seealso);
2664  }
2665  if (arguments) {
2666  ast_str_set(&item->arguments, 0, "%s", arguments);
2667  }
2668  if (synopsis) {
2669  ast_str_set(&item->synopsis, 0, "%s", synopsis);
2670  }
2671  if (description) {
2672  ast_str_set(&item->description, 0, "%s", description);
2673  }
2674 
2675  ast_free(syntax);
2676  ast_free(seealso);
2677  ast_free(arguments);
2678  ast_free(synopsis);
2679  ast_free(description);
2680  ast_xml_free_attr(name);
2681  return 0;
2682 }
struct ast_xml_node * node
Definition: xmldoc.h:78
const char * ast_xml_get_attribute(struct ast_xml_node *node, const char *attrname)
Get a node attribute by name.
Definition: xml.c:267
void ast_xml_free_attr(const char *attribute)
Free an attribute returned by ast_xml_get_attribute()
Definition: xml.c:253
int ast_str_set(struct ast_str **buf, ssize_t max_len, const char *fmt,...)
Set a dynamic string using variable arguments.
Definition: strings.h:1113
const ast_string_field type
Definition: xmldoc.h:74
struct ast_str * description
Definition: xmldoc.h:66
struct ast_str * arguments
Definition: xmldoc.h:62
struct ast_str * syntax
Definition: xmldoc.h:58
struct ast_str * seealso
Definition: xmldoc.h:60
struct ast_str * synopsis
Definition: xmldoc.h:64
static void xmldoc_purge_documentation ( void  )
static
Note
Must be called with xmldoc_tree locked

Definition at line 2896 of file xmldoc.c.

References ast_xml_close(), documentation_tree::doc, and documentation_tree::filename.

Referenced by xmldoc_unload_documentation().

2897 {
2898  struct documentation_tree *doctree;
2899 
2900  while ((doctree = AST_RWLIST_REMOVE_HEAD(&xmldoc_tree, entry))) {
2901  ast_free(doctree->filename);
2902  ast_xml_close(doctree->doc);
2903  ast_free(doctree);
2904  }
2905 }
XML documentation tree.
Definition: xmldoc.c:54
struct ast_xml_doc * doc
Definition: xmldoc.c:56
char * filename
Definition: xmldoc.c:55
void ast_xml_close(struct ast_xml_doc *doc)
Close an already open document and free the used structure.
Definition: xml.c:211
Definition: search.h:40
Container of documentation trees.
Definition: xmldoc.c:74

Variable Documentation

const struct strspecial_tags special_tags[]
static
Initial value:
= {
{ "note", "<note>NOTE:</note> ", "" },
{ "warning", "<warning>WARNING!!!:</warning> ", "" },
{ "example", "<example>Example:</example> ", "" },
}