utils: Improve docstring of 'substitute*' & co.

* guix/build/utils.scm (substitute): Clarify first sentence of
  docstring and add warning to the docstring about using '$' to match
  an end of line.
  (substitute*): Add warning to the docstring about using '$' to match
  an end of line.

Signed-off-by: Ludovic Courtès <ludo@gnu.org>
This commit is contained in:
Taylan Ulrich Bayırlı/Kammer 2014-11-25 21:52:13 +01:00 committed by Ludovic Courtès
parent 97e1120903
commit 094b2efc3c
1 changed files with 9 additions and 5 deletions

View File

@ -413,10 +413,11 @@ PROC's result is returned."
(false-if-exception (delete-file template)))))) (false-if-exception (delete-file template))))))
(define (substitute file pattern+procs) (define (substitute file pattern+procs)
"PATTERN+PROCS is a list of regexp/two-argument procedure. For each line "PATTERN+PROCS is a list of regexp/two-argument-procedure pairs. For each
of FILE, and for each PATTERN that it matches, call the corresponding PROC line of FILE, and for each PATTERN that it matches, call the corresponding
as (PROC LINE MATCHES); PROC must return the line that will be written as a PROC as (PROC LINE MATCHES); PROC must return the line that will be written as
substitution of the original line." a substitution of the original line. Be careful about using '$' to match the
end of a line; by itself it won't match the terminating newline of a line."
(let ((rx+proc (map (match-lambda (let ((rx+proc (map (match-lambda
(((? regexp? pattern) . proc) (((? regexp? pattern) . proc)
(cons pattern proc)) (cons pattern proc))
@ -476,7 +477,10 @@ When one of the MATCH-VAR is `_', no variable is bound to the corresponding
match substring. match substring.
Alternatively, FILE may be a list of file names, in which case they are Alternatively, FILE may be a list of file names, in which case they are
all subject to the substitutions." 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."
((substitute* file ((regexp match-var ...) body ...) ...) ((substitute* file ((regexp match-var ...) body ...) ...)
(let () (let ()
(define (substitute-one-file file-name) (define (substitute-one-file file-name)