Making sure we have references to external libraries.
[asterisk/asterisk.git] / main / xmldoc.c
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2008, Eliel C. Sardanons (LU1ALY) <eliels@gmail.com>
5  *
6  * See http://www.asterisk.org for more information about
7  * the Asterisk project. Please do not directly contact
8  * any of the maintainers of this project for assistance;
9  * the project provides a web site, mailing lists and IRC
10  * channels for your use.
11  *
12  * This program is free software, distributed under the terms of
13  * the GNU General Public License Version 2. See the LICENSE file
14  * at the top of the source tree.
15  */
16
17 /*! \file
18  *
19  * \brief XML Documentation API
20  *
21  * \author Eliel C. Sardanons (LU1ALY) <eliels@gmail.com>
22  *
23  * \extref libxml2 http://www.xmlsoft.org/
24  */
25
26 #include "asterisk.h"
27
28 ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
29
30 #include "asterisk/_private.h"
31 #include "asterisk/paths.h"
32 #include "asterisk/linkedlists.h"
33 #include "asterisk/strings.h"
34 #include "asterisk/config.h"
35 #include "asterisk/term.h"
36 #include "asterisk/xmldoc.h"
37
38 #ifdef AST_XML_DOCS
39
40 /*! \brief Default documentation language. */
41 static const char default_documentation_language[] = "en_US";
42
43 /*! \brief Number of columns to print when showing the XML documentation with a
44  *         'core show application/function *' CLI command. Used in text wrapping.*/
45 static const int xmldoc_text_columns = 74;
46
47 /*! \brief This is a value that we will use to let the wrapping mechanism move the cursor
48  *         backward and forward xmldoc_max_diff positions before cutting the middle of a
49  *         word, trying to find a space or a \n. */
50 static const int xmldoc_max_diff = 5;
51
52 /*! \brief XML documentation language. */
53 static char documentation_language[6];
54
55 /*! \brief XML documentation tree */
56 struct documentation_tree {
57         char *filename;                                 /*!< XML document filename. */
58         struct ast_xml_doc *doc;                        /*!< Open document pointer. */
59         AST_RWLIST_ENTRY(documentation_tree) entry;
60 };
61
62 static char *xmldoc_get_syntax_cmd(struct ast_xml_node *fixnode, const char *name, int printname);
63
64 /*!
65  * \brief Container of documentation trees
66  *
67  * \note A RWLIST is a sufficient container type to use here for now.
68  *       However, some changes will need to be made to implement ref counting
69  *       if reload support is added in the future.
70  */
71 static AST_RWLIST_HEAD_STATIC(xmldoc_tree, documentation_tree);
72
73 static const struct strcolorized_tags {
74         const char *init;      /*!< Replace initial tag with this string. */
75         const char *end;       /*!< Replace end tag with this string. */
76         const int colorfg;     /*!< Foreground color. */
77         const char *inittag;   /*!< Initial tag description. */
78         const char *endtag;    /*!< Ending tag description. */
79 } colorized_tags[] = {
80         { "<",  ">",  COLOR_GREEN,  "<replaceable>", "</replaceable>" },
81         { "\'", "\'", COLOR_BLUE,   "<literal>",     "</literal>" },
82         { "*",  "*",  COLOR_RED,    "<emphasis>",    "</emphasis>" },
83         { "\"", "\"", COLOR_YELLOW, "<filename>",    "</filename>" },
84         { "\"", "\"", COLOR_CYAN,   "<directory>",   "</directory>" },
85         { "${", "}",  COLOR_GREEN,  "<variable>",    "</variable>" },
86         { "",   "",   COLOR_BLUE,   "<value>",       "</value>" },
87         { "",   "",   COLOR_BLUE,   "<enum>",        "</enum>" },
88         { "\'", "\'", COLOR_GRAY,   "<astcli>",      "</astcli>" },
89
90         /* Special tags */
91         { "", "", COLOR_YELLOW, "<note>",   "</note>" },
92         { "", "", COLOR_RED,   "<warning>", "</warning>" }
93 };
94
95 static const struct strspecial_tags {
96         const char *tagname;            /*!< Special tag name. */
97         const char *init;               /*!< Print this at the beginning. */
98         const char *end;                /*!< Print this at the end. */
99 } special_tags[] = {
100         { "note",    "<note>NOTE:</note> ",             "" },
101         { "warning", "<warning>WARNING!!!:</warning> ", "" }
102 };
103
104 /*! \internal
105  *  \brief Calculate the space in bytes used by a format string
106  *         that will be passed to a sprintf function.
107  *  \param postbr The format string to use to calculate the length.
108  *  \retval The postbr length.
109  */
110 static int xmldoc_postbrlen(const char *postbr)
111 {
112         int postbrreallen = 0, i;
113         size_t postbrlen;
114
115         if (!postbr) {
116                 return 0;
117         }
118         postbrlen = strlen(postbr);
119         for (i = 0; i < postbrlen; i++) {
120                 if (postbr[i] == '\t') {
121                         postbrreallen += 8 - (postbrreallen % 8);
122                 } else {
123                         postbrreallen++;
124                 }
125         }
126         return postbrreallen;
127 }
128
129 /*! \internal
130  *  \brief Setup postbr to be used while wrapping the text.
131  *         Add to postbr array all the spaces and tabs at the beginning of text.
132  *  \param postbr output array.
133  *  \param len text array length.
134  *  \param text Text with format string before the actual string.
135  */
136 static void xmldoc_setpostbr(char *postbr, size_t len, const char *text)
137 {
138         int c, postbrlen = 0;
139
140         if (!text) {
141                 return;
142         }
143
144         for (c = 0; c < len; c++) {
145                 if (text[c] == '\t' || text[c] == ' ') {
146                         postbr[postbrlen++] = text[c];
147                 } else {
148                         break;
149                 }
150         }
151         postbr[postbrlen] = '\0';
152 }
153
154 /*! \internal
155  *  \brief Try to find a space or a break in text starting at currentpost
156  *         and moving at most maxdiff positions.
157  *         Helper for xmldoc_string_wrap().
158  *  \param text Input string where it will search.
159  *  \param currentpos Current position within text.
160  *  \param maxdiff Not move more than maxdiff inside text.
161  *  \retval 1 if a space or break is found inside text while moving.
162  *  \retval 0 if no space or break is found.
163  */
164 static int xmldoc_wait_nextspace(const char *text, int currentpos, int maxdiff)
165 {
166         int i, textlen;
167
168         if (!text) {
169                 return 0;
170         }
171
172         textlen = strlen(text);
173         for (i = currentpos; i < textlen; i++) {
174                 if (text[i] == ESC) {
175                         /* Move to the end of the escape sequence */
176                         while (i < textlen && text[i] != 'm') {
177                                 i++;
178                         }
179                 } else if (text[i] == ' ' || text[i] == '\n') {
180                         /* Found the next space or linefeed */
181                         return 1;
182                 } else if (i - currentpos > maxdiff) {
183                         /* We have looked the max distance and didn't find it */
184                         return 0;
185                 }
186         }
187
188         /* Reached the end and did not find it */
189
190         return 0;
191 }
192
193 /*! \internal
194  *  \brief Helper function for xmldoc_string_wrap().
195  *         Try to found a space or a break inside text moving backward
196  *         not more than maxdiff positions.
197  *  \param text The input string where to search for a space.
198  *  \param currentpos The current cursor position.
199  *  \param maxdiff The max number of positions to move within text.
200  *  \retval 0 If no space is found (Notice that text[currentpos] is not a space or a break)
201  *  \retval > 0 If a space or a break is found, and the result is the position relative to
202  *              currentpos.
203  */
204 static int xmldoc_foundspace_backward(const char *text, int currentpos, int maxdiff)
205 {
206         int i;
207
208         for (i = currentpos; i > 0; i--) {
209                 if (text[i] == ' ' || text[i] == '\n') {
210                         return (currentpos - i);
211                 } else if (text[i] == 'm' && (text[i - 1] >= '0' || text[i - 1] <= '9')) {
212                         /* give up, we found the end of a possible ESC sequence. */
213                         return 0;
214                 } else if (currentpos - i > maxdiff) {
215                         /* give up, we can't move anymore. */
216                         return 0;
217                 }
218         }
219
220         /* we found the beginning of the text */
221
222         return 0;
223 }
224
225 /*! \internal
226  *  \brief Justify a text to a number of columns.
227  *  \param text Input text to be justified.
228  *  \param columns Number of columns to preserve in the text.
229  *  \param maxdiff Try to not cut a word when goinf down.
230  *  \retval NULL on error.
231  *  \retval The wrapped text.
232  */
233 static char *xmldoc_string_wrap(const char *text, int columns, int maxdiff)
234 {
235         struct ast_str *tmp;
236         char *ret, postbr[160];
237         int count = 1, i, backspace, needtobreak = 0, colmax, textlen;
238
239         /* sanity check */
240         if (!text || columns <= 0 || maxdiff < 0) {
241                 ast_log(LOG_WARNING, "Passing wrong arguments while trying to wrap the text\n");
242                 return NULL;
243         }
244
245         tmp = ast_str_create(strlen(text) * 3);
246
247         if (!tmp) {
248                 return NULL;
249         }
250
251         /* Check for blanks and tabs and put them in postbr. */
252         xmldoc_setpostbr(postbr, sizeof(postbr), text);
253         colmax = columns - xmldoc_postbrlen(postbr);
254
255         textlen = strlen(text);
256         for (i = 0; i < textlen; i++) {
257                 if (needtobreak || !(count % colmax)) {
258                         if (text[i] == ' ') {
259                                 ast_str_append(&tmp, 0, "\n%s", postbr);
260                                 needtobreak = 0;
261                                 count = 1;
262                         } else if (text[i] != '\n') {
263                                 needtobreak = 1;
264                                 if (xmldoc_wait_nextspace(text, i, maxdiff)) {
265                                         /* wait for the next space */
266                                         ast_str_append(&tmp, 0, "%c", text[i]);
267                                         continue;
268                                 }
269                                 /* Try to look backwards */
270                                 backspace = xmldoc_foundspace_backward(text, i, maxdiff);
271                                 if (backspace) {
272                                         needtobreak = 1;
273                                         ast_str_truncate(tmp, -backspace);
274                                         i -= backspace + 1;
275                                         continue;
276                                 }
277                                 ast_str_append(&tmp, 0, "\n%s", postbr);
278                                 needtobreak = 0;
279                                 count = 1;
280                         }
281                         /* skip blanks after a \n */
282                         while (text[i] == ' ') {
283                                 i++;
284                         }
285                 }
286                 if (text[i] == '\n') {
287                         xmldoc_setpostbr(postbr, sizeof(postbr), &text[i] + 1);
288                         colmax = columns - xmldoc_postbrlen(postbr);
289                         needtobreak = 0;
290                         count = 1;
291                 }
292                 if (text[i] == ESC) {
293                         /* Ignore Escape sequences. */
294                         do {
295                                 ast_str_append(&tmp, 0, "%c", text[i]);
296                                 i++;
297                         } while (i < textlen && text[i] != 'm');
298                 } else {
299                         count++;
300                 }
301                 ast_str_append(&tmp, 0, "%c", text[i]);
302         }
303
304         ret = ast_strdup(ast_str_buffer(tmp));
305         ast_free(tmp);
306
307         return ret;
308 }
309
310 char *ast_xmldoc_printable(const char *bwinput, int withcolors)
311 {
312         struct ast_str *colorized;
313         char *wrapped = NULL;
314         int i, c, len, colorsection;
315         char *tmp;
316         size_t bwinputlen;
317         static const int base_fg = COLOR_CYAN;
318
319         if (!bwinput) {
320                 return NULL;
321         }
322
323         bwinputlen = strlen(bwinput);
324
325         if (!(colorized = ast_str_create(256))) {
326                 return NULL;
327         }
328
329         if (withcolors) {
330                 ast_term_color_code(&colorized, base_fg, 0);
331                 if (!colorized) {
332                         return NULL;
333                 }
334         }
335
336         for (i = 0; i < bwinputlen; i++) {
337                 colorsection = 0;
338                 /* Check if we are at the beginning of a tag to be colorized. */
339                 for (c = 0; c < ARRAY_LEN(colorized_tags); c++) {
340                         if (strncasecmp(bwinput + i, colorized_tags[c].inittag, strlen(colorized_tags[c].inittag))) {
341                                 continue;
342                         }
343
344                         if (!(tmp = strcasestr(bwinput + i + strlen(colorized_tags[c].inittag), colorized_tags[c].endtag))) {
345                                 continue;
346                         }
347
348                         len = tmp - (bwinput + i + strlen(colorized_tags[c].inittag));
349
350                         /* Setup color */
351                         if (withcolors) {
352                                 ast_term_color_code(&colorized, colorized_tags[c].colorfg, 0);
353                                 if (!colorized) {
354                                         return NULL;
355                                 }
356                         }
357
358                         /* copy initial string replace */
359                         ast_str_append(&colorized, 0, "%s", colorized_tags[c].init);
360                         if (!colorized) {
361                                 return NULL;
362                         }
363                         {
364                                 char buf[len + 1];
365                                 ast_copy_string(buf, bwinput + i + strlen(colorized_tags[c].inittag), sizeof(buf));
366                                 ast_str_append(&colorized, 0, "%s", buf);
367                         }
368                         if (!colorized) {
369                                 return NULL;
370                         }
371
372                         /* copy the ending string replace */
373                         ast_str_append(&colorized, 0, "%s", colorized_tags[c].end);
374                         if (!colorized) {
375                                 return NULL;
376                         }
377
378                         /* Continue with the last color. */
379                         if (withcolors) {
380                                 ast_term_color_code(&colorized, base_fg, 0);
381                                 if (!colorized) {
382                                         return NULL;
383                                 }
384                         }
385
386                         i += len + strlen(colorized_tags[c].endtag) + strlen(colorized_tags[c].inittag) - 1;
387                         colorsection = 1;
388                         break;
389                 }
390
391                 if (!colorsection) {
392                         ast_str_append(&colorized, 0, "%c", bwinput[i]);
393                         if (!colorized) {
394                                 return NULL;
395                         }
396                 }
397         }
398
399         if (withcolors) {
400                 ast_term_color_code(&colorized, COLOR_BRWHITE, 0);
401                 if (!colorized) {
402                         return NULL;
403                 }
404         }
405
406         /* Wrap the text, notice that string wrap will avoid cutting an ESC sequence. */
407         wrapped = xmldoc_string_wrap(ast_str_buffer(colorized), xmldoc_text_columns, xmldoc_max_diff);
408
409         ast_free(colorized);
410
411         return wrapped;
412 }
413
414 /*! \internal
415  *  \brief Cleanup spaces and tabs after a \n
416  *  \param text String to be cleaned up.
417  *  \param output buffer (not already allocated).
418  *  \param lastspaces Remove last spaces in the string.
419  */
420 static void xmldoc_string_cleanup(const char *text, struct ast_str **output, int lastspaces)
421 {
422         int i;
423         size_t textlen;
424
425         if (!text) {
426                 *output = NULL;
427                 return;
428         }
429
430         textlen = strlen(text);
431
432         *output = ast_str_create(textlen);
433         if (!(*output)) {
434                 ast_log(LOG_ERROR, "Problem allocating output buffer\n");
435                 return;
436         }
437
438         for (i = 0; i < textlen; i++) {
439                 if (text[i] == '\n' || text[i] == '\r') {
440                         /* remove spaces/tabs/\n after a \n. */
441                         while (text[i + 1] == '\t' || text[i + 1] == '\r' || text[i + 1] == '\n') {
442                                 i++;
443                         }
444                         ast_str_append(output, 0, " ");
445                         continue;
446                 } else {
447                         ast_str_append(output, 0, "%c", text[i]);
448                 }
449         }
450
451         /* remove last spaces (we dont want always to remove the trailing spaces). */
452         if (lastspaces) {
453                 ast_str_trim_blanks(*output);
454         }
455 }
456
457 /*! \internal
458  *  \brief Get the application/function node for 'name' application/function with language 'language'
459  *         if we don't find any, get the first application with 'name' no matter which language with.
460  *  \param type 'application', 'function', ...
461  *  \param name Application or Function name.
462  *  \param language Try to get this language (if not found try with en_US)
463  *  \retval NULL on error.
464  *  \retval A node of type ast_xml_node.
465  */
466 static struct ast_xml_node *xmldoc_get_node(const char *type, const char *name, const char *language)
467 {
468         struct ast_xml_node *node = NULL;
469         struct documentation_tree *doctree;
470         const char *lang;
471
472         AST_RWLIST_RDLOCK(&xmldoc_tree);
473         AST_LIST_TRAVERSE(&xmldoc_tree, doctree, entry) {
474                 /* the core xml documents have priority over thirdparty document. */
475                 node = ast_xml_get_root(doctree->doc);
476                 while ((node = ast_xml_find_element(node, type, "name", name))) {
477                         /* Check language */
478                         lang = ast_xml_get_attribute(node, "language");
479                         if (lang && !strcmp(lang, language)) {
480                                 ast_xml_free_attr(lang);
481                                 break;
482                         } else if (lang) {
483                                 ast_xml_free_attr(lang);
484                         }
485                 }
486
487                 if (node && ast_xml_node_get_children(node)) {
488                         break;
489                 }
490
491                 /* We didn't find the application documentation for the specified language,
492                 so, try to load documentation for any language */
493                 node = ast_xml_get_root(doctree->doc);
494                 if (ast_xml_node_get_children(node)) {
495                         if ((node = ast_xml_find_element(ast_xml_node_get_children(node), type, "name", name))) {
496                                 break;
497                         }
498                 }
499         }
500         AST_RWLIST_UNLOCK(&xmldoc_tree);
501
502         return node;
503 }
504
505 /*! \internal
506  *  \brief Helper function used to build the syntax, it allocates the needed buffer (or reallocates it),
507  *         and based on the reverse value it makes use of fmt to print the parameter list inside the
508  *         realloced buffer (syntax).
509  *  \param reverse We are going backwards while generating the syntax?
510  *  \param len Current length of 'syntax' buffer.
511  *  \param syntax Output buffer for the concatenated values.
512  *  \param fmt A format string that will be used in a sprintf call.
513  */
514 static void __attribute__((format(printf, 4, 5))) xmldoc_reverse_helper(int reverse, int *len, char **syntax, const char *fmt, ...)
515 {
516         int totlen, tmpfmtlen;
517         char *tmpfmt, tmp;
518         va_list ap;
519
520         va_start(ap, fmt);
521         if (ast_vasprintf(&tmpfmt, fmt, ap) < 0) {
522                 va_end(ap);
523                 return;
524         }
525         va_end(ap);
526
527         tmpfmtlen = strlen(tmpfmt);
528         totlen = *len + tmpfmtlen + 1;
529
530         *syntax = ast_realloc(*syntax, totlen);
531
532         if (!*syntax) {
533                 ast_free(tmpfmt);
534                 return;
535         }
536
537         if (reverse) {
538                 memmove(*syntax + tmpfmtlen, *syntax, *len);
539                 /* Save this char, it will be overwritten by the \0 of strcpy. */
540                 tmp = (*syntax)[0];
541                 strcpy(*syntax, tmpfmt);
542                 /* Restore the already saved char. */
543                 (*syntax)[tmpfmtlen] = tmp;
544                 (*syntax)[totlen - 1] = '\0';
545         } else {
546                 strcpy(*syntax + *len, tmpfmt);
547         }
548
549         *len = totlen - 1;
550         ast_free(tmpfmt);
551 }
552
553 /*! \internal
554  *  \brief Check if the passed node has 'what' tags inside it.
555  *  \param node Root node to search 'what' elements.
556  *  \param what node name to search inside node.
557  *  \retval 1 If a 'what' element is found inside 'node'.
558  *  \retval 0 If no 'what' is found inside 'node'.
559  */
560 static int xmldoc_has_inside(struct ast_xml_node *fixnode, const char *what)
561 {
562         struct ast_xml_node *node = fixnode;
563
564         for (node = ast_xml_node_get_children(fixnode); node; node = ast_xml_node_get_next(node)) {
565                 if (!strcasecmp(ast_xml_node_get_name(node), what)) {
566                         return 1;
567                 }
568         }
569         return 0;
570 }
571
572 /*! \internal
573  *  \brief Check if the passed node has at least one node inside it.
574  *  \param node Root node to search node elements.
575  *  \retval 1 If a node element is found inside 'node'.
576  *  \retval 0 If no node is found inside 'node'.
577  */
578 static int xmldoc_has_nodes(struct ast_xml_node *fixnode)
579 {
580         struct ast_xml_node *node = fixnode;
581
582         for (node = ast_xml_node_get_children(fixnode); node; node = ast_xml_node_get_next(node)) {
583                 if (strcasecmp(ast_xml_node_get_name(node), "text")) {
584                         return 1;
585                 }
586         }
587         return 0;
588 }
589
590 /*! \internal
591  *  \brief Check if the passed node has at least one specialtag.
592  *  \param node Root node to search "specialtags" elements.
593  *  \retval 1 If a "specialtag" element is found inside 'node'.
594  *  \retval 0 If no "specialtag" is found inside 'node'.
595  */
596 static int xmldoc_has_specialtags(struct ast_xml_node *fixnode)
597 {
598         struct ast_xml_node *node = fixnode;
599         int i;
600
601         for (node = ast_xml_node_get_children(fixnode); node; node = ast_xml_node_get_next(node)) {
602                 for (i = 0; i < ARRAY_LEN(special_tags); i++) {
603                         if (!strcasecmp(ast_xml_node_get_name(node), special_tags[i].tagname)) {
604                                 return 1;
605                         }
606                 }
607         }
608         return 0;
609 }
610
611 /*! \internal
612  *  \brief Build the syntax for a specified starting node.
613  *  \param rootnode A pointer to the ast_xml root node.
614  *  \param rootname Name of the application, function, option, etc. to build the syntax.
615  *  \param childname The name of each parameter node.
616  *  \param printparenthesis Boolean if we must print parenthesis if not parameters are found in the rootnode.
617  *  \param printrootname Boolean if we must print the rootname before the syntax and parenthesis at the begining/end.
618  *  \retval NULL on error.
619  *  \retval An ast_malloc'ed string with the syntax generated.
620  */
621 static char *xmldoc_get_syntax_fun(struct ast_xml_node *rootnode, const char *rootname, const char *childname, int printparenthesis, int printrootname)
622 {
623 #define GOTONEXT(__rev, __a) (__rev ? ast_xml_node_get_prev(__a) : ast_xml_node_get_next(__a))
624 #define ISLAST(__rev, __a)  (__rev == 1 ? (ast_xml_node_get_prev(__a) ? 0 : 1) : (ast_xml_node_get_next(__a) ? 0 : 1))
625 #define MP(__a) ((multiple ? __a : ""))
626         struct ast_xml_node *node = NULL, *firstparam = NULL, *lastparam = NULL;
627         const char *paramtype, *multipletype, *paramnameattr, *attrargsep, *parenthesis, *argname;
628         int reverse, required, paramcount = 0, openbrackets = 0, len = 0, hasparams=0;
629         int reqfinode = 0, reqlanode = 0, optmidnode = 0, prnparenthesis, multiple;
630         char *syntax = NULL, *argsep, *paramname;
631
632         if (ast_strlen_zero(rootname) || ast_strlen_zero(childname)) {
633                 ast_log(LOG_WARNING, "Tried to look in XML tree with faulty rootname or childname while creating a syntax.\n");
634                 return NULL;
635         }
636
637         if (!rootnode || !ast_xml_node_get_children(rootnode)) {
638                 /* If the rootnode field is not found, at least print name. */
639                 ast_asprintf(&syntax, "%s%s", (printrootname ? rootname : ""), (printparenthesis ? "()" : ""));
640                 return syntax;
641         }
642
643         /* Get the argument separator from the root node attribute name 'argsep', if not found
644         defaults to ','. */
645         attrargsep = ast_xml_get_attribute(rootnode, "argsep");
646         if (attrargsep) {
647                 argsep = ast_strdupa(attrargsep);
648                 ast_xml_free_attr(attrargsep);
649         } else {
650                 argsep = ast_strdupa(",");
651         }
652
653         /* Get order of evaluation. */
654         for (node = ast_xml_node_get_children(rootnode); node; node = ast_xml_node_get_next(node)) {
655                 if (strcasecmp(ast_xml_node_get_name(node), childname)) {
656                         continue;
657                 }
658                 required = 0;
659                 hasparams = 1;
660                 if ((paramtype = ast_xml_get_attribute(node, "required"))) {
661                         if (ast_true(paramtype)) {
662                                 required = 1;
663                         }
664                         ast_xml_free_attr(paramtype);
665                 }
666
667                 lastparam = node;
668                 reqlanode = required;
669
670                 if (!firstparam) {
671                         /* first parameter node */
672                         firstparam = node;
673                         reqfinode = required;
674                 }
675         }
676
677         if (!hasparams) {
678                 /* This application, function, option, etc, doesn't have any params. */
679                 ast_asprintf(&syntax, "%s%s", (printrootname ? rootname : ""), (printparenthesis ? "()" : ""));
680                 return syntax;
681         }
682
683         if (reqfinode && reqlanode) {
684                 /* check midnode */
685                 for (node = ast_xml_node_get_children(rootnode); node; node = ast_xml_node_get_next(node)) {
686                         if (strcasecmp(ast_xml_node_get_name(node), childname)) {
687                                 continue;
688                         }
689                         if (node != firstparam && node != lastparam) {
690                                 if ((paramtype = ast_xml_get_attribute(node, "required"))) {
691                                         if (!ast_true(paramtype)) {
692                                                 optmidnode = 1;
693                                                 break;
694                                         }
695                                         ast_xml_free_attr(paramtype);
696                                 }
697                         }
698                 }
699         }
700
701         if ((!reqfinode && reqlanode) || (reqfinode && reqlanode && optmidnode)) {
702                 reverse = 1;
703                 node = lastparam;
704         } else {
705                 reverse = 0;
706                 node = firstparam;
707         }
708
709         /* init syntax string. */
710         if (reverse) {
711                 xmldoc_reverse_helper(reverse, &len, &syntax,
712                         (printrootname ? (printrootname == 2 ? ")]" : ")"): ""));
713         } else {
714                 xmldoc_reverse_helper(reverse, &len, &syntax, "%s%s", (printrootname ? rootname : ""),
715                         (printrootname ? (printrootname == 2 ? "[(" : "(") : ""));
716         }
717
718         for (; node; node = GOTONEXT(reverse, node)) {
719                 if (strcasecmp(ast_xml_node_get_name(node), childname)) {
720                         continue;
721                 }
722
723                 /* Get the argument name, if it is not the leaf, go inside that parameter. */
724                 if (xmldoc_has_inside(node, "argument")) {
725                         parenthesis = ast_xml_get_attribute(node, "hasparams");
726                         prnparenthesis = 0;
727                         if (parenthesis) {
728                                 prnparenthesis = ast_true(parenthesis);
729                                 if (!strcasecmp(parenthesis, "optional")) {
730                                         prnparenthesis = 2;
731                                 }
732                                 ast_xml_free_attr(parenthesis);
733                         }
734                         argname = ast_xml_get_attribute(node, "name");
735                         if (argname) {
736                                 paramname = xmldoc_get_syntax_fun(node, argname, "argument", prnparenthesis, prnparenthesis);
737                                 ast_xml_free_attr(argname);
738                         } else {
739                                 /* Malformed XML, print **UNKOWN** */
740                                 paramname = ast_strdup("**unknown**");
741                         }
742                 } else {
743                         paramnameattr = ast_xml_get_attribute(node, "name");
744                         if (!paramnameattr) {
745                                 ast_log(LOG_WARNING, "Malformed XML %s: no %s name\n", rootname, childname);
746                                 if (syntax) {
747                                         /* Free already allocated syntax */
748                                         ast_free(syntax);
749                                 }
750                                 /* to give up is ok? */
751                                 ast_asprintf(&syntax, "%s%s", (printrootname ? rootname : ""), (printparenthesis ? "()" : ""));
752                                 return syntax;
753                         }
754                         paramname = ast_strdup(paramnameattr);
755                         ast_xml_free_attr(paramnameattr);
756                 }
757
758                 /* Defaults to 'false'. */
759                 multiple = 0;
760                 if ((multipletype = ast_xml_get_attribute(node, "multiple"))) {
761                         if (ast_true(multipletype)) {
762                                 multiple = 1;
763                         }
764                         ast_xml_free_attr(multipletype);
765                 }
766
767                 required = 0;   /* Defaults to 'false'. */
768                 if ((paramtype = ast_xml_get_attribute(node, "required"))) {
769                         if (ast_true(paramtype)) {
770                                 required = 1;
771                         }
772                         ast_xml_free_attr(paramtype);
773                 }
774
775                 /* build syntax core. */
776
777                 if (required) {
778                         /* First parameter */
779                         if (!paramcount) {
780                                 xmldoc_reverse_helper(reverse, &len, &syntax, "%s%s%s%s", paramname, MP("["), MP(argsep), MP("...]"));
781                         } else {
782                                 /* Time to close open brackets. */
783                                 while (openbrackets > 0) {
784                                         xmldoc_reverse_helper(reverse, &len, &syntax, (reverse ? "[" : "]"));
785                                         openbrackets--;
786                                 }
787                                 if (reverse) {
788                                         xmldoc_reverse_helper(reverse, &len, &syntax, "%s%s", paramname, argsep);
789                                 } else {
790                                         xmldoc_reverse_helper(reverse, &len, &syntax, "%s%s", argsep, paramname);
791                                 }
792                                 xmldoc_reverse_helper(reverse, &len, &syntax, "%s%s%s", MP("["), MP(argsep), MP("...]"));
793                         }
794                 } else {
795                         /* First parameter */
796                         if (!paramcount) {
797                                 xmldoc_reverse_helper(reverse, &len, &syntax, "[%s%s%s%s]", paramname, MP("["), MP(argsep), MP("...]"));
798                         } else {
799                                 if (ISLAST(reverse, node)) {
800                                         /* This is the last parameter. */
801                                         if (reverse) {
802                                                 xmldoc_reverse_helper(reverse, &len, &syntax, "[%s%s%s%s]%s", paramname,
803                                                                         MP("["), MP(argsep), MP("...]"), argsep);
804                                         } else {
805                                                 xmldoc_reverse_helper(reverse, &len, &syntax, "%s[%s%s%s%s]", argsep, paramname,
806                                                                         MP("["), MP(argsep), MP("...]"));
807                                         }
808                                 } else {
809                                         if (reverse) {
810                                                 xmldoc_reverse_helper(reverse, &len, &syntax, "%s%s%s%s%s]", paramname, argsep,
811                                                                         MP("["), MP(argsep), MP("...]"));
812                                         } else {
813                                                 xmldoc_reverse_helper(reverse, &len, &syntax, "[%s%s%s%s%s", argsep, paramname,
814                                                                         MP("["), MP(argsep), MP("...]"));
815                                         }
816                                         openbrackets++;
817                                 }
818                         }
819                 }
820                 ast_free(paramname);
821
822                 paramcount++;
823         }
824
825         /* Time to close open brackets. */
826         while (openbrackets > 0) {
827                 xmldoc_reverse_helper(reverse, &len, &syntax, (reverse ? "[" : "]"));
828                 openbrackets--;
829         }
830
831         /* close syntax string. */
832         if (reverse) {
833                 xmldoc_reverse_helper(reverse, &len, &syntax, "%s%s", (printrootname ? rootname : ""),
834                         (printrootname ? (printrootname == 2 ? "[(" : "(") : ""));
835         } else {
836                 xmldoc_reverse_helper(reverse, &len, &syntax, (printrootname ? (printrootname == 2 ? ")]" : ")") : ""));
837         }
838
839         return syntax;
840 #undef ISLAST
841 #undef GOTONEXT
842 #undef MP
843 }
844
845 /*! \internal
846  *  \brief Parse an enumlist inside a <parameter> to generate a COMMAND
847  *         syntax.
848  *  \param fixnode A pointer to the <enumlist> node.
849  *  \retval {<unknown>} on error.
850  *  \retval A string inside brackets {} with the enum's separated by pipes |.
851  */
852 static char *xmldoc_parse_cmd_enumlist(struct ast_xml_node *fixnode)
853 {
854         struct ast_xml_node *node = fixnode;
855         struct ast_str *paramname;
856         char *enumname, *ret;
857         int first = 1;
858
859         paramname = ast_str_create(128);
860         if (!paramname) {
861                 return ast_strdup("{<unkown>}");
862         }
863
864         ast_str_append(&paramname, 0, "{");
865
866         for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
867                 if (strcasecmp(ast_xml_node_get_name(node), "enum")) {
868                         continue;
869                 }
870
871                 enumname = xmldoc_get_syntax_cmd(node, "", 0);
872                 if (!enumname) {
873                         continue;
874                 }
875                 if (!first) {
876                         ast_str_append(&paramname, 0, "|");
877                 }
878                 ast_str_append(&paramname, 0, "%s", enumname);
879                 first = 0;
880                 ast_free(enumname);
881         }
882
883         ast_str_append(&paramname, 0, "}");
884
885         ret = ast_strdup(ast_str_buffer(paramname));
886         ast_free(paramname);
887
888         return ret;
889 }
890
891 /*! \internal
892  *  \brief Generate a syntax of COMMAND type.
893  *  \param fixnode The <syntax> node pointer.
894  *  \param name The name of the 'command'.
895  *  \param printname Print the name of the command before the paramters?
896  *  \retval On error, return just 'name'.
897  *  \retval On success return the generated syntax.
898  */
899 static char *xmldoc_get_syntax_cmd(struct ast_xml_node *fixnode, const char *name, int printname)
900 {
901         struct ast_str *syntax;
902         struct ast_xml_node *tmpnode, *node = fixnode;
903         char *ret, *paramname;
904         const char *paramtype, *attrname, *literal;
905         int required, isenum, first = 1, isliteral;
906
907         syntax = ast_str_create(128);
908         if (!syntax) {
909                 /* at least try to return something... */
910                 return ast_strdup(name);
911         }
912
913         /* append name to output string. */
914         if (printname) {
915                 ast_str_append(&syntax, 0, "%s", name);
916                 first = 0;
917         }
918
919         for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
920                 if (strcasecmp(ast_xml_node_get_name(node), "parameter")) {
921                         continue;
922                 }
923
924                 if (xmldoc_has_inside(node, "parameter")) {
925                         /* is this a recursive parameter. */
926                         paramname = xmldoc_get_syntax_cmd(node, "", 0);
927                         isenum = 1;
928                 } else if (!xmldoc_has_inside(node, "enumlist")) {
929                         /* this is a simple parameter. */
930                         attrname = ast_xml_get_attribute(node, "name");
931                         if (!attrname) {
932                                 /* ignore this bogus parameter and continue. */
933                                 continue;
934                         }
935                         paramname = ast_strdup(attrname);
936                         ast_xml_free_attr(attrname);
937                         isenum = 0;
938                 } else {
939                         /* parse enumlist (note that this is a special enumlist
940                         that is used to describe a syntax like {<param1>|<param2>|...} */
941                         for (tmpnode = ast_xml_node_get_children(node); tmpnode; tmpnode = ast_xml_node_get_next(tmpnode)) {
942                                 if (!strcasecmp(ast_xml_node_get_name(tmpnode), "enumlist")) {
943                                         break;
944                                 }
945                         }
946                         paramname = xmldoc_parse_cmd_enumlist(tmpnode);
947                         isenum = 1;
948                 }
949
950                 /* Is this parameter required? */
951                 required = 0;
952                 paramtype = ast_xml_get_attribute(node, "required");
953                 if (paramtype) {
954                         required = ast_true(paramtype);
955                         ast_xml_free_attr(paramtype);
956                 }
957
958                 /* Is this a replaceable value or a fixed parameter value? */
959                 isliteral = 0;
960                 literal = ast_xml_get_attribute(node, "literal");
961                 if (literal) {
962                         isliteral = ast_true(literal);
963                         ast_xml_free_attr(literal);
964                 }
965
966                 /* if required="false" print with [...].
967                  * if literal="true" or is enum print without <..>.
968                  * if not first print a space at the beginning.
969                  */
970                 ast_str_append(&syntax, 0, "%s%s%s%s%s%s",
971                                 (first ? "" : " "),
972                                 (required ? "" : "["),
973                                 (isenum || isliteral ? "" : "<"),
974                                 paramname,
975                                 (isenum || isliteral ? "" : ">"),
976                                 (required ? "" : "]"));
977                 first = 0;
978                 ast_free(paramname);
979         }
980
981         /* return a common string. */
982         ret = ast_strdup(ast_str_buffer(syntax));
983         ast_free(syntax);
984
985         return ret;
986 }
987
988 /*! \brief Types of syntax that we are able to generate. */
989 enum syntaxtype {
990         FUNCTION_SYNTAX,
991         COMMAND_SYNTAX
992 };
993
994 /*! \brief Mapping between type of node and type of syntax to generate. */
995 struct strsyntaxtype {
996         const char *type;
997         enum syntaxtype stxtype;
998 } stxtype[] = {
999         { "function",           FUNCTION_SYNTAX },
1000         { "application",        FUNCTION_SYNTAX },
1001         { "agi",                COMMAND_SYNTAX  }
1002 };
1003
1004 /*! \internal
1005  *  \brief Get syntax type based on type of node.
1006  *  \param type Type of node.
1007  *  \retval The type of syntax to generate based on the type of node.
1008  */
1009 static enum syntaxtype xmldoc_get_syntax_type(const char *type)
1010 {
1011         int i;
1012         for (i=0; i < ARRAY_LEN(stxtype); i++) {
1013                 if (!strcasecmp(stxtype[i].type, type)) {
1014                         return stxtype[i].stxtype;
1015                 }
1016         }
1017
1018         return FUNCTION_SYNTAX;
1019 }
1020
1021 char *ast_xmldoc_build_syntax(const char *type, const char *name)
1022 {
1023         struct ast_xml_node *node;
1024         char *syntax = NULL;
1025
1026         node = xmldoc_get_node(type, name, documentation_language);
1027         if (!node) {
1028                 return NULL;
1029         }
1030
1031         for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
1032                 if (!strcasecmp(ast_xml_node_get_name(node), "syntax")) {
1033                         break;
1034                 }
1035         }
1036
1037         if (node) {
1038                 if (xmldoc_get_syntax_type(type) == FUNCTION_SYNTAX) {
1039                         syntax = xmldoc_get_syntax_fun(node, name, "parameter", 1, 1);
1040                 } else {
1041                         syntax = xmldoc_get_syntax_cmd(node, name, 1);
1042                 }
1043         }
1044         return syntax;
1045 }
1046
1047 /*! \internal
1048  *  \brief Parse a <para> element.
1049  *  \param node The <para> element pointer.
1050  *  \param tabs Added this string before the content of the <para> element.
1051  *  \param posttabs Added this string after the content of the <para> element.
1052  *  \param buffer This must be an already allocated ast_str. It will be used
1053  *         to store the result (if already has something it will be appended to the current
1054  *         string).
1055  *  \retval 1 If 'node' is a named 'para'.
1056  *  \retval 2 If data is appended in buffer.
1057  *  \retval 0 on error.
1058  */
1059 static int xmldoc_parse_para(struct ast_xml_node *node, const char *tabs, const char *posttabs, struct ast_str **buffer)
1060 {
1061         const char *tmptext;
1062         struct ast_xml_node *tmp;
1063         int ret = 0;
1064         struct ast_str *tmpstr;
1065
1066         if (!node || !ast_xml_node_get_children(node)) {
1067                 return ret;
1068         }
1069
1070         if (strcasecmp(ast_xml_node_get_name(node), "para")) {
1071                 return ret;
1072         }
1073
1074         ast_str_append(buffer, 0, "%s", tabs);
1075
1076         ret = 1;
1077
1078         for (tmp = ast_xml_node_get_children(node); tmp; tmp = ast_xml_node_get_next(tmp)) {
1079                 /* Get the text inside the <para> element and append it to buffer. */
1080                 tmptext = ast_xml_get_text(tmp);
1081                 if (tmptext) {
1082                         /* Strip \n etc. */
1083                         xmldoc_string_cleanup(tmptext, &tmpstr, 0);
1084                         ast_xml_free_text(tmptext);
1085                         if (tmpstr) {
1086                                 if (strcasecmp(ast_xml_node_get_name(tmp), "text")) {
1087                                         ast_str_append(buffer, 0, "<%s>%s</%s>", ast_xml_node_get_name(tmp),
1088                                                         ast_str_buffer(tmpstr), ast_xml_node_get_name(tmp));
1089                                 } else {
1090                                         ast_str_append(buffer, 0, "%s", ast_str_buffer(tmpstr));
1091                                 }
1092                                 ast_free(tmpstr);
1093                                 ret = 2;
1094                         }
1095                 }
1096         }
1097
1098         ast_str_append(buffer, 0, "%s", posttabs);
1099
1100         return ret;
1101 }
1102
1103 /*! \internal
1104  *  \brief Parse special elements defined in 'struct special_tags' special elements must have a <para> element inside them.
1105  *  \param fixnode special tag node pointer.
1106  *  \param tabs put tabs before printing the node content.
1107  *  \param posttabs put posttabs after printing node content.
1108  *  \param buffer Output buffer, the special tags will be appended here.
1109  *  \retval 0 if no special element is parsed.
1110  *  \retval 1 if a special element is parsed (data is appended to buffer).
1111  *  \retval 2 if a special element is parsed and also a <para> element is parsed inside the specialtag.
1112  */
1113 static int xmldoc_parse_specialtags(struct ast_xml_node *fixnode, const char *tabs, const char *posttabs, struct ast_str **buffer)
1114 {
1115         struct ast_xml_node *node = fixnode;
1116         int ret = 0, i, count = 0;
1117
1118         if (!node || !ast_xml_node_get_children(node)) {
1119                 return ret;
1120         }
1121
1122         for (i = 0; i < ARRAY_LEN(special_tags); i++) {
1123                 if (strcasecmp(ast_xml_node_get_name(node), special_tags[i].tagname)) {
1124                         continue;
1125                 }
1126
1127                 ret = 1;
1128                 /* This is a special tag. */
1129
1130                 /* concat data */
1131                 if (!ast_strlen_zero(special_tags[i].init)) {
1132                         ast_str_append(buffer, 0, "%s%s", tabs, special_tags[i].init);
1133                 }
1134
1135                 /* parse <para> elements inside special tags. */
1136                 for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
1137                         /* first <para> just print it without tabs at the begining. */
1138                         if (xmldoc_parse_para(node, (!count ? "" : tabs), posttabs, buffer) == 2) {
1139                                 ret = 2;
1140                         }
1141                 }
1142
1143                 if (!ast_strlen_zero(special_tags[i].end)) {
1144                         ast_str_append(buffer, 0, "%s%s", special_tags[i].end, posttabs);
1145                 }
1146
1147                 break;
1148         }
1149
1150         return ret;
1151 }
1152
1153 /*! \internal
1154  *  \brief Parse an <argument> element from the xml documentation.
1155  *  \param fixnode Pointer to the 'argument' xml node.
1156  *  \param insideparameter If we are parsing an <argument> inside a <parameter>.
1157  *  \param paramtabs pre tabs if we are inside a parameter element.
1158  *  \param tabs What to be printed before the argument name.
1159  *  \param buffer Output buffer to put values found inside the <argument> element.
1160  *  \retval 1 If there is content inside the argument.
1161  *  \retval 0 If the argument element is not parsed, or there is no content inside it.
1162  */
1163 static int xmldoc_parse_argument(struct ast_xml_node *fixnode, int insideparameter, const char *paramtabs, const char *tabs, struct ast_str **buffer)
1164 {
1165         struct ast_xml_node *node = fixnode;
1166         const char *argname;
1167         int count = 0, ret = 0;
1168
1169         if (!node || !ast_xml_node_get_children(node)) {
1170                 return ret;
1171         }
1172
1173         /* Print the argument names */
1174         argname = ast_xml_get_attribute(node, "name");
1175         if (!argname) {
1176                 return 0;
1177         }
1178         if (xmldoc_has_inside(node, "para") || xmldoc_has_specialtags(node)) {
1179                 ast_str_append(buffer, 0, "%s%s%s", tabs, argname, (insideparameter ? "\n" : ""));
1180                 ast_xml_free_attr(argname);
1181         } else {
1182                 ast_xml_free_attr(argname);
1183                 return 0;
1184         }
1185
1186         for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
1187                 if (xmldoc_parse_para(node, (insideparameter ? paramtabs : (!count ? " - " : tabs)), "\n", buffer) == 2) {
1188                         count++;
1189                         ret = 1;
1190                 } else if (xmldoc_parse_specialtags(node, (insideparameter ? paramtabs : (!count ? " - " : tabs)), "\n", buffer) == 2) {
1191                         count++;
1192                         ret = 1;
1193                 }
1194         }
1195
1196         return ret;
1197 }
1198
1199 /*! \internal
1200  *  \brief Parse a <variable> node inside a <variablelist> node.
1201  *  \param node The variable node to parse.
1202  *  \param tabs A string to be appended at the begining of the output that will be stored
1203  *         in buffer.
1204  *  \param buffer This must be an already created ast_str. It will be used
1205  *         to store the result (if already has something it will be appended to the current
1206  *         string).
1207  *  \retval 0 if no data is appended.
1208  *  \retval 1 if data is appended.
1209  */
1210 static int xmldoc_parse_variable(struct ast_xml_node *node, const char *tabs, struct ast_str **buffer)
1211 {
1212         struct ast_xml_node *tmp;
1213         const char *valname;
1214         const char *tmptext;
1215         struct ast_str *cleanstr;
1216         int ret = 0, printedpara=0;
1217
1218         for (tmp = ast_xml_node_get_children(node); tmp; tmp = ast_xml_node_get_next(tmp)) {
1219                 if (xmldoc_parse_para(tmp, (ret ? tabs : ""), "\n", buffer)) {
1220                         printedpara = 1;
1221                         continue;
1222                 } else if (xmldoc_parse_specialtags(tmp, (ret ? tabs : ""), "\n", buffer)) {
1223                         printedpara = 1;
1224                         continue;
1225                 }
1226
1227                 if (strcasecmp(ast_xml_node_get_name(tmp), "value")) {
1228                         continue;
1229                 }
1230
1231                 /* Parse a <value> tag only. */
1232                 if (!printedpara) {
1233                         ast_str_append(buffer, 0, "\n");
1234                         printedpara = 1;
1235                 }
1236                 /* Parse each <value name='valuename'>desciption</value> */
1237                 valname = ast_xml_get_attribute(tmp, "name");
1238                 if (valname) {
1239                         ret = 1;
1240                         ast_str_append(buffer, 0, "%s<value>%s</value>", tabs, valname);
1241                         ast_xml_free_attr(valname);
1242                 }
1243                 tmptext = ast_xml_get_text(tmp);
1244                 /* Check inside this node for any explanation about its meaning. */
1245                 if (tmptext) {
1246                         /* Cleanup text. */
1247                         xmldoc_string_cleanup(tmptext, &cleanstr, 1);
1248                         ast_xml_free_text(tmptext);
1249                         if (cleanstr && ast_str_strlen(cleanstr) > 0) {
1250                                 ast_str_append(buffer, 0, ":%s", ast_str_buffer(cleanstr));
1251                         }
1252                         ast_free(cleanstr);
1253                 }
1254                 ast_str_append(buffer, 0, "\n");
1255         }
1256
1257         return ret;
1258 }
1259
1260 /*! \internal
1261  *  \brief Parse a <variablelist> node and put all the output inside 'buffer'.
1262  *  \param node The variablelist node pointer.
1263  *  \param tabs A string to be appended at the begining of the output that will be stored
1264  *         in buffer.
1265  *  \param buffer This must be an already created ast_str. It will be used
1266  *         to store the result (if already has something it will be appended to the current
1267  *         string).
1268  *  \retval 1 If a <variablelist> element is parsed.
1269  *  \retval 0 On error.
1270  */
1271 static int xmldoc_parse_variablelist(struct ast_xml_node *node, const char *tabs, struct ast_str **buffer)
1272 {
1273         struct ast_xml_node *tmp;
1274         const char *varname;
1275         char *vartabs;
1276         int ret = 0;
1277
1278         if (!node || !ast_xml_node_get_children(node)) {
1279                 return ret;
1280         }
1281
1282         if (strcasecmp(ast_xml_node_get_name(node), "variablelist")) {
1283                 return ret;
1284         }
1285
1286         /* use this spacing (add 4 spaces) inside a variablelist node. */
1287         ast_asprintf(&vartabs, "%s    ", tabs);
1288         if (!vartabs) {
1289                 return ret;
1290         }
1291         for (tmp = ast_xml_node_get_children(node); tmp; tmp = ast_xml_node_get_next(tmp)) {
1292                 /* We can have a <para> element inside the variable list */
1293                 if ((xmldoc_parse_para(tmp, (ret ? tabs : ""), "\n", buffer))) {
1294                         ret = 1;
1295                         continue;
1296                 } else if ((xmldoc_parse_specialtags(tmp, (ret ? tabs : ""), "\n", buffer))) {
1297                         ret = 1;
1298                         continue;
1299                 }
1300
1301                 if (!strcasecmp(ast_xml_node_get_name(tmp), "variable")) {
1302                         /* Store the variable name in buffer. */
1303                         varname = ast_xml_get_attribute(tmp, "name");
1304                         if (varname) {
1305                                 ast_str_append(buffer, 0, "%s<variable>%s</variable>: ", tabs, varname);
1306                                 ast_xml_free_attr(varname);
1307                                 /* Parse the <variable> possible values. */
1308                                 xmldoc_parse_variable(tmp, vartabs, buffer);
1309                                 ret = 1;
1310                         }
1311                 }
1312         }
1313
1314         ast_free(vartabs);
1315
1316         return ret;
1317 }
1318
1319 char *ast_xmldoc_build_seealso(const char *type, const char *name)
1320 {
1321         struct ast_str *outputstr;
1322         char *output;
1323         struct ast_xml_node *node;
1324         const char *typename;
1325         const char *content;
1326         int first = 1;
1327
1328         if (ast_strlen_zero(type) || ast_strlen_zero(name)) {
1329                 return NULL;
1330         }
1331
1332         /* get the application/function root node. */
1333         node = xmldoc_get_node(type, name, documentation_language);
1334         if (!node || !ast_xml_node_get_children(node)) {
1335                 return NULL;
1336         }
1337
1338         /* Find the <see-also> node. */
1339         for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
1340                 if (!strcasecmp(ast_xml_node_get_name(node), "see-also")) {
1341                         break;
1342                 }
1343         }
1344
1345         if (!node || !ast_xml_node_get_children(node)) {
1346                 /* we couldnt find a <see-also> node. */
1347                 return NULL;
1348         }
1349
1350         /* prepare the output string. */
1351         outputstr = ast_str_create(128);
1352         if (!outputstr) {
1353                 return NULL;
1354         }
1355
1356         /* get into the <see-also> node. */
1357         for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
1358                 if (strcasecmp(ast_xml_node_get_name(node), "ref")) {
1359                         continue;
1360                 }
1361
1362                 /* parse the <ref> node. 'type' attribute is required. */
1363                 typename = ast_xml_get_attribute(node, "type");
1364                 if (!typename) {
1365                         continue;
1366                 }
1367                 content = ast_xml_get_text(node);
1368                 if (!content) {
1369                         ast_xml_free_attr(typename);
1370                         continue;
1371                 }
1372                 if (!strcasecmp(typename, "application")) {
1373                         ast_str_append(&outputstr, 0, "%s%s()", (first ? "" : ", "), content);
1374                 } else if (!strcasecmp(typename, "function")) {
1375                         ast_str_append(&outputstr, 0, "%s%s", (first ? "" : ", "), content);
1376                 } else if (!strcasecmp(typename, "astcli")) {
1377                         ast_str_append(&outputstr, 0, "%s<astcli>%s</astcli>", (first ? "" : ", "), content);
1378                 } else {
1379                         ast_str_append(&outputstr, 0, "%s%s", (first ? "" : ", "), content);
1380                 }
1381                 first = 0;
1382                 ast_xml_free_text(content);
1383                 ast_xml_free_attr(typename);
1384         }
1385
1386         output = ast_strdup(ast_str_buffer(outputstr));
1387         ast_free(outputstr);
1388
1389         return output;
1390 }
1391
1392 /*! \internal
1393  *  \brief Parse a <enum> node.
1394  *  \brief fixnode An ast_xml_node pointer to the <enum> node.
1395  *  \bried buffer The output buffer.
1396  *  \retval 0 if content is not found inside the enum element (data is not appended to buffer).
1397  *  \retval 1 if content is found and data is appended to buffer.
1398  */
1399 static int xmldoc_parse_enum(struct ast_xml_node *fixnode, const char *tabs, struct ast_str **buffer)
1400 {
1401         struct ast_xml_node *node = fixnode;
1402         int ret = 0;
1403
1404         for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
1405                 if ((xmldoc_parse_para(node, (ret ? tabs : " - "), "\n", buffer))) {
1406                         ret = 1;
1407                 } else if ((xmldoc_parse_specialtags(node, (ret ? tabs : " - "), "\n", buffer))) {
1408                         ret = 1;
1409                 }
1410         }
1411         return ret;
1412 }
1413
1414 /*! \internal
1415  *  \brief Parse a <enumlist> node.
1416  *  \param fixnode As ast_xml pointer to the <enumlist> node.
1417  *  \param buffer The ast_str output buffer.
1418  *  \retval 0 if no <enumlist> node was parsed.
1419  *  \retval 1 if a <enumlist> node was parsed.
1420  */
1421 static int xmldoc_parse_enumlist(struct ast_xml_node *fixnode, const char *tabs, struct ast_str **buffer)
1422 {
1423         struct ast_xml_node *node = fixnode;
1424         const char *enumname;
1425         int ret = 0;
1426
1427         for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
1428                 if (strcasecmp(ast_xml_node_get_name(node), "enum")) {
1429                         continue;
1430                 }
1431
1432                 enumname = ast_xml_get_attribute(node, "name");
1433                 if (enumname) {
1434                         ast_str_append(buffer, 0, "%s<enum>%s</enum>", tabs, enumname);
1435                         ast_xml_free_attr(enumname);
1436
1437                         /* parse only enum elements inside a enumlist node. */
1438                         if ((xmldoc_parse_enum(node, tabs, buffer))) {
1439                                 ret = 1;
1440                         } else {
1441                                 ast_str_append(buffer, 0, "\n");
1442                         }
1443                 }
1444         }
1445         return ret;
1446 }
1447
1448 /*! \internal
1449  *  \brief Parse an <option> node.
1450  *  \param fixnode An ast_xml pointer to the <option> node.
1451  *  \param tabs A string to be appended at the begining of each line being added to the
1452  *              buffer string.
1453  *  \param buffer The output buffer.
1454  *  \retval 0 if no option node is parsed.
1455  *  \retval 1 if an option node is parsed.
1456  */
1457 static int xmldoc_parse_option(struct ast_xml_node *fixnode, const char *tabs, struct ast_str **buffer)
1458 {
1459         struct ast_xml_node *node;
1460         int ret = 0;
1461         char *optiontabs;
1462
1463         ast_asprintf(&optiontabs, "%s    ", tabs);
1464         if (!optiontabs) {
1465                 return ret;
1466         }
1467         for (node = ast_xml_node_get_children(fixnode); node; node = ast_xml_node_get_next(node)) {
1468                 if (!strcasecmp(ast_xml_node_get_name(node), "argument")) {
1469                         /* if this is the first data appended to buffer, print a \n*/
1470                         if (!ret && ast_xml_node_get_children(node)) {
1471                                 /* print \n */
1472                                 ast_str_append(buffer, 0, "\n");
1473                         }
1474                         if (xmldoc_parse_argument(node, 0, NULL, optiontabs, buffer)) {
1475                                 ret = 1;
1476                         }
1477                         continue;
1478                 }
1479
1480                 if (xmldoc_parse_para(node, (ret ? tabs :  ""), "\n", buffer)) {
1481                         ret = 1;
1482                 } else if (xmldoc_parse_specialtags(node, (ret ? tabs :  ""), "\n", buffer)) {
1483                         ret = 1;
1484                 }
1485
1486                 xmldoc_parse_variablelist(node, optiontabs, buffer);
1487
1488                 xmldoc_parse_enumlist(node, optiontabs, buffer);
1489         }
1490         ast_free(optiontabs);
1491
1492         return ret;
1493 }
1494
1495 /*! \internal
1496  *  \brief Parse an <optionlist> element from the xml documentation.
1497  *  \param fixnode Pointer to the optionlist xml node.
1498  *  \param tabs A string to be appended at the begining of each line being added to the
1499  *              buffer string.
1500  *  \param buffer Output buffer to put what is inside the optionlist tag.
1501  */
1502 static void xmldoc_parse_optionlist(struct ast_xml_node *fixnode, const char *tabs, struct ast_str **buffer)
1503 {
1504         struct ast_xml_node *node;
1505         const char *optname, *hasparams;
1506         char *optionsyntax;
1507         int optparams;
1508
1509         for (node = ast_xml_node_get_children(fixnode); node; node = ast_xml_node_get_next(node)) {
1510                 /* Start appending every option tag. */
1511                 if (strcasecmp(ast_xml_node_get_name(node), "option")) {
1512                         continue;
1513                 }
1514
1515                 /* Get the option name. */
1516                 optname = ast_xml_get_attribute(node, "name");
1517                 if (!optname) {
1518                         continue;
1519                 }
1520
1521                 optparams = 1;
1522                 hasparams = ast_xml_get_attribute(node, "hasparams");
1523                 if (hasparams && !strcasecmp(hasparams, "optional")) {
1524                         optparams = 2;
1525                 }
1526
1527                 optionsyntax = xmldoc_get_syntax_fun(node, optname, "argument", 0, optparams);
1528                 if (!optionsyntax) {
1529                         ast_xml_free_attr(optname);
1530                         ast_xml_free_attr(hasparams);
1531                         continue;
1532                 }
1533
1534                 ast_str_append(buffer, 0, "%s%s: ", tabs, optionsyntax);
1535
1536                 if (!xmldoc_parse_option(node, tabs, buffer)) {
1537                         ast_str_append(buffer, 0, "\n");
1538                 }
1539                 ast_xml_free_attr(optname);
1540                 ast_xml_free_attr(hasparams);
1541         }
1542 }
1543
1544 /*! \internal
1545  *  \brief Parse a 'parameter' tag inside a syntax element.
1546  *  \param fixnode A pointer to the 'parameter' xml node.
1547  *  \param tabs A string to be appended at the beginning of each line being printed inside
1548  *              'buffer'.
1549  *  \param buffer String buffer to put values found inside the parameter element.
1550  */
1551 static void xmldoc_parse_parameter(struct ast_xml_node *fixnode, const char *tabs, struct ast_str **buffer)
1552 {
1553         const char *paramname;
1554         struct ast_xml_node *node = fixnode;
1555         int hasarguments, printed = 0;
1556         char *internaltabs;
1557
1558         if (strcasecmp(ast_xml_node_get_name(node), "parameter")) {
1559                 return;
1560         }
1561
1562         hasarguments = xmldoc_has_inside(node, "argument");
1563         if (!(paramname = ast_xml_get_attribute(node, "name"))) {
1564                 /* parameter MUST have an attribute name. */
1565                 return;
1566         }
1567
1568         ast_asprintf(&internaltabs, "%s    ", tabs);
1569         if (!internaltabs) {
1570                 return;
1571         }
1572
1573         if (!hasarguments && xmldoc_has_nodes(node)) {
1574                 ast_str_append(buffer, 0, "%s\n", paramname);
1575                 ast_xml_free_attr(paramname);
1576                 printed = 1;
1577         }
1578
1579         for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
1580                 if (!strcasecmp(ast_xml_node_get_name(node), "optionlist")) {
1581                         xmldoc_parse_optionlist(node, internaltabs, buffer);
1582                 } else if (!strcasecmp(ast_xml_node_get_name(node), "enumlist")) {
1583                         xmldoc_parse_enumlist(node, internaltabs, buffer);
1584                 } else if (!strcasecmp(ast_xml_node_get_name(node), "argument")) {
1585                         xmldoc_parse_argument(node, 1, internaltabs, (!hasarguments ? "        " : ""), buffer);
1586                 } else if (!strcasecmp(ast_xml_node_get_name(node), "para")) {
1587                         if (!printed) {
1588                                 ast_str_append(buffer, 0, "%s\n", paramname);
1589                                 ast_xml_free_attr(paramname);
1590                                 printed = 1;
1591                         }
1592                         xmldoc_parse_para(node, internaltabs, "\n", buffer);
1593                         continue;
1594                 } else if ((xmldoc_parse_specialtags(node, internaltabs, "\n", buffer))) {
1595                         continue;
1596                 }
1597         }
1598         if (!printed) {
1599                 ast_xml_free_attr(paramname);
1600         }
1601         ast_free(internaltabs);
1602 }
1603
1604 char *ast_xmldoc_build_arguments(const char *type, const char *name)
1605 {
1606         struct ast_xml_node *node;
1607         struct ast_str *ret = ast_str_create(128);
1608         char *retstr = NULL;
1609
1610         if (ast_strlen_zero(type) || ast_strlen_zero(name)) {
1611                 return NULL;
1612         }
1613
1614         node = xmldoc_get_node(type, name, documentation_language);
1615
1616         if (!node || !ast_xml_node_get_children(node)) {
1617                 return NULL;
1618         }
1619
1620         /* Find the syntax field. */
1621         for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
1622                 if (!strcasecmp(ast_xml_node_get_name(node), "syntax")) {
1623                         break;
1624                 }
1625         }
1626
1627         if (!node || !ast_xml_node_get_children(node)) {
1628                 /* We couldn't find the syntax node. */
1629                 return NULL;
1630         }
1631
1632         for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
1633                 xmldoc_parse_parameter(node, "", &ret);
1634         }
1635
1636         if (ast_str_strlen(ret) > 0) {
1637                 /* remove last '\n' */
1638                 char *buf = ast_str_buffer(ret);
1639                 if (buf[ast_str_strlen(ret) - 1] == '\n') {
1640                         ast_str_truncate(ret, -1);
1641                 }
1642                 retstr = ast_strdup(ast_str_buffer(ret));
1643         }
1644         ast_free(ret);
1645
1646         return retstr;
1647 }
1648
1649 /*! \internal
1650  *  \brief Return the string within a node formatted with <para> and <variablelist> elements.
1651  *  \param node Parent node where content resides.
1652  *  \param raw If set, return the node's content without further processing.
1653  *  \param raw_wrap Wrap raw text.
1654  *  \retval NULL on error
1655  *  \retval Node content on success.
1656  */
1657 static struct ast_str *xmldoc_get_formatted(struct ast_xml_node *node, int raw_output, int raw_wrap)
1658 {
1659         struct ast_xml_node *tmp;
1660         const char *notcleanret, *tmpstr;
1661         struct ast_str *ret = ast_str_create(128);
1662
1663         if (raw_output) {
1664                 notcleanret = ast_xml_get_text(node);
1665                 tmpstr = notcleanret;
1666                 xmldoc_string_cleanup(ast_skip_blanks(notcleanret), &ret, 0);
1667                 ast_xml_free_text(tmpstr);
1668         } else {
1669                 for (tmp = ast_xml_node_get_children(node); tmp; tmp = ast_xml_node_get_next(tmp)) {
1670                         /* if found, parse a <para> element. */
1671                         if (xmldoc_parse_para(tmp, "", "\n", &ret)) {
1672                                 continue;
1673                         } else if (xmldoc_parse_specialtags(tmp, "", "\n", &ret)) {
1674                                 continue;
1675                         }
1676                         /* if found, parse a <variablelist> element. */
1677                         xmldoc_parse_variablelist(tmp, "", &ret);
1678                         xmldoc_parse_enumlist(tmp, "    ", &ret);
1679                 }
1680                 /* remove last '\n' */
1681                 /* XXX Don't modify ast_str internals manually */
1682                 tmpstr = ast_str_buffer(ret);
1683                 if (tmpstr[ast_str_strlen(ret) - 1] == '\n') {
1684                         ast_str_truncate(ret, -1);
1685                 }
1686         }
1687         return ret;
1688 }
1689
1690 /*!
1691  *  \brief Get the content of a field (synopsis, description, etc) from an asterisk document tree
1692  *  \param type Type of element (application, function, ...).
1693  *  \param name Name of element (Dial, Echo, Playback, ...).
1694  *  \param var Name of field to return (synopsis, description, etc).
1695  *  \param raw Field only contains text, no other elements inside it.
1696  *  \retval NULL On error.
1697  *  \retval Field text content on success.
1698  */
1699 static char *xmldoc_build_field(const char *type, const char *name, const char *var, int raw)
1700 {
1701         struct ast_xml_node *node;
1702         char *ret = NULL;
1703         struct ast_str *formatted;
1704
1705         if (ast_strlen_zero(type) || ast_strlen_zero(name)) {
1706                 ast_log(LOG_ERROR, "Tried to look in XML tree with faulty values.\n");
1707                 return ret;
1708         }
1709
1710         node = xmldoc_get_node(type, name, documentation_language);
1711
1712         if (!node) {
1713                 ast_log(LOG_WARNING, "Counldn't find %s %s in XML documentation\n", type, name);
1714                 return ret;
1715         }
1716
1717         node = ast_xml_find_element(ast_xml_node_get_children(node), var, NULL, NULL);
1718
1719         if (!node || !ast_xml_node_get_children(node)) {
1720                 ast_log(LOG_DEBUG, "Cannot find variable '%s' in tree '%s'\n", name, var);
1721                 return ret;
1722         }
1723
1724         formatted = xmldoc_get_formatted(node, raw, raw);
1725         if (ast_str_strlen(formatted) > 0) {
1726                 ret = ast_strdup(ast_str_buffer(formatted));
1727         }
1728         ast_free(formatted);
1729
1730         return ret;
1731 }
1732
1733 char *ast_xmldoc_build_synopsis(const char *type, const char *name)
1734 {
1735         return xmldoc_build_field(type, name, "synopsis", 1);
1736 }
1737
1738 char *ast_xmldoc_build_description(const char *type, const char *name)
1739 {
1740         return xmldoc_build_field(type, name, "description", 0);
1741 }
1742
1743 /*! \brief Close and unload XML documentation. */
1744 static void xmldoc_unload_documentation(void)
1745 {
1746         struct documentation_tree *doctree;
1747
1748         AST_RWLIST_WRLOCK(&xmldoc_tree);
1749         while ((doctree = AST_RWLIST_REMOVE_HEAD(&xmldoc_tree, entry))) {
1750                 ast_free(doctree->filename);
1751                 ast_xml_close(doctree->doc);
1752         }
1753         AST_RWLIST_UNLOCK(&xmldoc_tree);
1754
1755         ast_xml_finish();
1756 }
1757
1758 int ast_xmldoc_load_documentation(void)
1759 {
1760         struct ast_xml_node *root_node;
1761         struct ast_xml_doc *tmpdoc;
1762         struct documentation_tree *doc_tree;
1763         char *xmlpattern;
1764         struct ast_config *cfg = NULL;
1765         struct ast_variable *var = NULL;
1766         struct ast_flags cnfflags = { 0 };
1767         int globret, i, dup, duplicate;
1768         glob_t globbuf;
1769
1770         /* setup default XML documentation language */
1771         snprintf(documentation_language, sizeof(documentation_language), default_documentation_language);
1772
1773         if ((cfg = ast_config_load2("asterisk.conf", "" /* core can't reload */, cnfflags)) && cfg != CONFIG_STATUS_FILEINVALID) {
1774                 for (var = ast_variable_browse(cfg, "options"); var; var = var->next) {
1775                         if (!strcasecmp(var->name, "documentation_language")) {
1776                                 if (!ast_strlen_zero(var->value)) {
1777                                         snprintf(documentation_language, sizeof(documentation_language), "%s", var->value);
1778                                 }
1779                         }
1780                 }
1781                 ast_config_destroy(cfg);
1782         }
1783
1784         /* initialize the XML library. */
1785         ast_xml_init();
1786
1787         /* register function to be run when asterisk finish. */
1788         ast_register_atexit(xmldoc_unload_documentation);
1789
1790         /* Get every *-LANG.xml file inside $(ASTDATADIR)/documentation */
1791         ast_asprintf(&xmlpattern, "%s/documentation{/thirdparty/,/}*-{%s,%.2s_??,%s}.xml", ast_config_AST_DATA_DIR,
1792                         documentation_language, documentation_language, default_documentation_language);
1793         globbuf.gl_offs = 0;    /* initialize it to silence gcc */
1794         globret = glob(xmlpattern, MY_GLOB_FLAGS, NULL, &globbuf);
1795         if (globret == GLOB_NOSPACE) {
1796                 ast_log(LOG_WARNING, "Glob Expansion of pattern '%s' failed: Not enough memory\n", xmlpattern);
1797                 ast_free(xmlpattern);
1798                 return 1;
1799         } else if (globret  == GLOB_ABORTED) {
1800                 ast_log(LOG_WARNING, "Glob Expansion of pattern '%s' failed: Read error\n", xmlpattern);
1801                 ast_free(xmlpattern);
1802                 return 1;
1803         }
1804         ast_free(xmlpattern);
1805
1806         AST_RWLIST_WRLOCK(&xmldoc_tree);
1807         /* loop over expanded files */
1808         for (i = 0; i < globbuf.gl_pathc; i++) {
1809                 /* check for duplicates (if we already [try to] open the same file. */
1810                 duplicate = 0;
1811                 for (dup = 0; dup < i; dup++) {
1812                         if (!strcmp(globbuf.gl_pathv[i], globbuf.gl_pathv[dup])) {
1813                                 duplicate = 1;
1814                                 break;
1815                         }
1816                 }
1817                 if (duplicate) {
1818                         continue;
1819                 }
1820                 tmpdoc = NULL;
1821                 tmpdoc = ast_xml_open(globbuf.gl_pathv[i]);
1822                 if (!tmpdoc) {
1823                         ast_log(LOG_ERROR, "Could not open XML documentation at '%s'\n", globbuf.gl_pathv[i]);
1824                         continue;
1825                 }
1826                 /* Get doc root node and check if it starts with '<docs>' */
1827                 root_node = ast_xml_get_root(tmpdoc);
1828                 if (!root_node) {
1829                         ast_log(LOG_ERROR, "Error getting documentation root node");
1830                         ast_xml_close(tmpdoc);
1831                         continue;
1832                 }
1833                 /* Check root node name for malformed xmls. */
1834                 if (strcmp(ast_xml_node_get_name(root_node), "docs")) {
1835                         ast_log(LOG_ERROR, "Documentation file is not well formed!\n");
1836                         ast_xml_close(tmpdoc);
1837                         continue;
1838                 }
1839                 doc_tree = ast_calloc(1, sizeof(*doc_tree));
1840                 if (!doc_tree) {
1841                         ast_log(LOG_ERROR, "Unable to allocate documentation_tree structure!\n");
1842                         ast_xml_close(tmpdoc);
1843                         continue;
1844                 }
1845                 doc_tree->doc = tmpdoc;
1846                 doc_tree->filename = ast_strdup(globbuf.gl_pathv[i]);
1847                 AST_RWLIST_INSERT_TAIL(&xmldoc_tree, doc_tree, entry);
1848         }
1849         AST_RWLIST_UNLOCK(&xmldoc_tree);
1850
1851         globfree(&globbuf);
1852
1853         return 0;
1854 }
1855
1856 #endif /* AST_XML_DOCS */
1857
1858