2.3.4 Intermediate substitution functions (Extending LilyPond)

#### 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
    #})

#### Extending LilyPond v2.26.0 (stable-branch).

- 1 Scheme tutorial
  - 1.1 Introduction to Scheme
    - 1.1.1 Scheme sandbox
    - 1.1.2 Scheme variables
    - 1.1.3 Scheme simple data types
    - 1.1.4 Scheme compound data types
      - Pairs
      - Lists
      - Association lists (alists)
      - Hash tables
    - 1.1.5 Calculations in Scheme
    - 1.1.6 Scheme procedures
      - Defining procedures
      - Predicates
      - Return values
    - 1.1.7 Scheme conditionals
      - if
      - cond
  - 1.2 Scheme in LilyPond
    - 1.2.1 LilyPond Scheme syntax
    - 1.2.2 LilyPond variables
    - 1.2.3 Debugging Scheme code
    - 1.2.4 Input variables and Scheme
    - 1.2.5 Importing Scheme in LilyPond
    - 1.2.6 Object properties
    - 1.2.7 LilyPond compound variables
      - Offsets
      - Fractions
      - Extents
      - Property alists
      - Alist chains
    - 1.2.8 LilyPond’s box model
    - 1.2.9 Internal music representation
  - 1.3 Building complicated functions
    - 1.3.1 A first approach (example)
    - 1.3.2 Displaying music expressions
    - 1.3.3 Music properties
    - 1.3.4 Doubling a note with slurs (example)
    - 1.3.5 Adding articulation to notes (example)
- 2 Interfaces for programmers
  - 2.1 LilyPond code blocks
  - 2.2 Scheme functions
    - 2.2.1 Scheme function definitions
    - 2.2.2 Scheme function usage
    - 2.2.3 Void Scheme functions
  - 2.3 Music functions
    - 2.3.1 Music function definitions
    - 2.3.2 Music function usage
    - 2.3.3 Simple substitution functions
    - 2.3.4 Intermediate substitution functions
    - 2.3.5 Mathematics in functions
    - 2.3.6 Functions without arguments
    - 2.3.7 Void music functions
  - 2.4 Event functions
  - 2.5 Markup functions
    - 2.5.1 Markup construction in Scheme
    - 2.5.2 How markups work internally
    - 2.5.3 New markup command definition
      - Markup command definition syntax
      - On properties
      - A complete example
      - Adapting builtin commands
      - Converting markups to strings
    - 2.5.4 New markup list command definition
  - 2.6 Contexts for programmers
    - 2.6.1 Context evaluation
    - 2.6.2 Running a function on all layout objects
  - 2.7 Callback functions
  - 2.8 Unpure-pure containers
  - 2.9 Difficult tweaks
- 3 LilyPond Scheme interfaces
- Appendix A GNU Free Documentation License
- Appendix B Index