+The Guile interpreter is part of LilyPond, which means that
+Scheme can be included in LilyPond input files. There are several
+methods for including Scheme in LilyPond.
+
+The simplest way is to use a hash mark@tie{}@code{#} before a Scheme
+expression.
+
+Now LilyPond's input is structured into tokens and expressions, much
+like human language is structured into words and sentences. LilyPond
+has a lexer that recognizes tokens (literal numbers, strings, Scheme
+elements, pitches and so on), and a parser that understands the syntax,
+@rcontrib{LilyPond grammar}. Once it knows that a particular syntax rule
+applies, it executes actions associated with it.
+
+The hash mark@tie{}@code{#} method of embedding Scheme is a natural fit
+for this system. Once the lexer sees a hash mark, it calls the Scheme
+reader to read one full Scheme expression (this can be an identifier, an
+expression enclosed in parentheses, or several other things). After the
+Scheme expression is read, it is stored away as the value for an
+@code{SCM_TOKEN} in the grammar. Once the parser knows how to make use
+of this token, it calls Guile for evaluating the Scheme expression.
+Since the parser usually requires a bit of lookahead from the lexer to
+make its parsing decisions, this separation of reading and evaluation
+between lexer and parser is exactly what is needed to keep the execution
+of LilyPond and Scheme expressions in sync. For this reason, you should
+use the hash mark@tie{}@code{#} for calling Scheme whenever this is
+feasible.
+
+Another way to call the Scheme interpreter from LilyPond is the use of
+dollar@tie{}@code{$} instead of a hash mark for introducing Scheme
+expressions. In this case, Lilypond evaluates the code right after the
+lexer has read it. It checks the resulting type of the Scheme
+expression and then picks a token type (one of several
+@code{xxx_IDENTIFIER} in the syntax) for it. It creates a @emph{copy}
+of the value and uses that for the value of the token. If the value of
+the expression is void (Guile's value of @code{*unspecified*}), nothing
+at all is passed to the parser.
+
+This is, in fact, exactly the same mechanism that Lilypond employs when
+you call any variable or music function by name, as @code{\name}, with
+the only difference that the name is determined by the Lilypond lexer
+without consulting the Scheme reader, and thus only variable names
+consistent with the current Lilypond mode are accepted.
+
+The immediate action of @code{$} can lead to surprises, @ref{Input
+variables and Scheme}. Using @code{#} where the parser supports it
+is usually preferable. Inside of music expressions, expressions
+created using @code{#} @emph{are} interpreted as music. However,
+they are @emph{not} copied before use. If they are part of some
+structure that might still get used, you may need to use
+@code{ly:music-deep-copy} explicitly.
+
+@funindex $@@
+@funindex #@@
+There are also @q{list splicing} operators @code{$@@} and @code{#@@}
+that insert all elements of a list in the surrounding context.
+
+Now let's take a look at some actual Scheme code. Scheme procedures can
+be defined in LilyPond input files:
projects / lilypond.git / blobdiff