Doc -- add structure to Scheme tutorial

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

@c -*- coding: utf-8; mode: texinfo; -*-

@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
@chapter 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 @rlearning{Other sources of information}).  Alternatively, Windows
users may simply choose @q{Run} from the Start menu and enter
@q{guile}.

@menu
* Introduction to Scheme::
* Scheme in LilyPond::
@end menu

@node Introduction to Scheme
@section Introduction to Scheme

We begin with an introduction to Scheme.  For this brief introduction,
we will use the GUILE interpreter to explore how the language works.
Once we are familiar with Scheme, we will show how the language can
be integrated in LilyPond files.


@menu
* Scheme simple data types::
* Scheme compound data types::
* Calculations in Scheme::
* Scheme procedures::
* Scheme conditionals::
@end menu

@node Scheme simple data types
@subsection Scheme simple data types

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


@node Scheme compound data types
@subsection Scheme compound data types

@unnumberedsubsubsec Pairs

TODO -- write about pairs

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

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


@unnumberedsubsubsec Lists

TODO -- write about lists

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

@unnumberedsubsubsec Hash tables

TODO -- write about hash tables


@node Calculations in Scheme
@subsection Calculations in Scheme

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}.

The same assignment can be done in completely in Scheme as well,

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

@c this next section is confusing -- need to rewrite

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}.

@node Scheme procedures
@subsection Scheme procedures

@unnumberedsubsubsec Predicates

@unnumberedsubsubsec Return values

TODO -- write about scheme procedures

@node Scheme conditionals
@subsection Scheme conditionals

@unnumberedsubsubsec if

@unnumberedsubsubsec cond


@node Scheme in LilyPond
@section Scheme in LilyPond


@menu
* LilyPond Scheme syntax::
* LilyPond variables::
* Object properties::
* LilyPond compound variables::
@end menu

@node LilyPond Scheme syntax
@subsection LilyPond Scheme syntax

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

@c todo -- # introduces a scheme *expression*
@c         need the concept of an expression

If @code{#} is followed by an opening parenthesis, @code{(}, as in
the example above, the parser will remain in Scheme mode until
a matching closing parenthesis, @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.

@node LilyPond variables
@subsection LilyPond variables


TODO -- make this read right

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}.

@node Object properties
@subsection Object properties

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

@c  todo -- here we're getting interesting.  We're now introducing
@c  LilyPond variable types.  I think this deserves a section all
@c  its own

@node LilyPond compound variables
@subsection LilyPond compound variables

@unnumberedsubsubsec Offsets

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.

@unnumberedsubsubsec Extents

todo -- write something about extents

@unnumberedsubsubsec Property alists

todo -- write something about property alists

@unnumberedsubsubsec Alist chains

todo -- write something about alist chains

@ignore
@menu
* Tweaking with Scheme::
@end menu

@node Tweaking with Scheme
@section 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
@ref{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
@end ignore

@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

@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
@end ignore