[svn:perl6-synopsis] r14356 - doc/trunk/design/syn

[larry]

Author: larry
Date: Wed Mar 28 12:46:50 2007
New Revision: 14356

Modified:
   doc/trunk/design/syn/S04.pod
   doc/trunk/design/syn/S06.pod

Log:
Simplified -> binding not to autoalias $_ to first arg, per TheDamian++
Also clarified why "when" must always break from immediately surrounding block.
Juerd++'s double-pointy block now allowed as convenient way to make all
parameters default to "rw".
Implicit $_ arg now defined in terms of <->


Modified: doc/trunk/design/syn/S04.pod
==
--- doc/trunk/design/syn/S04.pod(original)
+++ doc/trunk/design/syn/S04.podWed Mar 28 12:46:50 2007
@@ -12,9 +12,9 @@
 
   Maintainer: Larry Wall <[EMAIL PROTECTED]>
   Date: 19 Aug 2004
-  Last Modified: 12 Mar 2007
+  Last Modified: 28 Mar 2007
   Number: 4
-  Version: 54
+  Version: 55
 
 This document summarizes Apocalypse 4, which covers the block and
 statement syntax of Perl.
@@ -390,8 +390,23 @@
 
 for =$*ARGS {...}
 
-Parameters are by default readonly within the block.  You can
-declare a parameter read/write by including the "C" trait.
+Arguments bound to the formal parameters of a pointy block are by
+default readonly within the block.  You can declare a parameter
+read/write by including the "C" trait.  The following treats
+every other value in C<@values> as modifiable:
+
+for @values -> $even is rw, $odd { ... }
+
+In the case where you want all your parameters to default to C,
+you may use the visually suggestive double-ended arrow to indicate that
+values flow both ways:
+
+for @values <-> $even, $odd { ... }
+
+This is equivalent to
+
+for @values -> $even is rw, $odd is rw { ... }
+
 If you rely on C<$_> as the implicit parameter to a block,
 then C<$_> is considered read/write by default.  That is,
 the construct:
@@ -400,10 +415,9 @@
 
 is actually short for:
 
-for @foo -> $_ is rw {...}
+for @foo <-> $_ {...}
 
-so you can modify the current list element in that case.  However,
-any time you specify the arguments, they default to read only.
+so you can modify the current list element in that case.
 
 When used as statement modifiers, C and C use a private
 instance of C<$_> for the left side of the statement.  The outer C<$_>
@@ -551,16 +565,20 @@
 }
 
 The current topic is always aliased to the special variable C<$_>.
-The C block is just one way to set the current topic, but a
-switch statement can be any block that sets C<$_>, including a C
-loop (in which the first loop parameter is the topic) or the body
-of a method (if you have declared the invocant as C<$_>).  So switching
-behavior is actually caused by the C statements in the block,
-not by the nature of the block itself.  A C statement implicitly
-does a "smart match" between the current topic (C<$_>) and the argument
-of the C.  If the smart match succeeds, C's associated block
-is executed, and the surrounding block is automatically broken out of.
-The value of the inner block is returned as the value of the outer block.
+The C block is just one way to set the current topic, but
+a switch statement can be any block that sets C<$_>, including a
+C loop (assuming one of its loop variables is bound to C<$_>)
+or the body of a method (if you have declared the invocant as C<$_>).
+So switching behavior is actually caused by the C statements in
+the block, not by the nature of the block itself.  A C statement
+implicitly does a "smart match" between the current topic (C<$_>) and
+the argument of the C.  If the smart match succeeds, C's
+associated block is executed, and the immediatly surrounding block
+is automatically broken out of.  (If that is not the block you wish
+to leave, you must use the C method to be more specific,
+since the compiler may find it difficult to guess which surrounding
+construct last set C<$_> as the topic.)  The value of the inner block
+is returned as the value of the outer block.
 
 If the smart match fails, control passes to the next statement
 normally, which may or may not be a C statement.  Since C
@@ -583,14 +601,12 @@
 fall off the last C into ordinary code.  But use of a C
 block is good documentation.
 
-If you use a C loop with a named parameter, the parameter is
-also aliased to C<$_> so that it can function as the topic of any
-C statements within the loop.  If you use a C statement
-with multiple parameters, only the first parameter is aliased to C<$_>
-as the topic.
+If you use a C loop with a parameter named C<$_> (either
+explicitly or implicitly), that parameter can function as the topic
+of any C statements within the loop.
 
 You can explicitly break out of a C block (and its surrounding
-switch) early using the C verb.  You can explicitly break out
+block) early using the C verb.  You can explicitly break out
 of a C block and go to the next statement by using C.
 (Note that, unlike C's idea of falling through, subsequent C
 conditions are evaluated.  To jump into the next C b

[svn:perl6-synopsis] r14357 - doc/trunk/design/syn

[larry]

Author: larry
Date: Wed Mar 28 13:17:43 2007
New Revision: 14357

Modified:
   doc/trunk/design/syn/S04.pod

Log:
Tweaked when/break to leave innermost block with formal $_ (also TheDamian++)


Modified: doc/trunk/design/syn/S04.pod
==
--- doc/trunk/design/syn/S04.pod(original)
+++ doc/trunk/design/syn/S04.podWed Mar 28 13:17:43 2007
@@ -14,7 +14,7 @@
   Date: 19 Aug 2004
   Last Modified: 28 Mar 2007
   Number: 4
-  Version: 55
+  Version: 56
 
 This document summarizes Apocalypse 4, which covers the block and
 statement syntax of Perl.
@@ -573,12 +573,14 @@
 the block, not by the nature of the block itself.  A C statement
 implicitly does a "smart match" between the current topic (C<$_>) and
 the argument of the C.  If the smart match succeeds, C's
-associated block is executed, and the immediatly surrounding block
-is automatically broken out of.  (If that is not the block you wish
-to leave, you must use the C method to be more specific,
-since the compiler may find it difficult to guess which surrounding
-construct last set C<$_> as the topic.)  The value of the inner block
-is returned as the value of the outer block.
+associated block is executed, and the innermost surrounding block
+that has C<$_> as one of its formal parameters (either explicit
+or implicit) is automatically broken out of.  (If that is not the
+block you wish to leave, you must use the C method to
+be more specific, since the compiler may find it difficult to guess
+which surrounding construct was intended as the actual topicalizer.)
+The value of the inner block is returned as the value of the outer
+block.
 
 If the smart match fails, control passes to the next statement
 normally, which may or may not be a C statement.  Since C
@@ -605,8 +607,12 @@
 explicitly or implicitly), that parameter can function as the topic
 of any C statements within the loop.
 
-You can explicitly break out of a C block (and its surrounding
-block) early using the C verb.  You can explicitly break out
+You can explicitly break out of a C block (and its surrounding 
topicalizer
+block) early using the C verb.  More precidely, it leaves the
+innermost block outside the C that uses C<$_> as one of its formal
+parameters, either explicitly or implicitly.
+
+You can explicitly break out
 of a C block and go to the next statement by using C.
 (Note that, unlike C's idea of falling through, subsequent C
 conditions are evaluated.  To jump into the next C block you

Re: [svn:perl6-synopsis] r14357 - doc/trunk/design/syn

[Juerd Waalboer]

[EMAIL PROTECTED] skribis 2007-03-28 13:17 (-0700):
> +block) early using the C verb.  More precidely, it leaves the

precisely?
-- 
korajn salutojn,

  juerd waalboer:  perl hacker  <[EMAIL PROTECTED]>  
  convolution: ict solutions and consultancy <[EMAIL PROTECTED]>

Ik vertrouw stemcomputers niet.
Zie .

[svn:perl6-synopsis] r14358 - doc/trunk/design/syn

[larry]

Author: larry
Date: Wed Mar 28 14:42:41 2007
New Revision: 14358

Modified:
   doc/trunk/design/syn/S04.pod

Log:
typo from Juerd++


Modified: doc/trunk/design/syn/S04.pod
==
--- doc/trunk/design/syn/S04.pod(original)
+++ doc/trunk/design/syn/S04.podWed Mar 28 14:42:41 2007
@@ -608,7 +608,7 @@
 of any C statements within the loop.
 
 You can explicitly break out of a C block (and its surrounding 
topicalizer
-block) early using the C verb.  More precidely, it leaves the
+block) early using the C verb.  More precisely, it leaves the
 innermost block outside the C that uses C<$_> as one of its formal
 parameters, either explicitly or implicitly.
 

[svn:perl6-synopsis] r14359 - doc/trunk/design/syn

[larry]

Author: larry
Date: Wed Mar 28 19:28:28 2007
New Revision: 14359

Modified:
   doc/trunk/design/syn/S09.pod

Log:
User-definable array indexing hammered out by TheDamian++ and Dataweaver++


Modified: doc/trunk/design/syn/S09.pod
==
--- doc/trunk/design/syn/S09.pod(original)
+++ doc/trunk/design/syn/S09.podWed Mar 28 19:28:28 2007
@@ -12,9 +12,9 @@
 
   Maintainer: Larry Wall <[EMAIL PROTECTED]>
   Date: 13 Sep 2004
-  Last Modified: 14 Mar 2007
+  Last Modified: 28 Mar 2007
   Number: 9
-  Version: 18
+  Version: 19
 
 =head1 Overview
 
@@ -146,6 +146,87 @@
 buffer type.  The unpacking is performed by coercion of such a buffer
 type back to the type of the compact struct.
 
+=head1 Standard array indexing
+
+Standard array indices are specified using square brackets. Standard
+indices always start at zero in each dimension of the array (see
+L<"Multidimensional arrays">), and are always contiguous:
+
+@dwarves[0] = "Happy";   # The 1st dwarf
+@dwarves[6] = "Doc"; # The 7th dwarf
+
+@seasons[0] = "Spring";  # The 1st season
+@seasons[2] = "Autumn"|"Fall";   # The 3rd season
+
+
+=head1 Fixed-size arrays
+
+A basic array declaration like:
+
+my @array;
+
+declares a one-dimensional array of indeterminate length. Such arrays
+are autoextending. For many purposes, though, it's useful to define
+array types of a particular size and shape that, instead of
+autoextending, fail if you try to access outside their
+declared dimensionality. Such arrays tend to be faster to allocate and
+access as well. (The language must, however, continue to protect you
+against overflow--these days, that's not just a reliability issue, but
+also a security issue.)
+
+To declare an array of fixed size, specify its maximum number of elements
+in square brackets immediately after its name:
+
+my @dwarves[7];   # Valid indices are 0..6
+
+my @seasons[4];   # Valid indices are 0..4
+
+No intervening whitespace is permitted between the name and the size
+specification, but "unspace" is allowed:
+
+my @values[10];   # Okay
+my @keys  [10];   # Error
+my @keys\ [10];   # Okay
+
+Note that the square brackets are a compile-time declarator, not a run-time
+operator, so you can't use the "dotted" form either:
+
+my @values.[10];  # Error
+my @keys\ .[10];  # Error
+
+Attempting to access an index outside a array's defined range will fail:
+
+@dwarves[7] = 'Sneaky';   # Fails with "invalid index" exception
+
+It's also possible to explicitly specify a normal autoextending array:
+
+my @vices[*]; # Length is: "whatever"
+  # Valid indices are 0..*
+
+=head1 Typed arrays
+
+The type of value stored in each element of the array (normally C)
+can be explicitly specified too, as an external C type:
+
+my num @nums; # Each element stores a native number
+my @nums of num;  # Same
+
+my Book @library[1_000_000];  # Each element stores a Book object
+my @library[1_000_000] of Book;   # Same
+
+Alternatively, the element storage type may be specified as part of the
+dimension specifier (much like a subroutine definition):
+
+my @nums[-->num];
+
+my @library[1_000_000 --> Book];
+
+Arrays may also be defined with a mixture of fixed and autoextending
+dimensions:
+
+my @calendar[12;*;24]; # "Month" dimension unlimited
+
+
 =head1 Compact arrays
 
 In declarations of the form:
@@ -166,6 +247,10 @@
 hard to make these elements look like objects when you treat them
 like objects--this is called autoboxing.)
 
+Such arrays are autoextending just like ordinary Perl arrays
+(at the price of occasionally copying the block of data to another
+memory location, or using a tree structure).
+
 A compact array is for most purposes interchangeable with the
 corresponding buffer type.  For example, apart from the sigil,
 these are equivalent declarations:
@@ -204,33 +289,45 @@
 known encoding.  Otherwise you must encode them explicitly from the
 higher-level abstraction into some buffer type.)
 
+
 =head1 Multidimensional arrays
 
-The declarations above declare one-dimensional arrays of indeterminate
-length.  Such arrays are autoextending just like ordinary Perl arrays
-(at the price of occasionally copying the block of data to another
-memory location, or using a tree structure).  For many purposes,
-though, it's useful to define array types of a particular size and
-shape that, instead of autoextending, throw an exception if you try
-to access outside their declared dimensionality.  Such arrays tend
-to be faster to allocate and access as well.  (The language must,
-however, continue to protect you against overflow--these days, that's
-not just a reliability issue, but also a security issue.)
+Perl 6 arrays are not restrict

[svn:perl6-synopsis] r14359 - doc/trunk/design/syn

[Bob Rogers]

   From: [EMAIL PROTECTED]
   Date: Wed, 28 Mar 2007 19:28:30 -0700 (PDT)

   Author: larry
   Date: Wed Mar 28 19:28:28 2007
   New Revision: 14359

   Modified:
  doc/trunk/design/syn/S09.pod

   Log:
   User-definable array indexing hammered out by TheDamian++ and Dataweaver++

   . . .

   +To declare an array of fixed size, specify its maximum number of elements
   +in square brackets immediately after its name:
   +
   +my @dwarves[7];   # Valid indices are 0..6
   +
   +my @seasons[4];   # Valid indices are 0..4

Huh??  I assume you didn't mean to throw in an extra season . . .

-- Bob Rogers
   http://rgrjr.dyndns.org/

[svn:perl6-synopsis] r14360 - doc/trunk/design/syn

[larry]

Author: larry
Date: Wed Mar 28 23:21:49 2007
New Revision: 14360

Modified:
   doc/trunk/design/syn/S09.pod

Log:
Clarifications requested by spinclad++ and Bob Rogers++.


Modified: doc/trunk/design/syn/S09.pod
==
--- doc/trunk/design/syn/S09.pod(original)
+++ doc/trunk/design/syn/S09.podWed Mar 28 23:21:49 2007
@@ -179,7 +179,7 @@
 
 my @dwarves[7];   # Valid indices are 0..6
 
-my @seasons[4];   # Valid indices are 0..4
+my @seasons[4];   # Valid indices are 0..3
 
 No intervening whitespace is permitted between the name and the size
 specification, but "unspace" is allowed:
@@ -222,9 +222,10 @@
 my @library[1_000_000 --> Book];
 
 Arrays may also be defined with a mixture of fixed and autoextending
-dimensions:
+dimensions.  There are always 12 months in a year and 24 hours in a day,
+but the number of days in the month can vary:
 
-my @calendar[12;*;24]; # "Month" dimension unlimited
+my @calendar[12;*;24]; # day-of-month dimension unlimited/ragged
 
 
 =head1 Compact arrays

[svn:perl6-synopsis] r14361 - doc/trunk/design/syn

[larry]

Author: larry
Date: Wed Mar 28 23:32:40 2007
New Revision: 14361

Modified:
   doc/trunk/design/syn/S09.pod

Log:
Clarification suggested by gaal++


Modified: doc/trunk/design/syn/S09.pod
==
--- doc/trunk/design/syn/S09.pod(original)
+++ doc/trunk/design/syn/S09.podWed Mar 28 23:32:40 2007
@@ -222,8 +222,9 @@
 my @library[1_000_000 --> Book];
 
 Arrays may also be defined with a mixture of fixed and autoextending
-dimensions.  There are always 12 months in a year and 24 hours in a day,
-but the number of days in the month can vary:
+dimensions (see below).  For example, there are always 12 months in
+a year and 24 hours in a day, but the number of days in the month
+can vary:
 
 my @calendar[12;*;24]; # day-of-month dimension unlimited/ragged
 

[svn:perl6-synopsis] r14362 - doc/trunk/design/syn

[larry]

Author: larry
Date: Thu Mar 29 00:55:18 2007
New Revision: 14362

Modified:
   doc/trunk/design/syn/S09.pod

Log:
typo spotted by Ruud++


Modified: doc/trunk/design/syn/S09.pod
==
--- doc/trunk/design/syn/S09.pod(original)
+++ doc/trunk/design/syn/S09.podThu Mar 29 00:55:18 2007
@@ -194,7 +194,7 @@
 my @values.[10];  # Error
 my @keys\ .[10];  # Error
 
-Attempting to access an index outside a array's defined range will fail:
+Attempting to access an index outside an array's defined range will fail:
 
 @dwarves[7] = 'Sneaky';   # Fails with "invalid index" exception