[bug#62814] [PATCH] Clarify substitute* docstring with an additional example

["Wicki Gabriel (wicg)" <wicg@zhaw.ch>]

[-- Attachment #1.1: Type: text/plain, Size: 215 bytes --]

Hello

I've created this little patch after wondering how to match (and substitute*) against end-of-line. My patch is based on
982698c52fb388e278dc4cec4b124406f23f102a.

Thanks for review and merge.

gabber

[-- Attachment #1.2: Type: text/html, Size: 1696 bytes --]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-guix-build-utils-Clarify-substitute-docstring-with-a.patch --]
[-- Type: text/x-patch; name="0001-guix-build-utils-Clarify-substitute-docstring-with-a.patch", Size: 1691 bytes --]

From 5ae3c5512e85189a47c859c6128adfd3bfc63159 Mon Sep 17 00:00:00 2001
From: Gabriel Wicki <gabriel@erlikon.ch>
Date: Thu, 13 Apr 2023 10:31:57 +0200
Subject: [PATCH] guix: build: utils: Clarify substitute* docstring with an
 example.

* guix/build/utils.scm (substitute*):  Add an example on how to match
end-of-line.
* doc/guix.texi (Build Utilities): Update the corresponding passage.
---
 doc/guix.texi        | 3 ++-
 guix/build/utils.scm | 3 ++-
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index acb6f0c2e1..71fa9f1dea 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -10321,7 +10321,8 @@ Alternatively, @var{file} may be a list of file names, in which case
 they are all subject to the substitutions.
 
 Be careful about using @code{$} to match the end of a line; by itself it
-won't match the terminating newline of a line.
+won't match the terminating newline of a line, e.g. to match a whole
+line ending with a backslash, one needs a regex like @code{"(.*)\\\\\n$"}.
 @end defmac
 
 @subsection File Search
diff --git a/guix/build/utils.scm b/guix/build/utils.scm
index dd5a91f52f..6add9afc1b 100644
--- a/guix/build/utils.scm
+++ b/guix/build/utils.scm
@@ -957,7 +957,8 @@ (define-syntax substitute*
 all subject to the substitutions.
 
 Be careful about using '$' to match the end of a line; by itself it won't
-match the terminating newline of a line."
+match the terminating newline of a line, e.g. to match a whole line ending
+with a backslash, one needs a regex like \"(.*)\\\\\n$\"."
     ((substitute* file ((regexp match-var ...) body ...) ...)
      (let ()
        (define (substitute-one-file file-name)
-- 
2.39.2