Author: lwall
Date: 2010-07-10 08:43:17 +0200 (Sat, 10 Jul 2010)
New Revision: 31611
Modified:
docs/Perl6/Spec/S02-bits.pod
docs/Perl6/Spec/S06-routines.pod
docs/Perl6/Spec/S09-data.pod
docs/Perl6/Spec/S10-packages.pod
docs/Perl6/Spec/S11-modules.pod
docs/Perl6/Spec/S12-objects.pod
docs/Perl6/Spec/S13-overloading.pod
Log:
[spec] random cleanup of fossils from before proto became a multi wrapper
Modified: docs/Perl6/Spec/S02-bits.pod
===================================================================
--- docs/Perl6/Spec/S02-bits.pod 2010-07-09 22:59:12 UTC (rev 31610)
+++ docs/Perl6/Spec/S02-bits.pod 2010-07-10 06:43:17 UTC (rev 31611)
@@ -13,8 +13,8 @@
Created: 10 Aug 2004
- Last Modified: 2 Jun 2010
- Version: 217
+ Last Modified: 9 Jul 2010
+ Version: 218
This document summarizes Apocalypse 2, which covers small-scale
lexical items and typological issues. (These Synopses also contain
@@ -1748,9 +1748,9 @@
of that name. Conversely, C<$x.substr> implies conversion to a string
or buffer type.
-The C<Cool> namespace also contains all multimethods of last resort;
+The C<Cool> module also contains all multisubs of last resort;
these are automatically searched if normal multiple dispatch does not
-find a viable candidate. Note that the C<Cool> namespace is mutable,
+find a viable candidate. Note that the C<Cool> package is mutable,
and both single and multiple dispatch must take into account changes
there for the purposes of run-time monkey patching. However, since
the multiple dispatcher uses the C<Cool> package only as a failover,
@@ -2271,20 +2271,23 @@
=item *
-With multiple dispatch, C<&foo> may actually be the name of a set
-of candidate functions (which you can use as if it were an ordinary function).
+With multiple dispatch, C<&foo> is actually the name of the C<proto>
controlling a set
+of candidate functions (which you can use as if it were an ordinary function,
because
+a C<proto> is really an C<only> function with pretentions to management of a
dispatcher).
However, in that case C<&foo> by itself is not sufficient to uniquely
name a specific function. To do that, the type may be refined by
using a signature literal as a postfix operator:
&foo:(Int,Num)
-It still just returns the C<Routine> object. A call may also be partially
+Use of a signature that does not unambiguously select a single multi results in
+failure.
+
+It still just returns a C<Routine> object. A call may also be partially
applied by using the C<.assuming> method:
&foo.assuming(1,2,3,:mice<blind>)
-
=item *
Slicing syntax is covered in S09. A multidimensional
Modified: docs/Perl6/Spec/S06-routines.pod
===================================================================
--- docs/Perl6/Spec/S06-routines.pod 2010-07-09 22:59:12 UTC (rev 31610)
+++ docs/Perl6/Spec/S06-routines.pod 2010-07-10 06:43:17 UTC (rev 31611)
@@ -17,7 +17,7 @@
Created: 21 Mar 2003
Last Modified: 9 Jul 2010
- Version: 138
+ Version: 139
This document summarizes Apocalypse 6, which covers subroutines and the
new type system.
@@ -63,7 +63,8 @@
also adds an implicit C<multi> to all routines of the same short
name within its scope, unless they have an explicit modifier.
(This is particularly useful when adding to rule sets or when attempting
-to compose conflicting methods from roles.)
+to compose conflicting methods from roles.) Abstractly, the C<proto>
+is a wrapper around the dispatch to the C<multi>.s
B<Only> (keyword: C<only>) routines do not share their short names
with other routines. This is the default modifier for all routines,
@@ -85,13 +86,13 @@
When you call any routine (or method, or rule) that may have multiple
candidates, the C<proto> is always called first (at least in the abstract--this
-can often be optimized away). In essence, a proto is dispatched exactly like
-an C<only> sub, but the proto itself may delegate to any of the candidates
+can often be optimized away). In essence, a C<proto> is dispatched exactly
like
+an C<only> sub, but the C<proto> itself may delegate to any of the candidates
it is "managing".
-It is the proto's responsibility to first vet the arguments for all the
+It is the C<proto>'s responsibility to first vet the arguments for all the
candidates; any call that does not match the proto's signature fails outright.
-Named arguments that bind to positionals in the proto sig will become
positionals
+Named arguments that bind to positionals in the C<proto> sig will become
positionals
for all subsequent calls to its managed multis.
The proto then builds (or otherwise acquires) a list of its managed candidates
@@ -100,50 +101,51 @@
for each of the various dispatchers.
This default behavior is implied by a block containing of a single
-C<*> (that is, a "whatever"). Hence the typical proto will simply
+C<*> (that is, a "whatever"). Hence the typical C<proto> will simply
have a body of C<{*}>.
proto method bar {*}
(We don't use C<...> for that because it would fail at run time,
-and proto blocks are not stubs, but are intended to be executed.)
+and C<proto> blocks are not stubs, but are intended to be executed.)
Other statements may be inserted before and after the C<{*}>
statement to capture control before or after the multi dispatch:
proto foo ($a,$b) { say "Called with $a $b"; {*}; say "Returning"; }
-(That proto is only good for multis with side effects and no return
+(That C<proto> is only good for C<multi>s with side effects and no return
value, since it returns the result of C<say>, which might not be what
you want. See below for how to fix that.)
The syntactic form C<&foo> (without a modifying signature) can never refer to
-a multi candidate. It may only refer to the single C<only> or C<proto> routine
-that would first be called by C<foo()>. Individual multis may be named by
+a C<multi> candidate. It may only refer to the single C<only> or C<proto>
routine
+that would first be called by C<foo()>. Individual C<multi>s may be named by
appending a signature to the noun form: C<&foo:($,$,*@)>.
-We used the term "managed" loosely above to indicate the set of multis in
+We used the term "managed" loosely above to indicate the set of C<multi>s in
question; the "managed set" is more accurately defined as the intersection
-of all the multis in the proto's downward scope with all the multis that
+of all the C<multi>s in the C<proto>'s downward scope with all the C<multi>s
that
are visible to the caller's upward-looking scope. For ordinary routines
this means looking down lexical scopes and looking up lexical scopes. [This
-is more or less how multis already behave.]
+is more or less how C<multi>s already behave.]
For methods this means looking down or up the inheritance tree; "managed set"
-in this case translates to the intersection of all methods in the proto's
-class or its subclasses with all multi methods visible to the object in its
+in this case translates to the intersection of all methods in the C<proto>'s
+class or its subclasses with all C<multi> methods visible to the object in its
parent classes, that is, the parent classes of the object's actual type on
whose behalf the method was called. [Note, this is a change from prior
multi method semantics, which restricted multimethods to a single class;
-the old semantics is equivalent to defining a proto in every class that has
-multimethods. The new way gives the user the ability to intermix multis at
+the old semantics is equivalent to defining a C<proto> in every class that has
+multimethods. The new way gives the user the ability to intermix C<multi>s at
different inheritance levels. (The first version of Rakudo * is not expected
to implement this).]
-Also, the old semantics of C<proto> providing the most-default multi body
-is hereby deprecated. Default multis should be marked with "C<is default>".
+Also, the old semantics of C<proto> providing the most-default C<multi> body
+is hereby deprecated. Default C<multi>s should be marked with "C<is default>".
-It is still possible to provide default behavior in the proto, however:
+It is still possible to provide default behavior in the C<proto>, however, by
+using it as a wrapper:
my proto sub foo (@args) {
do-something-before(@args);
@@ -151,7 +153,7 @@
do-something-after(@args);
}
-Note that this returns the value of do-something-after(), not the multi.
+Note that this returns the value of do-something-after(), not the C<multi>.
There are two ways to get around that. Here's one way:
my proto sub foo (@args) {
@@ -183,13 +185,13 @@
my proto method foo { {*}; UNDO nextsame; } # failover to super foo
-Note that, in addition to making multis work similarly to each other,
-the new proto semantics greatly simplify top-level dispatchers, which
-never have to worry about multis, because multis are always in the
+Note that, in addition to making C<multi>s work similarly to each other,
+the new C<proto> semantics greatly simplify top-level dispatchers, which
+never have to worry about C<multi>s, because C<multi>s are always in the
second half of the double dispatch (again, just in the abstract, since
-the first dispatch can often be optimized away, as if the proto were
+the first dispatch can often be optimized away, as if the C<proto> were
inlined). So in the abstract, C<foo()> only ever calls a single
-only/proto routine, and We Know Which One It Is at compile time.
+C<only>/C<proto> routine, and We Know Which One It Is at compile time.
This is less of a shift for method dispatch, which already assumed that there
is something like a single proto in each class that redispatches inside
@@ -197,7 +199,7 @@
more widely for its candidates than the current class. But note that our
semantics were inconsistent before, insofar as regex methods already had to
look for this larger managed set in order to do transitive LTM correctly.
-Now the semantics of normal method protos and regex protos are nearly
+Now the semantics of normal method C<proto>s and regex C<proto>s are nearly
identical, apart from the fact that regex candidate lists naturally have
fancier tiebreaking rules involving longest token matching.
@@ -795,8 +797,8 @@
foo(|$capture)
-the compiler must defer the decision on whether to treat it as a single
-or multiple dispatch based on whether the supplied C<Capture>'s first
+the compiler must defer the decision on whether to treat it as a method
+or function dispatch based on whether the supplied C<Capture>'s first
argument is marked as an invocant. For ordinary calls this can
always be determined at compile time, however.
@@ -953,7 +955,7 @@
It might seem that performance of binding would suffer by requiring
a named lookup before a positional lookup, but the compiler is able
to guarantee that subs with known fixed signatures (both C<only>s and
-C<multi>s with C<proto>s) translate named arguments to positional in the
+C<proto>s) translate named arguments to positional in the
first N positions. Also, purely positional calls may obviously omit any
named lookups, as may bindings that have already used up all the named
arguments. The compiler is also free to intuit proto signatures for
@@ -1061,7 +1063,7 @@
method addto (|$args ($self: @x)) { trace($args); $self += [+] @x }
-The inner signature is not required for non-multis since there can
+The inner signature is not required for non-C<multi>s since there can
only be one candidate, but for multiple dispatch the inner signature
is required at least for its types, or the declaration would not know
what signature to match against.
@@ -1602,6 +1604,7 @@
an array of children named C<.kids> or C<< .<kids> >>, use something
like:
+ proto traverse ($) {*}
multi traverse ( NAry $top ( :kids [$eldest, *...@siblings] ) ) {
traverse($eldest);
traverse(:kids(@siblings)); # (binds @siblings to $top)
@@ -2815,8 +2818,8 @@
Outside of any sub declaration, this call returns failure.
Note that C<&?ROUTINE> refers to the current single sub, even if it is
-declared "multi". To redispatch to the entire suite under a given short
-name, just use the named form, since there are no anonymous multis.
+declared C<multi>. To redispatch to the entire suite under a given short
+name, just use the named form to call the C<proto>, since there are no
anonymous C<multi>s.
=head2 The C<&?BLOCK> object
@@ -2872,8 +2875,8 @@
This special form should generally be restricted to named parameters.
-To curry a particular multi variant, it may be necessary to specify the type
-for one or more of its parameters:
+To curry a particular C<multi> variant, it may be necessary to specify the type
+for one or more of its parameters to pick out a single function:
&woof ::= &bark:(Dog).assuming :pitch<low>;
&pine ::= &bark:(Tree).assuming :pitch<yes>;
@@ -3160,7 +3163,8 @@
for @filenames { ... }
}
-If C<MAIN> is declared as a set of multi subs, MMD dispatch is performed.
+If C<MAIN> is declared as a C<proto> with a set of C<multi> subs,
+multi dispatch is performed by the C<proto>.
As with module and class declarations, a sub declaration
ending in semicolon is allowed at the outermost file scope if it is the
@@ -3171,8 +3175,8 @@
This form is allowed only for simple subs named C<MAIN> that are intended
to be run from the command line.
-Proto or multi definitions may not be written in semicolon form,
-nor may C<MAIN> subs within a module or class. (A C<MAIN> routine
+A C<proto> or C<multi> definition may not be written in semicolon form,
+nor may C<MAIN> subs within a module or class be written in semicolon form.
(A C<MAIN> routine
is allowed in a module or class, but is not usually invoked unless
the file is run directly (see a above). This corresponds to the
"unless caller" idiom of Perl 5.) In general, you may have only one
@@ -3314,33 +3318,36 @@
=head2 Implementation note on autothreading of only subs
-The natural way to implement autothreading for multi subs is to
+The natural way to implement autothreading for C<multi> subs is to
simply have the junctional signatures (the ones that can accept
C<Mu> or junction as well as C<Any> parameters) match more loosely than
the non-autothreading versions, and let multiple dispatch find the
appropriate sub based on the signature. Those generic routines
then end up redispatching to the more specific ones.
-On the other hand, the natural implementation of only subs is to
+On the other hand, the natural implementation of C<only> subs is to
call the sub in question directly for efficiency (and maybe even
inline it in some cases). That efficiency is, after all, the main
-reason for not just making all subs multi. However, this direct
+reason for not just making all subs C<multi>. However, this direct
call conflicts with the desire to allow autothreading. It might
be tempting to simply make everything multi dispatch underneath,
-and then say that the "only" declaration merely means that you get
+and then say that the C<only> declaration merely means that you get
an error if you redeclare. And maybe that is a valid approach if
the multiple dispatch mechanism is fast enough.
However, a direct call still needs to bind its arguments to its
parameters correctly, and it has to handle the case of failure to
bind somehow. So it is also possible to implement autothreading
-of only subs based on failover from the binding failure. This could
-either be a one-shot failover followed by a conversion to a multi call,
+of C<only> subs based on failover from the binding failure. This could
+either be a one-shot failover followed by a conversion to a C<multi> call,
or it could failover every time you try to autothread. If we assume
that junctional processing is likely to be fairly heavyweight most of
the time compared to the cost of failing to bind, that tends to argue
for failing over every time. This is also more conducive to inlining,
-since it's difficult to rewrite inlined calls.
+since it's difficult to rewrite inlined calls. In any case, nowadays
+a C<proto> declaration is considered to be a kind of C<only> sub,
+and needs to handle autothreading similaraly if the signature of
+the C<proto> excludes junctions.
=head2 Introspection
@@ -3359,9 +3366,7 @@
=item .signature
-This method returns the signature of the current routine. If this is a
-multi, it should return an "any" junction of the signature of each
-candidate.
+This method returns the signature of the current routine.
=item .cando(\$capture)
@@ -3370,11 +3375,11 @@
=item .push($candidate)
-Adds $candidate to the list of candidates for this multi, calling this
-method in an only routine should result in a failure. It is also
-accepted for multis declared in the source code to finalize the list
-of candidates and also return a failure here. But multis created by
-calling Multi.new() should be able add candidates at run-time.
+Adds C<$candidate> to the list of candidates for this C<proto>, calling this
+method in an C<only> routine should result in a failure. It is also
+accepted for C<multi>s declared in the source code to finalize the list
+of candidates and also return a failure here. But C<Proto>s created by
+calling C<Proto.new()> should be able add candidates at run-time.
=back
Modified: docs/Perl6/Spec/S09-data.pod
===================================================================
--- docs/Perl6/Spec/S09-data.pod 2010-07-09 22:59:12 UTC (rev 31610)
+++ docs/Perl6/Spec/S09-data.pod 2010-07-10 06:43:17 UTC (rev 31611)
@@ -13,8 +13,8 @@
Created: 13 Sep 2004
- Last Modified: 6 May 2010
- Version: 46
+ Last Modified: 9 Jul 2010
+ Version: 47
=head1 Overview
@@ -1046,7 +1046,7 @@
The exact semantics of autothreading with respect to control structures
are subject to change over time; it is therefore erroneous to pass
junctions to any control construct that is not implemented via as a
-normal single or multi dispatch. In particular, threading junctions
+normal single dispatch or function call. In particular, threading junctions
through conditionals correctly could involve continuations, which
are almost but not quite mandated in Perl 6.0.0. Alternately, we
may decide that boolean contexts always collapse the junction by
Modified: docs/Perl6/Spec/S10-packages.pod
===================================================================
--- docs/Perl6/Spec/S10-packages.pod 2010-07-09 22:59:12 UTC (rev 31610)
+++ docs/Perl6/Spec/S10-packages.pod 2010-07-10 06:43:17 UTC (rev 31611)
@@ -13,8 +13,8 @@
Created: 27 Oct 2004
- Last Modified: 19 Jun 2010
- Version: 12
+ Last Modified: 9 Jul 2010
+ Version: 13
=head1 Overview
@@ -215,7 +215,7 @@
The method form is inherited by subclasses. Submethods are never
inherited but may still do MMD within the class. (Ordinary multisubs
-are inherited only to the extent allowed by the MMD mechanism.)
+are "inherited" only to the extent allowed by nested lexical scopes.)
When the package in question is not a class, there is a slight problem
insofar as Perl 6 doesn't by default look into packages for functions
Modified: docs/Perl6/Spec/S11-modules.pod
===================================================================
--- docs/Perl6/Spec/S11-modules.pod 2010-07-09 22:59:12 UTC (rev 31610)
+++ docs/Perl6/Spec/S11-modules.pod 2010-07-10 06:43:17 UTC (rev 31611)
@@ -13,8 +13,8 @@
Created: 27 Oct 2004
- Last Modified: 19 Nov 2009
- Version: 32
+ Last Modified: 9 Jul 2010
+ Version: 33
=head1 Overview
@@ -108,10 +108,9 @@
calling C<Foo::Bar::.EXPORTALL> will export C<&bar> and C<&baz> at runtime
to the caller's package.
-Any proto declaration that is not declared "my" is exported by default.
-Any multi that depends on an exported proto is also automatically exported.
-When there is no proto for a multi, the autogenerated proto is assumed
-to be exportable.
+Any C<proto> declaration that is not declared C<my> is exported by default.
+Any C<multi> that depends on an exported C<proto> is also automatically
exported.
+(It is not currently allowed to have a C<multi> without a C<proto>.)
=head1 Dynamic exportation
@@ -231,7 +230,7 @@
do not automatically get imported into their surrounding scope:
my module Factorial {
- multi fact (Int $n) is export { [*] 1..$n }
+ sub fact (Int $n) is export { [*] 1..$n }
}
...
import Factorial 'fact'; # imports the multi
@@ -697,7 +696,7 @@
Note that most class modules do no language tweaking, and in any case
cannot perform language tweaks unless these are explicitly exported.
-Modules that export multis are technically language tweaks on the
+Modules that exported C<multi>s are technically language tweaks on the
semantic level, but as long as those new definitions modify semantics
within the existing grammar (by avoiding the definition of new macros
or operators), they do not fall into the language tweak category.
Modified: docs/Perl6/Spec/S12-objects.pod
===================================================================
--- docs/Perl6/Spec/S12-objects.pod 2010-07-09 22:59:12 UTC (rev 31610)
+++ docs/Perl6/Spec/S12-objects.pod 2010-07-10 06:43:17 UTC (rev 31611)
@@ -13,8 +13,8 @@
Created: 27 Oct 2004
- Last Modified: 21 May 2010
- Version: 103
+ Last Modified: 9 Jul 2010
+ Version: 104
=head1 Overview
@@ -76,8 +76,8 @@
but that is considered somewhat antisocial and should not be used
for forward declarations.
-[Conjecture: we may also allow the C<proto> and C<multi> modifiers
-to explicitly declare classes with multiple bodies participating in
+[Conjecture: we may also allow the C<proto> and C<multi> declarator modifiers
+on class definitions to explicitly declare classes with multiple bodies
participating in
a single definition intentionally.]
A named class declaration can occur as part of an expression, just like
@@ -225,10 +225,6 @@
method doit ($x: $a, $b, $c) { ... }
-This is true also for multi methods:
-
- multi method doit ($x: $a; $b; $c) { ... }
-
If you declare an explicit invocant for an Array type using an array variable,
you may use that directly in list context to produce its elements
@@ -287,7 +283,7 @@
However, here the built-in B<IO> class defines C<method close () is export>,
which puts a C<multi sub close (IO)> in scope by default. Thus if the
-C<$handle> evaluates to an IO object, then the two subroutine calls above
+C<$handle> evaluates to an C<IO> object, then the two subroutine calls above
are still translated into method calls.
Dot notation can omit the invocant if it's in C<$_>:
@@ -924,8 +920,8 @@
Since it's possible to be dispatching within more than one candidate
list at a time, these control flow calls are defined to apply only to
the dynamically innermost dispatcher. If, for instance, you have a
-single dispatch that then calls into a multiple dispatch on the multi
-methods within a class, C<nextsame> would go to the next best multi
+single dispatch to a C<proto> method that then calls into a multiple dispatch
on the C<multi>
+methods within a class, C<nextsame> within one of those C<multi>s would go to
the next best C<multi>
method within the class, not the next method candidate in the original
single dispatch. This is not a bad limitation, since dispatch loops
are dynamically scoped; to get to the outermost lists you can "pop"
@@ -978,9 +974,8 @@
of its invocant arguments. The "short name" doesn't. If you put
C<multi> in front of any sub (or method) declaration, it allows
multiple long names to share a short name, provided all of them are
-declared C<multi>. (Putting C<proto> on the first such declaration has
-the same effect, but usually you want to put the C<multi> explicitly
-anyway for documentation.) If a sub (or method) is not marked
+declared C<multi>, and there is a single C<proto> that manages them.
+If a sub (or method) is not marked
with C<multi> and it is not within the package or lexical scope of
a C<proto> of the same short name, it is considered unique, an I<only>
sub. You may mark a sub explicitly as C<only> if you're worried it
@@ -1002,27 +997,23 @@
any user-defined C<only> version of it must of necessity be declared
earlier in the user's lexical scope or not at all.)
-A C<proto> may share dispatch with multis declared after it in the same scope,
-but in that case it functions only as the final tie-breaker if the
-inner multis can't decide among themselves what to do. (It may
-then, of course, decide to redispatch outside of the current scope.)
+A C<proto> always functions as a dispatcher around any C<multi>s declared
after it in the same scope,
-Within its scope,
-the signature of a C<proto> also nails down the presumed order
-and naming of positional parameters, so that any multi call with named
-arguments in that scope can presume to rearrange those arguments into
-positional parameters based on that information. (Unrecognized names
+Within its scope, the signature of a C<proto> also nails down the presumed
+order and naming of positional parameters, so that any C<multi> call with
+named arguments in that scope can presume to rearrange those arguments
+into positional parameters based on that information. (Unrecognized names
remain named arguments.) Any other type information or traits attached
-to the C<proto> are also shared by the routines within its scope,
-so a C<proto> definition can be used to factor out common traits.
-This is particularly useful for establishing grammatical categories
-in a grammar by declaring a C<proto> C<token> or C<proto> C<rule>. (Perl 6's
-grammar does this, for instance.)
+to the C<proto> may also be passed along to the routines within its scope,
+so a C<proto> definition can be used to factor out common traits. This is
+particularly useful for establishing grammatical categories in a grammar by
+declaring a C<proto> C<token> or C<proto> C<rule>. (Perl 6's grammar does
+this, for instance.)
You can have multiple C<multi> variables of the same name in the
same scope, and they all share the same storage location and type.
-Usually these are declared by one C<proto> declaration at the top,
-and leaving the C<multi> implicit on the rest of the declarations.
+These are declared by one C<proto> declaration at the top, in which case
+you may leave the C<multi> implicit on the rest of the declarations in the
same scope.
You might do this when you suspect you'll have multiple declarations
of the same variable name (such code might be produced by a macro
or by a code generator, for instance) and you wish to suppress any
@@ -1031,10 +1022,10 @@
In contrast, C<multi> routines can have only one instance of the long
name in any namespace, and that instance hides any outer (or less-derived)
routines with the same long name. It does not hide any routines with
-the same short name but a different long name. In other words, multis
+the same short name but a different long name. In other words, C<multi>s
with the same short name can come from several different namespaces
provided their long names differ and their short names aren't hidden
-by an C<only> declaration in some intermediate scope.
+by an C<only> or C<proto> declaration in some intermediate scope.
When you call a routine with a particular short name, if there are
multiple visible long names, they are all considered candidates.
@@ -1049,6 +1040,7 @@
match (along with the fact that it is constrained). That is, if you have a
parameter:
subset Odd of Int where { $_ % 2 }
+ proto foo {*}
multi foo (Odd $i) {...}
it is treated as if you'd instead said:
@@ -1133,7 +1125,7 @@
multi sub infix:<..>(Int $min, Int $max;; Int $by = 1) {...}
The double semicolon, if any, determines the complete long name of
-a multi. (In the absence of that, a double semicolon is assumed
+a C<multi>. (In the absence of that, a double semicolon is assumed
after the last declared argument, but before any return signature.)
Note that a call to the routine must still be compatible with
subsequent arguments.
@@ -1176,13 +1168,13 @@
for purposes of tiebreaking; subsequent tiebreaking is provided by
the original order in the used module.
-[Conjecture: However, a given multi may advertise multiple long names,
+[Conjecture: However, a given C<multi> may advertise multiple long names,
some of which are shorter than the complete long name. This is done
by putting a semicolon after each advertised long name (replacing
the comma, if present). A semicolon has the effect of inserting two
candidates into the list. One of them is inserted with exactly the
same types, as if the semicolon were a comma. The other is inserted
-as if all the types after the semicolon were of type Any, which puts
+as if all the types after the semicolon were of type C<Any>, which puts
it later in the list than the narrower actual candidate. This merely
determines its sort order; the candidate uses its real type signature
if the dispatcher gets to it after rejecting all earlier entries on the
@@ -1202,18 +1194,6 @@
subroutine-dispatch process. However, they can be made to do so if
prefixed with a C<my> or C<our> declarator.
-The multi-method tiebreaking happens only within a given class; all
-parent classes' multis appear to the outside world to be C<only>
-methods (and indeed, a foreign object may have no clue how to
-advertise multiple methods anyway). In other words, longnames from
-different classes don't intermix as do the longnames in ordinary
-multi-sub dispatch. So multi methods work only within a class;
-outside the class, single-dispatch semantics are enforced to preserve
-encapsulation. To put it another way, multi methods are only for
-convenience of implementation within a given class; and specifically
-to make it easier to compose roles with similar but not identical
-methods into a single class.
-
Conjecture: In order to specify dispatch that includes the return
type context, it is necessary to place the return type before the double
semicolon:
@@ -1252,23 +1232,23 @@
There is no fail-over either from subroutine to method dispatch or
vice versa. However, you may use C<is export> on a method
-definition to make it available also as a multi sub. As with indirect
+definition to make it available also as a C<multi> sub. As with indirect
object syntax, the first argument is still always the invocant,
but the export allows you to use a comma after the invocant instead of
a colon, or to omit the colon entirely in the case of a method with
no arguments other than the invocant. Many standard methods (such
as C<IO::close> and C<Array::push>) are automatically exported to the
C<CORE> namespace by default. For other exported methods, you will not
-see the multi sub definition unless you C<use> the class in your scope,
-which will import the multi sub lexically, after which you can call it
+see the C<multi> sub definition unless you C<use> the class in your scope,
+which will import the C<proto> (and associated C<multi> subs) lexically, after
which you can call it
using normal subroutine call syntax.
In the absence of an explicit type on the method's invocant, the
-exported multi sub's first argument is implicitly constrained to
+exported C<multi> sub's first argument is implicitly constrained to
match the class in which it was defined or composed, so for instance
-the multi version of C<close> requires its first argument to be of
+the C<multi> version of C<close> requires its first argument to be of
type C<IO> or one of its subclasses. If the invocant is explicitly
-typed, that will govern the type coverage of the corresponding multi's
+typed, that will govern the type coverage of the corresponding C<multi>'s
first argument, whether that is more specific or more general than
the class's invocant would naturally be. (But be aware that if it's
more specific than C<::?CLASS>, the binding may reject an otherwise
@@ -1277,44 +1257,19 @@
cannot handle the broader type. In such a situation you must write
a wrapper to coerce to the narrower type.
-Note that explicit use of a syntactic category as a method name
-overrides the choice of dispatcher, so
-
- $x.infix:<*>($y)
-
-and
-
- infix:<*>($x,$y)
-
-are exactly equivalent. That is, both calls use the subroutine/multi
-dispatcher, not the method/single dispatcher. Likewise
-
- foo($bar)
-
-can be written
-
- $bar.prefix:<foo>()
-
-with the same meaning. To get single dispatch of that method
-name to a foreign function, you must say:
-
- $bar.'prefix:<foo>'()
-
-Most foreign languages are not going to understand such a method name,
-however.
-
=head1 Multi dispatch
Multi submethods work just like multi methods except they are constrained
to an exact type match on the invocant, just as ordinary submethods are.
-Perl 6.0.0 is not required to support multiple dispatch on named parameters,
-only on positional parameters. Note that most builtins will map known
-named parameters to positional via a C<proto> declaration.
+Perl 6.0.0 is not required to support multiple dispatch on named
+parameters, only on positional parameters. Note however that any
+C<proto> will map named arguments to known declared positional
+parameters and call the C<multi> candidates with positionals for
+those arguments rather than named arguments.
Within a multiple dispatch, C<nextsame> means to try the next best
-match, or next best default in case of tie, or the proto sub if there
-is one.
+match, or next best default in case of tie.
Attributes are tied to a particular class definition, so a multi method
can only directly access the attributes of a class it's defined within
@@ -1483,10 +1438,11 @@
You can leave out the block when matching against a literal value of some
kind:
+ proto sub fib (Int $) {*}
multi sub fib (Int $n where 0|1) { return $n }
multi sub fib (Int $n) { return fib($n-1) + fib($n-2) }
-In fact, you can leave out the 'where' declaration altogether:
+In fact, you can leave out the C<where> declaration altogether:
multi sub fib (0) { return 0 }
multi sub fib (1) { return 1 }
@@ -2203,7 +2159,7 @@
name the name of the method
signature the parameters of the method
as the coercion type of the method
- multi whether duplicate names are allowed
+ proto whether this method governs a set of multi methods
do the method body
The C<.^methods> method has a selector parameter that lets you
@@ -2216,7 +2172,7 @@
Note that, since introspection is primarily for use by the outside
world (the class already knows its own structure, after all), a set of
-multi methods are presented to be a single C<Routine> object. You need to
+C<multi> methods are presented to be a single C<proto> method. You need to
use C<.candidates> on that to break it down further.
The C<.^attributes> method returns a list of attribute descriptors
Modified: docs/Perl6/Spec/S13-overloading.pod
===================================================================
--- docs/Perl6/Spec/S13-overloading.pod 2010-07-09 22:59:12 UTC (rev 31610)
+++ docs/Perl6/Spec/S13-overloading.pod 2010-07-10 06:43:17 UTC (rev 31611)
@@ -13,8 +13,8 @@
Created: 2 Nov 2004
- Last Modified: 2 Feb 2010
- Version: 13
+ Last Modified: 9 Jul 2010
+ Version: 14
=head1 Overview
@@ -49,7 +49,7 @@
multi sub uc (TurkishStr $s) {...}
-A multi is automatically exported if goverened by a proto that is exported.
+A C<multi> is automatically exported if goverened by a proto that is exported.
It may also be explicitly exported:
multi sub uc (TurkishStr $s) is exported {...}
@@ -94,8 +94,8 @@
variable within the body, for instance, there would only be one
of them.
-A multi is in effect only within the scope in which it is defined or
-imported. Generally you want to put your multi subs into a package
+A C<multi> is in effect only within the scope in which it is defined or
+imported. Generally you want to put your C<multi> subs into a package
that will be imported wherever they are needed.
When you use the multiple signature syntax, the alternate signatures
@@ -106,12 +106,12 @@
omits any of the variable names. This is intended primarily to catch
editing errors.
-Conjectural: If the first parameter to a multi signature is followed
+Conjectural: If the first parameter to a C<multi> signature is followed
by an invocant colon, that signature represents two signatures, one
-for an ordinary method definition, and one for the corresponding multi
+for an ordinary method definition, and one for the corresponding C<multi>
definition that has a comma instead of the colon. This form is legal
only where the standard method definition would be legal, and only
-if any declared type of the first parameter is consistent with $?CLASS.
+if any declared type of the first parameter is consistent with C<$?CLASS>.
=head1 Fallbacks
@@ -123,6 +123,9 @@
are taken at face value and do not specify any underlying semantics.
As such, they're a "shallow" interpretation.
+[Note: the following section on "is deep" may no longer be necessary given
+the way metaoperators are now constructed.]
+
However, sometimes you want to specify a "deep" interpretation of
your operators. That is, you're specifying the abstract operation,
which may be used by various shallow operators. Any deep multi
@@ -150,7 +153,7 @@
is better written:
- method Str {...}
+ method Stringy {...}
(see below).
@@ -212,9 +215,9 @@
method Str { self.makestringval() }
-As with all methods, you can also export the corresponding multi:
+As with all methods, you can also export the corresponding C<multi>:
- method Str is export { self.makestringval() }
+ multi method Str is export { self.makestringval() }
in which case you can use both calling forms:
@@ -223,10 +226,8 @@
If the source class and the destination class both specify a
coercion routine, the ambiguity is settled by the ordinary rules
-of multiple dispatch. Usually the source class will have the more
-specific argument and will win; ties are also possible, and those
-calls will fail. Additional arguments may sway the dispatch one way
-or the other depending on the candidate list.
+of dispatch. That is, C<$x.Str> will always prefer the method form
+and C<Str($x)> will always prefer the functional form.
Note that, because the name of an anonymous class is unknown, coercion to
an anonymous class can only be specified by the destination class:
