GNU LilyPond

-- --

Manipulating music expressions

The \apply mechanism gives you access to the internal representation of music. You can write Scheme-functions that operate directly on it. The syntax is

     \apply #func music
     

This means that func is applied to music. The function func should return a music expression.

This example replaces the text string of a script. It also shows a dump of the music it processes, which is useful if you want to know more about how music is stored.

     #(define (testfunc x)
       (if (equal? (ly-get-mus-property x 'text) "foo")
           (ly-set-mus-property! x 'text "bar"))
       ;; recurse
       (ly-set-mus-property! x 'elements
         (map testfunc (ly-get-mus-property x 'elements)))
       (display x)
       x)
     
     \score {
       \notes
       \apply #testfunc { c'4_"foo" }
     }
     

For more information on what is possible, see the automatically generated documentation.

Directly accessing internal representations is dangerous: The implementation is subject to changes, so you should avoid this feature if possible.

A final example is a function that reverses a piece of music in time:

     #(define (reverse-music music)
       (let* ((elements (ly-get-mus-property music 'elements))
              (reversed (reverse elements))
              (span-dir (ly-get-mus-property music 'span-direction)))
         (ly-set-mus-property! music 'elements reversed)
         (if (dir? span-dir)
             (ly-set-mus-property! music 'span-direction (- span-dir)))
         (map reverse-music reversed)
         music))
     
     music = \notes { c'4 d'4( e'4 f'4 }
     
     \score {
       \context Voice {
         \music
         \apply #reverse-music \music
       }
     }
     

More examples are given in the distributed example files in input/test/.

• Span requests:

Please send GNU LilyPond questions and comments to lilypond-user@gnu.org.

Please send comments on these web pages to (address unknown)

Copyright (c) 1997--2002 Han-Wen Nienhuys and Jan Nieuwenhuizen.

Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.