- clean up (and clean up documentation for) matching functions

1 files changed, 30 insertions, 24 deletions

diff --git a/doc/format-specifiers.txt b/doc/format-specifiers.txt
index 1e3afa5..767de5c 100644
--- a/doc/format-specifiers.txt
+++ b/doc/format-specifiers.txt
@@ -43,7 +43,8 @@ directory.
 Additionally, several built-in "function"s are available for importing
 values from other entries and combining them with data from the current
 entry.  Generally, function invocations look like this:
-  %function(ARG1[,...])
+
+  %function(ARG[,...])
 
 A function invocation uses a comma-separated list of double-quoted
 arguments.  Any arguments which themselves contain a double-quote need
@@ -62,15 +63,17 @@ Evaluates ''EXPRESSION'', and if one or more values is produced,
 provides only the first value.  (Here, ''first'' refers to the first
 value in the list of values after they've been sorted.)  If no values
 result, then ''DEFAULT'' is evaluated as an expression and its result is
-provided.
+provided.  Nothing is done to ensure that ''DEFAULT'' provides only one
+value, however.
 
 === match ===
 
   match(''EXPRESSION'',''PATTERN''[,''DEFAULT''])
 
-Selects the value of ''EXPRESSION'' which matches the globbing pattern
-''PATTERN''.  If no values match, and a ''DEFAULT'' was specified, the
-''DEFAULT'' is evaluated as an expression and its result is provided.
+Selects the single value of ''EXPRESSION'' which matches the globbing
+pattern ''PATTERN''.  If no value matches, and a ''DEFAULT'' was
+specified, then ''DEFAULT'' is evaluated as an expression and its value
+is provided.
 
 Here's an example entry:
 
@@ -80,12 +83,12 @@ Here's an example entry:
 
 And here's how it evaluates out:
 
-  %match("%{member}","b*")       -> bob
-  %match("%{member}","d*")       -> dave
-  %match("%{member}","e*")        FAILS
-  %match("%{member}","e*","jim") -> jim
-  %match("%{member}","*","jim")  -> jim (when a single value is required)
-  %match("%{member}","*","jim")  -> (bob,dave) (when a list is acceptable)
+  %match("%{member}","b*")        -> bob
+  %match("%{member}","d*")        -> dave
+  %match("%{member}","e*")        no value
+  %match("%{member}","*e*")       -> dave
+  %match("%{member}","e*","jim")  -> jim
+  %match("%{member}","*","%{cn}") -> group
 
 === regmatch ===
 
@@ -93,7 +96,8 @@ And here's how it evaluates out:
 
 Selects the value of ''EXPRESSION'' which matches the extended regular
 expression ''PATTERN''.  If no values match, and a ''DEFAULT'' was
-specified, the ''DEFAULT'' is produced.
+specified, then ''DEFAULT'' is evaluated as an expression and its value
+is produced.
 
 Here's an example entry:
 
@@ -106,21 +110,23 @@ And here's how it evaluates out:
   %regmatch("%{member}","^b.*")       -> bob
   %regmatch("%{member}","^d.*")       -> dave
   %regmatch("%{member}","e")          -> dave
-  %regmatch("%{member}","^e")          FAILS
+  %regmatch("%{member}","^e")         no value
   %regmatch("%{member}","^e.*","jim") -> jim
-  %regmatch("%{member}",".*","jim")   -> jim (when a single value is required)
-  %regmatch("%{member}",".*","jim")   -> (bob,dave) (when a list is acceptable)
+  %regmatch("%{member}",".*","%{cn}") -> group
 
 === regsub ===
 
   regsub(''EXPRESSION'',''PATTERN'',''TEMPLATE''[,''DEFAULT''])
 
-Selects the value of EXPRESSION which matches the extended regular
-expression PATTERN and uses TEMPLATE to construct the result.  If no
-values match, and a DEFAULT was specified, the DEFAULT is produced,
-otherwise an error occurs.  The template is used to construct a result
-using the n'th substring from the matched value by using the sequence
-"%n" in the template.
+Selects the value of ''EXPRESSION'' which matches the extended regular
+expression ''PATTERN'' and uses ''TEMPLATE'' to build the result.  If no
+values match, and a ''DEFAULT'' was specified, then ''DEFAULT'' is
+evaluated as an expression and its value is produced, otherwise an error
+occurs.
+
+The template is treated as a literal value, but is allowed to
+incorporate the n'th substring (one of the first nine) from the matched
+value by including the sequence "%n" in the template.
 
 Here's an example entry:
 
@@ -132,11 +138,11 @@ And here's how it evaluates out:
 
   %regsub("%{member}","o","%0")          -> bob
   %regsub("%{member}","o","%1")          -> 
-  %regsub("%{member}","^o","%0")         FAILS
+  %regsub("%{member}","^o","%0")         no value
   %regsub("%{member}","^d(.).*","%1")    -> a
   %regsub("%{member}","^(.*)e","t%1y")   -> tdavy
-  %regsub("%{member}","^e","%1")         FAILS
-  %regsub("%{member}","^e","%1","jim")   -> jim
+  %regsub("%{member}","^o","%0","jim")   -> jim
+  %regsub("%{member}","^o","%0","%{cn}") -> group
 
 === deref ===