Smylers wrote:
> Jon Lang writes:
>> FWIW, the current proposal for aliasing blocks of ambient text is
>> functional; it just feels a bit kludgey,
>
> Why? To me it seems the opposite: what could be more natural for
> delimiting a block of code than braces?
Because sometimes you'll want to capture only part of a block of code,
or a little bit more than a block of code. In short, what you want
for documentation purposes won't always align with the conceptual
structure of the ambient code. I don't like the idea of being
required to break the code up into blocks whose only purpose is
documentation: if you're breaking the ambient code up into chunks for
documentation purposes, it should _look_ like the code is being broken
up into chunks for documentation purposes. Using Pod tricks for
denoting the start and end of aliased ambient text does that; using a
Perl block doesn't.
>> and I'm a bit bothered by the fact that you can't alias any ambient
>> text other than a code block.
>
> "Can't" is a bit strong: it's more that if you want to quote an
> arbitrary portion of code then you need to add some braces around it.
> But those braces are unlikely to harm the program.
>
> The exception is if you want to quote an 'unbalanced' portion of code,
> for example the start of a loop but not the entire loop. Do you
> consider that to be likely?
Actually, yes; I do.
>> how about saying that an ambient code alias is normally
>> terminated by the next blank line or Pod directive (as per =for)
>
> Braces are more robust than blank lines; if aliasing a brace-delimited
> block I may unthinkingly edit it to have a blank line in the middle of
> it, on the basis that the blank line isn't significant to perl.
And =begin blocks are more robust than =for blocks in the same way.
Perl may not care about blank lines; but Pod does. And the author of
a file with both Perl and Pod in it is being remiss in his duties if
he doesn't consider both paradigms. Incidently, note that declarator
blocks already behave this way in Pod: the presence or absence of a
blank line determines the code to which it gets attached.
> (Whereas if I edit the braces then I've changed the program as well as
> its docs.)
Right. If the braces weren't part of the ambient code, and were there
merely to delineate the aliased text, I'd have less of a problem with
them. In fact, my main problem with them at that point would be how
much they look like a code block without being one, and the confusion
that's sure to arise.
>> > Let's see what others think.
>>
>> OK.
>
> I like the braces. I suggest initially only providing for braces, but
> with the possibility of later adding options to indicate other
> termination points if in practice there turn out to be many situations
> where the braces don't work well.
I like the idea of using the braces if they're there, and using
something else if they're not. Again, my concern is is being forced
to alias an entire code block, never anything more or less; I'm not
opposed to being _able_ to alias an entire code block, and I'm
especially not opposed to being able to do so in a simple and
intuitive manner.
But let me propose something for the "absence of braces" case:
introduce a new kind of delimiter into Perl - something that works
like an embedded comment, except that it doesn't actually comment
anything out. In the absence of a curly brace at the start of the
next line of code, a code alias will bind to the first "document tag"
that it finds, that isn't already claimed by another =alias directive.
For example:
=alias loop
#:[[
=alias loop-head
loop #:[($i = 1; $i < $j; $i *= 2)]
=alias loop-body
{
DoSomething($i);
}
]]
In this example, I'm using #:[...] as a stand-in for the
"documentation tag" syntax. As such,
"loop" is aliased to:
loop ($i = 1; $i < $j; $i *= 2)
{
DoSomething($i);
}
"loop-head" is aliased to:
($i = 1; $i < $j; $i *= 2)
And "loop-body" is aliased to:
{
DoSomething($i);
}
I'm not fond of the "document tag" syntax used in the above example;
it looks a little bit too much like a comment. But whatever does get
used, it should be brief and distinct.
And since we're talking about connecting code and documentation, it's
possible that we might want to have this kind of alias be a special
case of the declaration block rather than a stand-alone directive,
using similar rules to determine what to alias (but focused on code
blocks and doc tags rather than declarators).
I've got to run right now; but I've more thoughts that just got
triggered by this. I'll get back to you as soon as I can.
--
Jonathan "Dataweaver" Lang
