+@node Lilypond code blocks
+@section Lilypond code blocks
+
+Lilypond code blocks look like
+@example
+ #@{ @var{Lilypond code} #@}
+@end example
+They can be used anywhere where you can write Scheme code: the Scheme
+reader actually is changed for accommodating LilyPond code blocks. When
+the LilyPond code block is being read, it is parsed superficially and
+replaced by a call to the LilyPond @code{parser} which is executed at
+runtime to interpret the LilyPond code block.
+
+The point of the superficial parsing is the interpretation of @code{$}
+signs which can be used for splicing in expressions from the surrounding
+lexical Scheme context (like @code{let} variables and function
+parameters). @code{$} can be used in the following ways:
+
+@table @code
+@item $$
+just passes a single @code{$} to the LilyPond parser.
+@item $@var{form}
+will evaluate the Scheme form at runtime and splice its value as an
+identifier @code{\form} into the LilyPond parser. Depending on the
+value type, it may be interpreted as several different syntactic
+entities.
+@item #$@var{form}
+will evaluate the Scheme form at runtime and splice its value as a
+Scheme expression into the LilyPond parser.
+@item #@var{form}
+Forms in Scheme expressions started with @code{#} are read and parsed
+recursively for @code{$} signs. Those are treated as follows:
+@item #@dots{}$@var{variable}
+splices the value of the variable into the surrounding expression.
+@item #@dots{}($ @var{form} @dots{})
+splices the value of the form into the surrounding expression. As
+opposed to a LilyPond level @code{$@var{form}}, you need to separate the
+form with a blank, making @code{$} be recognizable as a separate Scheme
+symbol.
+@end table
+
+A LilyPond code block may contain anything that you can use on the right
+side of an assignment. In addition, an empty LilyPond block corresponds
+to a void music expression, and a LilyPond block containing multiple
+music events gets turned into a sequential music expression.
+
+@node Scheme functions
+@section Scheme functions
+@cindex Scheme functions (LilyPond syntax)
+
+@emph{Scheme functions} are Scheme procedures that can create Scheme
+expressions from input written in LilyPond syntax. They can be called
+in pretty much all places where using @code{#} for specifying a value in
+Scheme syntax is allowed. While Scheme has functions of its own, this
+chapter is concerned with @emph{syntactic} functions, functions that
+receive arguments specified in LilyPond syntax.
+
+@menu
+* Scheme function definitions::
+* Scheme function usage::
+* Void scheme functions::
+@end menu
+
+@node Scheme function definitions
+@subsection Scheme function definitions
+@funindex define-scheme-function
+
+The general form for defining scheme functions is:
+
+@example
+function =
+#(define-scheme-function
+ (parser location @var{arg1} @var{arg2} @dots{})
+ (@var{type1?} @var{type2?} @dots{})
+ @var{body})
+@end example
+
+@noindent
+where
+
+@multitable @columnfractions .33 .66
+@item @code{parser}
+@tab needs to be literally @code{parser} in order to give LilyPond code
+blocks (@code{#@{}@dots{}@code{#@}}) access to the parser.
+
+@item @code{@var{argN}}
+@tab @var{n}th argument
+
+@item @code{@var{typeN?}}
+@tab a Scheme @emph{type predicate} for which @code{@var{argN}}
+must return @code{#t}. Some of these predicates are specially
+recognized by the parser, see below. There is also a special form
+@code{(@emph{predicate?} @emph{default})} for specifying optional
+arguments. If the actual argument is missing when the function is being
+called, the default value is substituted instead. Default values are
+evaluated at definition time (including LilyPond code blocks!), so if
+you need a default calculated at runtime, instead write a special value
+you can easily recognize. If you write the predicate in parentheses but
+don't follow it with a default value, @code{#f} is used as the default.
+Default values are not verified with @emph{predicate?} at either
+definition or run time: it is your responsibility to deal with the
+values you specify. Default values that happen to be music expressions
+are copied while setting @code{origin} to the @code{location} parameter.
+
+@item @code{@var{body}}
+@tab A sequence of Scheme forms evaluated in order, the last one being
+used as the return value of the scheme function. It may contain
+LilyPond code blocks enclosed in hashed braces
+(@tie{}@w{@code{#@{@dots{}#@}}}@tie{}), like described in @ref{Lilypond
+code blocks}. Within LilyPond code blocks, use @code{$} to reference
+function arguments (eg., @samp{$arg1}) or to start an inline Scheme
+expression containing function arguments (eg., @w{@samp{$(cons arg1
+arg2)}}). If your function returns a music expression, it is cloned and
+given the correct @code{origin}.
+@end multitable
+
+@noindent
+Some type predicates are specially handled by the parser since it
+can't recognize the arguments reliably otherwise. Currently these are
+@code{ly:pitch?} and @code{ly:duration?}.
+
+Suitability of arguments for all other predicates is determined by
+actually calling the predicate after Lilypond has already converted
+them into a Scheme expression. As a consequence, the argument can be
+specified in Scheme syntax if desired (introduced with @code{#} or as
+the result of calling a scheme function), but Lilypond will also
+convert a number of Lilypond constructs into Scheme before actually
+checking the predicate on them. Currently, those include music,
+simple strings (with or without quotes), numbers, full markups and markup
+lists, score, book, bookpart, context definition and output definition
+blocks.
+
+For some kinds of expression (like most music not enclosed in braces)
+Lilypond needs to look further than the expression itself in order to
+determine its end. If such an expression were considered for an
+optional argument by evaluating its predicate, Lilypond would not be
+able to ``backup'' when it decides the expression does not fit the
+parameter. So some forms of music might need to be enclosed in braces
+to make them acceptable to Lilypond. There are also some other
+complications that may cause a predicate function to be called several
+times on successive versions of an argument (like @code{3} and
+@code{3\cm}) or several interpretations (like @code{"a" 4} in lyric
+mode, which can either be a string followed by a number, or a lyric
+event of duration @code{4}).
+
+Music arguments preceding @code{ly:duration?} arguments must also be
+lookahead-free. This may also hold for the last argument of a scheme
+function that is used as the last part of another expression, since
+otherwise Lilypond won't know whether following postevents or
+durations apply to the argument of the Scheme function, or to the
+containing music expression.
+
+For a list of available type predicates, see
+@ruser{Predefined type predicates}.
+
+@seealso
+
+Notation Reference:
+@ruser{Predefined type predicates}.
+
+Installed Files:
+@file{lily/music-scheme.cc},
+@file{scm/c++.scm},
+@file{scm/lily.scm}.
+
+@node Scheme function usage
+@subsection Scheme function usage
+
+Scheme functions can be called pretty much anywhere where a Scheme
+expression starting with @code{#} can be written. You call a scheme
+function by writing its name preceded by @code{\}, followed by its
+arguments. The last argument can't be an optional argument. If there
+are several optional arguments in a row, they are filled with values
+left to right. Once an optional argument can't match input, it and all
+immediately following optional arguments are replaced with their default
+values, and the matching continues with the next non-optional argument.
+
+Apart from places where a Scheme value is required, there are a few
+places where @code{#} expressions are currently accepted and evaluated
+for their side effects but otherwise ignored. Mostly those are the
+places where an assignment would be acceptable as well.
+
+Since it is a bad idea to return values that can be misinterpreted in
+some context, you should use normal scheme functions only for those
+cases where you always return a useful value, and use void scheme
+functions (@pxref{Void scheme functions}) otherwise.
+
+@node Void scheme functions
+@subsection Void scheme functions
+@funindex define-void-function
+@funindex \void
+
+Sometimes a procedure is executed in order to perform an action rather
+than return a value. Some programming languages (like C and Scheme)
+use functions for either concept and just discard the returned value
+(usually by allowing any expression to act as statement, ignoring the
+result). This is clever but error-prone: most C compilers nowadays
+offer warnings for various non-``void'' expressions being discarded.
+For many functions executing an action, the Scheme standards declare
+the return value to be unspecified. Lilypond's Scheme interpreter
+Guile has a unique ``unspecified'' value that it usually (such when
+using @code{set!} directly on a variable) but unfortunately not
+consistently returns in such cases.
+
+Defining a Lilypond function with @code{define-void-function} makes
+sure that this special value (the only value satisfying the predicate
+@code{void?}) will be returned.
+
+@example
+noPointAndClick =
+#(define-void-function
+ (parser location)
+ ()
+ (ly:set-option 'point-and-click #f))
+...
+\noPointAndClick % disable point and click
+@end example
+
+If you want to evaluate an expression only for its side-effect and
+don't want any value it may return interpreted, you can do so by
+prefixing it with @code{\void}:
+
+@example
+\void #(hashq-set! some-table some-key some-value)
+@end example
+
+That way, you can be sure that Lilypond will not assign meaning to the
+returned value regardless of where it encounters it. This will also
+work for music functions such as @code{\displayMusic}.
projects / lilypond.git / blobdiff