func_strings.c

/*
 * Asterisk -- An open source telephony toolkit.
 *
 * Copyright (C) 2005-2006, Digium, Inc.
 * Portions Copyright (C) 2005, Tilghman Lesher.  All rights reserved.
 * Portions Copyright (C) 2005, Anthony Minessale II
 *
 * See http://www.asterisk.org for more information about
 * the Asterisk project. Please do not directly contact
 * any of the maintainers of this project for assistance;
 * the project provides a web site, mailing lists and IRC
 * channels for your use.
 *
 * This program is free software, distributed under the terms of
 * the GNU General Public License Version 2. See the LICENSE file
 * at the top of the source tree.
 */

/*! \file
 *
 * \brief String manipulation dialplan functions
 *
 * \author Tilghman Lesher
 * \author Anothony Minessale II 
 * \ingroup functions
 */

/*** MODULEINFO
	<support_level>core</support_level>
 ***/

#include "asterisk.h"

#include <regex.h>
#include <ctype.h>

#include "asterisk/module.h"
#include "asterisk/channel.h"
#include "asterisk/pbx.h"
#include "asterisk/utils.h"
#include "asterisk/app.h"
#include "asterisk/localtime.h"
#include "asterisk/test.h"

AST_THREADSTORAGE(result_buf);
AST_THREADSTORAGE(tmp_buf);

/*** 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>The delimiter may be specified as a special or extended ASCII character, by encoding it.  The characters
			<literal>\n</literal>, <literal>\r</literal>, and <literal>\t</literal> are all recognized as the newline,
			carriage return, and tab characters, respectively.  Also, octal and hexadecimal specifications are recognized
			by the patterns <literal>\0nnn</literal> and <literal>\xHH</literal>, respectively.  For example, if you wanted
			to encode a comma as the delimiter, you could use either <literal>\054</literal> or <literal>\x2C</literal>.</para>
			<para>Example: If ${example} contains <literal>ex-amp-le</literal>, then ${FIELDQTY(example,-)} returns 3.</para>
		</description>
	</function>
	<function name="FIELDNUM" language="en_US">
		<synopsis>
			Return the 1-based offset of a field in a list
		</synopsis>
		<syntax>
			<parameter name="varname" required="true" />
			<parameter name="delim" required="true" />
			<parameter name="value" required="true" />
		</syntax>
		<description>
			<para>Search the variable named <replaceable>varname</replaceable> for the string <replaceable>value</replaceable>
			delimited by <replaceable>delim</replaceable> and return a 1-based offset as to its location. If not found
			or an error occured, return <literal>0</literal>.</para>
			<para>The delimiter may be specified as a special or extended ASCII character, by encoding it.  The characters
			<literal>\n</literal>, <literal>\r</literal>, and <literal>\t</literal> are all recognized as the newline,
			carriage return, and tab characters, respectively.  Also, octal and hexadecimal specifications are recognized
			by the patterns <literal>\0nnn</literal> and <literal>\xHH</literal>, respectively.  For example, if you wanted
			to encode a comma as the delimiter, you could use either <literal>\054</literal> or <literal>\x2C</literal>.</para>
		        <para>Example: If ${example} contains <literal>ex-amp-le</literal>, then ${FIELDNUM(example,-,amp)} returns 2.</para>
		</description>
	</function>
	<function name="LISTFILTER" language="en_US">
		<synopsis>Remove an item from a list, by name.</synopsis>
		<syntax>
			<parameter name="varname" required="true" />
			<parameter name="delim" required="true" default="," />
			<parameter name="value" required="true" />
		</syntax>
		<description>
			<para>Remove <replaceable>value</replaceable> from the list contained in the <replaceable>varname</replaceable>
			variable, where the list delimiter is specified by the <replaceable>delim</replaceable> parameter.  This is
			very useful for removing a single channel name from a list of channels, for example.</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="REPLACE" language="en_US">
		<synopsis>
			Replace a set of characters in a given string with another character.
		</synopsis>
		<syntax>
			<parameter name="varname" required="true" />
			<parameter name="find-chars" required="true" />
			<parameter name="replace-char" required="false" />
		</syntax>
		<description>
			<para>Iterates through a string replacing all the <replaceable>find-chars</replaceable> with
			<replaceable>replace-char</replaceable>.  <replaceable>replace-char</replaceable> may be either
			empty or contain one character.  If empty, all <replaceable>find-chars</replaceable> will be
			deleted from the output.</para>
			<note><para>The replacement only occurs in the output.  The original variable is not
			altered.</para></note>
		</description>
	</function>
	<function name="STRREPLACE" language="en_US">
		<synopsis>
			Replace instances of a substring within a string with another string.
		</synopsis>
		<syntax>
			<parameter name="varname" required="true" />
			<parameter name="find-string" required="true" />
			<parameter name="replace-string" required="false" />
			<parameter name="max-replacements" required="false" />
		</syntax>
		<description>
			<para>Searches for all instances of the <replaceable>find-string</replaceable> in provided variable and
			replaces them with <replaceable>replace-string</replaceable>.  If <replaceable>replace-string</replaceable>
			is an empty string, this will effecively delete that substring.  If <replaceable>max-replacements</replaceable>
			is specified, this function will stop after performing replacements <replaceable>max-replacements</replaceable> times.</para>
			<note><para>The replacement only occurs in the output.  The original variable is not altered.</para></note>
		</description>
	</function>
	<function name="PASSTHRU" language="en_US">
		<synopsis>
			Pass the given argument back as a value.
		</synopsis>
		<syntax>
			<parameter name="string" required="false" />
		</syntax>
		<description>
			<para>Literally returns the given <replaceable>string</replaceable>.  The intent is to permit
			other dialplan functions which take a variable name as an argument to be able to take a literal
			string, instead.</para>
			<note><para>The functions which take a variable name need to be passed var and not
			${var}.  Similarly, use PASSTHRU() and not ${PASSTHRU()}.</para></note>
			<para>Example: ${CHANNEL} contains SIP/321-1</para>
			<para>         ${CUT(PASSTHRU(${CUT(CHANNEL,-,1)}),/,2)}) will return 321</para>
		</description>
	</function>
	<function name="REGEX" language="en_US">
		<synopsis>
			Check string against a regular expression.
		</synopsis>
		<syntax argsep=" ">
			<parameter name="&quot;regular expression&quot;" 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>