Re: Creating LilyPond Object Models

[Paul Morris]

Thanks Carl, Johannes, and David for working on this overview.

> On Apr 23, 2015, at 4:25 AM, Johannes Rohrer <address@hidden> wrote:
> 
> Translators selectively (based on assigned Event Classes) "accept"
> Events from the stream that were sorted into "their" context and process
> them. Typically, they will produce "output objects" (for Engravers:
> layout objects, aka Grobs; for Performers: Audio_items) and "announce"
> these. Other Translators can "acknowledge" certain types of announced
> objects to process them further.

Thanks especially for this insight.  After a little digging into the source 
code I now understand the difference between “listeners” and “acknowledgers” in 
a scheme engraver created with the "make-engraver" macro.  

In short, “listeners” respond to particular stream events:
http://lilypond.org/doc/v2.18/Documentation/internals/music-classes
while “acknowledgers” respond to particular grobs that have been “announced” by 
other engravers (that created the grobs based on the stream events that they 
“listened” to).  This process of acknowledging grobs happens through grob 
interfaces:
http://lilypond.org/doc/v2.18/Documentation/internals/graphical-object-interfaces

Basically like this:

[stream event] —> [engraver A with listener] —> [grob]

[grob] —> [engraver B with acknowledger] —> […]

but engravers can have both listeners and acknowledgers, and more than one of 
each.  Here’s an example:

%%%%%%%%%%%%%%%%%%
\version "2.18.2"

#(define Some_custom_engraver
     (make-engraver
      (listeners
       ((key-change-event engraver event)
        (display event)(newline)
        ;; do something with key-change-event events
        )
       ((note-event engraver event)
        (display event)(newline)
        ;; do something with note-event events
        ))
       (acknowledgers
        ((key-signature-interface engraver grob source-engraver)
         (display grob)(newline)
         ;; do something with key-signature grobs
         )
       ((note-head-interface engraver grob source-engraver)
       (display grob)(newline)
       ;; do something with note-head grobs
       ))))

\new Staff \with {
  \consists \Some_custom_engraver
}{
  \key c \major
  c'1
}
%%%%%%%%%%%%%%%%%%

As far as I can tell the order in which engravers are “consisted” in their 
given context determines the order in which they receive the incoming events 
and grobs.  

It’s probably *very* rare that a user would ever need to create an engraver and 
need to know about listeners and acknowledgers.  

For anyone wanting to go further there’s more that I don’t understand 
(initialize, start-translation-timestep, process-music, etc.), to quote from 
the doc string of the make-engraver macro at the bottom of scm/output-lib.scm:

Symbols mapping to a function would be @code{initialize},
@code{start-translation-timestep}, @code{process-music},
@code{process-acknowledged}, @code{stop-translation-timestep}, and
@code{finalize}.  Symbols mapping to another alist specified in the
same manner are @code{listeners} with the subordinate symbols being
event classes, and @code{acknowledgers} and @code{end-acknowledgers}
with the subordinate symbols being interfaces.”

Let me know if I’ve misrepresented anything.

Thanks again,
-Paul