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