Extending LilyPond: 1.3.1 Displaying music expressions

### 1.3.1 Displaying music expressions

When writing a music function it is often instructive to inspect how a music expression is stored internally. This can be done with the music function `\displayMusic`.

>     {
>       \displayMusic { c'4\f }
>     }

will display

>     (make-music
>       'SequentialMusic
>       'elements
>       (list (make-music
>               'NoteEvent
>               'articulations
>               (list (make-music
>                       'AbsoluteDynamicEvent
>                       'text
>                       "f"))
>               'duration
>               (ly:make-duration 2 0 1/1)
>               'pitch
>               (ly:make-pitch 0 0 0))))

By default, LilyPond will print these messages to the console along with all the other messages. To split up these messages and save the results of `\display{STUFF}`, you can specify an optional output port to use:

>     {
>       \displayMusic #(open-output-file "display.txt") { c'4\f }
>     }

This will overwrite a previous output file whenever it is called; if you need to write more than one expression, you would use a variable for your port and reuse it:

>     {
>       port = #(open-output-file "display.txt")
>       \displayMusic \port { c'4\f }
>       \displayMusic \port { d'4 }
>       #(close-output-port port)
>     }

Guile’s manual describes ports in detail. Closing the port is actually only necessary if you need to read the file before LilyPond finishes; in the first example, we did not bother to do so.

A bit of reformatting makes the above information easier to read:

>     (make-music 'SequentialMusic
>       'elements (list
>                  (make-music 'NoteEvent
>                    'articulations (list
>                                    (make-music 'AbsoluteDynamicEvent
>                                                'text
>                                                "f"))
>                    'duration (ly:make-duration 2 0 1/1)
>                    'pitch    (ly:make-pitch 0 0 0))))

A `{ … }` music sequence has the name `SequentialMusic`, and its inner expressions are stored as a list in its `'elements` property. A note is represented as a `NoteEvent` object (storing the duration and pitch properties) with attached information (in this case, an `AbsoluteDynamicEvent` with a `"f"` text property) stored in its `articulations` property.

`\displayMusic` returns the music it displays, so it will get interpreted as well as displayed. To avoid interpretation, write `\void` before `\displayMusic`.

#### LilyPond — Extending v2.22.2 (stable-branch).