Acl expansions: tests and documentation

3 files changed, 37 insertions, 9 deletions

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index 29aacf61c..eb5bd4cba 100644
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -8764,14 +8764,15 @@ expansion item below.
 .cindex "&%acl%&" "call from expansion"
 The name and zero to nine argument strings are first expanded separately.  The expanded
 arguments are assigned to the variables &$acl_arg1$& to &$acl_arg9$& in order.
-Any used are made empty.  The variable &$acl_narg$& is set to the number of
+Any unused are made empty.  The variable &$acl_narg$& is set to the number of
 arguments.  The named ACL (see chapter &<<CHAPACL>>&) is called
 and may use the variables; if another acl expansion is used the values
 are overwritten.  If the ACL sets
-a value using a "message =" modifier and returns accept, the value becomes
+a value using a "message =" modifier and returns accept or deny, the value becomes
 the result of the expansion.
-If no message was set but the ACL returned accept, or if the ACL returned defer,
-the value is an empty string.  Otherwise the expansion fails.
+If no message was set and the ACL returned accept or deny
+the value is an empty string.
+If the ACL returned defer the result is a forced-fail.  Otherwise the expansion fails.
 
 
 .vitem "&*${dlfunc{*&<&'file'&>&*}{*&<&'function'&>&*}{*&<&'arg'&>&*}&&&
@@ -10059,6 +10060,21 @@ In all cases, a relative comparator OP is testing if <&'string1'&> OP
 10M, not if 10M is larger than &$message_size$&.
 
 
+.vitem &*acl&~{{*&<&'name'&>&*}{*&<&'arg1'&>&*}&&&
+	{*&<&'arg2'&>&*}...}*&
+.cindex "expansion" "calling an acl"
+.cindex "&%acl%&" "expansion condition"
+The name and zero to nine argument strings are first expanded separately.  The expanded
+arguments are assigned to the variables &$acl_arg1$& to &$acl_arg9$& in order.
+Any unused are made empty.  The variable &$acl_narg$& is set to the number of
+arguments.  The named ACL (see chapter &<<CHAPACL>>&) is called
+and may use the variables; if another acl expansion is used the values
+are overwritten.  If the ACL sets
+a value using a "message =" modifier the variable $value becomes
+the result of the expansion, otherwise it is empty.
+If the ACL returns accept the condition is true; if deny, false.
+If the ACL returns defer the result is a forced-fail.
+
 .vitem &*bool&~{*&<&'string'&>&*}*&
 .cindex "expansion" "boolean parsing"
 .cindex "&%bool%& expansion condition"
@@ -27301,6 +27317,7 @@ The conditions are as follows:
 .vitem &*acl&~=&~*&<&'name&~of&~acl&~or&~ACL&~string&~or&~file&~name&~'&>
 .cindex "&ACL;" "nested"
 .cindex "&ACL;" "indirect"
+.cindex "&ACL;" "arguments"
 .cindex "&%acl%& ACL condition"
 The possible values of the argument are the same as for the
 &%acl_smtp_%&&'xxx'& options. The named or inline ACL is run. If it returns
@@ -27310,6 +27327,10 @@ condition is on a &%warn%& verb. In that case, a &"defer"& return makes the
 condition false. This means that further processing of the &%warn%& verb
 ceases, but processing of the ACL continues.
 
+If the argument is a named ACL, up to nine space-separated optional values
+can be appended; they appear in $acl_arg1 to $acl_arg9, and $acl_narg is set
+to the count of values.  The name and values are expanded separately.
+
 If the nested &%acl%& returns &"drop"& and the outer condition denies access,
 the connection is dropped. If it returns &"discard"&, the verb must be
 &%accept%& or &%discard%&, and the action is taken immediately &-- no further
diff --git a/doc/doc-txt/ChangeLog b/doc/doc-txt/ChangeLog
index 504c3f551..9dbc65c09 100644
--- a/doc/doc-txt/ChangeLog
+++ b/doc/doc-txt/ChangeLog
@@ -44,7 +44,9 @@ NM/01 Bugzilla 1197 - Spec typo
 
 JH/03 Add expansion operators ${listnamed:name} and ${listcount:string}
 
-JH/04 Add expansion item ${acl {name}{arg}...}
+JH/04 Add expansion item ${acl {name}{arg}...}, expansion condition
+      "acl {{name}{arg}...}", and optional args on acl condition
+      "acl = name arg..."
 
 Exim version 4.80
 -----------------
diff --git a/doc/doc-txt/NewStuff b/doc/doc-txt/NewStuff
index 3c5c4913b..df2ede807 100644
--- a/doc/doc-txt/NewStuff
+++ b/doc/doc-txt/NewStuff
@@ -87,10 +87,15 @@ Version 4.81
  8. New expansion operators ${listnamed:name} to get the content of a named list
     and ${listcount:string} to count the items in a list.
 
- 9. New expansion item ${acl {name}{arg}...} to call an ACL.  The argument can
-    be accessed by the ACL in $acl_arg1 to $acl_arg9.  $acl_narg will be the
-    number of arguments. The expansion result is set by a "message =" modifier
-    and an "accept" return from the ACL.
+ 9. The "acl = name" condition on an ACL now supports optional arguments.
+    New expansion item "${acl {name}{arg}...}" and expansion condition
+    "acl {{name}{arg}...}" are added.  In all cases up to nine arguments
+    can be used, appearing in $acl_arg1 to $acl_arg9 for the called ACL.
+    Variable $acl_narg contains the number of arguments.  If the ACL sets
+    a "message =" value this becomes the result of the expansion item,
+    or the value of $value for the expansion condition.  If the ACL returns
+    accept the expansion condition is true; if reject, false.  A defer
+    return results in a forced fail.
 
 Version 4.80
 ------------