Re: Adds some info about pure properties to the CG. (issue 5364048)

[Joe Neeman]

Bah, I just wrote out a nice reply on the codereview site and it got eaten...

On Fri, Nov 18, 2011 at 12:03 AM, address@hidden <address@hidden> wrote:

On Nov 16, 2011, at 2:19 AM, address@hidden wrote:

> http://codereview.appspot.com/5364048/diff/4001/Documentation/contributor/programming-work.itexi#newcode1888
> Documentation/contributor/programming-work.itexi:1888: taken from the
> stencil.
> Actually, the requirement is different: the print function must not have
> any side effects. The print function doesn't necessarily have to deliver
> the same result at all stages in the compilation process. For example,
> if some side-effect modifies the font size of a grob mid-compilation,
> then note-head::print will deliver a stencil of a different height.
>

Then I misunderstood what pure means in lily-speak.  I thought that a pure function had the dual condition that it (a) always return the same value for a given begin and end range; and (b) not trigger any side effects.

Are there any cases where pure functions do deliver different results for the same range before line breaking?  And, if not, would this even be conceivable/desirable?

I can't think of a situation where it's desirable, but it's certainly conceivable. If I write lily code that, for whatever reason, has a callback which changes Slur 'height-limit then Slur::calc_pure_height will also change. We tend to avoid the use of set_property after the translation step, so this sort of thing is unlikely; the point is, though, that the pure callback itself doesn't worry about such things. It just tries to avoid side-effects, and if something else with side effects messes with grob properties then the pure callback can change its value accordingly.

Lastly, the idea of "not trigger any side effects" is something that I grok more than I understand.  Is there any way to communicate what it means to "not trigger side effects" (i.e. never calls (or results in the calling of) set_property on another property with a pure estimation, etc.) to someone who doesn't know what these side effects are?

The main side effects in lilypond are set_property, set_object and suicide. These are easy to avoid; the trickier part is that any call to get_property could conceivably trigger a callback that will itself have side effects.

 

> http://codereview.appspot.com/5364048/diff/4001/Documentation/contributor/programming-work.itexi#newcode1901
> Documentation/contributor/programming-work.itexi:1901: @end itemize
> I think the preceding four lists can be understood as follows: if you
> have a Grob and you want to estimate its height, what can you do?
>
> - If its Y-extent callback is pure, just use it (pure-functions)
> - If its Y-extent callback is ly:grob::stencil-height and the stencil
> callback is pure, then it's safe to use ly:grob::stencil-height
> (pure-print-functions)
> - If we have a manually-created pure version of its Y-extent callback,
> use that (pure-conversions-alist and pure-print-to-height-conversions)

I agree, but is this not clear from the document as it stands and, if not, how should it be modified so that it is clear?  My biggest worry is clarity, as I often don't understand what I'm saying, so I'd imagine that others will have an even harder time.

I'm not sure which version is better for new readers. It's just that you're explaining these lists in terms of what they contain, while I find it easier to think of them in terms of their role in call-pure-function (which also helps to explain why we would bother to have these lists in the first place).

Cheers,

Joe