Clarify description of ARRAY function
[asterisk/asterisk.git] / funcs / func_strings.c
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2005, Digium, Inc.
5  * Portions Copyright (C) 2005, Tilghman Lesher.  All rights reserved.
6  * Portions Copyright (C) 2005, Anthony Minessale II
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18
19 /*! \file
20  *
21  * \brief String manipulation dialplan functions
22  *
23  * \author Tilghman Lesher
24  * \author Anothony Minessale II 
25  */
26
27 #include <stdlib.h>
28 #include <stdio.h>
29 #include <string.h>
30 #include <sys/types.h>
31 #include <regex.h>
32
33 #include "asterisk.h"
34
35 /* ASTERISK_FILE_VERSION(__FILE__, "$Revision$") */
36
37 #include "asterisk/channel.h"
38 #include "asterisk/pbx.h"
39 #include "asterisk/logger.h"
40 #include "asterisk/utils.h"
41 #include "asterisk/app.h"
42 #include "asterisk/localtime.h"
43
44 static char *function_fieldqty(struct ast_channel *chan, char *cmd, char *data, char *buf, size_t len)
45 {
46         char *varval, workspace[4096];
47         int fieldcount = 0;
48         char *parse;
49         AST_DECLARE_APP_ARGS(args,
50                 AST_APP_ARG(varname);
51                 AST_APP_ARG(delim);
52         );
53
54         parse = ast_strdupa(data);
55         if (!parse) {
56                 ast_log(LOG_ERROR, "Out of memory\n");
57                 ast_copy_string(buf, "0", len);
58                 return buf;
59         }
60
61         AST_STANDARD_APP_ARGS(args, parse);
62         if (args.delim) {
63                 pbx_retrieve_variable(chan, args.varname, &varval, workspace, sizeof(workspace), NULL);
64                 while (strsep(&varval, args.delim))
65                         fieldcount++;
66         } else {
67                 fieldcount = 1;
68         }
69         snprintf(buf, len, "%d", fieldcount);
70
71         return buf;
72 }
73
74 #ifndef BUILTIN_FUNC
75 static
76 #endif
77 struct ast_custom_function fieldqty_function = {
78         .name = "FIELDQTY",
79         .synopsis = "Count the fields, with an arbitrary delimiter",
80         .syntax = "FIELDQTY(<varname>,<delim>)",
81         .read = function_fieldqty,
82 };
83
84 static char *builtin_function_filter(struct ast_channel *chan, char *cmd, char *data, char *buf, size_t len)
85 {
86         char *parse;
87         AST_DECLARE_APP_ARGS(args,
88                 AST_APP_ARG(allowed);
89                 AST_APP_ARG(string);
90         );
91         char *outbuf=buf;
92
93         parse = ast_strdupa(data);
94         if (!parse) {
95                 ast_log(LOG_ERROR, "Out of memory");
96                 return "";
97         }
98
99         AST_STANDARD_APP_ARGS(args, parse);
100
101         if (!args.string ) {
102                 ast_log(LOG_ERROR, "Usage: FILTER(<allowed-chars>,<string>)\n");
103                 return "";
104         }
105
106         for ( ; *(args.string) && (buf + len - 1 > outbuf); (args.string)++) {
107                 if (strchr(args.allowed, *(args.string))) {
108                         *outbuf = *(args.string);
109                         outbuf++;
110                 }
111         }
112         *outbuf = '\0';
113         
114         return buf;
115 }
116
117 #ifndef BUILTIN_FUNC
118 static
119 #endif
120 struct ast_custom_function filter_function = {
121         .name = "FILTER",
122         .synopsis = "Filter the string to include only the allowed characters",
123         .syntax = "FILTER(<allowed-chars>,<string>)",
124         .read = builtin_function_filter,
125 };
126
127 static char *builtin_function_regex(struct ast_channel *chan, char *cmd, char *data, char *buf, size_t len) 
128 {
129         char *parse;
130         AST_DECLARE_APP_ARGS(args,
131                 AST_APP_ARG(null);
132                 AST_APP_ARG(reg);
133                 AST_APP_ARG(str);
134         );
135                                 
136
137         char errstr[256] = "";
138         int errcode;
139         regex_t regexbuf;
140
141         ast_copy_string(buf, "0", len);
142         
143         parse = ast_strdupa(data);
144         if (!parse) {
145                 ast_log(LOG_ERROR, "Out of memory in %s(%s)\n", cmd, data);
146                 return buf;
147         }
148
149         AST_NONSTANDARD_APP_ARGS(args, parse, '"');
150
151         ast_log(LOG_DEBUG, "FUNCTION REGEX (%s)(%s)\n", args.reg, args.str);
152
153         if ((errcode = regcomp(&regexbuf, args.reg, REG_EXTENDED | REG_NOSUB))) {
154                 regerror(errcode, &regexbuf, errstr, sizeof(errstr));
155                 ast_log(LOG_WARNING, "Malformed input %s(%s): %s\n", cmd, data, errstr);
156         } else {
157                 if (!regexec(&regexbuf, args.str, 0, NULL, 0))
158                         ast_copy_string(buf, "1", len); 
159         }
160         regfree(&regexbuf);
161
162         return buf;
163 }
164
165 #ifndef BUILTIN_FUNC
166 static
167 #endif
168 struct ast_custom_function regex_function = {
169         .name = "REGEX",
170         .synopsis = "Regular Expression: Returns 1 if data matches regular expression.",
171         .syntax = "REGEX(\"<regular expression>\" <data>)",
172         .read = builtin_function_regex,
173 };
174
175 static void builtin_function_array(struct ast_channel *chan, char *cmd, char *data, const char *value)
176 {
177         char *varv[100];
178         char *valuev[100];
179         char *var, *value2;
180         int varcount, valuecount, i;
181
182         var = ast_strdupa(data);
183         value2 = ast_strdupa(value);
184         if (!var || !value2) {
185                 ast_log(LOG_ERROR, "Out of memory\n");
186                 return;
187         }
188
189         /* The functions this will generally be used with are SORT and ODBC_*, which
190          * both return comma-delimited lists.  However, if somebody uses literal lists,
191          * their commas will be translated to vertical bars by the load, and I don't
192          * want them to be surprised by the result.  Hence, we prefer commas as the
193          * delimiter, but we'll fall back to vertical bars if commas aren't found.
194          */
195         if (strchr(var, ',')) {
196                 varcount = ast_app_separate_args(var, ',', varv, 100);
197         } else {
198                 varcount = ast_app_separate_args(var, '|', varv, 100);
199         }
200
201         if (strchr(value2, ',')) {
202                 valuecount = ast_app_separate_args(value2, ',', valuev, 100);
203         } else {
204                 valuecount = ast_app_separate_args(value2, '|', valuev, 100);
205         }
206
207         for (i = 0; i < varcount; i++) {
208                 if (i < valuecount) {
209                         pbx_builtin_setvar_helper(chan, varv[i], valuev[i]);
210                 } else {
211                         /* We could unset the variable, by passing a NULL, but due to
212                          * pushvar semantics, that could create some undesired behavior. */
213                         pbx_builtin_setvar_helper(chan, varv[i], "");
214                 }
215         }
216 }
217
218 #ifndef BUILTIN_FUNC
219 static
220 #endif
221 struct ast_custom_function array_function = {
222         .name = "ARRAY",
223         .synopsis = "Allows setting multiple variables at once",
224         .syntax = "ARRAY(var1[,var2[...][,varN]])",
225         .write = builtin_function_array,
226         .desc =
227 "The comma-separated list passed as a value to which the function is set will\n"
228 "be interpreted as a set of values to which the comma-separated list of\n"
229 "variable names in the argument should be set.\n"
230 "Hence, Set(ARRAY(var1,var2)=1,2) will set var1 to 1 and var2 to 2\n"
231 "Note: remember to either backslash your commas in extensions.conf or quote the\n"
232 "entire argument, since Set can take multiple arguments itself.\n",
233 };
234
235 static char *builtin_function_len(struct ast_channel *chan, char *cmd, char *data, char *buf, size_t len) 
236 {
237         int length = 0;
238         if (data) {
239                 length = strlen(data);
240         }
241         snprintf(buf, len, "%d", length);
242         return buf;
243 }
244
245 #ifndef BUILTIN_FUNC
246 static
247 #endif
248 struct ast_custom_function len_function = {
249         .name = "LEN",
250         .synopsis = "Returns the length of the argument given",
251         .syntax = "LEN(<string>)",
252         .read = builtin_function_len,
253 };
254
255 static char *acf_strftime(struct ast_channel *chan, char *cmd, char *data, char *buf, size_t len) 
256 {
257         char *parse;
258         AST_DECLARE_APP_ARGS(args,
259                 AST_APP_ARG(epoch);
260                 AST_APP_ARG(timezone);
261                 AST_APP_ARG(format);
262         );
263         long epochi;
264         struct tm time;
265
266         buf[0] = '\0';
267
268         if (ast_strlen_zero(data)) {
269                 ast_log(LOG_ERROR, "Asterisk function STRFTIME() requires an argument.\n");
270                 return buf;
271         }
272         
273         parse = ast_strdupa(data);
274         if (!parse) {
275                 ast_log(LOG_ERROR, "Out of memory\n");
276                 return buf;
277         }
278         
279         AST_STANDARD_APP_ARGS(args, parse);
280
281         if (ast_strlen_zero(args.epoch) || !sscanf(args.epoch, "%ld", &epochi)) {
282                 struct timeval tv = ast_tvnow();
283                 epochi = tv.tv_sec;
284         }
285
286         ast_localtime(&epochi, &time, args.timezone);
287
288         if (!strftime(buf, len, args.format?args.format:"%c", &time)) {
289                 ast_log(LOG_WARNING, "C function strftime() output nothing?!!\n");
290         }
291         buf[len - 1] = '\0';
292
293         return buf;
294 }
295
296 #ifndef BUILTIN_FUNC
297 static
298 #endif
299 struct ast_custom_function strftime_function = {
300         .name = "STRFTIME",
301         .synopsis = "Returns the current date/time in a specified format.",
302         .syntax = "STRFTIME([<epoch>][,[timezone][,format]])",
303         .read = acf_strftime,
304 };
305
306 static char *function_eval(struct ast_channel *chan, char *cmd, char *data, char *buf, size_t len) 
307 {
308         memset(buf, 0, len);
309
310         if (ast_strlen_zero(data)) {
311                 ast_log(LOG_WARNING, "EVAL requires an argument: EVAL(<string>)\n");
312                 return buf;
313         }
314
315         pbx_substitute_variables_helper(chan, data, buf, len - 1);
316
317         return buf;
318 }
319
320 #ifndef BUILTIN_FUNC
321 static
322 #endif
323 struct ast_custom_function eval_function = {
324         .name = "EVAL",
325         .synopsis = "Evaluate stored variables.",
326         .syntax = "EVAL(<variable>)",
327         .desc = "Using EVAL basically causes a string to be evaluated twice.\n"
328                 "When a variable or expression is in the dialplan, it will be\n"
329                 "evaluated at runtime. However, if the result of the evaluation\n"
330                 "is in fact a variable or expression, using EVAL will have it\n"
331                 "evaluated a second time. For example, if the variable ${MYVAR}\n"
332                 "contains \"${OTHERVAR}\", then the result of putting ${EVAL(${MYVAR})}\n"
333                 "in the dialplan will be the contents of the variable, OTHERVAR.\n"
334                 "Normally, by just putting ${MYVAR} in the dialplan, you would be\n"
335                 "left with \"${OTHERVAR}\".\n", 
336         .read = function_eval,
337 };
338