Merge branch 'master_condition_description'

[users/jgh/exim.git] / doc / doc-docbook / spec.xfpt

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index 4d620a36f98652c710df9db0a8b7182858bf5bf2..2a52666f67ead87359331d2619809abb437e5c97 100644 (file)
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -7346,22 +7346,25 @@ 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.
 
+.new
 Here are some examples of the output format. The first line of each pair is an
 LDAP query, and the second is the data that is returned. The attribute called
-&%attr1%& has two values, whereas &%attr2%& has only one value:
+&%attr1%& has two values, one of them with an embedded comma, 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
+.wen
 You can
 make use of Exim's &%-be%& option to run expansion tests and thereby check the
 results of LDAP lookups.
@@ -7370,6 +7373,8 @@ 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.
+The doubling of embedded commas allows you to use the returned data as a
+comma separated list (using the "<," syntax for changing the input list separator).
 .wen
 
 
@@ -16823,15 +16828,18 @@ 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:
+Historical note: We have &%condition%& on ACLs and on Routers.  Routers
+are far older, and use one set of semantics.  ACLs are newer and when
+they were created, the ACL &%condition%& process was given far stricter
+parse semantics.  The &%bool{}&% expansion condition uses the same rules as
+ACLs.  The &%bool_lax{}%& expansion condition uses the same rules as
+Routers.  More pointedly, the &%bool_lax{}%& was written to match the existing
+Router rules processing behavior.
+
+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
+# If used in an ACL condition will fail with a syntax error, but
+# in a router condition any extra characters are treated as a string
 
 $ exim -be '${if eq {${lc:GOOGLE.com}} {google.com}} {yes} {no}}'
 true {yes} {no}}
@@ -16849,10 +16857,16 @@ 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
+&%condition%&, Exim's 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.
+
+Thus, in a Router, the above expansion strings will both always evaluate
+true, as the result of expansion is a non-empty string which doesn't
+match an explicit false value.  This can be tricky to debug.  By
+contrast, in an ACL either of those strings will always result in an
+expansion error because the result doesn't look sufficiently boolean.
 .wen