new reader macros for shell- and Perl-style matching & replacement

Signed-off-by: Sean Whitton <spwhitton@spwhitton.name>

2 files changed, 55 insertions, 2 deletions

diff --git a/doc/news.rst b/doc/news.rst
index da40c27..80701d6 100644
--- a/doc/news.rst
+++ b/doc/news.rst
@@ -26,6 +26,9 @@ you should review this document and see if your consfig needs updating.
 1.3.0 (unreleased)
 ------------------
 
+- New reader macros ``#~m//`` and ``#~s///`` for shell- and Perl-style regular
+  expression matching and replacement.
+
 - New reader macro ``#>>EOF>>`` which is like ``#>EOF>`` except that it skips
   over the remainder of the current line and its newline.  This is more like
   how heredocs work in other languages.
@@ -57,8 +60,8 @@ you should review this document and see if your consfig needs updating.
   without having to read the source of properties modules.
 
 - New Emacs major mode, ``consfigurator-lisp-mode``.  This takes care of
-  informing Emacs that parts of the buffer are CL-INTERPOL and CL-HEREDOC
-  strings, fixing SLIME's C-c C-c in certain cases.
+  informing Emacs that parts of the buffer are CL-INTERPOL, CL-HEREDOC and our
+  ``#~m//`` and ``#~s///`` strings, fixing SLIME's C-c C-c in certain cases.
 
 1.2.2 (2023-02-20)
 ------------------
diff --git a/doc/reader.rst b/doc/reader.rst
index e6f9c3a..1d78cd2 100644
--- a/doc/reader.rst
+++ b/doc/reader.rst
@@ -22,6 +22,52 @@ Sharp-question mark is the well-known CL-INTERPOL_ reader macro.
 
 .. _CL-INTERPOL: https://edicl.github.io/cl-interpol/
 
+``#~m//``: PCRE matching
+------------------------
+
+This provides an abbreviation for shell- and Perl-style regexp matching:
+
+.. code-block:: none
+
+  (#~m/b.+b/i "FooBarBaz") => "BarB"
+  (#~m/b(.+)b/i "FooBarBaz") => #("ar")
+  (mapcar #3~m/(\w+)(\W+)(\w+)/ '("one two" "three four" "five six"))
+      => ("two" "four" "six")
+
+Any delimiters supported by ``CL-INTERPOL`` may be used, and the ``m`` is
+always optional.  Trailing options ``g``, ``i``, ``m``, ``s`` and ``x`` are
+meaningful.  The return value depends on the numeric argument before the
+tilde:
+
+- ``#~m//``, with no argument, returns a vector of the substrings
+  corresponding to the capture groups, or if there were no capture groups,
+  just the whole matched string.
+
+- ``#0~m//`` returns two values: the whole matched string, and a vector of
+  capture group substrings.  (This is plain ``CL-PPCRE:SCAN-TO-STRINGS``.)
+
+- ``#n~m//`` returns two values: the nth capture group's substring, and a
+  vector of all the capture group substrings.
+
+``#!~m//``: PCRE negative matching
+----------------------------------
+
+Equivalent to ``(not #~m//)``.
+
+``#~s///``: PCRE substitution
+-----------------------------
+
+This provides an abbreviation for shell- and Perl-style regexp substitution:
+
+.. code-block:: none
+
+  (#~s/foo/bar/ "foobarbaz") => "foofoobaz"
+  (mapcar #~s/:.+:/`\&`/ '(":Hello:" ":Goodbye:")) => ("`:Hello:`" "`:Goodbye:`")
+
+Again, any delimiters supported by ``CL-INTERPOL`` may be used, and the same
+trailing options are meaningful.  This is ``CL-PPCRE:REGEX-REPLACE`` or
+``CL-PPCRE:REGEX-REPLACE-ALL``, which see regarding return values.
+
 ``#>EOF>`` and ``#>>EOF>>``: Heredocs
 -------------------------------------
 
@@ -55,3 +101,7 @@ See also
 - `perlop(1) <https://perldoc.perl.org/perlop>`_
 
 - `inferior-shell <https://cliki.net/inferior-shell>`_
+
+- `Let Over Lambda ch. 4
+  <https://letoverlambda.com/index.cl/guest/chap4.html>`_, which originally
+  inspired ``#~m//`` and ``#~s///``.