[lilypond.git] / Documentation / user / scheme-tutorial.itely

@c -*- coding: utf-8; mode: texinfo; -*-
@c This file is part of lilypond.tely
@ignore
    Translation of GIT committish: FILL-IN-HEAD-COMMITTISH

    When revising a translation, copy the HEAD committish of the
    version that you are working on.  See TRANSLATION for details.
@end ignore

@c \version "2.12.0"

@node Scheme tutorial
@appendix Scheme tutorial

@funindex #
@cindex Scheme
@cindex GUILE
@cindex Scheme, in-line code
@cindex accessing Scheme
@cindex evaluating Scheme
@cindex LISP

LilyPond uses the Scheme programming language, both as part of the
input syntax, and as internal mechanism to glue modules of the program
together.  This section is a very brief overview of entering data in
Scheme.  If you want to know more about Scheme, see
@uref{http://@/www@/.schemers@/.org}.

LilyPond uses the GNU Guile implementation of Scheme, which is
based on the Scheme @qq{R5RS} standard. If you are learning Scheme
to use with LilyPond, working with a different implementation (or
referring to a different standard) is not recommended. Information
on guile can be found at @uref{http://www.gnu.org/software/guile/}.
The @qq{R5RS} Scheme standard is located at
@uref{http://www.schemers.org/Documents/Standards/R5RS/}.

The LilyPond installation also includes the Guile implementation of
Scheme.  On most systems you can experiment in a Scheme sandbox by
opening a terminal window and typing @q{guile}.  On some systems,
notably Windows, you may need to set the environment variable
@code{GUILE_LOAD_PATH} to the directory @code{../usr/shr/guile/1.8}
in the LilyPond installation (for the full path to this directory
see @ref{Other sources of information}).  Alternatively, Windows
users may simply choose @q{Run} from the Start menu and enter
@q{guile}.

The most basic concept in a language is data typing: numbers, character
strings, lists, etc.  Here is a list of data types that are relevant to
LilyPond input.

@table @asis
@item Booleans
Boolean values are True or False.  The Scheme for True is @code{#t}
and False is @code{#f}.
@funindex ##t
@funindex ##f

@item Numbers
Numbers are entered in the standard fashion,
@code{1} is the (integer) number one, while @code{-1.5} is a
floating point number (a non-integer number).

@item Strings
Strings are enclosed in double quotes,

@example
"this is a string"
@end example

Strings may span several lines

@example
"this
is
a string"
@end example

Quotation marks and newlines can also be added with so-called escape
sequences.  The string @code{a said "b"} is entered as

@example
"a said \"b\""
@end example

Newlines and backslashes are escaped with @code{\n} and @code{\\}
respectively.
@end table


In a music file, snippets of Scheme code are introduced with the hash
mark @code{#}.  So, the previous examples translated to LilyPond are

@example
##t ##f
#1 #-1.5
#"this is a string"
#"this
is
a string"
@end example

Note that LilyPond comments (@code{%} and @code{%@{ %@}}) cannot
be used within Scheme code.  Comments in Guile Scheme are entered
as follows:

@example
; this is a single-line comment

#!
  This a (non-nestable) Guile-style block comment
  But these are rarely used by Schemers and never in
  LilyPond source code
!#
@end example

Multiple consecutive scheme expressions in a music file can be
combined using the @code{begin} operator. This permits the number
of hash marks to be reduced to one.

@example
#(begin
  (define foo 0)
  (define bar 1))
@end example

If @code{#} is followed by an opening bracket, @code{(}, as in
the example above, the parser will remain in Scheme mode until
a matching closing bracket, @code{)}, is found, so further
@code{#} symbols to introduce a Scheme section are not required.

For the rest of this section, we will assume that the data is entered
in a music file, so we add @code{#}s everywhere.

Scheme can be used to do calculations.  It uses @emph{prefix}
syntax.  Adding 1 and@tie{}2 is written as @code{(+ 1 2)} rather than the
traditional @math{1+2}.

@lisp
#(+ 1 2)
  @result{} #3
@end lisp

The arrow @result{} shows that the result of evaluating @code{(+ 1 2)}
is@tie{}@code{3}.  Calculations may be nested; the result of a function may
be used for another calculation.

@lisp
#(+ 1 (* 3 4))
  @result{} #(+ 1 12)
  @result{} #13
@end lisp

These calculations are examples of evaluations; an expression like
@code{(* 3 4)} is replaced by its value @code{12}.  A similar thing
happens with variables.  After defining a variable

@example
twelve = #12
@end example

@noindent
variables can also be used in expressions, here

@example
twentyFour = #(* 2 twelve)
@end example

@noindent
the number 24 is stored in the variable @code{twentyFour}.
The same assignment can be done in completely in Scheme as well,

@example
#(define twentyFour (* 2 twelve))
@end example

The @emph{name} of a variable is also an expression, similar to a
number or a string.  It is entered as

@example
#'twentyFour
@end example

@funindex #'symbol
@cindex quoting in Scheme

The quote mark @code{'} prevents the Scheme interpreter from substituting
@code{24} for the @code{twentyFour}.  Instead, we get the name
@code{twentyFour}.

This syntax will be used very frequently, since many of the layout
tweaks involve assigning (Scheme) values to internal variables, for
example

@example
\override Stem #'thickness = #2.6
@end example

This instruction adjusts the appearance of stems.  The value @code{2.6}
is put into the @code{thickness} variable of a @code{Stem}
object.  @code{thickness} is measured relative to the thickness of
staff lines, so these stem lines will be @code{2.6} times the
width of staff lines.  This makes stems almost twice as thick as their
normal size.  To distinguish between variables defined in input files (like
@code{twentyFour} in the example above) and variables of internal
objects, we will call the latter @q{properties} and the former
@q{variables.}  So, the stem object has a @code{thickness} property,
while @code{twentyFour} is an variable.

@cindex properties vs. variables
@cindex variables vs. properties

Two-dimensional offsets (X and Y coordinates) as well as object sizes
(intervals with a left and right point) are entered as @code{pairs}.  A
pair@footnote{In Scheme terminology, the pair is called @code{cons},
and its two elements are called @code{car} and @code{cdr} respectively.}
is entered as @code{(first . second)} and, like symbols, they must be quoted,

@example
\override TextScript #'extra-offset = #'(1 . 2)
@end example

This assigns the pair (1, 2) to the @code{extra-offset} property of the
TextScript object.  These numbers are measured in staff-spaces, so
this command moves the object 1 staff space to the right, and 2 spaces up.

The two elements of a pair may be arbitrary values, for example

@example
#'(1 . 2)
#'(#t . #f)
#'("blah-blah" . 3.14159265)
@end example

A list is entered by enclosing its elements in parentheses, and adding
a quote.  For example,

@example
#'(1 2 3)
#'(1 2 "string" #f)
@end example

We have been using lists all along.  A calculation, like @code{(+ 1 2)}
is also a list (containing the symbol @code{+} and the numbers 1
and@tie{}2).  Normally lists are interpreted as calculations, and the
Scheme interpreter substitutes the outcome of the calculation.  To enter a
list, we stop the evaluation.  This is done by quoting the list with a
quote @code{'} symbol.  So, for calculations do not use a quote.

Inside a quoted list or pair, there is no need to quote anymore.  The
following is a pair of symbols, a list of symbols and a list of lists
respectively,

@example
#'(stem . head)
#'(staff clef key-signature)
#'((1) (2))
@end example


@menu
* Tweaking with Scheme::
@end menu

@node Tweaking with Scheme
@appendixsec Tweaking with Scheme

We have seen how LilyPond output can be heavily modified using
commands like
@code{\override TextScript #'extra-offset = ( 1 . -1)}.  But
we have even more power if we use Scheme.  For a full explanation
of this, see the @ref{Scheme tutorial}, and
@ruser{Interfaces for programmers}.

We can use Scheme to simply @code{\override} commands,

TODO Find a simple example
@c This isn't a valid example with skylining
@c It works fine without padText  -td

@ignore
@lilypond[quote,verbatim,ragged-right]
padText = #(define-music-function (parser location padding) (number?)
#{
  \once \override TextScript #'padding = #$padding
#})

\relative c''' {
  c4^"piu mosso" b a b
  \padText #1.8
  c4^"piu mosso" d e f
  \padText #2.6
  c4^"piu mosso" fis a g
}
@end lilypond
@end ignore

We can use it to create new commands:

@c Check this is a valid example with skylining
@c It is - 'padding still works


@lilypond[quote,verbatim,ragged-right]
tempoPadded = #(define-music-function (parser location padding tempotext)
  (number? string?)
#{
  \once \override Score.MetronomeMark #'padding = $padding
  \tempo \markup { \bold $tempotext }
#})

\relative c'' {
  \tempo \markup { "Low tempo" }
  c4 d e f g1
  \tempoPadded #4.0 #"High tempo"
  g4 f e d c1
}
@end lilypond


Even music expressions can be passed in:

@lilypond[quote,verbatim,ragged-right]
pattern = #(define-music-function (parser location x y) (ly:music? ly:music?)
#{
  $x e8 a b $y b a e
#})

\relative c''{
  \pattern c8 c8\f
  \pattern {d16 dis} { ais16-> b\p }
}
@end lilypond