aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorLudovic Courtès <ludo@gnu.org>2023-07-14 16:15:38 +0200
committerLudovic Courtès <ludo@gnu.org>2023-07-14 16:16:25 +0200
commita33a335c89ce3766e2bd662bffc897bd0da2b9cd (patch)
tree8da4b7dbae9805a77c7e2efde030b96694a8099c /doc
parentff4f5a725e2888c1443b50d97d90ad575a59c335 (diff)
downloadguix-a33a335c89ce3766e2bd662bffc897bd0da2b9cd.tar.gz
guix-a33a335c89ce3766e2bd662bffc897bd0da2b9cd.zip
doc: Mention gexps in the "Scheme Crash Course".
* doc/guix-cookbook.texi (A Scheme Crash Course): Add note on gexps.
Diffstat (limited to 'doc')
-rw-r--r--doc/guix-cookbook.texi47
1 files changed, 40 insertions, 7 deletions
diff --git a/doc/guix-cookbook.texi b/doc/guix-cookbook.texi
index b3c3bac971..2e58c6c795 100644
--- a/doc/guix-cookbook.texi
+++ b/doc/guix-cookbook.texi
@@ -234,10 +234,11 @@ A list structure can be created with the @code{list} procedure:
@end lisp
@item
-The @dfn{quote} disables evaluation of a parenthesized expression: the
-first term is not called over the other terms (@pxref{Expression Syntax,
-quote,, guile, GNU Guile Reference Manual}). Thus it effectively
-returns a list of terms.
+@cindex S-expression
+The @dfn{quote} disables evaluation of a parenthesized expression, also
+called an S-expression or ``s-exp'': the first term is not called over
+the other terms (@pxref{Expression Syntax, quote,, guile, GNU Guile
+Reference Manual}). Thus it effectively returns a list of terms.
@lisp
'(display (string-append "Hello " "Guix" "\n"))
@@ -248,9 +249,10 @@ returns a list of terms.
@end lisp
@item
-The @dfn{quasiquote} disables evaluation of a parenthesized expression
-until @dfn{unquote} (a comma) re-enables it. Thus it provides us with
-fine-grained control over what is evaluated and what is not.
+The @code{quasiquote} (@code{`}, a backquote) disables evaluation of a
+parenthesized expression until @code{unquote} (@code{,}, a comma)
+re-enables it. Thus it provides us with fine-grained control over what
+is evaluated and what is not.
@lisp
`(2 a 5 7 (2 ,a 5 ,(+ a 4)))
@@ -261,6 +263,37 @@ Note that the above result is a list of mixed elements: numbers, symbols (here
@code{a}) and the last element is a list itself.
@item
+@cindex G-expressions, syntax
+@cindex gexps, syntax
+@findex #~
+@findex #$
+@findex gexp
+@findex ungexp
+Guix defines a variant of S-expressions on steroids called
+@dfn{G-expressions} or ``gexps'', which come with a variant of
+@code{quasiquote} and @code{unquote}: @code{#~} (or @code{gexp}) and
+@code{#$} (or @code{ungexp}). They let you @emph{stage code for later
+execution}.
+
+For example, you'll encounter gexps in some package definitions where
+they provide code to be executed during the package build process. They
+look like this:
+
+@lisp
+;; Below is a G-expression representing staged code.
+#~(begin
+ ;; Invoke 'ls' from the package defined by the 'coreutils'
+ ;; variable.
+ (system* #$(file-append coreutils "/bin/ls") "-l")
+
+ ;; Create this package's output directory.
+ (mkdir #$output))
+@end lisp
+
+@xref{G-Expressions,,, guix, GNU Guix Reference Manual}, for more on
+gexps.
+
+@item
Multiple variables can be named locally with @code{let} (@pxref{Local
Bindings,,, guile, GNU Guile Reference Manual}):