---
I think this covers the let function, but comments/suggestions are welcome in
case I missed something.
Regards,
- Jouke
doc/make.texi | 87 ++++++++++++++++++++++++++++++++++++++++++++-------
1 file changed, 75 insertions(+), 12 deletions(-)
diff --git a/doc/make.texi b/doc/make.texi
index 21573c0..f20f4fc 100644
--- a/doc/make.texi
+++ b/doc/make.texi
@@ -276,6 +276,7 @@ Functions for Transforming Text
* Text Functions:: General-purpose text manipulation functions.
* File Name Functions:: Functions for manipulating file names.
* Conditional Functions:: Functions that implement conditions.
+* Let Function:: Lexically scoped variables.
* Foreach Function:: Repeat some text with controlled variation.
* File Function:: Write text to a file.
* Call Function:: Expand a user-defined function.
@@ -7032,6 +7033,7 @@ be substituted.
* Text Functions:: General-purpose text manipulation functions.
* File Name Functions:: Functions for manipulating file names.
* Conditional Functions:: Functions that implement conditions.
+* Let Function:: Lexically scoped variables.
* Foreach Function:: Repeat some text with controlled variation.
* File Function:: Write text to a file.
* Call Function:: Expand a user-defined function.
@@ -7632,7 +7634,7 @@ the file names to refer to an existing file or directory.
Use the
@code{wildcard} function to test for existence.
@end table
-@node Conditional Functions, Foreach Function, File Name Functions, Functions
+@node Conditional Functions, Let Function, File Name Functions, Functions
@section Functions for Conditionals
@findex if
@cindex conditional expansion
@@ -7685,14 +7687,69 @@ the result of the expansion is the expansion of the
last argument.
@end table
-@node Foreach Function, File Function, Conditional Functions, Functions
+@node Let Function, Foreach Function, Conditional Functions, Functions
+@section The @code{let} Function
+@findex let
+@cindex variables, lexically scoped
+
+The @code{let} function provides a means to limit the scope of a variable.
+The substitution of a value bound to a name in a @code{let} expression
+happens only in the text within the lexical scope defined by the @code{let}
+expression.
+
+Additionally, the @code{let} function enables list unpackinging. In that
+regard, it resembles the @code{read} command in the shell, @code{sh}.
+
+The syntax of the @code{let} function is:
+
+@example
+$(let @var{var} [@var{var} ...],@var{list},@var{text})
+@end example
+
+@noindent
+The first two arguments, the @var{var} list and @var{list}, are expanded
+before anything else is done; note that the last argument, @var{text}, is
+@strong{not} expanded at the same time. Then, each word of the expanded
+value of @var{list} is bound to each of the variable names, @var{var}, in
+turn, with the final variable name being bound to the remainder of the
+expanded @var{list}. In other words, the first word of @var{list} is
+bound to the first variable @var{var}, the second word to the second
+variable @var{var}, and so on. If there are fewer words than there are
+@var{var} operands, the remaining @var{var}s are set to empty string. If
+there are fewer @var{var}s than words, the last @var{var} is set to what
+is left of the expanded @var{list} after the words bound to the earlier
+@var{var}s are removed. After all variables are thus bound, @var{text} is
+expanded.
+
+This macro reverses the order of the words in the list that it is given as
+its first argument:
+
+@example
+reverse = $(let first rest,$1,$(if $(rest),$(call reverse,$(rest)) )$(first))
+@end example
+
+The @var{first} and @var{rest} variables are no longer available after the
+macro is expanded. If variables by those names existed beforehand, they
+are not affected by the expansion of the @code{reverse} macro.
+
+The @code{let} function has no permanent effect on the variables
+@var{var}; their value and flavor after the @code{let} function call are
+the same as they were beforehand. The values which are taken from
+@var{list} are in effect only temporarily, during the execution of
+@code{let}. The variables @var{var} are simply-expanded variables
+during the execution of @code{let}. If @var{var} was undefined
+before the @code{foreach} function call, it is undefined after the call.
+@xref{Flavors, ,The Two Flavors of Variables}.@refill
+
+@node Foreach Function, File Function, Let Function, Functions
@section The @code{foreach} Function
@findex foreach
@cindex words, iterating over
-The @code{foreach} function is very different from other functions. It
-causes one piece of text to be used repeatedly, each time with a different
-substitution performed on it. It resembles the @code{for} command in the
+The @code{foreach} function is similar to the @code{let} function, but very
+different from other functions. It causes one piece of text to be used
+repeatedly, each time with a different substitution performed on it. The
+@code{foreach} function resembles the @code{for} command in the
shell @code{sh} and the @code{foreach} command in the C-shell @code{csh}.
The syntax of the @code{foreach} function is:
@@ -7751,13 +7808,14 @@ actual function call to be re-expanded under the
control of @code{foreach};
a simply-expanded variable would not do, since @code{wildcard} would be
called only once at the time of defining @code{find_files}.
-The @code{foreach} function has no permanent effect on the variable
-@var{var}; its value and flavor after the @code{foreach} function call are
-the same as they were beforehand. The other values which are taken from
-@var{list} are in effect only temporarily, during the execution of
-@code{foreach}. The variable @var{var} is a simply-expanded variable
-during the execution of @code{foreach}. If @var{var} was undefined
-before the @code{foreach} function call, it is undefined after the call.
+Like the @code{let} function, the @code{foreach} function has no permanent
+effect on the variable @var{var}; its value and flavor after the
+@code{foreach} function call are the same as they were beforehand. The
+other values which are taken from @var{list} are in effect only
+temporarily, during the execution of @code{foreach}. The variable
+@var{var} is a simply-expanded variable during the execution of
+@code{foreach}. If @var{var} was undefined before the @code{foreach}
+function call, it is undefined after the call.
@xref{Flavors, ,The Two Flavors of Variables}.@refill
You must take care when using complex variable expressions that result in
@@ -12397,6 +12455,11 @@ Return a string describing the flavor of the
@code{make} variable
@var{variable}.@*
@xref{Flavor Function, , The @code{flavor} Function}.
+@item $(let @var{var} [@var{var} ...],@var{words},@var{text})
+Evaluate @var{text} with the @var{var}s bound to the words in
+@var{words}.@*
+@xref{Let Function, ,The @code{let} Function}.
+
@item $(foreach @var{var},@var{words},@var{text})
Evaluate @var{text} with @var{var} bound to each word in @var{words},
and concatenate the results.@*
--
2.28.0
