X-Git-Url: https://git.exim.org/exim.git/blobdiff_plain/a7538db17824b7fd70c12ef7561a67b85d6f247e..93cad488cb2c9a31aea345c8910a9f9c5815071c:/doc/doc-docbook/spec.xfpt

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index 0775cb139..4d620a36f 100644
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -7338,6 +7338,10 @@ If you specify multiple attributes, the result contains space-separated, quoted
 strings, each preceded by the attribute name and an equals sign. Within the
 quotes, the quote character, backslash, and newline are escaped with
 backslashes, and commas are used to separate multiple values for the attribute.
+.new
+Any commas in attribute values are doubled
+(permitting treatment of the values as a comma-separated list).
+.wen
 Apart from the escaping, the string within quotes takes the same form as the
 output when a single attribute is requested. Specifying no attributes is the
 same as specifying all of an entry's attributes.
@@ -7347,21 +7351,26 @@ LDAP query, and the second is the data that is returned. The attribute called
 &%attr1%& has two values, whereas &%attr2%& has only one value:
 .code
 ldap:///o=base?attr1?sub?(uid=fred)
-value1.1, value1.2
+value1.1,value1.2
 
 ldap:///o=base?attr2?sub?(uid=fred)
 value two
 
 ldap:///o=base?attr1,attr2?sub?(uid=fred)
-attr1="value1.1, value1.2" attr2="value two"
+attr1="value1.1,value1.2" attr2="value two"
 
 ldap:///o=base??sub?(uid=fred)
-objectClass="top" attr1="value1.1, value1.2" attr2="value two"
+objectClass="top" attr1="value1.1,value1.2" attr2="value two"
 .endd
-The &%extract%& operator in string expansions can be used to pick out
-individual fields from data that consists of &'key'&=&'value'& pairs. You can
+You can
 make use of Exim's &%-be%& option to run expansion tests and thereby check the
 results of LDAP lookups.
+The &%extract%& operator in string expansions can be used to pick out
+individual fields from data that consists of &'key'&=&'value'& pairs.
+.new
+The &%listextract%& operator should be used to pick out individual values
+of attributes, even when only a single value is expected.
+.wen
 
 
 
@@ -11664,7 +11673,7 @@ This variable is like &$message_headers$& except that no processing of the
 contents of header lines is done.
 
 .vitem &$message_id$&
-This is an old name for &$message_exim_id$&, which is now deprecated.
+This is an old name for &$message_exim_id$&. It is now deprecated.
 
 .vitem &$message_linecount$&
 .vindex "&$message_linecount$&"
@@ -16813,6 +16822,39 @@ If the expansion fails (other than forced failure) delivery is deferred. Some
 of the other precondition options are common special cases that could in fact
 be specified using &%condition%&.
 
+.new
+When originally designed, Exim's ACL system enforced very strict parsing
+of the &%condition%& expansion everywhere it was being processed.
+Through the 4.7x release cycle, the &%condition%& processing while in a
+router became more loose, internally adopting the use of &%bool_lax%&
+instead of the more rigid &%bool%&.  This is best illustrated in an
+example:
+.code
+# This used to fail with a syntax error, now it
+# treats any extra characters as a string
+
+$ exim -be '${if eq {${lc:GOOGLE.com}} {google.com}} {yes} {no}}'
+true {yes} {no}}
+
+$ exim -be '${if eq {${lc:WHOIS.com}} {google.com}} {yes} {no}}'
+ {yes} {no}}
+.endd
+In each example above, the &%if%& statement actually ends after
+&"{google.com}}"&.  Since no true or false braces were defined, the
+default &%if%& behavior is to return a boolean true or a null answer
+(which evaluates to false). The rest of the line is then treated as a
+string. So the first example resulted in the boolean answer &"true"&
+with the string &" {yes} {no}}"& appended to it. The second example
+resulted in the null output (indicating false) with the string
+&" {yes} {no}}"& appended to it.
+
+In fact you can put excess forward braces in too.  In the router
+&%condition%&, Exim's ACL parser only looks for &"{"& symbols when they
+mean something, like after a &"$"& or when required as part of a
+conditional.  But otherwise &"{"& and &"}"& are treated as ordinary
+string characters.
+.wen
+
 
 .option debug_print routers string&!! unset
 .cindex "testing" "variables in drivers"