Documentation/user/scheme-tutorial.itely

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