Damian Conway wrote:
> Jon Lang kept his promise:
>
>> I promised some further thoughts; here they are:
>
> Much appreciated.
You're welcome.
>> As written, declarator aliasing attaches the alias to a piece of code,
>> and draws both the name and the alias from that. What about using a
>> special case of the declarator block for this? That is:
>>
>> class Database::Handle { #=alias
>> has IO $!handle; #=alias
>> my Bool method open ($filename) {...} #=alias
>>
>> =for para
>> Note that the A<method> method of class A<class>
>> stores the resulting low-level database handle
>> in its private A<has> attribute.
>>
>> }
>>
>
> or:
>
>> class Database::Handle { #=>
>> has IO $!handle; #=>
>> my Bool method open ($filename) {...} #=>
>>
>> =for para
>> Note that the A<method> method of class A<class>
>> stores the resulting low-level database handle
>> in its private A<has> attribute.
>>
>> }
>
> Definitely interesting ideas, especially the second one. My concern
> would be that they compete
> with the #= blocks which might also be needed on such declarations.
I don't think that there will be a problem. First, #=> is easy enough
to distinguish from #=; I don't foresee any confusion. Second, your
existing rules for #= already allow for multiple such blocks to be
attached to one thing, with the rule being that you append the latter
ones to the former ones:
#= Class Foo
class Foo {
#= a sample class used to illustrate.
#= This particular class has nothing in it.
}
...results in the equivalent of:
=for pod
Class Foo
a sample class used to illustrate.
This particular class has nothing in it.
With the ability to attach multiple declarator blocks to a single
declarator, it should be trivial to replace any one of them with a
declarator alias:
#=>
class Foo {
#= Class Foo
#= a sample class used to illustrate.
#= This particular class has nothing in it.
}
There _is_ a question about when the alias becomes available:
#= Class A<class>
class Foo {
#= a sample class used to illustrate.
#= This particular class has nothing in it.
#=> X<this assigns to the 'class' declarator alias.>
Would A<class> in the first line become 'Foo', or would it be whatever
A<class> was before that line? My later suggestion of an empty A<>
mitigates this problem by making such references less frequent in
practice; but it doesn't eliminate it. My personal preference would
be for it to refer to 'Foo'; but that would involve postponing the
evaluation of Foo's WHY block until all possible relevant data has
been collected.
>> Regardless of what syntax you use for declarator aliasing, I'd also
>> recommend some sort of numbering scheme if you alias more than one
>> declarator of the same type in the same lexical scope:
>
> It's definitely an issue I hadn't considered properly. However, I
> think the correct
> solution is not numbering (which is always fraught with problems when
> subsequent
> maintenance adds an extra declarator in the middle), but rather naming. Like
> so:
I tend to agree. I only proposed numbering as a way of being able to
access different declarators without having to explicitly label them.
I can definitely understand if this option gets dropped as being too
error-prone with regard to maintenance.
> =alias
> class Database::Handle {
> =alias
> has IO $!handle;
>
> =alias open
> my Bool method open ($filename) {...}
>
> =alias close
> my Bool method close() {...}
>
> =for para
> Note that the A<open> method of class A<class>
> stores the resulting low-level database handle
> in its private A<has> attribute, while the A<close>
> method closes that handle.
> }
The problem with this example is that '=alias name' isn't a declarator
alias; it's a block alias. (I don't have a problem with the
underlying concept that you're trying to illustrate.) So A<open>
would be 'my Bool method open($filename) {...}', when what you'd be
looking for in a named declarator alias would be 'open'. (And it
might not even be that, unless you loosen the syntactic requirements
for a block alias: there are no subsequent curly braces to define how
much gets aliased.) Which brings me to:
>> If you adopt the declarator block basis for declarator aliasing, you
>> could even let the documenter choose his own names:
>>
>> class Database::Handle { #=>
>> has IO $!handle; #=>
>>
>> my Bool method open ($filename) {...} #=>m1
>> my Bool method close () {...} #=>m2
This would be a way to do a named declarator alias, for distinguishing
between multiple aliases to the same type of declarator.
Indeed, you might end up making extensive use of embedded named
declarator aliases (ENDAs? :P ), since as soon as you reach the
close-bracket, you have the rest of the line available for other uses
(such as declarator blocks):
class Database::Handle { #=>
has IO $!handle; #=>
my Bool method open ($filename) {...} #=>[m1] #= Here's a
block for A<m1>.
my Bool method close () {...} #=>m2
And given that brief names are going to be preferred, this could
result in very compact, yet still readable, combinations of declarator
aliases and blocks.
>> An unrelated possibility would be to allow empty A<> tags in a
>> declarator block, with 'A<>' being replaced with the name of the
>> declarator to which the block is attached:
>
> These are both very useful ideas.
> I'll ponder them carefully in preparation for the next revision.
>
> Thanks, Jon!
No; thank you.
--
Jonathan "Dataweaver" Lang
