Revert the previous change to FILTER and fix the embedded documentation instead.
[asterisk/asterisk.git] / funcs / func_strings.c
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2005-2006, 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 "asterisk.h"
28
29 ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
30
31 #include <stdlib.h>
32 #include <stdio.h>
33 #include <string.h>
34 #include <sys/types.h>
35 #include <regex.h>
36
37 #include "asterisk/module.h"
38 #include "asterisk/channel.h"
39 #include "asterisk/pbx.h"
40 #include "asterisk/logger.h"
41 #include "asterisk/utils.h"
42 #include "asterisk/app.h"
43 #include "asterisk/localtime.h"
44
45 static int function_fieldqty(struct ast_channel *chan, char *cmd,
46                              char *parse, char *buf, size_t len)
47 {
48         char *varval;
49         int fieldcount = 0;
50         AST_DECLARE_APP_ARGS(args,
51                              AST_APP_ARG(varname);
52                              AST_APP_ARG(delim);
53                 );
54
55         AST_STANDARD_APP_ARGS(args, parse);
56         if (args.delim) {
57                 pbx_retrieve_variable(chan, args.varname, &varval, buf, len, NULL);
58                 while (strsep(&varval, args.delim))
59                         fieldcount++;
60         } else {
61                 fieldcount = 1;
62         }
63         snprintf(buf, len, "%d", fieldcount);
64
65         return 0;
66 }
67
68 static struct ast_custom_function fieldqty_function = {
69         .name = "FIELDQTY",
70         .synopsis = "Count the fields, with an arbitrary delimiter",
71         .syntax = "FIELDQTY(<varname>|<delim>)",
72         .read = function_fieldqty,
73 };
74
75 static int filter(struct ast_channel *chan, char *cmd, char *parse, char *buf,
76                   size_t len)
77 {
78         AST_DECLARE_APP_ARGS(args,
79                              AST_APP_ARG(allowed);
80                              AST_APP_ARG(string);
81         );
82         char *outbuf = buf;
83
84         AST_STANDARD_APP_ARGS(args, parse);
85
86         if (!args.string) {
87                 ast_log(LOG_ERROR, "Usage: FILTER(<allowed-chars>|<string>)\n");
88                 return -1;
89         }
90
91         for (; *(args.string) && (buf + len - 1 > outbuf); (args.string)++) {
92                 if (strchr(args.allowed, *(args.string)))
93                         *outbuf++ = *(args.string);
94         }
95         *outbuf = '\0';
96
97         return 0;
98 }
99
100 static struct ast_custom_function filter_function = {
101         .name = "FILTER",
102         .synopsis = "Filter the string to include only the allowed characters",
103         .syntax = "FILTER(<allowed-chars>|<string>)",
104         .read = filter,
105 };
106
107 static int regex(struct ast_channel *chan, char *cmd, char *parse, char *buf,
108                  size_t len)
109 {
110         AST_DECLARE_APP_ARGS(args,
111                              AST_APP_ARG(null);
112                              AST_APP_ARG(reg);
113                              AST_APP_ARG(str);
114         );
115         int errcode;
116         regex_t regexbuf;
117
118         buf[0] = '\0';
119
120         AST_NONSTANDARD_APP_ARGS(args, parse, '"');
121
122         ast_log(LOG_DEBUG, "FUNCTION REGEX (%s)(%s)\n", args.reg, args.str);
123
124         if ((errcode = regcomp(&regexbuf, args.reg, REG_EXTENDED | REG_NOSUB))) {
125                 regerror(errcode, &regexbuf, buf, len);
126                 ast_log(LOG_WARNING, "Malformed input %s(%s): %s\n", cmd, parse, buf);
127                 return -1;
128         } else {
129                 if (!regexec(&regexbuf, args.str, 0, NULL, 0))
130                         strcpy(buf, "1");
131         }
132         regfree(&regexbuf);
133
134         return 0;
135 }
136
137 static struct ast_custom_function regex_function = {
138         .name = "REGEX",
139         .synopsis =
140                 "Regular Expression: Returns 1 if data matches regular expression.",
141         .syntax = "REGEX(\"<regular expression>\" <data>)",
142         .read = regex,
143 };
144
145 static int array(struct ast_channel *chan, char *cmd, char *var,
146                  const char *value)
147 {
148         AST_DECLARE_APP_ARGS(arg1,
149                              AST_APP_ARG(var)[100];
150         );
151         AST_DECLARE_APP_ARGS(arg2,
152                              AST_APP_ARG(val)[100];
153         );
154         char *value2;
155         int i;
156
157         value2 = ast_strdupa(value);
158         if (!var || !value2)
159                 return -1;
160
161         /* The functions this will generally be used with are SORT and ODBC_*, which
162          * both return comma-delimited lists.  However, if somebody uses literal lists,
163          * their commas will be translated to vertical bars by the load, and I don't
164          * want them to be surprised by the result.  Hence, we prefer commas as the
165          * delimiter, but we'll fall back to vertical bars if commas aren't found.
166          */
167         ast_log(LOG_DEBUG, "array (%s=%s)\n", var, value2);
168         if (strchr(var, ','))
169                 AST_NONSTANDARD_APP_ARGS(arg1, var, ',');
170         else
171                 AST_STANDARD_APP_ARGS(arg1, var);
172
173         if (strchr(value2, ','))
174                 AST_NONSTANDARD_APP_ARGS(arg2, value2, ',');
175         else
176                 AST_STANDARD_APP_ARGS(arg2, value2);
177
178         for (i = 0; i < arg1.argc; i++) {
179                 ast_log(LOG_DEBUG, "array set value (%s=%s)\n", arg1.var[i],
180                         arg2.val[i]);
181                 if (i < arg2.argc) {
182                         pbx_builtin_setvar_helper(chan, arg1.var[i], arg2.val[i]);
183                 } else {
184                         /* We could unset the variable, by passing a NULL, but due to
185                          * pushvar semantics, that could create some undesired behavior. */
186                         pbx_builtin_setvar_helper(chan, arg1.var[i], "");
187                 }
188         }
189
190         return 0;
191 }
192
193 static struct ast_custom_function array_function = {
194         .name = "ARRAY",
195         .synopsis = "Allows setting multiple variables at once",
196         .syntax = "ARRAY(var1[|var2[...][|varN]])",
197         .write = array,
198         .desc =
199                 "The comma-separated list passed as a value to which the function is set will\n"
200                 "be interpreted as a set of values to which the comma-separated list of\n"
201                 "variable names in the argument should be set.\n"
202                 "Hence, Set(ARRAY(var1|var2)=1\\,2) will set var1 to 1 and var2 to 2\n"
203                 "Note: remember to either backslash your commas in extensions.conf or quote the\n"
204                 "entire argument, since Set can take multiple arguments itself.\n",
205 };
206
207 static int acf_sprintf(struct ast_channel *chan, char *cmd, char *data, char *buf, size_t len)
208 {
209 #define SPRINTF_FLAG    0
210 #define SPRINTF_WIDTH   1
211 #define SPRINTF_PRECISION       2
212 #define SPRINTF_LENGTH  3
213 #define SPRINTF_CONVERSION      4
214         int i, state = -1, argcount = 0;
215         char *formatstart = NULL, *bufptr = buf;
216         char formatbuf[256] = "";
217         int tmpi;
218         double tmpd;
219         AST_DECLARE_APP_ARGS(arg,
220                                 AST_APP_ARG(format);
221                                 AST_APP_ARG(var)[100];
222         );
223
224         AST_STANDARD_APP_ARGS(arg, data);
225
226         /* Scan the format, converting each argument into the requisite format type. */
227         for (i = 0; arg.format[i]; i++) {
228                 switch (state) {
229                 case SPRINTF_FLAG:
230                         if (strchr("#0- +'I", arg.format[i]))
231                                 break;
232                         state = SPRINTF_WIDTH;
233                 case SPRINTF_WIDTH:
234                         if (arg.format[i] >= '0' && arg.format[i] <= '9')
235                                 break;
236
237                         /* Next character must be a period to go into a precision */
238                         if (arg.format[i] == '.') {
239                                 state = SPRINTF_PRECISION;
240                         } else {
241                                 state = SPRINTF_LENGTH;
242                                 i--;
243                         }
244                         break;
245                 case SPRINTF_PRECISION:
246                         if (arg.format[i] >= '0' && arg.format[i] <= '9')
247                                 break;
248                         state = SPRINTF_LENGTH;
249                 case SPRINTF_LENGTH:
250                         if (strchr("hl", arg.format[i])) {
251                                 if (arg.format[i + 1] == arg.format[i])
252                                         i++;
253                                 state = SPRINTF_CONVERSION;
254                                 break;
255                         } else if (strchr("Lqjzt", arg.format[i]))
256                                 state = SPRINTF_CONVERSION;
257                                 break;
258                         state = SPRINTF_CONVERSION;
259                 case SPRINTF_CONVERSION:
260                         if (strchr("diouxXc", arg.format[i])) {
261                                 /* Integer */
262
263                                 /* Isolate this format alone */
264                                 ast_copy_string(formatbuf, formatstart, sizeof(formatbuf));
265                                 formatbuf[&arg.format[i] - formatstart + 1] = '\0';
266
267                                 /* Convert the argument into the required type */
268                                 if (sscanf(arg.var[argcount++], "%i", &tmpi) != 1) {
269                                         ast_log(LOG_ERROR, "Argument '%s' is not an integer number for format '%s'\n", arg.var[argcount - 1], formatbuf);
270                                         goto sprintf_fail;
271                                 }
272
273                                 /* Format the argument */
274                                 snprintf(bufptr, buf + len - bufptr, formatbuf, tmpi);
275
276                                 /* Update the position of the next parameter to print */
277                                 bufptr = strchr(buf, '\0');
278                         } else if (strchr("eEfFgGaA", arg.format[i])) {
279                                 /* Double */
280
281                                 /* Isolate this format alone */
282                                 ast_copy_string(formatbuf, formatstart, sizeof(formatbuf));
283                                 formatbuf[&arg.format[i] - formatstart + 1] = '\0';
284
285                                 /* Convert the argument into the required type */
286                                 if (sscanf(arg.var[argcount++], "%lf", &tmpd) != 1) {
287                                         ast_log(LOG_ERROR, "Argument '%s' is not a floating point number for format '%s'\n", arg.var[argcount - 1], formatbuf);
288                                         goto sprintf_fail;
289                                 }
290
291                                 /* Format the argument */
292                                 snprintf(bufptr, buf + len - bufptr, formatbuf, tmpd);
293
294                                 /* Update the position of the next parameter to print */
295                                 bufptr = strchr(buf, '\0');
296                         } else if (arg.format[i] == 's') {
297                                 /* String */
298
299                                 /* Isolate this format alone */
300                                 ast_copy_string(formatbuf, formatstart, sizeof(formatbuf));
301                                 formatbuf[&arg.format[i] - formatstart + 1] = '\0';
302
303                                 /* Format the argument */
304                                 snprintf(bufptr, buf + len - bufptr, formatbuf, arg.var[argcount++]);
305
306                                 /* Update the position of the next parameter to print */
307                                 bufptr = strchr(buf, '\0');
308                         } else if (arg.format[i] == '%') {
309                                 /* Literal data to copy */
310                                 *bufptr++ = arg.format[i];
311                         } else {
312                                 /* Not supported */
313
314                                 /* Isolate this format alone */
315                                 ast_copy_string(formatbuf, formatstart, sizeof(formatbuf));
316                                 formatbuf[&arg.format[i] - formatstart + 1] = '\0';
317
318                                 ast_log(LOG_ERROR, "Format type not supported: '%s' with argument '%s'\n", formatbuf, arg.var[argcount++]);
319                                 goto sprintf_fail;
320                         }
321                         state = -1;
322                         break;
323                 default:
324                         if (arg.format[i] == '%') {
325                                 state = SPRINTF_FLAG;
326                                 formatstart = &arg.format[i];
327                                 break;
328                         } else {
329                                 /* Literal data to copy */
330                                 *bufptr++ = arg.format[i];
331                         }
332                 }
333         }
334         return 0;
335 sprintf_fail:
336         return -1;
337 }
338
339 static struct ast_custom_function sprintf_function = {
340         .name = "SPRINTF",
341         .synopsis = "Format a variable according to a format string",
342         .syntax = "SPRINTF(<format>|<arg1>[|...<argN>])",
343         .read = acf_sprintf,
344         .desc =
345 "Parses the format string specified and returns a string matching that format.\n"
346 "Supports most options supported by sprintf(3).  Returns a shortened string if\n"
347 "a format specifier is not recognized.\n",
348 };
349
350 static int quote(struct ast_channel *chan, char *cmd, char *data, char *buf, size_t len)
351 {
352         char *bufptr = buf, *dataptr = data;
353         *bufptr++ = '"';
354         for (; bufptr < buf + len - 1; dataptr++) {
355                 if (*dataptr == '\\') {
356                         *bufptr++ = '\\';
357                         *bufptr++ = '\\';
358                 } else if (*dataptr == '"') {
359                         *bufptr++ = '\\';
360                         *bufptr++ = '"';
361                 } else if (*dataptr == '\0') {
362                         break;
363                 } else {
364                         *bufptr++ = *dataptr;
365                 }
366         }
367         *bufptr++ = '"';
368         *bufptr = '\0';
369         return 0;
370 }
371
372 static struct ast_custom_function quote_function = {
373         .name = "QUOTE",
374         .synopsis = "Quotes a given string, escaping embedded quotes as necessary",
375         .syntax = "QUOTE(<string>)",
376         .read = quote,
377 };
378
379
380 static int len(struct ast_channel *chan, char *cmd, char *data, char *buf,
381                size_t len)
382 {
383         int length = 0;
384
385         if (data)
386                 length = strlen(data);
387
388         snprintf(buf, len, "%d", length);
389
390         return 0;
391 }
392
393 static struct ast_custom_function len_function = {
394         .name = "LEN",
395         .synopsis = "Returns the length of the argument given",
396         .syntax = "LEN(<string>)",
397         .read = len,
398 };
399
400 static int acf_strftime(struct ast_channel *chan, char *cmd, char *parse,
401                         char *buf, size_t len)
402 {
403         AST_DECLARE_APP_ARGS(args,
404                              AST_APP_ARG(epoch);
405                              AST_APP_ARG(timezone);
406                              AST_APP_ARG(format);
407         );
408         time_t epochi;
409         struct tm tm;
410
411         buf[0] = '\0';
412
413         if (ast_strlen_zero(parse)) {
414                 ast_log(LOG_ERROR,
415                                 "Asterisk function STRFTIME() requires an argument.\n");
416                 return -1;
417         }
418
419         AST_STANDARD_APP_ARGS(args, parse);
420
421         ast_get_time_t(args.epoch, &epochi, time(NULL), NULL);
422         ast_localtime(&epochi, &tm, args.timezone);
423
424         if (!args.format)
425                 args.format = "%c";
426
427         if (!strftime(buf, len, args.format, &tm))
428                 ast_log(LOG_WARNING, "C function strftime() output nothing?!!\n");
429
430         buf[len - 1] = '\0';
431
432         return 0;
433 }
434
435 static struct ast_custom_function strftime_function = {
436         .name = "STRFTIME",
437         .synopsis = "Returns the current date/time in a specified format.",
438         .syntax = "STRFTIME([<epoch>][|[timezone][|format]])",
439         .read = acf_strftime,
440 };
441
442 static int acf_strptime(struct ast_channel *chan, char *cmd, char *data,
443                         char *buf, size_t len)
444 {
445         AST_DECLARE_APP_ARGS(args,
446                              AST_APP_ARG(timestring);
447                              AST_APP_ARG(timezone);
448                              AST_APP_ARG(format);
449         );
450         struct tm time;
451
452         memset(&time, 0, sizeof(struct tm));
453
454         buf[0] = '\0';
455
456         if (!data) {
457                 ast_log(LOG_ERROR,
458                                 "Asterisk function STRPTIME() requires an argument.\n");
459                 return -1;
460         }
461
462         AST_STANDARD_APP_ARGS(args, data);
463
464         if (ast_strlen_zero(args.format)) {
465                 ast_log(LOG_ERROR,
466                                 "No format supplied to STRPTIME(<timestring>|<timezone>|<format>)");
467                 return -1;
468         }
469
470         if (!strptime(args.timestring, args.format, &time)) {
471                 ast_log(LOG_WARNING, "C function strptime() output nothing?!!\n");
472         } else {
473                 snprintf(buf, len, "%d", (int) ast_mktime(&time, args.timezone));
474         }
475
476         return 0;
477 }
478
479 static struct ast_custom_function strptime_function = {
480         .name = "STRPTIME",
481         .synopsis =
482                 "Returns the epoch of the arbitrary date/time string structured as described in the format.",
483         .syntax = "STRPTIME(<datetime>|<timezone>|<format>)",
484         .desc =
485                 "This is useful for converting a date into an EPOCH time, possibly to pass to\n"
486                 "an application like SayUnixTime or to calculate the difference between two\n"
487                 "date strings.\n"
488                 "\n"
489                 "Example:\n"
490                 "  ${STRPTIME(2006-03-01 07:30:35|America/Chicago|%Y-%m-%d %H:%M:%S)} returns 1141219835\n",
491         .read = acf_strptime,
492 };
493
494 static int function_eval(struct ast_channel *chan, char *cmd, char *data,
495                          char *buf, size_t len)
496 {
497         buf[0] = '\0';
498
499         if (ast_strlen_zero(data)) {
500                 ast_log(LOG_WARNING, "EVAL requires an argument: EVAL(<string>)\n");
501                 return -1;
502         }
503
504         pbx_substitute_variables_helper(chan, data, buf, len - 1);
505
506         return 0;
507 }
508
509 static struct ast_custom_function eval_function = {
510         .name = "EVAL",
511         .synopsis = "Evaluate stored variables.",
512         .syntax = "EVAL(<variable>)",
513         .desc = "Using EVAL basically causes a string to be evaluated twice.\n"
514                 "When a variable or expression is in the dialplan, it will be\n"
515                 "evaluated at runtime. However, if the result of the evaluation\n"
516                 "is in fact a variable or expression, using EVAL will have it\n"
517                 "evaluated a second time. For example, if the variable ${MYVAR}\n"
518                 "contains \"${OTHERVAR}\", then the result of putting ${EVAL(${MYVAR})}\n"
519                 "in the dialplan will be the contents of the variable, OTHERVAR.\n"
520                 "Normally, by just putting ${MYVAR} in the dialplan, you would be\n"
521                 "left with \"${OTHERVAR}\".\n",
522         .read = function_eval,
523 };
524
525 static int keypadhash(struct ast_channel *chan, char *cmd, char *data, char *buf, size_t len)
526 {
527         char *bufptr, *dataptr;
528
529         for (bufptr = buf, dataptr = data; bufptr < buf + len - 1; dataptr++) {
530                 if (*dataptr == '1') {
531                         *bufptr++ = '1';
532                 } else if (strchr("AaBbCc2", *dataptr)) {
533                         *bufptr++ = '2';
534                 } else if (strchr("DdEeFf3", *dataptr)) {
535                         *bufptr++ = '3';
536                 } else if (strchr("GgHhIi4", *dataptr)) {
537                         *bufptr++ = '4';
538                 } else if (strchr("JjKkLl5", *dataptr)) {
539                         *bufptr++ = '5';
540                 } else if (strchr("MmNnOo6", *dataptr)) {
541                         *bufptr++ = '6';
542                 } else if (strchr("PpQqRrSs7", *dataptr)) {
543                         *bufptr++ = '7';
544                 } else if (strchr("TtUuVv8", *dataptr)) {
545                         *bufptr++ = '8';
546                 } else if (strchr("WwXxYyZz9", *dataptr)) {
547                         *bufptr++ = '9';
548                 } else if (*dataptr == '0') {
549                         *bufptr++ = '0';
550                 } else if (*dataptr == '\0') {
551                         *bufptr++ = '\0';
552                         break;
553                 }
554         }
555         buf[len - 1] = '\0';
556
557         return 0;
558 }
559
560 static struct ast_custom_function keypadhash_function = {
561         .name = "KEYPADHASH",
562         .synopsis = "Hash the letters in the string into the equivalent keypad numbers.",
563         .syntax = "KEYPADHASH(<string>)",
564         .read = keypadhash,
565         .desc = "Example:  ${KEYPADHASH(Les)} returns \"537\"\n",
566 };
567
568 static char *tdesc = "String handling dialplan functions";
569
570 static int unload_module(void *mod)
571 {
572         int res = 0;
573
574         res |= ast_custom_function_unregister(&fieldqty_function);
575         res |= ast_custom_function_unregister(&filter_function);
576         res |= ast_custom_function_unregister(&regex_function);
577         res |= ast_custom_function_unregister(&array_function);
578         res |= ast_custom_function_unregister(&quote_function);
579         res |= ast_custom_function_unregister(&len_function);
580         res |= ast_custom_function_unregister(&strftime_function);
581         res |= ast_custom_function_unregister(&strptime_function);
582         res |= ast_custom_function_unregister(&eval_function);
583         res |= ast_custom_function_unregister(&keypadhash_function);
584         res |= ast_custom_function_unregister(&sprintf_function);
585
586         return res;
587 }
588
589 static int load_module(void *mod)
590 {
591         int res = 0;
592
593         res |= ast_custom_function_register(&fieldqty_function);
594         res |= ast_custom_function_register(&filter_function);
595         res |= ast_custom_function_register(&regex_function);
596         res |= ast_custom_function_register(&array_function);
597         res |= ast_custom_function_register(&quote_function);
598         res |= ast_custom_function_register(&len_function);
599         res |= ast_custom_function_register(&strftime_function);
600         res |= ast_custom_function_register(&strptime_function);
601         res |= ast_custom_function_register(&eval_function);
602         res |= ast_custom_function_register(&keypadhash_function);
603         res |= ast_custom_function_register(&sprintf_function);
604
605         return res;
606 }
607
608 static const char *description(void)
609 {
610         return tdesc;
611 }
612
613
614 static const char *key(void)
615 {
616         return ASTERISK_GPL_KEY;
617 }
618
619 STD_MOD(MOD_1 | NO_USECOUNT, NULL, NULL, NULL);