2.3 Music functions

Music functions are Scheme procedures that can create music expressions automatically, and can be used to greatly simplify the input file.

2.3.1 Music function definitions

The general form for defining music functions is:

function =
#(define-music-function
     (arg1 arg2 …)
     (type1? type2? …)
   body)

quite in analogy to Scheme function definitions. More often than not, body will be a LilyPond code block.

For a list of available type predicates, see (notation)Predefined type predicates section ‘Predefined type predicates’ in Notation Reference.

See also

Notation Reference: (notation)Predefined type predicates section ‘Predefined type predicates’ in Notation Reference.

Installed Files: ‘lily/music-scheme.cc’, ‘scm/c++.scm’, ‘scm/lily.scm’.

2.3.2 Music function usage

A ‘music function’ has to return an expression matching the predicate ly:music?. This makes music function calls suitable as arguments of type ly:music? for another music function call.

When using a music function call in other contexts, the context may cause further semantic restrictions.

• At the top level in a music expression a post-event is not accepted.
• When a music function (as opposed to an event function) returns an expression of type post-event, LilyPond requires one of the named direction indicators (-, ^, and _) in order to properly integrate the post-event produced by the music function call into the surrounding expression.
• As a chord constituent. The returned expression must be of a rhythmic-event type, most likely a NoteEvent.

‘Polymorphic’ functions, like \tweak, can be applied to post-events, chord constituent and top level music expressions.

2.3.3 Simple substitution functions

Simple substitution functions are music functions whose output music expression is written in LilyPond format and contains function arguments in the output expression. They are described in (notation)Substitution function examples section ‘Substitution function examples’ in Notation Reference.

2.3.4 Intermediate substitution functions

Intermediate substitution functions involve a mix of Scheme code and LilyPond code in the music expression to be returned.

Some \override commands require an argument consisting of a pair of numbers (called a cons cell in Scheme).

The pair can be directly passed into the music function, using a pair? variable:

manualBeam =
#(define-music-function
     (beg-end)
     (pair?)
   #{
     \once \override Beam.positions = #beg-end
   #})

\relative c' {
  \manualBeam #'(3 . 6) c8 d e f
}

Alternatively, the numbers making up the pair can be passed as separate arguments, and the Scheme code used to create the pair can be included in the music expression:

manualBeam = #(define-music-function (beg end) (number? number?) #{ \once \override Beam.positions = #(cons beg end) #}) \relative c' { \manualBeam #3 #6 c8 d e f }

Properties are maintained conceptually using one stack per property per grob per context. Music functions may need to override one or several properties for the duration of the function, restoring them to their previous value before exiting. However, normal overrides pop and discard the top of the current property stack before pushing to it, so the previous value of the property is lost when it is overridden. When the previous value must be preserved, prefix the \override command with \temporary, like this:

\temporary \override …

The use of \temporary causes the (usually set) pop-first property in the override to be cleared, so the previous value is not popped off the property stack before pushing the new value onto it. When a subsequent \revert pops off the temporarily overriden value, the previous value will re-emerge.

In other words, calling \temporary \override and \revert in succession on the same property will have a net effect of zero. Similarly, pairing \temporary and \undo on the same music containing overrides will have a net effect of zero.

Here is an example of a music function which makes use of this. The use of \temporary ensures the values of the cross-staff and style properties are restored on exit to whatever values they had when the crossStaff function was called. Without \temporary the default values would have been set on exit.

crossStaff =
#(define-music-function (notes) (ly:music?)
  (_i "Create cross-staff stems")
  #{
  \temporary \override Stem.cross-staff = #cross-staff-connect
  \temporary \override Flag.style = #'no-flag
  #notes
  \revert Stem.cross-staff
  \revert Flag.style
#})

2.3.5 Mathematics in functions

Music functions can involve Scheme programming in addition to simple substitution,

AltOn = #(define-music-function (mag) (number?) #{ \override Stem.length = #(* 7.0 mag) \override NoteHead.font-size = #(inexact->exact (* (/ 6.0 (log 2.0)) (log mag))) #}) AltOff = { \revert Stem.length \revert NoteHead.font-size } \relative { c'2 \AltOn #0.5 c4 c \AltOn #1.5 c c \AltOff c2 }

This example may be rewritten to pass in music expressions,

withAlt = #(define-music-function (mag music) (number? ly:music?) #{ \override Stem.length = #(* 7.0 mag) \override NoteHead.font-size = #(inexact->exact (* (/ 6.0 (log 2.0)) (log mag))) #music \revert Stem.length \revert NoteHead.font-size #}) \relative { c'2 \withAlt #0.5 { c4 c } \withAlt #1.5 { c c } c2 }

2.3.6 Functions without arguments

In most cases a function without arguments should be written with a variable,

dolce = \markup{ \italic \bold dolce }

However, in rare cases it may be useful to create a music function without arguments,

displayBarNum =
#(define-music-function
     ()
     ()
   (if (eq? #t (ly:get-option 'display-bar-numbers))
       #{ \once \override Score.BarNumber.break-visibility = ##f #}
       #{#}))

To actually display bar numbers where this function is called, invoke lilypond with

lilypond -d display-bar-numbers FILENAME.ly

2.3.7 Void music functions

A music function must return a music expression. If you want to execute a function only for its side effect, you should use define-void-function. But there may be cases where you sometimes want to produce a music expression, and sometimes not (like in the previous example). Returning a void music expression via #{ #} will achieve that.

This document was generated by gub on July 13, 2020 using texi2html 1.82.

Jiné jazyky: deutsch, español, français.
O automatickém výběru řeči.