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