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 (* 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.  This moves the object 1 staff space to the right,
 166 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