[svn-commits] eliel: branch group/appdocsxml r146404 - /team/group/appdocsxml/funcs/
SVN commits to the Digium repositories
svn-commits at lists.digium.com
Sat Oct 4 15:04:14 CDT 2008
Author: eliel
Date: Sat Oct 4 15:04:14 2008
New Revision: 146404
URL: http://svn.digium.com/view/asterisk?view=rev&rev=146404
Log:
Added XML documentation for functions:
FIELDQTY()
FILTER()
REGEX()
ARRAY()
QUOTE()
LEN()
STRFTIME()
STRPTIME()
EVAL()
KEYPADHASH()
SPRINTF()
HASHKEYS()
HASH()
and ClearHash() application.
Patch by snuffy (snuff-home, snuff-work) Thanks, great job!
(minor modifications by me to fix some syntaxs).
Modified:
team/group/appdocsxml/funcs/func_strings.c
Modified: team/group/appdocsxml/funcs/func_strings.c
URL: http://svn.digium.com/view/asterisk/team/group/appdocsxml/funcs/func_strings.c?view=diff&rev=146404&r1=146403&r2=146404
==============================================================================
--- team/group/appdocsxml/funcs/func_strings.c (original)
+++ team/group/appdocsxml/funcs/func_strings.c Sat Oct 4 15:04:14 2008
@@ -39,6 +39,238 @@
#include "asterisk/app.h"
#include "asterisk/localtime.h"
+/*** DOCUMENTATION
+ <function name="FIELDQTY" language="en_US">
+ <synopsis>
+ Count the fields with an arbitrary delimiter
+ </synopsis>
+ <syntax>
+ <parameter name="varname" required="true" />
+ <parameter name="delim" required="true" />
+ </syntax>
+ <description>
+ <para>Example: ${FIELDQTY(ex-amp-le,-)} returns 3</para>
+ </description>
+ </function>
+ <function name="FILTER" language="en_US">
+ <synopsis>
+ Filter the string to include only the allowed characters
+ </synopsis>
+ <syntax>
+ <parameter name="allowed-chars" required="true" />
+ <parameter name="string" required="true" />
+ </syntax>
+ <description>
+ <para>Permits all characters listed in <replaceable>allowed-chars</replaceable>,
+ filtering all others outs. In addition to literally listing the characters,
+ you may also use ranges of characters (delimited by a <literal>-</literal></para>
+ <para>Hexadecimal characters started with a <literal>\x</literal>(i.e. \x20)</para>
+ <para>Octal characters started with a <literal>\0</literal> (i.e. \040)</para>
+ <para>Also <literal>\t</literal>,<literal>\n</literal> and <literal>\r</literal> are recognized.</para>
+ <note><para>If you want the <literal>-</literal> character it needs to be prefixed with a
+ <literal>\</literal></para></note>
+ </description>
+ </function>
+ <function name="REGEX" language="en_US">
+ <synopsis>
+ Check string against a regular expression.
+ </synopsis>
+ <syntax argsep=" ">
+ <parameter name=""regular expression"" required="true" />
+ <parameter name="string" required="true" />
+ </syntax>
+ <description>
+ <para>Return <literal>1</literal> on regular expression match or <literal>0</literal> otherwise</para>
+ <para>Please note that the space following the double quotes separating the
+ regex from the data is optional and if present, is skipped. If a space is
+ desired at the beginning of the data, then put two spaces there; the second
+ will not be skipped.</para>
+ </description>
+ </function>
+ <application name="ClearHash" language="en_US">
+ <synopsis>
+ Clear the keys from a specified hashname.
+ </synopsis>
+ <syntax>
+ <parameter name="hashname" required="true" />
+ </syntax>
+ <description>
+ <para>Clears all keys out of the specified <replaceable>hashname</replaceable>.</para>
+ </description>
+ </application>
+ <function name="HASH" language="en_US">
+ <synopsis>
+ Implementation of a dialplan associative array
+ </synopsis>
+ <syntax>
+ <parameter name="hashname" required="true" />
+ <parameter name="hashkey" />
+ </syntax>
+ <description>
+ <para>In two arguments mode, gets and sets values to corresponding keys within
+ a named associative array. The single-argument mode will only work when assigned
+ to from a function defined by func_odbc</para>
+ </description>
+ </function>
+ <function name="HASHKEYS" language="en_US">
+ <synopsis>
+ Retrieve the keys of the HASH() function.
+ </synopsis>
+ <syntax>
+ <parameter name="hashname" required="true" />
+ </syntax>
+ <description>
+ <para>Returns a comma-delimited list of the current keys of the associative array
+ defined by the HASH() function. Note that if you iterate over the keys of
+ the result, adding keys during iteration will cause the result of the HASHKEYS()
+ function to change.</para>
+ </description>
+ </function>
+ <function name="KEYPADHASH" language="en_US">
+ <synopsis>
+ Hash the letters in string into equivalent keypad numbers.
+ </synopsis>
+ <syntax>
+ <parameter name="string" required="true" />
+ </syntax>
+ <description>
+ <para>Example: ${KEYPADHASH(Les)} returns "537"</para>
+ </description>
+ </function>
+ <function name="ARRAY" language="en_US">
+ <synopsis>
+ Allows setting multiple variables at once.
+ </synopsis>
+ <syntax>
+ <parameter name="var1" required="true" />
+ <parameter name="var2" required="false" multiple="true" />
+ <parameter name="varN" required="false" />
+ </syntax>
+ <description>
+ <para>The comma-delimited list passed as a value to which the function is set will
+ be interpreted as a set of values to which the comma-delimited list of
+ variable names in the arguement should be set.</para>
+ <para>Example: Set(ARRAY(var1,var2)=1,2) will set var1 to 1 and var2 to 2</para>
+ </description>
+ </function>
+ <function name="STRPTIME" language="en_US">
+ <synopsis>
+ Returns the epoch of the arbitrary date/time string structured as described by the format.
+ </synopsis>
+ <syntax>
+ <parameter name="datetime" required="true" />
+ <parameter name="timezone" required="true" />
+ <parameter name="format" required="true" />
+ </syntax>
+ <description>
+ <para>This is useful for converting a date into <literal>EPOCH</literal> time,
+ possibly to pass to an application like SayUnixTime or to calculate the difference
+ between the two date strings</para>
+ <para>Example: ${STRPTIME(2006-03-01 07:30:35,America/Chicago,%Y-%m-%d %H:%M:%S)} returns 1141219835</para>
+ </description>
+ </function>
+ <function name="STRFTIME" language="en_US">
+ <synopsis>
+ Returns the current date/time in the specified format.
+ </synopsis>
+ <syntax>
+ <parameter name="epoch" />
+ <parameter name="timezone" />
+ <parameter name="format" />
+ </syntax>
+ <description>
+ <para>STRFTIME supports all of the same formats as the underlying C function
+ <emphasis>strftime(3)</emphasis> - see the man page for details.
+ It also supports the following format: <literal>%[n]q</literal> - fractions of a second,
+ with leading zeros.</para>
+ <para>Example: <literal>%3q</literal> will give milliseconds and <literal>%1q</literal>
+ will give tenths of a second. The default is set at milliseconds (n=3).
+ The common case is to use it in combination with %S, as in <literal>%S.%3q</literal>.</para>
+ </description>
+ </function>
+ <function name="EVAL" language="en_US">
+ <synopsis>
+ Evaluate stored variables
+ </synopsis>
+ <syntax>
+ <parameter name="variable" required="true" />
+ </syntax>
+ <description>
+ <para>Using EVAL basically causes a string to be evaluated twice.
+ When a variable or expression is in the dialplan, it will be
+ evaluated at runtime. However, if the results of the evaluation
+ is in fact another variable or expression, using EVAL will have it
+ evaluated a second time.</para>
+ <para>Example: If the <variable>MYVAR</variable> contains
+ <variable>OTHERVAR</variable>, then the result of ${EVAL(
+ <variable>MYVAR</variable>)} in the dialplan will be the
+ contents of <variable>OTHERVAR</variable>. Normally just
+ putting <variable>MYVAR</variable> in the dialplan the result
+ would be <variable>OTHERVAR</variable>.</para>
+ </description>
+ </function>
+ <function name="TOUPPER" language="en_US">
+ <synopsis>
+ Convert string to all uppercase letters.
+ </synopsis>
+ <syntax>
+ <parameter name="string" required="true" />
+ </syntax>
+ <description>
+ <para>Example: ${TOUPPER(Example)} returns "EXAMPLE"</para>
+ </description>
+ </function>
+ <function name="TOLOWER" language="en_US">
+ <synopsis>
+ Convert string to all lowercase letters.
+ </synopsis>
+ <syntax>
+ <parameter name="string" required="true" />
+ </syntax>
+ <description>
+ <para>Example: ${TOLOWER(Example)} returns "example"</para>
+ </description>
+ </function>
+ <function name="LEN" language="en_US">
+ <synopsis>
+ Return the length of the string given.
+ </synopsis>
+ <syntax>
+ <parameter name="string" required="true" />
+ </syntax>
+ <description>
+ <para>Example: ${LEN(example)} returns 7</para>
+ </description>
+ </function>
+ <function name="SPRINTF" language="en_US">
+ <synopsis>
+ Format a variable according to a format string.
+ </synopsis>
+ <syntax>
+ <parameter name="format" required="true" />
+ <parameter name="arg1" required="true" />
+ <parameter name="arg2" multiple="true" />
+ <parameter name="argN" />
+ </syntax>
+ <description>
+ <para>Parses the format string specified and returns a string matching
+ that format. Supports most options found in <emphasis>sprintf(3)</emphasis>.
+ Returns a shortened string if a format specifier is not recognized.</para>
+ </description>
+ </function>
+ <function name="QUOTE" language="en_US">
+ <synopsis>
+ Quotes a given string, escaping embedded quotes as necessary
+ </synopsis>
+ <syntax>
+ <parameter name="string" required="true" />
+ </syntax>
+ <description>
+ <para>Example: ${QUOTE(ab"c"de)} will return "abcde"</para>
+ </description>
+ </function>
+ ***/
+
static int function_fieldqty(struct ast_channel *chan, const char *cmd,
char *parse, char *buf, size_t len)
{
@@ -81,8 +313,6 @@
static struct ast_custom_function fieldqty_function = {
.name = "FIELDQTY",
- .synopsis = "Count the fields, with an arbitrary delimiter",
- .syntax = "FIELDQTY(<varname>,<delim>)",
.read = function_fieldqty,
};
@@ -147,16 +377,7 @@
static struct ast_custom_function filter_function = {
.name = "FILTER",
- .synopsis = "Filter the string to include only the allowed characters",
- .syntax = "FILTER(<allowed-chars>,<string>)",
.read = filter,
- .desc =
-"Permits all characters listed in <allowed-chars>, filtering all others out.\n"
-"In addition to literally listing the characters, you may also use ranges of\n"
-"characters (delimited by a '-'), as well as hexadecimal characters started\n"
-"with a \\x (i.e. \\x20) and octal characters started with \\0 (i.e. \\040).\n"
-"Also, \\t, \\n, and \\r are recognized. If you want a literal '-' character,\n"
-"simply prefix it with a '\\'\n",
};
static int regex(struct ast_channel *chan, const char *cmd, char *parse, char *buf,
@@ -198,13 +419,6 @@
static struct ast_custom_function regex_function = {
.name = "REGEX",
- .synopsis = "Regular Expression",
- .desc =
- "Returns 1 if data matches regular expression, or 0 otherwise.\n"
- "Please note that the space following the double quotes separating the regex from the data\n"
- "is optional and if present, is skipped. If a space is desired at the beginning of the data,\n"
- "then put two spaces there; the second will not be skipped.\n",
- .syntax = "REGEX(\"<regular expression>\" <data>)",
.read = regex,
};
@@ -212,10 +426,6 @@
#define HASH_FORMAT HASH_PREFIX "%s~"
static char *app_clearhash = "ClearHash";
-static char *syn_clearhash = "Clear the keys from a specified hashname";
-static char *desc_clearhash =
-"ClearHash(<hashname>)\n"
-" Clears all keys out of the specified hashname\n";
/* This function probably should migrate to main/pbx.c, as pbx_builtin_clearvar_prefix() */
static void clearvar_prefix(struct ast_channel *chan, const char *prefix)
@@ -400,38 +610,18 @@
static struct ast_custom_function hash_function = {
.name = "HASH",
- .synopsis = "Implementation of a dialplan associative array",
- .syntax = "HASH(hashname[,hashkey])",
.write = hash_write,
.read = hash_read,
- .desc =
- "In two argument mode, gets and sets values to corresponding keys within a named\n"
- "associative array. The single-argument mode will only work when assigned to from\n"
- "a function defined by func_odbc.so.\n",
};
static struct ast_custom_function hashkeys_function = {
.name = "HASHKEYS",
- .synopsis = "Retrieve the keys of a HASH()",
- .syntax = "HASHKEYS(<hashname>)",
.read = hashkeys_read,
- .desc =
- "Returns a comma-delimited list of the current keys of an associative array\n"
- "defined by the HASH() function. Note that if you iterate over the keys of\n"
- "the result, adding keys during iteration will cause the result of the HASHKEYS\n"
- "function to change.\n",
};
static struct ast_custom_function array_function = {
.name = "ARRAY",
- .synopsis = "Allows setting multiple variables at once",
- .syntax = "ARRAY(var1[,var2[...][,varN]])",
.write = array,
- .desc =
- "The comma-separated list passed as a value to which the function is set will\n"
- "be interpreted as a set of values to which the comma-separated list of\n"
- "variable names in the argument should be set.\n"
- "Hence, Set(ARRAY(var1,var2)=1,2) will set var1 to 1 and var2 to 2.\n",
};
static int acf_sprintf(struct ast_channel *chan, const char *cmd, char *data, char *buf, size_t len)
@@ -580,13 +770,7 @@
static struct ast_custom_function sprintf_function = {
.name = "SPRINTF",
- .synopsis = "Format a variable according to a format string",
- .syntax = "SPRINTF(<format>,<arg1>[,...<argN>])",
.read = acf_sprintf,
- .desc =
-"Parses the format string specified and returns a string matching that format.\n"
-"Supports most options supported by sprintf(3). Returns a shortened string if\n"
-"a format specifier is not recognized.\n",
};
static int quote(struct ast_channel *chan, const char *cmd, char *data, char *buf, size_t len)
@@ -613,8 +797,6 @@
static struct ast_custom_function quote_function = {
.name = "QUOTE",
- .synopsis = "Quotes a given string, escaping embedded quotes as necessary",
- .syntax = "QUOTE(<string>)",
.read = quote,
};
@@ -634,8 +816,6 @@
static struct ast_custom_function len_function = {
.name = "LEN",
- .synopsis = "Returns the length of the argument given",
- .syntax = "LEN(<string>)",
.read = len,
};
@@ -670,16 +850,6 @@
static struct ast_custom_function strftime_function = {
.name = "STRFTIME",
- .synopsis = "Returns the current date/time in a specified format.",
- .syntax = "STRFTIME([<epoch>][,[timezone][,format]])",
- .desc =
-"STRFTIME sports all of the same formats as the underlying C function\n"
-"strftime(3) - see the man page for details. It also supports the\n"
-"following format:\n"
-" %[n]q - fractions of a second, with leading zeroes. For example, %3q will\n"
-" give milliseconds and %1q will give tenths of a second. The default\n"
-" is to output milliseconds (n=3). The common case is to use it in\n"
-" combination with %S, as in \"%S.%3q\".\n",
.read = acf_strftime,
};
@@ -722,16 +892,6 @@
static struct ast_custom_function strptime_function = {
.name = "STRPTIME",
- .synopsis =
- "Returns the epoch of the arbitrary date/time string structured as described in the format.",
- .syntax = "STRPTIME(<datetime>,<timezone>,<format>)",
- .desc =
- "This is useful for converting a date into an EPOCH time, possibly to pass to\n"
- "an application like SayUnixTime or to calculate the difference between two\n"
- "date strings.\n"
- "\n"
- "Example:\n"
- " ${STRPTIME(2006-03-01 07:30:35,America/Chicago,%Y-%m-%d %H:%M:%S)} returns 1141219835\n",
.read = acf_strptime,
};
@@ -754,17 +914,6 @@
static struct ast_custom_function eval_function = {
.name = "EVAL",
- .synopsis = "Evaluate stored variables.",
- .syntax = "EVAL(<variable>)",
- .desc = "Using EVAL basically causes a string to be evaluated twice.\n"
- "When a variable or expression is in the dialplan, it will be\n"
- "evaluated at runtime. However, if the result of the evaluation\n"
- "is in fact a variable or expression, using EVAL will have it\n"
- "evaluated a second time. For example, if the variable ${MYVAR}\n"
- "contains \"${OTHERVAR}\", then the result of putting ${EVAL(${MYVAR})}\n"
- "in the dialplan will be the contents of the variable, OTHERVAR.\n"
- "Normally, by just putting ${MYVAR} in the dialplan, you would be\n"
- "left with \"${OTHERVAR}\".\n",
.read = function_eval,
};
@@ -805,10 +954,7 @@
static struct ast_custom_function keypadhash_function = {
.name = "KEYPADHASH",
- .synopsis = "Hash the letters in the string into the equivalent keypad numbers.",
- .syntax = "KEYPADHASH(<string>)",
.read = keypadhash,
- .desc = "Example: ${KEYPADHASH(Les)} returns \"537\"\n",
};
static int string_toupper(struct ast_channel *chan, const char *cmd, char *data, char *buf, size_t buflen)
@@ -822,10 +968,7 @@
static struct ast_custom_function toupper_function = {
.name = "TOUPPER",
- .synopsis = "Convert the string to upper case.",
- .syntax = "TOUPPER(<string>)",
.read = string_toupper,
- .desc = "Example: ${TOUPPER(Example)} returns \"EXAMPLE\"\n",
};
static int string_tolower(struct ast_channel *chan, const char *cmd, char *data, char *buf, size_t buflen)
@@ -839,10 +982,7 @@
static struct ast_custom_function tolower_function = {
.name = "TOLOWER",
- .synopsis = "Convert the string to lower case.",
- .syntax = "TOLOWER(<string>)",
.read = string_tolower,
- .desc = "Example: ${TOLOWER(Example)} returns \"example\"\n",
};
static int unload_module(void)
@@ -886,7 +1026,7 @@
res |= ast_custom_function_register(&sprintf_function);
res |= ast_custom_function_register(&hashkeys_function);
res |= ast_custom_function_register(&hash_function);
- res |= ast_register_application(app_clearhash, exec_clearhash, syn_clearhash, desc_clearhash);
+ res |= ast_register_application_xml(app_clearhash, exec_clearhash);
res |= ast_custom_function_register(&toupper_function);
res |= ast_custom_function_register(&tolower_function);
More information about the svn-commits
mailing list