Author: larry
Date: Mon Mar 17 10:37:26 2008
New Revision: 14522
Modified:
doc/trunk/design/syn/S02.pod
doc/trunk/design/syn/S03.pod
doc/trunk/design/syn/S04.pod
doc/trunk/design/syn/S05.pod
doc/trunk/design/syn/S06.pod
doc/trunk/design/syn/S09.pod
Log:
Various typos and suggestions from (spinclad, nick, daniel)<<++
Clarification of semantics of list assignment, batch iteration
ss:g/scalar context/item context/
Modified: doc/trunk/design/syn/S02.pod
==============================================================================
--- doc/trunk/design/syn/S02.pod (original)
+++ doc/trunk/design/syn/S02.pod Mon Mar 17 10:37:26 2008
@@ -12,7 +12,7 @@
Maintainer: Larry Wall <[EMAIL PROTECTED]>
Date: 10 Aug 2004
- Last Modified: 15 Mar 2008
+ Last Modified: 17 Mar 2008
Number: 2
Version: 130
@@ -1317,8 +1317,11 @@
Sigils are now invariant. C<$> always means a scalar variable, C<@>
an array variable, and C<%> a hash variable, even when subscripting.
-Variables such as C<@array> and C<%hash> in scalar context simply
-return themselves as C<Array> and C<Hash> objects.
+In item context, variables such as C<@array> and C<%hash> simply
+return themselves as C<Array> and C<Hash> objects. (Item context was
+formerly known as scalar context, but we now reserve the "scalar"
+notion for talking about variables rather than contexts, much as
+arrays are disassociated from list context.)
=item *
@@ -1364,35 +1367,39 @@
The context in which a subscript is evaluated is no longer controlled
by the sigil either. Subscripts are always evaluated in list context.
-If you need to force inner context to scalar, we now have convenient
+If you need to force inner context to item (scalar), we now have convenient
single-character context specifiers such as + for numbers and ~ for strings:
- $x = g(); # scalar context and g()
+ $x = g(); # item context for g()
@x[f()] = g(); # list context for f() and g()
- @x[f()] = +g(); # list context for f(), scalar context for g()
- @x[+f()] = g(); # scalar context for f(), list context for g()
+ @x[f()] = +g(); # list context for f(), numeric item context for
g()
+ @x[+f()] = g(); # numeric item context for f(), list context for
g()
@x[f()] = @y[g()]; # list context for f() and g()
@x[f()] = [EMAIL PROTECTED]()]; # list context for f() and g()
- @x[+f()] = @y[g()]; # scalar context for f(), list context for g()
- @x[f()] = @y[+g()]; # list context for f(), scalar context for g()
+ @x[+f()] = @y[g()]; # numeric item context for f(), list context for
g()
+ @x[f()] = @y[+g()]; # list context for f(), numeric item context for
g()
-Sigils used as list prefix operators may also be used to force context:
+ %x{~f()} = %y{g()}; # string item context for f(), list context for g()
+ %x{f()} = %y{~g()}; # list context for f(), string item context for g()
- @x = $ g(); # scalar context for g()
- $x = @ g(); # list context for g()
- $x = % g(); # list context for g() (and coercion to hash)
+Sigils used either as functions or as list prefix operators also
+force context, so these also work:
-These may also be used in functional form:
+ @x[$(g())] # item context for g()
+ @x[$ g()] # item context for g()
+ %x{$(g())} # item context for g()
+ %x{$ g()} # item context for g()
- @x = $(g()); # scalar context for g()
- $x = @(g()); # list context for g()
- $x = %(g()); # list context for g() (and coercion to hash)
+But note that these don't do the same thing:
+
+ @x[$g()] # call function in $g
+ %x{$g()} # call function in $g
=item *
There is a need to distinguish list assignment from list binding.
-List assignment works exactly as it does in Perl 5, copying the
+List assignment works much like it does in Perl 5, copying the
values. There's a new C<:=> binding operator that lets you bind
names to Array and Hash objects without copying, in the same way
as subroutine arguments are bound to formal parameters. See S06
@@ -1429,7 +1436,7 @@
hash, all named arguments; into a scalar, its invocant.
All prefix sigil operators accept one positional argument, evaluated in
-scalar context as a rvalue. They can interpolate in strings if called with
+item context as a rvalue. They can interpolate in strings if called with
parentheses. The special syntax form C<$()> translates into C<$( $/ )>
to operate on the current match object; the same applies to C<@()> and C<%()>.
@@ -1454,7 +1461,7 @@
be used within other signatures to apply additional type constraints.
When applied to a C<Capture> argument, the signature allows you to
take the types of the capture's arguments from C<MySig>, but declare
-the (untyped) variable names yourself via an addition signature
+the (untyped) variable names yourself via an additional signature
in parentheses:
sub foo (Num Dog|Cat $numdog, MySig $a ($i,$j,$k,$mousestatus)) {...}
@@ -2186,7 +2193,7 @@
@a = 1, 'x', 'y', 2;
-In scalar context, though, the implied parentheses are not removed, so
+In item context, though, the implied parentheses are not removed, so
$a = < a b >;
@@ -2211,7 +2218,7 @@
$a = 'a';
And if bound to a scalar parameter, no list is constructed.
-To force a single value to become a list object in scalar context,
+To force a single value to become a list object in item context,
you should use C<< ['a'] >> for clarity as well as correctness.
Much like the relationship between single quotes and double quotes, single
@@ -2560,7 +2567,7 @@
print "The results are &baz().\n"
-The function is called in scalar context. (If it returns a list anyway,
+The function is called in item context. (If it returns a list anyway,
that list is interpolated as if it were an array in string context.)
=item *
@@ -2572,7 +2579,7 @@
print "The attribute is $obj.attr().\n"
print "The attribute is $obj.attr<Jan>.\n"
-The method is called in scalar context. (If it returns a list,
+The method is called in item context. (If it returns a list,
that list is interpolated as if it were an array.)
It is allowed to have a cascade of argumentless methods as long as
@@ -2597,8 +2604,8 @@
A bare closure also interpolates in double-quotish context. It may
not be followed by any dereferencers, since you can always put them
-inside the closure. The expression inside is evaluated in scalar
-(string) context. You can force list context on the expression using
+inside the closure. The expression inside is evaluated in string item
+context. You can force list context on the expression using
the C<list> operator if necessary.
The following means the same as the previous example.
@@ -3117,11 +3124,11 @@
=item *
-Perl still has the three main contexts: void, scalar, and list.
+Perl still has the three main contexts: void, item (scalar), and list.
=item *
-In addition to undifferentiated scalars, we also have these scalar contexts:
+In addition to undifferentiated items, we also have these item contexts:
Context Type OOtype Operator
------- ---- ------ --------
@@ -3183,13 +3190,13 @@
=item *
There is a "C<list>" operator which imposes a list context on
-its arguments even if C<list> itself occurs in a scalar context.
-In list context, it flattens lazily. In a scalar context, it returns
+its arguments even if C<list> itself occurs in a item context.
+In list context, it flattens lazily. In an item context, it returns
the resulting list as a single C<List> object. (So the C<list> operator
really does exactly the same thing as putting a list in parentheses with
at least one comma. But it's more readable in some situations.)
-To force a non-flattening scalar context, use the "C<item>" operator.
+To force a non-flattening item context, use the "C<item>" operator.
=item *
@@ -3227,9 +3234,22 @@
=item *
To force non-lazy list flattening, use the C<eager> list operator.
-Don't use it on an infinite generator unless you have a machine with
-infinite memory, and are willing to wait a long time. It may also
-be applied to a scalar iterator to force immediate iteration to completion.
+Don't use it on an infinite list unless you have a machine with
+infinite memory, and are willing to wait a long time. To expand an
+interator object to completion, iterate it with C<< prefix:<=> >>
+inside an eager list:
+
+ @lines = eager =$filehandle; # read all remaining lines
+
+By contrast,
+
+ @lines = =$filehandle;
+
+makes no guarantee about how many lines ahead the iterator has read.
+Iterators appending to a list are allowed to process in batches, even
+when stored within an array. The array knows that it is extensible,
+and calls the iterator as it needs more elements. (Counting the elements
+in the array will also force eager completion.)
=item *
@@ -3256,18 +3276,18 @@
However, function calls in the argument list can't know their eventual
context because the method hasn't been dispatched yet, so we don't
know which signature to check against. As in Perl 5, list context
-is assumed unless you explicitly qualify the argument with a scalar
+is assumed unless you explicitly qualify the argument with an item
context operator.
=item *
The C<< => >> operator now constructs C<Pair> objects rather than merely
-functioning as a comma. Both sides are in scalar context.
+functioning as a comma. Both sides are in item context.
=item *
The C<< .. >> operator now constructs C<Range> objects rather than merely
-functioning as an operator. Both sides are in scalar context.
+functioning as an operator. Both sides are in item context.
=item *
Modified: doc/trunk/design/syn/S03.pod
==============================================================================
--- doc/trunk/design/syn/S03.pod (original)
+++ doc/trunk/design/syn/S03.pod Mon Mar 17 10:37:26 2008
@@ -12,9 +12,9 @@
Maintainer: Larry Wall <[EMAIL PROTECTED]>
Date: 8 Mar 2004
- Last Modified: 15 Feb 2008
+ Last Modified: 17 Mar 2008
Number: 3
- Version: 132
+ Version: 133
=head1 Overview
@@ -655,13 +655,18 @@
Unary C<=> reads lines from a filehandle or filename, or
iterates an iterator, or in general causes a scalar to explode its guts
when it would otherwise not. How it does that is context sensitive.
-For instance, C<=$iterator> is item/list sensitive and will
+For instance, C<=$iterator> is item/list context sensitive and will
produce one value in item context but many values in list context.
-(Use C<@$iterator> to force a fetch of all the values even in item
-context, and C<$$iterator> to force a fetch of a single value even
-in list context.) On the other hand, C<=$capture> interpolates all
+The production of values is abstract here, so a lazy list merely
+remembers that it should iterate the iterator to completion upon
+demand. Use an eager list to force completion.
+
+Use C<@$iterator> to produce a list all the values even in item
+context, and C<$$iterator> to produce a single value even
+in list context. On the other hand, C<=$capture> produces all
parts of the capture that makes sense in the current list context,
-depending on what controls that list context.
+depending on what controls that list context. [Conjecture: the
+previous sentence is non-sensical.]
=back
@@ -1516,6 +1521,29 @@
all a bit pseudo insofar as we have to figure out whether the left side
is a list or a scalar destination.
+In any case, list assignment is defined to be arbitrarily lazy,
+insofar is it basically does the obvious copying as long as there
+are scalar destinations on the left or already-computed values on
+the right. However, many list lvalues end with an array destination
+(where assignment directly to an array can be considered a degenerate
+case). When copying into an array destination, the list assignment
+continues to copy in known values immediately, but suspends when it
+hits an actively iterating iterator (but not one merely passed as an
+object within the list). The array location on the left is then set
+as an extensible array, with the remainder of the list on the right
+as the producer of its remaining values.
+
+(Note that when we say that an iterator in list context suspends,
+it is not required to suspend immediately. When the scheduler is
+running an iterator, it may choose to precompute values in batches if
+it thinks that approach will increase throughput. This is likely to
+be the case on single-core architectures with heavy context switching,
+and may very well be the case even on manycore CPU architectures when
+there are more iterators than cores, such that cores may still have
+to do context switching.)
+
+Assignment to a hash is not lazy.
+
=item *
C<< infix:<:> >>, the invocant marker
@@ -2166,7 +2194,7 @@
If a function is contextually sensitive and you wish to return a scalar
value, you must use C<item> (or C<$> or C<+> or C<~>) if you wish to
-force scalar context for either the subscript or the right side:
+force item context for either the subscript or the right side:
@a[foo()] = bar(); # foo() and bar() called in list context
@a[item foo()] = item bar(); # foo() and bar() called in item context
Modified: doc/trunk/design/syn/S04.pod
==============================================================================
--- doc/trunk/design/syn/S04.pod (original)
+++ doc/trunk/design/syn/S04.pod Mon Mar 17 10:37:26 2008
@@ -1204,7 +1204,7 @@
is okay.
In the absence of error exception propagation, a successful exit is one that
-returns a defined value in scalar context, or any number of values
+returns a defined value in item context, or any number of values
in list context as long as the length is defined. (A length of +Inf
is considered a defined length. A length of 0 is also a defined length,
which means it's a "successful" return even though the list would evaluate
@@ -1216,7 +1216,7 @@
fail "message";
-and not care about whether the function is being called in scalar or list
+and not care about whether the function is being called in item or list
context. To return an explicit scalar undef, you can always say
return undef;
Modified: doc/trunk/design/syn/S05.pod
==============================================================================
--- doc/trunk/design/syn/S05.pod (original)
+++ doc/trunk/design/syn/S05.pod Mon Mar 17 10:37:26 2008
@@ -14,9 +14,9 @@
Maintainer: Patrick Michaud <[EMAIL PROTECTED]> and
Larry Wall <[EMAIL PROTECTED]>
Date: 24 Jun 2002
- Last Modified: 20 Feb 2008
+ Last Modified: 17 Mar 2008
Number: 5
- Version: 73
+ Version: 74
This document summarizes Apocalypse 5, which is about the new regex
syntax. We now try to call them I<regex> rather than "regular
@@ -410,8 +410,8 @@
With the new C<:ov> (C<:overlap>) modifier, the current regex will
match at all possible character positions (including overlapping)
-and return all matches in a list context, or a disjunction of matches
-in a scalar context. The first match at any position is returned.
+and return all matches in list context, or a disjunction of matches
+in item context. The first match at any position is returned.
The matches are guaranteed to be returned in left-to-right order with
respect to the starting positions.
@@ -425,7 +425,7 @@
With the new C<:ex> (C<:exhaustive>) modifier, the current regex will
match every possible way (including overlapping) and return all matches
-in a list context, or a disjunction of matches in a scalar context.
+in a list context, or a disjunction of matches in item context.
The matches are guaranteed to be returned in left-to-right order with
respect to the starting positions. The order within each starting
position is not guaranteed and may depend on the nature of both the
@@ -845,7 +845,7 @@
=item *
-The default way in which the engine handles a scalar is to match it
+The default way in which the engine handles a string scalar is to match it
as a C<< '...' >> literal (i.e. it does not treat the interpolated string
as a subpattern). In other words, a Perl 6:
@@ -1639,9 +1639,10 @@
}
}
-Using C<{...}> or C</.../> in the scalar context of the first argument
-causes it to produce a C<Code> or C<Regex> object, which the switch
-statement then selects upon.
+When you call C<my_grep>, the first argument is bound in item context,
+so passing C<{...}> or C</.../> produces a C<Code> or C<Regex> object,
+which the switch statement then selects upon. (Normal C<grep> just
+lets a smartmatch operator do all the work.)
=item *
Modified: doc/trunk/design/syn/S06.pod
==============================================================================
--- doc/trunk/design/syn/S06.pod (original)
+++ doc/trunk/design/syn/S06.pod Mon Mar 17 10:37:26 2008
@@ -13,9 +13,9 @@
Maintainer: Larry Wall <[EMAIL PROTECTED]>
Date: 21 Mar 2003
- Last Modified: 7 Feb 2008
+ Last Modified: 17 Mar 2008
Number: 6
- Version: 93
+ Version: 94
This document summarizes Apocalypse 6, which covers subroutines and the
@@ -458,7 +458,7 @@
Also, C<$ro> may not be returned from an lvalue subroutine or method.
Parameters may be required or optional. They may be passed by position,
-or by name. Individual parameters may confer a scalar or list context
+or by name. Individual parameters may confer an item or list context
on their corresponding arguments, but unlike in Perl 5, this is decided
lazily at parameter binding time.
@@ -593,7 +593,7 @@
method get_name ($self:) {...}
method set_name ($_: $newname) {...}
-The corresponding argument (the invocant) is evaluated in scalar context
+The corresponding argument (the invocant) is evaluated in item context
and is passed as the left operand of the method call operator:
print $obj.get_name();
@@ -659,7 +659,7 @@
sub numcmp ($x!, $y!) { return $x <=> $y }
-The corresponding arguments are evaluated in scalar context and may be
+The corresponding arguments are evaluated in item context and may be
passed positionally or by name. To pass an argument by name,
specify it as a pair: C<< I<parameter_name> => I<argument_value> >>.
@@ -700,7 +700,7 @@
sub xml_tag ($tag, $endtag = matching_tag($tag) ) {...}
Arguments that correspond to optional parameters are evaluated in
-scalar context. They can be omitted, passed positionally, or passed by
+item context. They can be omitted, passed positionally, or passed by
name:
my_substr("foobar"); # $from is 0, $len is infinite
@@ -745,7 +745,7 @@
sub globalize (:g(:$global)) {...}
-Arguments that correspond to named parameters are evaluated in scalar
+Arguments that correspond to named parameters are evaluated in item
context. They can only be passed by name, so it doesn't matter what
order you pass them in:
@@ -796,7 +796,7 @@
sub duplicate($n, *%flag, [EMAIL PROTECTED]) {...}
Named arguments are bound to the slurpy hash (C<*%flag>
-in the above example). Such arguments are evaluated in scalar context.
+in the above example). Such arguments are evaluated in item context.
Any remaining variadic arguments at the end of the argument list
are bound to the slurpy array (C<[EMAIL PROTECTED]> above) and are evaluated
in list context.
@@ -1939,7 +1939,7 @@
sub f { (:x<1>) } # always just one positional Pair object
On the caller's end, the C<Capture> is interpolated into any new argument list
-much like an array would be, that is, as a scalar in scalar context, and as a
+much like an array would be, that is, as an item in item context, and as a
list in list context. This is the default behavior, but the
caller may use C<< prefix:<|> >> to inline the returned values as part of the
new argument list. The caller may also bind the returned C<Capture> directly.
@@ -2117,7 +2117,7 @@
smart match (C<~~>) or a C<when>:
given want {
- when :($) {...} # called in scalar context
+ when :($) {...} # called in item context
when :(*@) {...} # called in list context
when :($ is rw) {...} # expected to return an lvalue
when :($,$) {...} # expected to return two values
@@ -2126,7 +2126,7 @@
Or use its shorthand methods to reduce line noise:
- if want.item {...} # called in non-lvalue scalar context
+ if want.item {...} # called in non-lvalue item context
elsif want.list {...} # called in list context
elsif want.void {...} # called in void context
elsif want.rw {...} # expected to return an lvalue
Modified: doc/trunk/design/syn/S09.pod
==============================================================================
--- doc/trunk/design/syn/S09.pod (original)
+++ doc/trunk/design/syn/S09.pod Mon Mar 17 10:37:26 2008
@@ -12,9 +12,9 @@
Maintainer: Larry Wall <[EMAIL PROTECTED]>
Date: 13 Sep 2004
- Last Modified: 3 Jan 2008
+ Last Modified: 17 Mar 2008
Number: 9
- Version: 23
+ Version: 24
=head1 Overview
@@ -960,12 +960,12 @@
one(one($a,$b),$c)
Some contexts, such as boolean contexts, have special rules for dealing
-with junctions. In any scalar context not expecting a junction of
+with junctions. In any item context not expecting a junction of
values, a junction produces automatic parallelization of the algorithm.
In particular, if a junction is used as an argument to any routine
(operator, closure, method, etc.), and the scalar parameter you
are attempting to bind the argument to is inconsistent with the
-Junction type, that routine is "autothreaded", meaning the routine
+C<Junction> type, that routine is "autothreaded", meaning the routine
will be called automatically as many times as necessary to process
the individual scalar elements of the junction in parallel.
@@ -1143,7 +1143,7 @@
The default hash iterator is a property called C<.iterator> that can be
user replaced. When the hash itself needs an iterator for C<.pairs>,
C<.keys>, C<.values>, or C<.kv>, it calls C<%hash.iterator()> to
-start one. In scalar context, C<.iterator> returns an iterator object.
+start one. In item context, C<.iterator> returns an iterator object.
In list context, it returns a lazy list fed by the iterator. It must
be possible for a hash to be in more than one iterator at a time,
as long as the iterator state is stored in a lazy list.
