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 @node Scheme tutorial
  11 @appendix Scheme tutorial
  12
  13 @funindex #
  14 @cindex Scheme
  15 @cindex GUILE
  16 @cindex Scheme, in-line code
  17 @cindex accessing Scheme
  18 @cindex evaluating Scheme
  19 @cindex LISP
  20
  21 LilyPond uses the Scheme programming language, both as part of the
  22 input syntax, and as internal mechanism to glue modules of the program
  23 together.  This section is a very brief overview of entering data in
  24 Scheme.  If you want to know more about Scheme, see
  25 @uref{http://@/www@/.schemers@/.org}.
  26
  27 The most basic thing of a language is data: numbers, character
  28 strings, lists, etc.  Here is a list of data types that are relevant to
  29 LilyPond input.
  30
  31 @table @asis
  32 @item Booleans
  33 Boolean values are True or False.  The Scheme for True is @code{#t}
  34 and False is @code{#f}.
  35 @funindex ##t
  36 @funindex ##f
  37
  38 @item Numbers
  39 Numbers are entered in the standard fashion,
  40 @code{1} is the (integer) number one, while @code{-1.5} is a
  41 floating point number (a non-integer number).
  42
  43 @item Strings
  44 Strings are enclosed in double quotes,
  45
  46 @example
  47 "this is a string"
  48 @end example
  49
  50 Strings may span several lines
  51
  52 @example
  53 "this
  54 is
  55 a string"
  56 @end example
  57
  58 Quotation marks and newlines can also be added with so-called escape
  59 sequences.  The string @code{a said "b"} is entered as
  60
  61 @example
  62 "a said \"b\""
  63 @end example
  64
  65 Newlines and backslashes are escaped with @code{\n} and @code{\\}
  66 respectively.
  67 @end table
  68
  69
  70 In a music file, snippets of Scheme code are introduced with the hash
  71 mark @code{#}.  So, the previous examples translated in LilyPond are
  72
  73 @example
  74 ##t ##f
  75 #1 #-1.5
  76 #"this is a string"
  77 #"this
  78 is
  79 a string"
  80 @end example
  81
  82 For the rest of this section, we will assume that the data is entered
  83 in a music file, so we add @code{#}s everywhere.
  84
  85 Scheme can be used to do calculations.  It uses @emph{prefix}
  86 syntax.  Adding 1 and@tie{}2 is written as @code{(+ 1 2)} rather than the
  87 traditional @math{1+2}.
  88
  89 @lisp
  90 #(+ 1 2)
  91   @result{} #3
  92 @end lisp
  93
  94 The arrow @result{} shows that the result of evaluating @code{(+ 1 2)}
  95 is@tie{}@code{3}.  Calculations may be nested; the result of a function may
  96 be used for another calculation.
  97
  98 @lisp
  99 #(+ 1 (* 3 4))
 100   @result{} #(+ 1 12)
 101   @result{} #13
 102 @end lisp
 103
 104 These calculations are examples of evaluations; an expression like
 105 @code{(* 3 4)} is replaced by its value @code{12}.  A similar thing
 106 happens with variables.  After defining a variable
 107
 108 @example
 109 twelve = #12
 110 @end example
 111
 112 @noindent
 113 variables can also be used in expressions, here
 114
 115 @example
 116 twentyFour = #(* 2 twelve)
 117 @end example
 118
 119 @noindent
 120 the number 24 is stored in the variable @code{twentyFour}.
 121 The same assignment can be done in completely in Scheme as well,
 122
 123 @example
 124 #(define twentyFour (* 2 twelve))
 125 @end example
 126
 127 The @emph{name} of a variable is also an expression, similar to a
 128 number or a string.  It is entered as
 129
 130 @example
 131 #'twentyFour
 132 @end example
 133
 134 @funindex #'symbol
 135 @cindex quoting in Scheme
 136
 137 The quote mark @code{'} prevents the Scheme interpreter from substituting
 138 @code{24} for the @code{twentyFour}.  Instead, we get the name
 139 @code{twentyFour}.
 140
 141 This syntax will be used very frequently, since many of the layout
 142 tweaks involve assigning (Scheme) values to internal variables, for
 143 example
 144
 145 @example
 146 \override Stem #'thickness = #2.6
 147 @end example
 148
 149 This instruction adjusts the appearance of stems.  The value @code{2.6}
 150 is put into the @code{thickness} variable of a @code{Stem}
 151 object.  @code{thickness} is measured relative to the thickness of
 152 staff lines, so these stem lines will be @code{2.6} times the
 153 width of staff lines.  This makes stems almost twice as thick as their
 154 normal size.  To distinguish between variables defined in input files (like
 155 @code{twentyFour} in the example above) and variables of internal
 156 objects, we will call the latter @q{properties} and the former
 157 @q{identifiers.}  So, the stem object has a @code{thickness} property,
 158 while @code{twentyFour} is an identifier.
 159
 160 @cindex properties vs. identifiers
 161 @cindex identifiers vs. properties
 162
 163 Two-dimensional offsets (X and Y coordinates) as well as object sizes
 164 (intervals with a left and right point) are entered as @code{pairs}.  A
 165 pair@footnote{In Scheme terminology, the pair is called @code{cons},
 166 and its two elements are called @code{car} and @code{cdr} respectively.}
 167 is entered as @code{(first . second)} and, like symbols, they must be quoted,
 168
 169 @example
 170 \override TextScript #'extra-offset = #'(1 . 2)
 171 @end example
 172
 173 This assigns the pair (1, 2) to the @code{extra-offset} property of the
 174 TextScript object.  These numbers are measured in staff-spaces, so
 175 this command moves the object 1 staff space to the right, and 2 spaces up.
 176
 177 The two elements of a pair may be arbitrary values, for example
 178
 179 @example
 180 #'(1 . 2)
 181 #'(#t . #f)
 182 #'("blah-blah" . 3.14159265)
 183 @end example
 184
 185 A list is entered by enclosing its elements in parentheses, and adding
 186 a quote.  For example,
 187
 188 @example
 189 #'(1 2 3)
 190 #'(1 2 "string" #f)
 191 @end example
 192
 193 We have been using lists all along.  A calculation, like @code{(+ 1 2)}
 194 is also a list (containing the symbol @code{+} and the numbers 1
 195 and@tie{}2).  Normally lists are interpreted as calculations, and the
 196 Scheme interpreter substitutes the outcome of the calculation.  To enter a
 197 list, we stop the evaluation.  This is done by quoting the list with a
 198 quote @code{'} symbol.  So, for calculations do not use a quote.
 199
 200 Inside a quoted list or pair, there is no need to quote anymore.  The
 201 following is a pair of symbols, a list of symbols and a list of lists
 202 respectively,
 203
 204 @example
 205 #'(stem . head)
 206 #'(staff clef key-signature)
 207 #'((1) (2))
 208 @end example
 209
 210
 211