[asterisk-commits] eliel: branch group/appdocsxml r153096 - in /team/group/appdocsxml: apps/ doc...

SVN commits to the Asterisk project asterisk-commits at lists.digium.com
Fri Oct 31 11:04:48 CDT 2008


Author: eliel
Date: Fri Oct 31 11:04:47 2008
New Revision: 153096

URL: http://svn.digium.com/view/asterisk?view=rev&rev=153096
Log:
Make possible to generate syntaxs like:
GosubIf(condition?[labeliftrue[(arg1[,...][,argN])]][:labeliffalse[(arg1[,...][,argN])]])


Modified:
    team/group/appdocsxml/apps/app_dial.c
    team/group/appdocsxml/apps/app_exec.c
    team/group/appdocsxml/apps/app_stack.c
    team/group/appdocsxml/doc/appdocsxml.dtd
    team/group/appdocsxml/main/pbx.c

Modified: team/group/appdocsxml/apps/app_dial.c
URL: http://svn.digium.com/view/asterisk/team/group/appdocsxml/apps/app_dial.c?view=diff&rev=153096&r1=153095&r2=153096
==============================================================================
--- team/group/appdocsxml/apps/app_dial.c (original)
+++ team/group/appdocsxml/apps/app_dial.c Fri Oct 31 11:04:47 2008
@@ -69,7 +69,7 @@
 		</synopsis>
 		<syntax>
 			<parameter name="Technology/Resource" required="true" argsep="&amp;">
-				<argument name="Technology/Resource" multiple="true" required="true">
+				<argument name="Technology/Resource" required="true">
 					<para>Specification of the device(s) to dial.  These must be in the format of
 					<literal>Technology/Resource</literal>, where <replaceable>Technology</replaceable>
 					represents a particular channel driver, and <replaceable>Resource</replaceable>

Modified: team/group/appdocsxml/apps/app_exec.c
URL: http://svn.digium.com/view/asterisk/team/group/appdocsxml/apps/app_exec.c?view=diff&rev=153096&r1=153095&r2=153096
==============================================================================
--- team/group/appdocsxml/apps/app_exec.c (original)
+++ team/group/appdocsxml/apps/app_exec.c Fri Oct 31 11:04:47 2008
@@ -42,8 +42,9 @@
 			Executes dialplan application.
 		</synopsis>
 		<syntax>
-			<parameter name="appname(arguments)" required="true">
+			<parameter name="appname" required="true" hasparams="true">
 				<para>Application name and arguments of the dialplan application to execute.</para>
+				<argument name="arguments" required="true" />
 			</parameter>
 		</syntax>
 		<description>
@@ -60,7 +61,9 @@
 			Executes dialplan application, always returning.
 		</synopsis>
 		<syntax>
-			<parameter name="appname(arguments)" required="true" />
+			<parameter name="appname" required="true" hasparams="true">
+				<argument name="arguments" required="true" />
+			</parameter>
 		</syntax>
 		<description>
 			<para>Allows an arbitrary application to be invoked even when not
@@ -90,8 +93,12 @@
 		<syntax argsep="?">
 			<parameter name="expression" required="true" />
 			<parameter name="execapp" required="true" argsep=":">
-				<argument name="appiftrue(args)" required="true" />
-				<argument name="appiffalse(args)" required="false" />
+				<argument name="appiftrue" required="true" hasparams="true">
+					<argument name="args" required="true" />
+				</argument>
+				<argument name="appiffalse" required="false" hasparams="true">
+					<argument name="args" required="true" />
+				</argument>
 			</parameter>
 		</syntax>
 		<description>

Modified: team/group/appdocsxml/apps/app_stack.c
URL: http://svn.digium.com/view/asterisk/team/group/appdocsxml/apps/app_stack.c?view=diff&rev=153096&r1=153095&r2=153096
==============================================================================
--- team/group/appdocsxml/apps/app_stack.c (original)
+++ team/group/appdocsxml/apps/app_stack.c Fri Oct 31 11:04:47 2008
@@ -40,33 +40,76 @@
 #include "asterisk/channel.h"
 #include "asterisk/agi.h"
 
+/*** DOCUMENTATION
+	<application name="Gosub" language="en_US">
+		<synopsis>
+			Jump to label, saving return address.
+		</synopsis>
+		<syntax>
+			<parameter name="context" />
+			<parameter name="exten" />
+			<parameter name="priority" required="true" hasparams="optional">
+				<argument name="arg1" multiple="true" required="true" />
+				<argument name="argN" />
+			</parameter>
+		</syntax>
+		<description>
+			<para>Jumps to the label specified, saving the return address.</para>
+		</description>
+	</application>
+	<application name="GosubIf" language="en_US">
+		<synopsis>
+			Conditionally jump to label, saving return address.
+		</synopsis>
+		<syntax argsep="?">
+			<parameter name="condition" required="true" />
+			<parameter name="destination" required="true" argsep=":">
+				<argument name="labeliftrue" hasparams="optional">
+					<argument name="arg1" required="true" multiple="true" />
+					<argument name="argN" />
+				</argument>
+				<argument name="labeliffalse" hasparams="optional">
+					<argument name="arg1" required="true" multiple="true" />
+					<argument name="argN" />
+				</argument>
+			</parameter>
+		</syntax>
+		<description>
+			<para>If the condition is true, then jump to labeliftrue.  If false, jumps to
+			labeliffalse, if specified.  In either case, a jump saves the return point
+			in the dialplan, to be returned to with a Return.</para>
+		</description>
+	</application>
+	<application name="Return" language="en_US">
+		<synopsis>
+			Return from gosub routine.
+		</synopsis>
+		<syntax>
+			<parameter name="value">
+				<para>Return value.</para>
+			</parameter>
+		</syntax>
+		<description>
+			<para>Jumps to the last label on the stack, removing it. The return <replaceable>value</replaceable>, if
+			any, is saved in the channel variable <variable>GOSUB_RETVAL</variable>.</para>
+		</description>
+	</application>
+	<application name="StackPop" language="en_US">
+		<synopsis>
+			Remove one address from gosub stack.
+		</synopsis>
+		<syntax />
+		<description>
+			<para>Removes last label on the stack, discarding it.</para>
+		</description>
+	</application>
+ ***/
 static int agi_loaded = 0;
 
 static const char *app_gosub = "Gosub";
 static const char *app_gosubif = "GosubIf";
 static const char *app_return = "Return";
 static const char *app_pop = "StackPop";
-
-static const char *gosub_synopsis = "Jump to label, saving return address";
-static const char *gosubif_synopsis = "Conditionally jump to label, saving return address";
-static const char *return_synopsis = "Return from gosub routine";
-static const char *pop_synopsis = "Remove one address from gosub stack";
-
-static const char *gosub_descrip =
-"  Gosub([[context,]exten,]priority[(arg1[,...][,argN])]):\n"
-"Jumps to the label specified, saving the return address.\n";
-static const char *gosubif_descrip =
-"  GosubIf(condition?labeliftrue[(arg1[,...])][:labeliffalse[(arg1[,...])]]):\n"
-"If the condition is true, then jump to labeliftrue.  If false, jumps to\n"
-"labeliffalse, if specified.  In either case, a jump saves the return point\n"
-"in the dialplan, to be returned to with a Return.\n";
-static const char *return_descrip =
-"  Return([return-value]):\n"
-"Jumps to the last label on the stack, removing it.  The return value, if\n"
-"any, is saved in the channel variable GOSUB_RETVAL.\n";
-static const char *pop_descrip =
-"  StackPop():\n"
-"Removes last label on the stack, discarding it.\n";
 
 static void gosub_free(void *data);
 
@@ -530,10 +573,10 @@
 		ast_agi_register(ast_module_info->self, &gosub_agi_command);
 	}
 
-	ast_register_application(app_pop, pop_exec, pop_synopsis, pop_descrip);
-	ast_register_application(app_return, return_exec, return_synopsis, return_descrip);
-	ast_register_application(app_gosubif, gosubif_exec, gosubif_synopsis, gosubif_descrip);
-	ast_register_application(app_gosub, gosub_exec, gosub_synopsis, gosub_descrip);
+	ast_register_application_xml(app_pop, pop_exec);
+	ast_register_application_xml(app_return, return_exec);
+	ast_register_application_xml(app_gosubif, gosubif_exec);
+	ast_register_application_xml(app_gosub, gosub_exec);
 	ast_custom_function_register(&local_function);
 
 	return 0;

Modified: team/group/appdocsxml/doc/appdocsxml.dtd
URL: http://svn.digium.com/view/asterisk/team/group/appdocsxml/doc/appdocsxml.dtd?view=diff&rev=153096&r1=153095&r2=153096
==============================================================================
--- team/group/appdocsxml/doc/appdocsxml.dtd (original)
+++ team/group/appdocsxml/doc/appdocsxml.dtd Fri Oct 31 11:04:47 2008
@@ -24,6 +24,7 @@
   <!ATTLIST parameter name CDATA #REQUIRED>
   <!ATTLIST parameter required (yes|no|true|false) "false">
   <!ATTLIST parameter multiple (yes|no|true|false) "false">
+  <!ATTLIST parameter hasparams (yes|no|true|false|optional) "false">
   <!ATTLIST parameter argsep CDATA ",">
 
   <!ELEMENT optionlist (option+)>
@@ -36,10 +37,11 @@
   <!ELEMENT enum (para|note|warning)*>
   <!ATTLIST enum name CDATA #REQUIRED>
 
-  <!ELEMENT argument (para|note|warning|variablelist)*>
+  <!ELEMENT argument (para|note|warning|variablelist|argument)*>
   <!ATTLIST argument name CDATA #REQUIRED>
   <!ATTLIST argument multiple (yes|no|true|false) "false">
   <!ATTLIST argument required (yes|no|true|false) "false">
+  <!ATTLIST argument hasparams (yes|no|true|false|optional) "false">
 
   <!ELEMENT para (#PCDATA|astcli|literal|emphasis|filename|directory|replaceable|variable)*>
   <!ELEMENT literal (#PCDATA)>

Modified: team/group/appdocsxml/main/pbx.c
URL: http://svn.digium.com/view/asterisk/team/group/appdocsxml/main/pbx.c?view=diff&rev=153096&r1=153095&r2=153096
==============================================================================
--- team/group/appdocsxml/main/pbx.c (original)
+++ team/group/appdocsxml/main/pbx.c Fri Oct 31 11:04:47 2008
@@ -195,9 +195,8 @@
 				<argument name="mdays" required="true" />
 				<argument name="months" required="true" />
 			</parameter>
-			<parameter name="application" required="true" argsep="">
-				<argument name="appname" required="true" />
-				<argument name="(appargs)" />
+			<parameter name="appname" required="true" hasparams="optional">
+				<argument name="appargs" required="true" />
 			</parameter>
 		</syntax>
 		<description>
@@ -3627,16 +3626,17 @@
  *  \param printparenthesis Boolean if we must print parenthesis if not parameters are found in the rootnode.
  *  \param printrootname Boolean if we must print the rootname before the syntax and parenthesis at the begining/end.
  *  \retval NULL on error.
- *  \retval An ast_malloc'ed string with the syntax generated. */
+ *  \retval An ast_malloc'ed string with the syntax generated.
+ */
 static char *xmldoc_get_syntax(struct ast_xml_node *rootnode, const char *rootname, const char *childname, int printparenthesis, int printrootname)
 {
 #define GOTONEXT(__rev, __a) (__rev ? ast_xml_node_get_prev(__a) : ast_xml_node_get_next(__a))
 #define ISLAST(__rev, __a)  (__rev == 1 ? (ast_xml_node_get_prev(__a) ? 0 : 1) : (ast_xml_node_get_next(__a) ? 0 : 1))
 #define MP(__a) ((multiple ? __a : ""))
 	struct ast_xml_node *node = NULL, *firstparam = NULL, *lastparam = NULL;
-	const char *paramtype, *multipletype, *paramname, *attrargsep;
+	const char *paramtype, *multipletype, *paramname, *attrargsep, *parenthesis, *argname;
 	int reverse, required, paramcount = 0, openbrackets = 0, len = 0, hasparams=0;
-	int reqfinode = 0, reqlanode = 0, optmidnode = 0;
+	int reqfinode = 0, reqlanode = 0, optmidnode = 0, prnparenthesis;
 	char *syntax = NULL, *argsep;
 	int paramnamemalloc, multiple;
 
@@ -3719,9 +3719,11 @@
 
 	/* init syntax string. */
 	if (reverse) {
-		xmldoc_reverse_helper(reverse, &len, &syntax, (printrootname ? ")" : ""));
+		xmldoc_reverse_helper(reverse, &len, &syntax,
+			(printrootname ? (printrootname == 2 ? ")]" : ")"): ""));
 	} else {
-		xmldoc_reverse_helper(reverse, &len, &syntax, "%s%s", (printrootname ? rootname : ""), (printrootname ? "(" : ""));
+		xmldoc_reverse_helper(reverse, &len, &syntax, "%s%s", (printrootname ? rootname : ""),
+			(printrootname ? (printrootname == 2 ? "[(" : "(") : ""));
 	}
 
 	for (; node; node = GOTONEXT(reverse, node)) {
@@ -3729,8 +3731,26 @@
 			continue;
 		}
 
+		/* Get the argument name, if it is not the leaf, go inside that parameter. */
 		if (xmldoc_has_arguments(node)) {
-			paramname = xmldoc_get_syntax(node, "parameter", "argument", 0, 0);
+			parenthesis = ast_xml_get_attribute(node, "hasparams");
+			prnparenthesis = 0;
+			if (parenthesis) {
+				prnparenthesis = ast_true(parenthesis);
+				if (!strcasecmp(parenthesis, "optional")) {
+					prnparenthesis = 2;
+				}
+				ast_xml_free_attr(parenthesis);
+			}
+			argname = ast_xml_get_attribute(node, "name");
+			if (argname) {
+				paramname = xmldoc_get_syntax(node, argname, "argument", prnparenthesis, prnparenthesis);
+				ast_xml_free_attr(argname);
+				paramnamemalloc = 1;
+			} else {
+				/* Malformed XML, print **UNKOWN** */
+				paramname = ast_strdup("**unknown**");
+			}
 			paramnamemalloc = 1;
 		} else {
 			paramnamemalloc = 0;
@@ -3769,7 +3789,7 @@
 		if (required) {
 			/* First parameter */
 			if (!paramcount) {
-				xmldoc_reverse_helper(reverse, &len, &syntax, "%s", paramname);
+				xmldoc_reverse_helper(reverse, &len, &syntax, "%s%s%s%s", paramname, MP("["), MP(argsep), MP("...]"));
 			} else {
 				while (openbrackets > 0) {
 					xmldoc_reverse_helper(reverse, &len, &syntax, (reverse ? "[" : "]"));
@@ -3823,9 +3843,10 @@
 
 	/* close syntax string. */
 	if (reverse) {
-		xmldoc_reverse_helper(reverse, &len, &syntax, "%s%s", (printrootname ? rootname : ""), (printrootname ? "(" : ""));
+		xmldoc_reverse_helper(reverse, &len, &syntax, "%s%s", (printrootname ? rootname : ""), 
+			(printrootname ? (printrootname == 2 ? "[(" : "(") : ""));
 	} else {
-		xmldoc_reverse_helper(reverse, &len, &syntax, (printrootname ? ")" : ""));
+		xmldoc_reverse_helper(reverse, &len, &syntax, (printrootname ? (printrootname == 2 ? ")]" : ")") : ""));
 	}
 
 	return syntax;




More information about the asterisk-commits mailing list