Documentation/user/scheme-tutorial.itely

   1
   2
   3 @node Scheme tutorial
   4 @appendix Scheme tutorial
   5
   6 @findex #
   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.  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 @findex ##t
  29 @findex ##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 @findex #'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.  @code{thickness} is measured relative to the thickness of
 145 staff lines, so these stem lines will be @code{2.6} times the
 146 width of staff lines.  This makes stems almost twice as thick as their
 147 normal size. To distinguish between variables defined in input files (like
 148 @code{twentyFour} in the example above) and variables of internal
 149 objects, we will call the latter ``properties'' and the former
 150 ``identifiers.''  So, the stem object has a @code{thickness} property,
 151 while @code{twentyFour} is an identifier.
 152
 153 @cindex properties vs. identifiers
 154 @cindex identifiers vs. properties
 155
 156 Two-dimensional offsets (X and Y coordinates) as well as object sizes
 157 (intervals with a left and right point) are entered as @code{pairs}.  A
 158 pair@footnote{In Scheme terminology, the pair is called @code{cons},
 159 and its two elements are called @code{car} and @code{cdr} respectively.}
 160 is entered as @code{(first . second)} and, like symbols, they must be quoted,
 161
 162 @example
 163 \override TextScript #'extra-offset = #'(1 . 2)
 164 @end example
 165
 166 This assigns the pair (1, 2) to the @code{extra-offset} property of the
 167 TextScript object.  These numbers are measured in staff-spaces, so
 168 this command moves the object 1 staff space to the right, and 2 spaces up.
 169
 170 The two elements of a pair may be arbitrary values, for example
 171
 172 @example
 173 #'(1 . 2)
 174 #'(#t . #f)
 175 #'("blah-blah" . 3.14159265)
 176 @end example
 177
 178 A list is entered by enclosing its elements in parentheses, and adding
 179 a quote.  For example,
 180
 181 @example
 182 #'(1 2 3)
 183 #'(1 2 "string" #f)
 184 @end example
 185
 186 We have been using lists all along.  A calculation, like @code{(+ 1 2)}
 187 is also a list (containing the symbol @code{+} and the numbers 1
 188 and@tie{}2).  Normally lists are interpreted as calculations, and the
 189 Scheme interpreter substitutes the outcome of the calculation.  To enter a
 190 list, we stop the evaluation.  This is done by quoting the list with a
 191 quote @code{'} symbol.  So, for calculations do not use a quote.
 192
 193 Inside a quoted list or pair, there is no need to quote anymore.  The
 194 following is a pair of symbols, a list of symbols and a list of lists
 195 respectively,
 196
 197 @example
 198 #'(stem . head)
 199 #'(staff clef key-signature)
 200 #'((1) (2))
 201 @end example