Documentation/user/scheme-tutorial.itely

   1 @c -*- coding: utf-8; mode: texinfo; -*-
   2 @c This file is part of lilypond.tely
   3 @ignore
   4     Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
   5
   6     When revising a translation, copy the HEAD committish of the
   7     version that you are working on.  See TRANSLATION for details.
   8 @end ignore
   9
  10 @c \version "2.11.61"
  11
  12 @node Scheme tutorial
  13 @appendix Scheme tutorial
  14
  15 @funindex #
  16 @cindex Scheme
  17 @cindex GUILE
  18 @cindex Scheme, in-line code
  19 @cindex accessing Scheme
  20 @cindex evaluating Scheme
  21 @cindex LISP
  22
  23 LilyPond uses the Scheme programming language, both as part of the
  24 input syntax, and as internal mechanism to glue modules of the program
  25 together.  This section is a very brief overview of entering data in
  26 Scheme.  If you want to know more about Scheme, see
  27 @uref{http://@/www@/.schemers@/.org}.
  28
  29 The most basic thing of a language is data: numbers, character
  30 strings, lists, etc.  Here is a list of data types that are relevant to
  31 LilyPond input.
  32
  33 @table @asis
  34 @item Booleans
  35 Boolean values are True or False.  The Scheme for True is @code{#t}
  36 and False is @code{#f}.
  37 @funindex ##t
  38 @funindex ##f
  39
  40 @item Numbers
  41 Numbers are entered in the standard fashion,
  42 @code{1} is the (integer) number one, while @code{-1.5} is a
  43 floating point number (a non-integer number).
  44
  45 @item Strings
  46 Strings are enclosed in double quotes,
  47
  48 @example
  49 "this is a string"
  50 @end example
  51
  52 Strings may span several lines
  53
  54 @example
  55 "this
  56 is
  57 a string"
  58 @end example
  59
  60 Quotation marks and newlines can also be added with so-called escape
  61 sequences.  The string @code{a said "b"} is entered as
  62
  63 @example
  64 "a said \"b\""
  65 @end example
  66
  67 Newlines and backslashes are escaped with @code{\n} and @code{\\}
  68 respectively.
  69 @end table
  70
  71
  72 In a music file, snippets of Scheme code are introduced with the hash
  73 mark @code{#}.  So, the previous examples translated in LilyPond are
  74
  75 @example
  76 ##t ##f
  77 #1 #-1.5
  78 #"this is a string"
  79 #"this
  80 is
  81 a string"
  82 @end example
  83
  84 For the rest of this section, we will assume that the data is entered
  85 in a music file, so we add @code{#}s everywhere.
  86
  87 Scheme can be used to do calculations.  It uses @emph{prefix}
  88 syntax.  Adding 1 and@tie{}2 is written as @code{(+ 1 2)} rather than the
  89 traditional @math{1+2}.
  90
  91 @lisp
  92 #(+ 1 2)
  93   @result{} #3
  94 @end lisp
  95
  96 The arrow @result{} shows that the result of evaluating @code{(+ 1 2)}
  97 is@tie{}@code{3}.  Calculations may be nested; the result of a function may
  98 be used for another calculation.
  99
 100 @lisp
 101 #(+ 1 (* 3 4))
 102   @result{} #(+ 1 12)
 103   @result{} #13
 104 @end lisp
 105
 106 These calculations are examples of evaluations; an expression like
 107 @code{(* 3 4)} is replaced by its value @code{12}.  A similar thing
 108 happens with variables.  After defining a variable
 109
 110 @example
 111 twelve = #12
 112 @end example
 113
 114 @noindent
 115 variables can also be used in expressions, here
 116
 117 @example
 118 twentyFour = #(* 2 twelve)
 119 @end example
 120
 121 @noindent
 122 the number 24 is stored in the variable @code{twentyFour}.
 123 The same assignment can be done in completely in Scheme as well,
 124
 125 @example
 126 #(define twentyFour (* 2 twelve))
 127 @end example
 128
 129 The @emph{name} of a variable is also an expression, similar to a
 130 number or a string.  It is entered as
 131
 132 @example
 133 #'twentyFour
 134 @end example
 135
 136 @funindex #'symbol
 137 @cindex quoting in Scheme
 138
 139 The quote mark @code{'} prevents the Scheme interpreter from substituting
 140 @code{24} for the @code{twentyFour}.  Instead, we get the name
 141 @code{twentyFour}.
 142
 143 This syntax will be used very frequently, since many of the layout
 144 tweaks involve assigning (Scheme) values to internal variables, for
 145 example
 146
 147 @example
 148 \override Stem #'thickness = #2.6
 149 @end example
 150
 151 This instruction adjusts the appearance of stems.  The value @code{2.6}
 152 is put into the @code{thickness} variable of a @code{Stem}
 153 object.  @code{thickness} is measured relative to the thickness of
 154 staff lines, so these stem lines will be @code{2.6} times the
 155 width of staff lines.  This makes stems almost twice as thick as their
 156 normal size.  To distinguish between variables defined in input files (like
 157 @code{twentyFour} in the example above) and variables of internal
 158 objects, we will call the latter @q{properties} and the former
 159 @q{variables.}  So, the stem object has a @code{thickness} property,
 160 while @code{twentyFour} is an variable.
 161
 162 @cindex properties vs. variables
 163 @cindex variables vs. properties
 164
 165 Two-dimensional offsets (X and Y coordinates) as well as object sizes
 166 (intervals with a left and right point) are entered as @code{pairs}.  A
 167 pair@footnote{In Scheme terminology, the pair is called @code{cons},
 168 and its two elements are called @code{car} and @code{cdr} respectively.}
 169 is entered as @code{(first . second)} and, like symbols, they must be quoted,
 170
 171 @example
 172 \override TextScript #'extra-offset = #'(1 . 2)
 173 @end example
 174
 175 This assigns the pair (1, 2) to the @code{extra-offset} property of the
 176 TextScript object.  These numbers are measured in staff-spaces, so
 177 this command moves the object 1 staff space to the right, and 2 spaces up.
 178
 179 The two elements of a pair may be arbitrary values, for example
 180
 181 @example
 182 #'(1 . 2)
 183 #'(#t . #f)
 184 #'("blah-blah" . 3.14159265)
 185 @end example
 186
 187 A list is entered by enclosing its elements in parentheses, and adding
 188 a quote.  For example,
 189
 190 @example
 191 #'(1 2 3)
 192 #'(1 2 "string" #f)
 193 @end example
 194
 195 We have been using lists all along.  A calculation, like @code{(+ 1 2)}
 196 is also a list (containing the symbol @code{+} and the numbers 1
 197 and@tie{}2).  Normally lists are interpreted as calculations, and the
 198 Scheme interpreter substitutes the outcome of the calculation.  To enter a
 199 list, we stop the evaluation.  This is done by quoting the list with a
 200 quote @code{'} symbol.  So, for calculations do not use a quote.
 201
 202 Inside a quoted list or pair, there is no need to quote anymore.  The
 203 following is a pair of symbols, a list of symbols and a list of lists
 204 respectively,
 205
 206 @example
 207 #'(stem . head)
 208 #'(staff clef key-signature)
 209 #'((1) (2))
 210 @end example
 211
 212
 213 @menu
 214 * Tweaking with Scheme::
 215 @end menu
 216
 217 @node Tweaking with Scheme
 218 @appendixsec Tweaking with Scheme
 219
 220 We have seen how LilyPond output can be heavily modified using
 221 commands like
 222 @code{\override TextScript #'extra-offset = ( 1 . -1)}.  But
 223 we have even more power if we use Scheme.  For a full explanation
 224 of this, see the @ref{Scheme tutorial}, and
 225 @ruser{Interfaces for programmers}.
 226
 227 We can use Scheme to simply @code{\override} commands,
 228
 229 TODO Find a simple example
 230 @c This isn't a valid example with skylining
 231 @c It works fine without padText  -td
 232
 233 @ignore
 234 @lilypond[quote,verbatim,ragged-right]
 235 padText = #(define-music-function (parser location padding) (number?)
 236 #{
 237   \once \override TextScript #'padding = #$padding
 238 #})
 239
 240 \relative c''' {
 241   c4^"piu mosso" b a b
 242   \padText #1.8
 243   c4^"piu mosso" d e f
 244   \padText #2.6
 245   c4^"piu mosso" fis a g
 246 }
 247 @end lilypond
 248 @end ignore
 249
 250 We can use it to create new commands:
 251
 252 @c Check this is a valid example with skylining
 253 @c It is - 'padding still works
 254
 255 @lilypond[quote,verbatim,ragged-right]
 256 tempoMark = #(define-music-function (parser location padding marktext)
 257                                     (number? string?)
 258 #{
 259   \once \override Score . RehearsalMark #'padding = $padding
 260   \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
 261   \mark \markup { \bold $marktext }
 262 #})
 263
 264 \relative c'' {
 265   c2 e
 266   \tempoMark #3.0 #"Allegro"
 267   g c
 268 }
 269 @end lilypond
 270
 271 Even music expressions can be passed in:
 272
 273 @lilypond[quote,verbatim,ragged-right]
 274 pattern = #(define-music-function (parser location x y) (ly:music? ly:music?)
 275 #{
 276   $x e8 a b $y b a e
 277 #})
 278
 279 \relative c''{
 280   \pattern c8 c8\f
 281   \pattern {d16 dis} { ais16-> b\p }
 282 }
 283 @end lilypond
 284
 285
 286
 287
 288