[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: More explanations to make-engraver available
|
From: |
Urs Liska |
|
Subject: |
Re: More explanations to make-engraver available |
|
Date: |
Sat, 9 Jun 2018 23:54:07 +0200 |
|
User-agent: |
Mozilla/5.0 (X11; Linux x86_64; rv:52.0) Gecko/20100101 Thunderbird/52.7.0 |
Am 09.06.2018 um 10:57 schrieb David Kastrup:
Urs Liska <address@hidden> writes:
I'm wondering if there's any comprehensive write-up about the
components of make-engraver available anywhere.
So far all my (rather few) engravers have been simply based on a
template provided by someone else, but I would be really glad to
become more independent about that.
I understand that a (Scheme) engraver is a lambda function that is
passed a context, and that it (usually, always?) returns an object
created with (make-engraver).
I further see that within make-engraver one defines a (subset of a)
number of different elements (initialize, process-music etc.) that
will then process the given context at different stages of the
compilation process. I have also read the docstring of make-engraver
in scm/output-lib.scm.
However, it is still unclear to me what exactly the different elements
that can be defined in make-engraver are doing, in what order they are
called, which information they are passed and what the "results" of
these calls are.
Rather than having to resort to browsing through the LSR and getting
the information by guessing from existing engravers I would really
like to see this properly explained somewhere, either in a
comprehensive tutorial or - better - in the official documentation.
Did I just not find that or is that actually missing information?
It's not user-level documented information.
OK, I see (or of course that was expected).
However, I think this would fit well in the Extending manual.
Basically there is
ly/event-listener.ly and input/regression/scheme-engraver.ly and
input/regression/scheme-engraver-instance.ly for the Scheme level, well,
examples (documentation would be a bit much to say).
OK, this gets much closer to what I need than the mere make-engraver
docstring.
Am I understanding the following things right?
1)
(listeners ((note-event engraver event) <body>))
creates a function that is called for each note-event. It is passed the
engraver (from which the context can be derived) and the event itself,
and these can be used in the function body.
To create multiple listeners I can simply add further list elements of
the form
((<event-class> engraver event) <body>)
2)
From the above I'm slightly confused about what the "engraver" is here.
Somehow the engraver I'm creating with make-engraver must be a different
object than the one that is passed to the listener, isn't it?
3)
As an alternative to the above syntax I can write
(listeners
(<event-class> . <handler>))
where <handler> is a function that expects the same <engraver> and
<event> arguments as the ad-hoc functions above.
4)
(initialize) is called once, when the context is started being
parsed(?), and the <translator> only has information about the context,
not about any elements (music) within. So that can be used to set up
things, like printing a message, preparing some storage, reading/setting
options etc.
5)
What are start-translation-timestep and stop-translation-timestep used
for? IIUC they don't get information about any grobs, so are they used
to do set-up/housekeeping before or after a timestep is processed?
And (of course) a few more questions:
1)
acknowledgers and end-acknowledgers are a little unclear to me.
The functions in acknowledgers are called whenever a grob is created,
right? But is that while processing the input or later while doing
engraving?
And what is it we can do here with the <engraver> and <source-engraver>
arguments?
When are the functions in end-acknowledgers called?
2)
When are process-music and process-acknowledgers called and to what
information do we have access in these functions?
I'm sure this won't be the last questions as any replies will probably
trigger more questions and raise more confusion on my side ;-) But I'd
be glad about any further enlightenment.
Urs
You'll likely find more useful information in the "Engraver tutorial" in
the Contributor's guide. It's about C++ engravers but it's pretty
straightforward to figure out which parts would correspond to Scheme
engravers and which not (for example, ignore everything dealing with
garbage collection).