A Scheme Crash Course (GNU Guix Cookbook)

1.1 A Scheme Crash Course

Guix uses the Guile implementation of Scheme. To start playing with the language, install it with guix install guile and start a REPL—short for read-eval-print loop—by running guile from the command line.

Alternatively you can also run guix shell guile -- guile if you’d rather not have Guile installed in your user profile.

In the following examples, lines show what you would type at the REPL; lines starting with “⇒” show evaluation results, while lines starting with “-|” show things that get printed. See Using Guile Interactively in GNU Guile Reference Manual, for more details on the REPL.

Scheme syntax boils down to a tree of expressions (or s-expression in Lisp lingo). An expression can be a literal such as numbers and strings, or a compound which is a parenthesized list of compounds and literals. #true and #false (abbreviated #t and #f) stand for the Booleans “true” and “false”, respectively.
Examples of valid expressions:
```
"Hello World!"
⇒ "Hello World!"

17
⇒ 17

(display (string-append "Hello " "Guix" "\n"))
-| Hello Guix!
⇒ #<unspecified>
```
This last example is a function call nested in another function call. When a parenthesized expression is evaluated, the first term is the function and the rest are the arguments passed to the function. Every function returns the last evaluated expression as its return value.
Anonymous functions—procedures in Scheme parlance—are declared with the lambda term:
```
(lambda (x) (* x x))
⇒ #<procedure 120e348 at <unknown port>:24:0 (x)>
```
The above procedure returns the square of its argument. Since everything is an expression, the lambda expression returns an anonymous procedure, which can in turn be applied to an argument:
```
((lambda (x) (* x x)) 3)
⇒ 9
```
Procedures are regular values just like numbers, strings, Booleans, and so on.

Anything can be assigned a global name with define:

(define a 3)
(define square (lambda (x) (* x x)))
(square a)
⇒ 9

Procedures can be defined more concisely with the following syntax:
```
(define (square x) (* x x))
```
A list structure can be created with the list procedure:
```
(list 2 a 5 7)
⇒ (2 3 5 7)
```

Standard procedures are provided by the (srfi srfi-1) module to create and process lists (see list processing in GNU Guile Reference Manual). Here are some of the most useful ones in action:

(use-modules (srfi srfi-1))  ;import list processing procedures

(append (list 1 2) (list 3 4))
⇒ (1 2 3 4)

(map (lambda (x) (* x x)) (list 1 2 3 4))
⇒ (1 4 9 16)

(delete 3 (list 1 2 3 4))        ⇒ (1 2 4)
(filter odd? (list 1 2 3 4))     ⇒ (1 3)
(remove even? (list 1 2 3 4))    ⇒ (1 3)
(find number? (list "a" 42 "b")) ⇒ 42

Notice how the first argument to map, filter, remove, and find is a procedure!

The 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 (see quote in GNU Guile Reference Manual). Thus it effectively returns a list of terms.
```
'(display (string-append "Hello " "Guix" "\n"))
⇒ (display (string-append "Hello " "Guix" "\n"))

'(2 a 5 7)
⇒ (2 a 5 7)
```
The quasiquote (`, a backquote) disables evaluation of a parenthesized expression until unquote (,, a comma) re-enables it. Thus it provides us with fine-grained control over what is evaluated and what is not.
```
`(2 a 5 7 (2 ,a 5 ,(+ a 4)))
⇒ (2 a 5 7 (2 3 5 7))
```
Note that the above result is a list of mixed elements: numbers, symbols (here a) and the last element is a list itself.

Guix defines a variant of S-expressions on steroids called G-expressions or “gexps”, which come with a variant of quasiquote and unquote: #~ (or gexp) and #$ (or ungexp). They let you 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:

(use-modules (guix gexp)           ;so we can write gexps
             (gnu packages base))  ;for 'coreutils'

;; 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))

See G-Expressions in GNU Guix Reference Manual, for more on gexps.

Multiple variables can be named locally with let (see Local Bindings in GNU Guile Reference Manual):

(define x 10)
(let ((x 2)
      (y 3))
  (list x y))
⇒ (2 3)

x
⇒ 10

y
error→ In procedure module-lookup: Unbound variable: y

Use let* to allow later variable declarations to refer to earlier definitions.

(let* ((x 2)
       (y (* x 3)))
  (list x y))
⇒ (2 6)

Keywords are typically used to identify the named parameters of a procedure. They are prefixed by #: (hash, colon) followed by alphanumeric characters: #:like-this. See Keywords in GNU Guile Reference Manual.
The percentage % is typically used for read-only global variables in the build stage. Note that it is merely a convention, like _ in C. Scheme treats % exactly the same as any other letter.
Modules are created with define-module (see Creating Guile Modules in GNU Guile Reference Manual). For instance
```
(define-module (guix build-system ruby)
  #:use-module (guix store)
  #:export (ruby-build
            ruby-build-system))
```
defines the module guix build-system ruby which must be located in guix/build-system/ruby.scm somewhere in the Guile load path. It depends on the (guix store) module and it exports two variables, ruby-build and ruby-build-system.

See Package Modules in GNU Guix Reference Manual, for info on modules that define packages.

Going further: Scheme is a language that has been widely used to teach programming and you’ll find plenty of material using it as a vehicle. Here’s a selection of documents to learn more about Scheme:
A Scheme Primer, by Christine Lemmer-Webber and the Spritely Institute.
Scheme at a Glance, by Steve Litt.
Structure and Interpretation of Computer Programs, by Harold Abelson and Gerald Jay Sussman, with Julie Sussman. Colloquially known as “SICP”, this book is a reference.
You can also install it and read it from your computer:
guix install sicp info-reader
info sicp
You’ll find more books, tutorials and other resources at https://schemers.org/.