Getting started#
Meeting the Scheme sandbox#
The Scheme “sandbox” is a convenient way to explore Scheme and do quick tests. It is an “interactive prompt”, or Read-Eval-Print-Loop. Unlike a LilyPond file, where the contained Scheme code is read and executed in batch, a Read-Eval-Print-Loop works interactively, by asking for an expression, evaluating it, and printing the result back. This is much like a pocket calculator.
To fire up the Scheme sandbox, you first need to open a terminal. On Linux, I trust you to do that. Under macOS, you need to launch the “Terminal” application. Under Windows, open whichever folder in the file explorer, and select “Windows Powershell” in the File menu.
In your terminal, run this command:
/full/path/to/lilypond-x.y.z/bin/lilypond scheme-sandbox
or, on Windows:
C:\full\path\to\lilypond-x.y.z\bin\lilypond scheme-sandbox
In either case, you should replace the path with the full path to the directory
where you placed LilyPond when you set it up. (If you installed LilyPond through
a package manager or otherwise have LilyPond in your search path, you can just
use lilypond scheme-sandbox.)
This command should give you either a screen like this:
GNU LilyPond 2.24.1 (running Guile 2.2)
Processing `.../share/lilypond/2.24.1/ly/scheme-sandbox.ly'
Parsing...
GNU Guile 2.2.7
Copyright (C) 1995-2019 Free Software Foundation, Inc.
Guile comes with ABSOLUTELY NO WARRANTY; for details type `,show w'.
This program is free software, and you are welcome to redistribute it
under certain conditions; type `,show c' for details.
Enter `,help' for help.
scheme@(#{ g100}#)>
The line scheme@... indicates that Guile is here, ready to listen to your
requests. You can enter a code snippet, and it will evaluate it. Let us start
with the simplest of snippets: a number.
guile> 42
42
Remember how I said the sandbox was like a calculator? You typed 42, and since indeed the value of this number is 42, the interpreter answers back 42. Now let us write a more interesting computation (the syntax used will be explained soon):
guile> (+ 42 5)
47
Here, we computed 42+5, of which the result is 47.
While you follow this tutorial, you can paste code examples in the sandbox and play around with variants of these examples. In the rest of this text, by convention, the symbol “⇒” is used to denote the value of an expression. Suppose I write:
(+ 42 5)
⇒ 47
By this, I mean that with the code (+ 42 5), you will get the result 47. In
particular, if you want to test yourself, you can type (+ 42 5) in the
sandbox, and it will answer 47. Note that the same convention is used in Guile’s
own manual.
To exit the sandbox, enter (quit), or more simply, press Control-D.
To finish this introduction to the Scheme sandbox, I need to mention a detail
that you may have found annoying if you have already started typing some
examples in the sandbox. If you try to delete characters, it may not work and
print strange characters. This can be worked around by installing the
rlwrap program, and by using the command
rlwrap ...lilypond scheme-sandbox instead of ...lilypond scheme-sandbox. On
GNU/Linux, rlwrap is likely present in your distribution’s packages. Under
macOS, you can install it via Homebrew or MacPorts. Under Windows, it is likely
possible to install it through Cygwin, if you feel bold (not for UNIX newbies).
Inserting Scheme code in a LilyPond file#
About anywhere in a LilyPond file, you can switch to Scheme mode by writing a hash, the “#” character. This reads one complete Scheme expression, and hands you back to LilyPond when this expression is over. Here are some common examples:
#(set-global-staff-size 18)
\markup \vspace #5
\shape #'((0 . 0) (0.1 . 0.3) (0.1 . 0.5) (0 . 1.0)) Slur
Scheme is often used to input values, such as the argument 5 to
\markup \vspace, or the list of offsets passed to \shape. If you type these
values in a Scheme expression that is not passed to LilyPond but just written on
the top-level, it is usually just lost, unlike the sandbox, which prints them.
For example, this minimal LilyPond file produces neither graphical output, nor a
message in the log file:
#'((0 . 0) (0.1 . 0.3) (0.1 . 0.5) (0 . 1.0))
It is possible to force a value to be printed by calling the display function
on it. This is used like this; the syntax will become clear later.
#(display '((0 . 0) (0.1 . 0.3) (0.1 . 0.5) (0 . 1.0)))
Within Scheme code, it is even possible to switch back to LilyPond mode in order
to input some value in LilyPond syntax. This is done by enclosing the LilyPond
code within #{ and #}. For example:
#(skip-of-length #{ { c'8 d' e' f' e' d' } #})
Literals#
This part deals with how to input values of frequently used types, those that typical LilyPond users will meet often.
Let’s start with the beginning: numbers. They are written in Scheme just like in English:
5
⇒ 5
-10
⇒ -10
Non-integer numbers can be entered using a dot. This sort of number is generally called a floating-point number in computer science.
5.3
⇒ 5.3
-10.42
⇒ -10.42
Another common type is strings, which represent text as a sequence of characters. They are input between straight double quotes.
"Sonata IV"
⇒ "Sonata IV"
They can contain newlines.
"Twinkle, twinkle, little star
How I wonder what you are"
⇒ "Twinkle, twinkle, little star
How I wonder what you are"
You can also indicate a newline character using \n. Both forms are strictly
equivalent.
"Twinkle, twinkle, little star\nHow I wonder what you are"
⇒ "Twinkle, twinkle, little star
How I wonder what you are"
If the string contains an actual double quote character, you need to “escape” it using a backslash, so that it is not interpreted as the end of the string.
"Rondo \"alla turca\""
⇒ "Rondo \"alla turca\""
In order to print a string, you can call the display function on it.
(display "Rondo \"alla turca\"\n")
⊨ Rondo "alla turca"
Now is a good time to introduce another convention for this tutorial. When I
write “⊨”, this means that the code prints what follows the “⊨” sign. For
example, the code below prints Rondo "alla turca" on the console. Beware of
the difference between printing a string, with display (which I denote with
“⊨”), and merely using it without display (which I denote using “⇒”). Despite
the superficial similarity, these are vastly different things. When you just do
"Rondo", this gives you the string “Rondo”. You can pass this string
somewhere, for example give it to LilyPond:
\header {
title = "Rondo"
}
On the other hand, display is just a one-time order to Guile to print the
value on the console. Once Guile has executed this request, it doesn’t give you
anything back. display does not return a meaningful value. It just prints the
string, which is useful for debugging.
It is important to understand the difference between how a string is input and
how it is displayed. By definition, a string is a sequence of characters.
Despite the superficial look, the string "\"\"\n" contains just three
characters, namely two double quotes and one newline. We only need these
backslashes to avoid a confusion when Guile reads the string. They are not part
of the resulting string, as confirmed by display:
(display "\"\"\n")
⊨ ""
It is useful to know that LilyPond recognizes a syntax similar to Scheme’s for numbers and strings. The lines below are equivalent:
\override TextScript.Y-offset = 5.2
\override TextScript.Y-offset = #5.2
Similarly, these are equivalent:
title = #"Rondo"
title = "Rondo"
title = Rondo
(Of course, the third syntax can only work with a single word. You need the double quotes as soon as there are spaces in the string.)
Defining variables#
Practically all LilyPond users know that their code will be much easier to follow and modify if they organize it using variables.
clarinet = \relative {
...
}
{ \clarinet }
{ \transpose c d \clarinet }
There are several advantages to this. For one thing, once you have defined a variable, you can reuse it in several places without typing it over again. For another, even if you do not need to use it in multiple places, using a variable makes the code more structured and thus easier to understand and later modify.
The syntax to define variables in Scheme is:
(define name value)
For example, to assign 5 to the variable x, you can use:
(define x 5)
After that, you can refer to the variable simply by its name. This is in contrast with LilyPond, where referring to a variable is done by writing its name preceded with a backslash.
(define x 5)
(display x)
⊨ 5
For multi-word variable names, the convention is to use dashes.
(define my-variable 44)
Perhaps surprisingly, variable names can contain some special characters.
Notably, these are accepted: +, -, *, /, ?, !, =, &, |, @. A
few characters are not valid, such as parentheses and quotes. (The precise rules
on valid variable names are somewhat complex, and it is not useful to know about
them in detail.)
(define x+|^ 34)
(display x+|^)
⊨ 34
Comments#
In LilyPond, comments start with a
%character, and continue until the end of the line. Scheme syntax is slightly different; the character used for comments is not%, but;. The principle of comments stays the same: they allow to explain the code for the human reader, or to stash some code away temporarily. They are annotations in the source file that are completely ignored by the interpreter.LilyPond also has multiline comments, which unlike simple
%comments can span several lines. They start with%{and are terminated by%}. Scheme has an equivalent syntax too; the delimiters are#!and!#.