<!-- header_tag -->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html401/loose.dtd">
<html>
<!-- Copyright C 1999-2009 by the authors
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1
or any later version published by the Free Software Foundation;
with no Invariant Sections.
A copy of the license is included in the section entitled "GNU
Free Documentation License".
-->
<!-- Created on December 15, 2009 by texi2html 1.82
texi2html was written by:
Lionel Cons <Lionel.Cons@cern.ch> (original author)
Karl Berry <karl@freefriends.org>
Olaf Bachmann <obachman@mathematik.uni-kl.de>
and many others.
Maintained by: Many creative people.
Send bugs and suggestions to <texi2html-bug@nongnu.org>
-->
<head>
<title>GNU LilyPond Learning Manual: B. Scheme tutorial</title>
<meta name="description" content="GNU LilyPond Learning Manual: B. Scheme tutorial">
<meta name="keywords" content="GNU LilyPond Learning Manual: B. Scheme tutorial">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="texi2html 1.82">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link href="index.html#Top" rel="start" title="GNU LilyPond — Learning Manual">
<link href="LilyPond-index.html#LilyPond-index" rel="index" title="D. LilyPond index">
<link href="index_toc.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="index_abt.html#SEC_About" rel="help" title="About This Document">
<link href="index.html#Top" rel="up" title="GNU LilyPond — Learning Manual">
<link href="LilyPond-index.html#LilyPond-index" rel="next" title="D. LilyPond index">
<link href="lilypond_002dbook-templates.html#lilypond_002dbook-templates" rel="previous" title="A.7 lilypond-book templates">
<link rel="stylesheet" type="text/css" title="Patrick McCarty's design" href="lilypond-mccarty.css">
<link rel="alternate stylesheet" type="text/css" href="lilypond.css" title="Andrew Hawryluk's design">
<link rel="alternate stylesheet" type="text/css" href="lilypond-blue.css" title="Kurt Kroon's blue design">
<!--[if lte IE 7]>
<link href="lilypond-ie-fixes.css" rel="stylesheet" type="text/css">
<![endif]-->
</head>
<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
<div id="main">
<a name="Scheme-tutorial"></a>
<table class="nav_table">
<tr><td valign="middle" align="left" colspan="1">[<a href="Templates.html#Templates" title="Beginning of this chapter or previous chapter"> << Templates </a>]</td><td valign="middle" align="center" colspan="3">[<a href="index.html#Top" title="Cover (top) of document" rel="start">Top</a>][<a href="index_toc.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="LilyPond-index.html#LilyPond-index" title="Index" rel="index">Index</a>][<a href="index_abt.html#SEC_About" title="About (help)" rel="help"> ? </a>]</td><td valign="middle" align="right" colspan="1">[<a href="GNU-Free-Documentation-License.html#GNU-Free-Documentation-License" title="Next chapter"> GNU Free Documentation License >> </a>]</td></tr><tr><td valign="middle" align="left" colspan="2">[<a href="lilypond_002dbook-templates.html#lilypond_002dbook-templates" title="Previous section in reading order" accesskey="p" rel="previous"> < </a>]</td><td valign="middle" align="center" colspan="1">[<a href="index.html#Top" title="Up section" accesskey="u" rel="up"> Up : Top </a>]</td><td valign="middle" align="right" colspan="2">[<a href="Tweaking-with-Scheme.html#Tweaking-with-Scheme" title="Next section in reading order" accesskey="n" rel="next"> Tweaking with Scheme > </a>]</td></tr></table>
<a name="Scheme-tutorial"></a>
<h1 class="appendix">B. Scheme tutorial</h1>
<a name="index-_0023"></a>
<a name="index-_0023-1"></a>
<a name="index-Scheme"></a>
<a name="index-GUILE"></a>
<a name="index-Scheme_002c-in_002dline-code"></a>
<a name="index-accessing-Scheme"></a>
<a name="index-evaluating-Scheme"></a>
<a name="index-LISP"></a>
<p>LilyPond uses the Scheme programming language, both as part of the
input syntax, and as internal mechanism to glue modules of the program
together. This section is a very brief overview of entering data in
Scheme. If you want to know more about Scheme, see
<a href="http://www.schemers.org">http://www.schemers.org</a>.
</p>
<p>The most basic thing of a language is data: numbers, character
strings, lists, etc. Here is a list of data types that are relevant to
LilyPond input.
</p>
<dl compact="compact">
<dt> Booleans</dt>
<dd><p>Boolean values are True or False. The Scheme for True is <code>#t</code>
and False is <code>#f</code>.
<a name="index-_0023_0023t"></a>
<a name="index-_0023_0023t-1"></a>
<a name="index-_0023_0023f"></a>
<a name="index-_0023_0023f-1"></a>
</p>
</dd>
<dt> Numbers</dt>
<dd><p>Numbers are entered in the standard fashion,
<code>1</code> is the (integer) number one, while <code>-1.5</code> is a
floating point number (a non-integer number).
</p>
</dd>
<dt> Strings</dt>
<dd><p>Strings are enclosed in double quotes,
</p>
<blockquote><pre class="example">"this is a string"
</pre></blockquote>
<p>Strings may span several lines
</p>
<blockquote><pre class="example">"this
is
a string"
</pre></blockquote>
<p>Quotation marks and newlines can also be added with so-called escape
sequences. The string <code>a said "b"</code> is entered as
</p>
<blockquote><pre class="example">"a said \"b\""
</pre></blockquote>
<p>Newlines and backslashes are escaped with <code>\n</code> and <code>\\</code>
respectively.
</p></dd>
</dl>
<p>In a music file, snippets of Scheme code are introduced with the hash
mark <code>#</code>. So, the previous examples translated in LilyPond are
</p>
<blockquote><pre class="example">##t ##f
#1 #-1.5
#"this is a string"
#"this
is
a string"
</pre></blockquote>
<p>For the rest of this section, we will assume that the data is entered
in a music file, so we add <code>#</code>s everywhere.
</p>
<p>Scheme can be used to do calculations. It uses <em>prefix</em>
syntax. Adding 1 and 2 is written as <code>(+ 1 2)</code> rather than the
traditional <em>1+2</em>.
</p>
<table><tr><td> </td><td><pre class="lisp">#(+ 1 2)
⇒ #3
</pre></td></tr></table>
<p>The arrow ⇒ shows that the result of evaluating <code>(+ 1 2)</code>
is <code>3</code>. Calculations may be nested; the result of a function may
be used for another calculation.
</p>
<table><tr><td> </td><td><pre class="lisp">#(+ 1 (* 3 4))
⇒ #(+ 1 12)
⇒ #13
</pre></td></tr></table>
<p>These calculations are examples of evaluations; an expression like
<code>(* 3 4)</code> is replaced by its value <code>12</code>. A similar thing
happens with variables. After defining a variable
</p>
<blockquote><pre class="example">twelve = #12
</pre></blockquote>
<p>variables can also be used in expressions, here
</p>
<blockquote><pre class="example">twentyFour = #(* 2 twelve)
</pre></blockquote>
<p>the number 24 is stored in the variable <code>twentyFour</code>.
The same assignment can be done in completely in Scheme as well,
</p>
<blockquote><pre class="example">#(define twentyFour (* 2 twelve))
</pre></blockquote>
<p>The <em>name</em> of a variable is also an expression, similar to a
number or a string. It is entered as
</p>
<blockquote><pre class="example">#'twentyFour
</pre></blockquote>
<a name="index-_0023_0027symbol"></a>
<a name="index-_0023_0027symbol-1"></a>
<a name="index-quoting-in-Scheme"></a>
<p>The quote mark <code>'</code> prevents the Scheme interpreter from substituting
<code>24</code> for the <code>twentyFour</code>. Instead, we get the name
<code>twentyFour</code>.
</p>
<p>This syntax will be used very frequently, since many of the layout
tweaks involve assigning (Scheme) values to internal variables, for
example
</p>
<blockquote><pre class="example">\override Stem #'thickness = #2.6
</pre></blockquote>
<p>This instruction adjusts the appearance of stems. The value <code>2.6</code>
is put into the <code>thickness</code> variable of a <code>Stem</code>
object. <code>thickness</code> is measured relative to the thickness of
staff lines, so these stem lines will be <code>2.6</code> times the
width of staff lines. This makes stems almost twice as thick as their
normal size. To distinguish between variables defined in input files (like
<code>twentyFour</code> in the example above) and variables of internal
objects, we will call the latter ‘properties’ and the former
‘variables.’ So, the stem object has a <code>thickness</code> property,
while <code>twentyFour</code> is an variable.
</p>
<a name="index-properties-vs_002e-variables"></a>
<a name="index-variables-vs_002e-properties"></a>
<p>Two-dimensional offsets (X and Y coordinates) as well as object sizes
(intervals with a left and right point) are entered as <code>pairs</code>. A
pair<sup><a name="DOCF1" href="#FOOT1">1</a></sup>
is entered as <code>(first . second)</code> and, like symbols, they must be quoted,
</p>
<blockquote><pre class="example">\override TextScript #'extra-offset = #'(1 . 2)
</pre></blockquote>
<p>This assigns the pair (1, 2) to the <code>extra-offset</code> property of the
TextScript object. These numbers are measured in staff-spaces, so
this command moves the object 1 staff space to the right, and 2 spaces up.
</p>
<p>The two elements of a pair may be arbitrary values, for example
</p>
<blockquote><pre class="example">#'(1 . 2)
#'(#t . #f)
#'("blah-blah" . 3.14159265)
</pre></blockquote>
<p>A list is entered by enclosing its elements in parentheses, and adding
a quote. For example,
</p>
<blockquote><pre class="example">#'(1 2 3)
#'(1 2 "string" #f)
</pre></blockquote>
<p>We have been using lists all along. A calculation, like <code>(+ 1 2)</code>
is also a list (containing the symbol <code>+</code> and the numbers 1
and 2). Normally lists are interpreted as calculations, and the
Scheme interpreter substitutes the outcome of the calculation. To enter a
list, we stop the evaluation. This is done by quoting the list with a
quote <code>'</code> symbol. So, for calculations do not use a quote.
</p>
<p>Inside a quoted list or pair, there is no need to quote anymore. The
following is a pair of symbols, a list of symbols and a list of lists
respectively,
</p>
<blockquote><pre class="example">#'(stem . head)
#'(staff clef key-signature)
#'((1) (2))
</pre></blockquote>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top"><a href="Tweaking-with-Scheme.html#Tweaking-with-Scheme" accesskey="1">B.1 Tweaking with Scheme</a></td><td> </td><td align="left" valign="top">
</td></tr>
</table>
<div class="footnote">
<hr>
<h3>Footnotes</h3>
<p class="footnote"><small>[<a name="FOOT1" href="#DOCF1">1</a>]</small> In Scheme terminology, the pair is called <code>cons</code>,
and its two elements are called <code>car</code> and <code>cdr</code> respectively.
</p></div>
<hr size="6">
<table class="nav_table">
<tr><td valign="middle" align="left" colspan="1">[<a href="Templates.html#Templates" title="Beginning of this chapter or previous chapter"> << Templates </a>]</td><td valign="middle" align="center" colspan="3">[<a href="index.html#Top" title="Cover (top) of document" rel="start">Top</a>][<a href="index_toc.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="LilyPond-index.html#LilyPond-index" title="Index" rel="index">Index</a>][<a href="index_abt.html#SEC_About" title="About (help)" rel="help"> ? </a>]</td><td valign="middle" align="right" colspan="1">[<a href="GNU-Free-Documentation-License.html#GNU-Free-Documentation-License" title="Next chapter"> GNU Free Documentation License >> </a>]</td></tr><tr><td valign="middle" align="left" colspan="2">[<a href="lilypond_002dbook-templates.html#lilypond_002dbook-templates" title="Previous section in reading order" accesskey="p" rel="previous"> < </a>]</td><td valign="middle" align="center" colspan="1">[<a href="index.html#Top" title="Up section" accesskey="u" rel="up"> Up : Top </a>]</td><td valign="middle" align="right" colspan="2">[<a href="Tweaking-with-Scheme.html#Tweaking-with-Scheme" title="Next section in reading order" accesskey="n" rel="next"> Tweaking with Scheme > </a>]</td></tr></table>
<!-- footer_tag -->
<div class="footer">
<p class="footer_version">
This page is for LilyPond-2.12.3 (stable-branch).
</p>
<p class="footer_report">
Your <a href="http://lilypond.org/web/devel/participating/documentation-adding">suggestions for the documentation</a> are welcome, please report errors to our <a href="http://post.gmane.org/post.php?group=gmane.comp.gnu.lilypond.bugs">bug list</a>.
</p>
</div>
<p id="languages">
Other languages: <a href="Scheme-tutorial.es.html">español</a>, <a href="Scheme-tutorial.de.html">deutsch</a>.
<br>
</p>
<!-- FOOTER -->
<!-- end div#main here -->
</div>
<div id="tocframe">
<p class="toc_uplink"><a href="../index.html"
title="Documentation Index"><< Back to Documentation Index</a></p>
<h4 class="toc_header"> <a href="index.html#Top" title="Start of the manual">Learning Manual</a></h4>
<div class="contents">
<ul class="toc">
<li><a name="toc-Preface-1" href="Preface.html#Preface">Preface</a> </li>
<li><a name="toc-Introduction-1" href="Introduction.html#Introduction">1. Introduction</a>
<ul class="toc">
<li><a name="toc-Background-1" href="Background.html#Background">1.1 Background</a> </li>
<li><a name="toc-About-the-documentation-1" href="About-the-documentation.html#About-the-documentation">1.2 About the documentation</a> </li>
</ul>
</li>
<li><a name="toc-Tutorial-1" href="Tutorial.html#Tutorial">2. Tutorial</a>
<ul class="toc">
<li><a name="toc-First-steps-1" href="First-steps.html#First-steps">2.1 First steps</a> </li>
<li><a name="toc-Single-staff-notation-1" href="Single-staff-notation.html#Single-staff-notation">2.2 Single staff notation</a> </li>
<li><a name="toc-Multiple-notes-at-once-1" href="Multiple-notes-at-once.html#Multiple-notes-at-once">2.3 Multiple notes at once</a> </li>
<li><a name="toc-Songs-1" href="Songs.html#Songs">2.4 Songs</a> </li>
<li><a name="toc-Final-touches-1" href="Final-touches.html#Final-touches">2.5 Final touches</a> </li>
</ul>
</li>
<li><a name="toc-Fundamental-concepts-1" href="Fundamental-concepts.html#Fundamental-concepts">3. Fundamental concepts</a>
<ul class="toc">
<li><a name="toc-How-LilyPond-input-files-work-1" href="How-LilyPond-input-files-work.html#How-LilyPond-input-files-work">3.1 How LilyPond input files work</a> </li>
<li><a name="toc-Voices-contain-music-1" href="Voices-contain-music.html#Voices-contain-music">3.2 Voices contain music</a> </li>
<li><a name="toc-Contexts-and-engravers-1" href="Contexts-and-engravers.html#Contexts-and-engravers">3.3 Contexts and engravers</a> </li>
<li><a name="toc-Extending-the-templates-1" href="Extending-the-templates.html#Extending-the-templates">3.4 Extending the templates</a> </li>
</ul>
</li>
<li><a name="toc-Tweaking-output-1" href="Tweaking-output.html#Tweaking-output">4. Tweaking output</a>
<ul class="toc">
<li><a name="toc-Tweaking-basics-1" href="Tweaking-basics.html#Tweaking-basics">4.1 Tweaking basics</a> </li>
<li><a name="toc-The-Internals-Reference-manual-1" href="The-Internals-Reference-manual.html#The-Internals-Reference-manual">4.2 The Internals Reference manual</a> </li>
<li><a name="toc-Appearance-of-objects-1" href="Appearance-of-objects.html#Appearance-of-objects">4.3 Appearance of objects</a> </li>
<li><a name="toc-Placement-of-objects-1" href="Placement-of-objects.html#Placement-of-objects">4.4 Placement of objects</a> </li>
<li><a name="toc-Collisions-of-objects-1" href="Collisions-of-objects.html#Collisions-of-objects">4.5 Collisions of objects</a> </li>
<li><a name="toc-Further-tweaking-1" href="Further-tweaking.html#Further-tweaking">4.6 Further tweaking</a> </li>
</ul>
</li>
<li><a name="toc-Working-on-LilyPond-projects-1" href="Working-on-LilyPond-projects.html#Working-on-LilyPond-projects">5. Working on LilyPond projects</a>
<ul class="toc">
<li><a name="toc-Suggestions-for-writing-LilyPond-input-files-1" href="Suggestions-for-writing-LilyPond-input-files.html#Suggestions-for-writing-LilyPond-input-files">5.1 Suggestions for writing LilyPond input files</a> </li>
<li><a name="toc-When-things-don_0027t-work-1" href="When-things-don_0027t-work.html#When-things-don_0027t-work">5.2 When things don’t work</a> </li>
<li><a name="toc-Scores-and-parts-1" href="Scores-and-parts.html#Scores-and-parts">5.3 Scores and parts</a> </li>
</ul>
</li>
<li><a name="toc-Templates-1" href="Templates.html#Templates">A. Templates</a>
<ul class="toc">
<li><a name="toc-Single-staff-1" href="Single-staff.html#Single-staff">A.1 Single staff</a> </li>
<li><a name="toc-Piano-templates-1" href="Piano-templates.html#Piano-templates">A.2 Piano templates</a> </li>
<li><a name="toc-String-quartet-2" href="String-quartet.html#String-quartet">A.3 String quartet</a> </li>
<li><a name="toc-Vocal-ensembles-1" href="Vocal-ensembles.html#Vocal-ensembles">A.4 Vocal ensembles</a> </li>
<li><a name="toc-Ancient-notation-templates-1" href="Ancient-notation-templates.html#Ancient-notation-templates">A.5 Ancient notation templates</a> </li>
<li><a name="toc-Jazz-combo-1" href="Jazz-combo.html#Jazz-combo">A.6 Jazz combo</a> </li>
<li><a name="toc-lilypond_002dbook-templates-1" href="lilypond_002dbook-templates.html#lilypond_002dbook-templates">A.7 lilypond-book templates</a> </li>
</ul>
</li>
<li class="toc_current"><a name="toc-Scheme-tutorial-1" href="Scheme-tutorial.html#Scheme-tutorial">B. Scheme tutorial</a>
<ul class="toc">
<li><a name="toc-Tweaking-with-Scheme-1" href="Tweaking-with-Scheme.html#Tweaking-with-Scheme">B.1 Tweaking with Scheme</a> </li>
</ul>
</li>
<li><a name="toc-GNU-Free-Documentation-License-1" href="GNU-Free-Documentation-License.html#GNU-Free-Documentation-License">C. GNU Free Documentation License</a> </li>
<li><a name="toc-LilyPond-index-1" href="LilyPond-index.html#LilyPond-index">D. LilyPond index</a> </li>
</ul>
</div>
</div>
</body>
</html>
