Documentation fixes (bug #1554).

git-svn-id: http://svn.digium.com/svn/asterisk/trunk@2889 f38db490-d61c-443f-a65b-d21fe96a405b

1 files changed, 133 insertions, 5 deletions

diff --git a/doc/README.variables b/doc/README.variables
index f33e7836f..e62e5d35b 100755
--- a/doc/README.variables
+++ b/doc/README.variables
@@ -1,18 +1,37 @@
-GENERAL ENHANCEMENTS TO EXTENSION LOGIC : 
+EXTENSION LOGIC : 
 
-QUOTING: 
+There are two levels of parameter evaluation done in asterisk in 
+extensions.conf.
+The first, and most frequently used, is the substitution of variable
+references with their values. 
+
+Then there are the evaluations done in $[ .. ]. This will be
+discussed below.
+
+___________________________
+PARAMETER QUOTING: 
+---------------------------
 
 exten => s,5,BackGround,blabla
 
 The parameter (blabla) can be quoted ("blabla"). In this case, a 
-comma does not terminate the field. 
+comma does not terminate the field. However, the double quotes
+will be passed down to the Background command, in this example.
 
 Also, characters special to variable substitution, expression evaluation, etc
 (see below), can be quoted. For example, to literally use a $ on the 
 string "$1231", quote it with a preceding \. Special characters that must
 be quoted to be used, are [ ] $ " \. (to write \ itself, use \\). 
 
+These Double quotes and escapes are evaluated at the level of the
+asterisk config file parser. 
+
+Double quotes can also be used inside expressions, as discussed below.
+
+
+___________________________
 VARIABLES: 
+---------------------------
 
 Parameter strings can include variables. Variable names are arbitrary strings. 
 They are stored in the respective channel structure. 
@@ -64,15 +83,17 @@ value "blabla".
 In fact, everything contained ${here} is just replaced with the value of 
 the variable "here". 
 
+___________________________
 EXPRESSIONS: 
+---------------------------
 
 Everything contained inside a bracket pair prefixed by a $ (like $[this]) is 
 considered as an expression and it is evaluated. Evaluation works similar to 
 (but is done on a later stage than) variable substitution: the expression 
 (including the square brackets) is replaced by the result of the expression 
 evaluation. The arguments and operands of the expression MUST BE separated 
-with spaces (take care NOT to leave ANY spaces between opening and closing 
-square brackets and the first and last arguments). 
+by at least one space. 
+
 
 For example, after the sequence: 
 
@@ -81,6 +102,52 @@ exten => 1,2,SetVar,"koko=$[2 * ${lala}]";
 
 the value of variable koko is "6".
 
+And, further:
+
+exten => 1,1,SetVar,"lala=$[1+2]";
+
+will not work as you might have expected. Since all the chars in the single 
+token "1+2" are not numbers, it will be evaluated as the string "1+2". Again,
+please do not forget, that this is a very simple parsing engine, and it
+uses a space (at least one), to separate "tokens".
+
+and, further:
+
+exten => 1,1,SetVar,"lala=$[  1 +    2   ]";
+
+will parse as intended. Extra spaces are ignored.
+
+___________________________
+SPACES INSIDE VARIABLE
+---------------------------
+If the variable being evaluated contains spaces, there can be problems.
+
+For these cases, double quotes around text that may contain spaces
+will force the surrounded text to be evaluated as a single token.
+The double quotes will be counted as part of that lexical token.
+
+As an example:
+
+exten => s,6,GotoIf($[ "${CALLERIDNAME}" : "Privacy Manager" ]?callerid-liar|s|1:s|7)
+
+The variable CALLERIDNAME could evaluate to "DELOREAN MOTORS" (with a space)
+but the above will evaluate to:
+
+"DELOREAN MOTORS" : "Privacy Manager"
+
+and will evaluate to 0.
+
+The above without double quotes would have evaluated to:
+
+DELOREAN MOTORS : Privacy Manager
+
+and will result in syntax errors, because token DELOREAN is immediately
+followed by token MOTORS and the expression parser will not know how to 
+evaluate this expression.
+
+_____________________
+OPERATORS
+---------------------
 Operators are listed below in order of increasing precedence.  Operators
 with equal precedence are grouped within { } symbols.
 
@@ -124,7 +191,9 @@ Parentheses are used for grouping in the usual manner.
 The parser must be parsed with bison (bison is REQUIRED - yacc cannot 
 produce pure parsers, which are reentrant) 
 
+___________________________
 CONDITIONALS
+---------------------------
 
 There is one conditional operator - the conditional goto : 
 
@@ -148,3 +217,62 @@ exten => s,3,SetVar,"varb=$[${vara} + 2]"
 exten => s,4,SetVar,"varc=$[${varb} * 2]"
 exten => s,5,GotoIf,"$[${varc} = 6]?99|1:s|6";
 
+___________________________
+PARSE ERRORS
+---------------------------
+
+Syntax errors are now output with 3 lines.
+
+If the extensions.conf file contains a line like:
+
+exten => s,6,GotoIf($[ "${CALLERIDNUM}"  = "3071234567" & "${CALLERIDNAME}" : "Privacy Manager" ]?callerid-liar|s|1:s|7)
+
+You may see an error in /var/log/asterisk/messages like this:
+
+May  3 15:58:53 WARNING[1234455344]: ast_yyerror(): syntax error: parse error; Input:
+ "3072312154"  : "3071234567" & & "Steves Extension" : "Privacy Manager"
+ ^^^^^^^^^^^^^^^^^^^^^^^^^^^
+                                  ^
+
+The first line shows the string passed to the expression parser. This
+string is the result of the variable replacements, etc. This way, you
+can see the actual string that went into the parser.
+
+The second line usually shows a string of '^' chars, that show what's
+been legally parsed so far.
+
+And the third line shows where the parser was (lookahead token lexing,
+etc), when the parse hit the rocks. A single '^' here. The error is
+going to be somewhere between the last '^' on the second line, and the
+'^' on the third line. That's right, in the example above, there are two
+'&' chars, separated by a space, and this is a definite no-no!
+
+
+___________________________
+NULL STRINGS
+---------------------------
+
+Testing to see if a string is null can be done in one of two different ways:
+
+exten => _XX.,1,GotoIf($["${calledid}" != ""]?3) 
+
+exten => _XX.,1,GotoIf($[foo${calledid} != foo]?3) 
+
+
+The second example above is the way suggested by the WIKI. It will 
+work as long as there are no spaces in the evaluated value.
+
+The first way should work in all cases, and indeed, might now
+be the safest way to handle this situation.
+
+___________________________
+WARNING
+---------------------------
+
+If you need to do complicated things with strings, asterisk expressions
+is most likely NOT the best way to go about it. AGI scripts are an
+excellent option to this need, and make available the full power of
+whatever language you desire, be it Perl, C, C++, Cobol, RPG, Java,
+Snobol, PL/I, Scheme, Common Lisp, Shell scripts, Tcl, Forth, Modula,
+Pascal, APL, assembler, etc.
+