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