X-Git-Url: https://git.distorted.org.uk/~mdw/exim-config/blobdiff_plain/185b5456076ca86959643ce2f19c98c0f82f281e..12d3b444e8703fb16cc4d8e9fe267d3d0aa11c6e:/defs.m4

diff --git a/defs.m4 b/defs.m4
index f9b3333..f2767fd 100644
--- a/defs.m4
+++ b/defs.m4
@@ -45,7 +45,7 @@ m4_divert(-1)
 m4_define(<:ONEOF:>, <:m4_ifelse(<:$#:>, <:1:>, <:$1:>,
 	<:$1:>, <::>, <:ONEOF(m4_shift($@)):>, <:$1:>):>)
 
-## DEFCONF(CONF, DEFAULT)
+## DEFCONF(conf, default)
 ##
 ## Define config variable CONF, assigning it the DEFAULT value if not
 ## overridden by `SETCONF'.
@@ -53,7 +53,7 @@ m4_define(<:DEFCONF:>,
 <:m4_ifdef(<:CONF_$1:>, <::>,
 <:m4_define(<:CONF_$1:>, <:$2:>):>):>)
 
-## SETCONF(CONF, VALUE)
+## SETCONF(conf, value)
 ##
 ## Set config variable VALUE.
 m4_define(<:SETCONF:>, <:m4_define(<:CONF_$1:>, <:$2:>):>)
@@ -73,10 +73,32 @@ m4_pushdef(<:_foreach_func:>, <:$1:>)m4_dnl
 _FOREACH($2)<::>m4_dnl
 m4_popdef(<:_foreach_func:>):>)
 
+## CLRSEP
+##
+## Clear the separator.  Use in conjunction with `SEP' below.
+m4_define(<:CLRSEP:>, <:m4_define(<:__sep:>, <::>):>)m4_dnl
+
+## SEP(newsep)
+##
+## Insert the current separator, and then set the separator to NEWSEP.  This
+## is handy in `FOREACH' loops, in order to separate the items with the
+## correct number of fenceposts: call `CLRSEP' before the list, and begin
+## each item with SEP(...).
+m4_define(<:SEP:>, <:__sep<::>m4_define(<:__sep:>, <:$1:>):>)m4_dnl
+
+## DIVERT(name)
+##
+## Make _div:NAME be the current diversion.
 m4_define(<:DIVERT:>, <:m4_dnl
 m4_divert(m4_indir(<:_div:$1:>))m4_dnl
 :>)
 
+## SECTION(name, [sub])
+##
+## Contribute the following text to section NAME, inserting appropriate
+## header text to the top of the section if necessary.  If a SUB-section name
+## is given, then the contribution is made to the subsection, and the
+## subsection's header (if any) is also inserted.
 m4_define(<:SECTION:>, <:m4_dnl
 DIVERT(<:$1:>)m4_dnl
 m4_ifdef(<:_done:$1:>, <::>, <:m4_dnl
@@ -90,6 +112,13 @@ m4_ifdef(<:_done:$1/$2:>, <::>, <:m4_dnl
 m4_ifdef(<:_head:$1/$2:>, <:<:##:> m4_indir(<:_head:$1/$2:>)
 :>)m4_define(<:_done:$1/$2:>):>):>):>)
 
+## LOOKUP_DOMAIN(dom, [if-found], [if-not-found])
+##
+## Look up DOM in the master domains file.  If it's found, put the
+## information found in `$value' and expand to IF-FOUND, which may use `KV'
+## to extract keyword values, and defaults to `$value'; otherwise, obey
+## IF-NOT-FOUND, which may be the token `fail', or replacement text in
+## braces.
 m4_define(<:LOOKUP_DOMAIN:>,
 	<:if exists{CONF_sysconf_dir/domains.conf} \
 	     {${lookup {$1}partial0-lsearch{CONF_sysconf_dir/domains.conf} \
@@ -98,7 +127,19 @@ m4_define(<:LOOKUP_DOMAIN:>,
 				 <:$2$3:>)}} \
 	     $3:>)
 
+## KV(key, result)
+##
+## Extract the value of the named KEY in the ${extract ...}-style string in
+## the current $value (where it may have been left by `LOOKUP-DOMAIN').  The
+## RESULT is a pair {IF-FOUND}{IF-NOT-FOUND}; the former may use $value to
+## refer to the value; the latter may be `fail' (not in braces) to force
+## expansion failure.
 m4_define(<:KV:>, <:${extract {$1}{$value}$2}:>)
+
+## DOMKV(key, result)
+##
+## Extract the value of the named KEY in the ${extract ...}-style string in
+## $domain_data; see `KV'.
 m4_define(<:DOMKV:>, <:${extract {$1}{$domain_data}$2}:>)
 
 m4_divert(999)m4_dnl