Expansions: new ${lheader:<name>}. Bug 2272

3 files changed, 26 insertions, 1 deletions

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index f865fc9a1..0d6c23907 100644
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -9434,11 +9434,14 @@ letters appear. For example:
         &*$h_*&<&'header&~name'&>&*:*&" &&&
        "&*$bheader_*&<&'header&~name'&>&*:*&&~or&~&&&
         &*$bh_*&<&'header&~name'&>&*:*&" &&&
+       "&*$lheader_*&<&'header&~name'&>&*:*&&~or&~&&&
+        &*$lh_*&<&'header&~name'&>&*:*&"
        "&*$rheader_*&<&'header&~name'&>&*:*&&~or&~&&&
         &*$rh_*&<&'header&~name'&>&*:*&"
 .cindex "expansion" "header insertion"
 .vindex "&$header_$&"
 .vindex "&$bheader_$&"
+.vindex "&$lheader_$&"
 .vindex "&$rheader_$&"
 .cindex "header lines" "in expansion strings"
 .cindex "header lines" "character sets"
@@ -9451,7 +9454,7 @@ The newline that terminates a header line is not included in the expansion, but
 internal newlines (caused by splitting the header line over several physical
 lines) may be present.
 
-The difference between &%rheader%&, &%bheader%&, and &%header%& is in the way
+The difference between the four pairs of expansions is in the way
 the data in the header line is interpreted.
 
 .ilist
@@ -9460,6 +9463,15 @@ the data in the header line is interpreted.
 processing at all, and without the removal of leading and trailing white space.
 
 .next
+.cindex "list" "of header lines"
+&%lheader%& gives a colon-separated list, one element per header when there
+are multiple headers with a given name.
+Any embedded colon characters within an element are doubled, so normal Exim
+list-processing facilities can be used.
+The terminating newline of each element is removed; in other respects
+the content is &"raw"&.
+
+.next
 .cindex "base64 encoding" "in header lines"
 &%bheader%& removes leading and trailing white space, and then decodes base64
 or quoted-printable MIME &"words"& within the header text, but does no
diff --git a/doc/doc-txt/NewStuff b/doc/doc-txt/NewStuff
index 30ec7c981..aaf9734f0 100644
--- a/doc/doc-txt/NewStuff
+++ b/doc/doc-txt/NewStuff
@@ -9,6 +9,11 @@ the documentation is updated, this file is reduced to a short list.
 Version 4.92
 --------------
 
+ 1. ${l_header:<name>} and ${l_h:<name>} expansion items, giving a colon-sep
+    list when there are multiple headers having a given name.  This matters
+    when individual headers are wrapped onto multiple lines; with previous
+    facilities hard to parse.
+
 Version 4.91
 --------------
 
diff --git a/doc/doc-txt/experimental-spec.txt b/doc/doc-txt/experimental-spec.txt
index ac3f1cc23..15df15267 100644
--- a/doc/doc-txt/experimental-spec.txt
+++ b/doc/doc-txt/experimental-spec.txt
@@ -801,6 +801,14 @@ There are three new variables: $arc_state, $arc_state_reason, $arc_domains:
 			problematic elements may have empty list elements
   $arc_oldest_pass	lowest passing instance number of chain
 
+Example:
+  logwrite = oldest-p-ams: <${reduce {$lh_ARC-Authentication-Results:} \
+				{} \
+				{${if = {$arc_oldest_pass} \
+					{${extract {i}{${extract {1}{;}{$item}}}}} \
+					{$item} {$value}}} \
+			    }>
+
 Receive log lines for an ARC pass will be tagged "ARC".