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