Document and unit-test regex-capture reset logic

docs/src/reference-main-regular-expressions.md.in

@@ -78,6 +78,46 @@ GENMD-EOF
 
 * Up to nine matches are supported: `\1` through `\9`, while `\0` is the entire match string; `\15` is treated as `\1` followed by an unrelated `5`.
 
+## Resetting captures
+
+If you use `(...)` in your regular expression, then up to 9 matches are supported for the `=~`
+operator, and an arbitrary number of matches are supported for the `match` DSL function.
+
+* Before any match is done, `"\1"` etc. in a string evaluate to themselves. 
+* After a successful match is done, `"\1"` etc. in a string evaluate to the matched substring.
+* After an unsuccessful match is done, `"\1"` etc. in a string evaluate to the empty string.
+* You can match against `null` to reset to the original state.
+
+GENMD-CARDIFY-HIGHLIGHT-ONE
+mlr repl
+
+[mlr] "\1:\2"
+"\1:\2"
+
+[mlr] "abc" =~ "..."
+true
+
+[mlr] "\1:\2"
+":"
+
+[mlr] "abc" =~ "(.).(.)"
+true
+
+[mlr] "\1:\2"
+"a:c"
+
+[mlr] "abc" =~ "(.)x(.)"
+false
+
+[mlr] "\1:\2"
+":"
+
+[mlr] "abc" =~ null
+
+[mlr] "\1:\2"
+"\1:\2"
+GENMD-EOF
+
 ## More information
 
 Regular expressions are those supported by the [Go regexp package](https://pkg.go.dev/regexp), which in turn are of type [RE2](https://github.com/google/re2/wiki/Syntax) except for `\C`:

test/cases/dsl-regex-matching/null-reset/cmd

@@ -0,0 +1 @@
+mlr -n put -f ${CASEDIR}/mlr

test/cases/dsl-regex-matching/null-reset/expout

@@ -0,0 +1,9 @@
+[\1]:[\2]
+true
+[]:[]
+true
+[a]:[c]
+false
+[]:[]
+null
+[\1]:[\2]

test/cases/dsl-regex-matching/null-reset/mlr

@@ -0,0 +1,11 @@
+end {
+  print("[\1]:[\2]");
+  print("abc" =~ "...");
+  print("[\1]:[\2]");
+  print("abc" =~ "(.).(.)");
+  print("[\1]:[\2]");
+  print("abc" =~ "(.)x(.)");
+  print("[\1]:[\2]");
+  print("abc" =~ null);
+  print("[\1]:[\2]");
+}