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.
@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
(define bar 1))
@end example
-If @code{#} is followed by an opening bracket, @code{(}, as in
+@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 bracket, @code{)}, is found, so further
+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.
-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
+@node LilyPond variables
+@subsection LilyPond variables
-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
+TODO -- make this read right
-These calculations are examples of evaluations; an expression like
-@code{(* 3 4)} is replaced by its value @code{12}. A similar thing
+A similar thing
happens with variables. After defining a variable
@example
-twelve = #12
+twelve = 12
@end example
@noindent
variables can also be used in expressions, here
@example
-twentyFour = #(* 2 twelve)
+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}.
+@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
@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},
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
+@unnumberedsubsubsec Extents
-@example
-#'(1 . 2)
-#'(#t . #f)
-#'("blah-blah" . 3.14159265)
-@end example
+todo -- write something about extents
-A list is entered by enclosing its elements in parentheses, and adding
-a quote. For example,
+@unnumberedsubsubsec Property alists
-@example
-#'(1 2 3)
-#'(1 2 "string" #f)
-@end example
+todo -- write something about property alists
-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 Alist chains
+todo -- write something about alist chains
+@ignore
@menu
* Tweaking with Scheme::
@end menu
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]
@end lilypond
@end ignore
+@ignore
We can use it to create new commands:
@c Check this is a valid example with skylining
\pattern {d16 dis} { ais16-> b\p }
}
@end lilypond
-
-
-
-
-
+@end ignore
projects / lilypond.git / commitdiff