Author: larry
Date: Mon May 14 10:13:16 2007
New Revision: 14390
Modified:
doc/trunk/design/syn/S02.pod
doc/trunk/design/syn/S06.pod
doc/trunk/design/syn/S12.pod
Log:
coercion type renamed from "returns" to "as" to avoid confusion with "of" type.
ambiguity in block-end parsing noted by rhr++
Modified: doc/trunk/design/syn/S02.pod
==============================================================================
--- doc/trunk/design/syn/S02.pod (original)
+++ doc/trunk/design/syn/S02.pod Mon May 14 10:13:16 2007
@@ -822,19 +822,19 @@
In either case this sets the C<of> property of the container to C<Dog>.
-Subroutines have a variant of the C<of> property, C<returns>, that sets
-the C<returns> property instead. The C<returns> property specifies a
+Subroutines have a variant of the C<of> property, C<as>, that sets
+the C<as> property instead. The C<as> property specifies a
constraint (or perhaps coercion) to be enforced on the return value (either
by explicit call to C<return> or by implicit fall-off-the-end return).
This constraint, unlike the C<of> property, is not advertised as the
type of the routine. You can think of it as the implicit type signature of
the (possibly implicit) return statement. It's therefore available for
-type inferencing within the routine but not outside it. If no inner type
+type inferencing within the routine but not outside it. If no C<as> type
is declared, it is assumed to be the same as the C<of> type, if declared.
sub get_pet() of Animal {...} # of type, obviously
our Animal sub get_pet() {...} # of type
- sub get_pet() returns Animal {...} # inner type
+ sub get_pet() as Animal {...} # as type
A value type on an array or hash specifies the type stored by each element:
@@ -892,18 +892,19 @@
my Hash of Array of Recipe %book; # HoHoAoRecipe
my %book of Hash of Array of Recipe; # same thing
-The C<returns> form may be used in subroutines:
+The C<as> form may be used in subroutines:
- my sub get_book ($key) returns Hash of Array of Recipe {...}
+ my sub get_book ($key) as Hash of Array of Recipe {...}
Alternately, the return type may be specified within the signature:
my sub get_book ($key --> Hash of Array of Recipe) {...}
There is a slight difference, insofar as the type inferencer will
-ignore a C<returns> but pay attention to C<< --> >> or prefix type
+ignore a C<as> but pay attention to C<< --> >> or prefix type
declarations, also known as the C<of> type. Only the inside of the
-subroutine pays attention to C<returns>.
+subroutine pays attention to C<as>, and essentially coerces the return
+value to the indicated type, just as if you'd coerced each return expression.
You may also specify the C<of> type as the C<of> trait:
@@ -963,18 +964,18 @@
On a scoped subroutine, a return type can be specified before or after
the name. We call all return types "return types", but distinguish
-two kinds of return types, the C<inner> type and the C<of> type,
+two kinds of return types, the C<as> type and the C<of> type,
because the C<of> type is normally an "official" named type and
-declares the official interface to the routine, while the C<inner>
+declares the official interface to the routine, while the C<as>
type is merely a constraint on what may be returned by the routine
from the routine's point of view.
- our sub lay returns Egg {...} # inner type
+ our sub lay as Egg {...} # as type
our Egg sub lay {...} # of type
our sub lay of Egg {...} # of type
our sub lay (--> Egg) {...} # of type
- my sub hat returns Rabbit {...} # inner type
+ my sub hat as Rabbit {...} # as type
my Rabbit sub hat {...} # of type
my sub hat of Rabbit {...} # of type
my sub hat (--> Rabbit) {...} # of type
@@ -983,14 +984,14 @@
namespace (module, class, grammar, or package), as if it's scoped with
the C<our> scope modifier. Any return type must go after the name:
- sub lay returns Egg {...} # inner type
+ sub lay as Egg {...} # as type
sub lay of Egg {...} # of type
sub lay (--> Egg) {...} # of type
On an anonymous subroutine, any return type can only go after the C<sub>
keyword:
- $lay = sub returns Egg {...}; # inner type
+ $lay = sub as Egg {...}; # as type
$lay = sub of Egg {...}; # of type
$lay = sub (--> Egg) {...}; # of type
@@ -1003,14 +1004,14 @@
without affecting the meaning.
The return type may also be specified after a C<< --> >> token within
-the signature. This doesn't mean exactly the same thing as C<returns>.
+the signature. This doesn't mean exactly the same thing as C<as>.
The C<of> type is the "official" return type, and may therefore be
-used to do type inferencing outside the sub. The C<inner> type only
+used to do type inferencing outside the sub. The C<as> type only
makes the return type available to the internals of the sub so that
the C<return> statement can know its context, but outside the sub we
don't know anything about the return value, as if no return type had
been declared. The prefix form specifies the C<of> type rather than
-the C<inner> type, so the return type of
+the C<as> type, so the return type of
my Fish sub wanda ($x) { ... }
@@ -1020,15 +1021,15 @@
I<not> as if you'd said
- my sub wanda ($x) returns Fish { ... }
+ my sub wanda ($x) as Fish { ... }
-It is possible for the C<of> type to disagree with the C<inner> type:
+It is possible for the C<of> type to disagree with the C<as> type:
- my Squid sub wanda ($x) returns Fish { ... }
+ my Squid sub wanda ($x) as Fish { ... }
or equivalently,
- my sub wanda ($x --> Squid) returns Fish { ... }
+ my sub wanda ($x --> Squid) as Fish { ... }
This is not lying to yourself--it's lying to the world. Having a
different inner type is useful if you wish to hold your routine to
Modified: doc/trunk/design/syn/S06.pod
==============================================================================
--- doc/trunk/design/syn/S06.pod (original)
+++ doc/trunk/design/syn/S06.pod Mon May 14 10:13:16 2007
@@ -13,9 +13,9 @@
Maintainer: Larry Wall <[EMAIL PROTECTED]>
Date: 21 Mar 2003
- Last Modified: 28 Mar 2007
+ Last Modified: 14 May 2007
Number: 6
- Version: 82
+ Version: 83
This document summarizes Apocalypse 6, which covers subroutines and the
@@ -143,7 +143,7 @@
statement level control syntax. A bare block where a term is expected
merely produces a C<Code> object. If the term bare block occurs in a list,
it is considered the final element of that list unless followed immediately
-by a comma or comma surrogate.
+by a comma or comma surrogate (intervening C<\h*> or "unspace" is allowed).
=head2 "Pointy blocks"
Modified: doc/trunk/design/syn/S12.pod
==============================================================================
--- doc/trunk/design/syn/S12.pod (original)
+++ doc/trunk/design/syn/S12.pod Mon May 14 10:13:16 2007
@@ -1316,13 +1316,13 @@
}
Other traits are applied with a single word, and we call one of those a
-"trait verb". For instance, the "C<returns>" trait
+"trait verb". For instance, the "C<as>" trait
is defined something like this:
- role returns {
- has ReturnType $.returns;
- multi sub trait_verb:returns($container; ReturnType $arg) {
- $container does returns($arg);
+ role as {
+ has ReturnType $.as;
+ multi sub trait_verb:as($container; ReturnType $arg) {
+ $container does as($arg);
}
...
}
@@ -1811,7 +1811,7 @@
name the name of the method
signature the parameters of the method
- returns the return type of the method
+ as the coercion type of the method
multi whether duplicate names are allowed
do the method body
