Documentation/user/scheme-tutorial.itely

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