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

Author: larry
Date: Fri Apr 21 13:27:05 2006
New Revision: 8902

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

Log:
Attempt to straighten out Buf vs Str semantics.
In line with autobox-to-uppercase rule, buf types now autobox to Buf types.
There is no native str type.
Smeared distinction between buffer strings and corresponding compact arrays.
I think Bufs and bufs should be mutable.  Their identity is their location.
Also renamed Tuple to Seq to avoid confusion with relational database jive.


Modified: doc/trunk/design/syn/S02.pod
==============================================================================
--- doc/trunk/design/syn/S02.pod	(original)
+++ doc/trunk/design/syn/S02.pod	Fri Apr 21 13:27:05 2006
@@ -12,9 +12,9 @@
 
   Maintainer: Larry Wall <larry@wall.org>
   Date: 10 Aug 2004
-  Last Modified: 18 Apr 2006
+  Last Modified: 21 Apr 2006
   Number: 2
-  Version: 24
+  Version: 25
 
 This document summarizes Apocalypse 2, which covers small-scale
 lexical items and typological issues.  (These Synopses also contain
@@ -319,6 +319,7 @@
 =item *
 
 C<my Dog $spot> by itself does not automatically call a C<Dog> constructor.
+It merely installs an undefined C<Dog> prototype as the object.
 The actual constructor syntax turns out to be C<my Dog $spot .= new;>,
 making use of the C<.=> mutator method-call syntax.
 
@@ -339,10 +340,10 @@
 immutable types (e.g. C<Int>, C<Num>, C<Complex>, C<Rational>, C<Str>,
 C<Bit>, C<Rule>, C<Set>, C<Junction>, C<Code>, B<Block>, C<List>,
 C<Tuple>), as well as mutable (container) types, such as C<Scalar>,
-C<Array>, C<Hash>, C<Routine>, C<Module>, etc.
+C<Array>, C<Hash>, C<Buf>, C<Routine>, C<Module>, etc.
 
 Non-object (native) types are lowercase: C<int>, C<num>, C<complex>,
-C<rational>, C<str>, C<bit>.  Native types are primarily intended for
+C<rational>, C<buf>, C<bit>.  Native types are primarily intended for
 declaring compact array storage.  However, Perl will try to make those
 look like their corresponding uppercase types if you treat them that way.
 (In other words, it does autoboxing.  Note, however, that sometimes
@@ -392,10 +393,19 @@
 
 =item *
 
-A C<Str> is a Unicode string object.  A C<str> is a stringish view of
-an array of integers, and has no Unicode or character properties without
-explicit conversion to some kind of C<Str>.  Typically it's an array of bytes
-serving as a buffer.
+A C<Str> is a Unicode string object.  (There is no corresponding
+native C<str> type.)  A C<Buf> is a stringish view of an array of
+integers, and has no Unicode or character properties without explicit
+conversion to some kind of C<Str>.  (A C<buf> is the native counterpart.)
+Typically it's an array of bytes serving as a buffer.  Bitwise
+operations on a C<Buf> treat the entire buffer as a single large
+integer.  Bitwise operations on a C<Str> generally fail unless the
+C<Str> in question can provide an abstract C<Btr> interface somehow.
+Coercion to C<Btr> should generally invalidate the C<Str> interface.
+As a generic type C<Btr> may be instantiated as (or bound to) any
+of C<buf8>, C<buf16>, or C<buf32> (or to any type that provide the
+appropriate C<Buf> interface), but when used to create a buffer C<Buf>
+defaults to C<buf8>.
 
 =back
 
@@ -1554,7 +1564,7 @@
     boolean     bit     Bit     ?
     integer     int     Int     int
     numeric     num     Num     +
-    string      str     Str     ~
+    string      buf     Str     ~
 
 There are also various container contexts that require particular kinds of
 containers.

Modified: doc/trunk/design/syn/S06.pod
==============================================================================
--- doc/trunk/design/syn/S06.pod	(original)
+++ doc/trunk/design/syn/S06.pod	Fri Apr 21 13:27:05 2006
@@ -13,9 +13,9 @@
 
   Maintainer: Larry Wall <larry@wall.org>
   Date: 21 Mar 2003
-  Last Modified: 18 Apr 2006
+  Last Modified: 21 Apr 2006
   Number: 6
-  Version: 25
+  Version: 26
 
 
 This document summarizes Apocalypse 6, which covers subroutines and the
@@ -717,10 +717,10 @@
     *(x=>1);          # Pair, becomes \(x=>1)
     *{x=>1, y=>2};    # Hash, becomes \(x=>1, y=>2)
 
-C<List> (also C<Tuple>, C<Range>, etc.) are simply turned into
+C<List> (also C<Seq>, C<Range>, etc.) are simply turned into
 positional arguments:
 
-    *(1,2,3);         # Tuple, becomes \(1,2,3)
+    *(1,2,3);         # Seq, becomes \(1,2,3)
     *(1..3);          # Range, becomes \(1,2,3)
     *(1..2, 3);       # List, becomes \(1,2,3)
     *([x=>1, x=>2]);  # List (from an Array), becomes \((x=>1), (x=>2))
@@ -1307,8 +1307,7 @@
     bit         single native bit
     int         native signed integer
     uint        native unsigned integer (autoboxes to Int)
-    buf         native bytes (finite sequence of "uint8"s, no Unicode)
-    str         native string (finite sequence of native integers, no Unicode)
+    buf         native buffer (finite seq of native ints or uints, no Unicode)
     num         native floating point
     complex	native complex number
     bool        native boolean
@@ -1329,7 +1328,6 @@
 
     Bit         Perl single bit (allows traits, aliasing, undef, etc.)
     Int         Perl integer (allows Inf/NaN, arbitrary precision, etc.)
-    Buf         Perl buffer (possibly lazy list of bytes, can be subscripted)
     Str         Perl string (finite sequence of Unicode characters)
     Num         Perl number
     Complex     Perl complex number
@@ -1337,15 +1335,15 @@
     Exception   Perl exception
     Code        Base class for all executable objects
     Block       Executable objects that have lexical scopes
-    List        Lazy Perl list (composed of Tuple and Range parts)
-    Tuple       Completely evaluated (hence immutable) sequence
+    List        Lazy Perl list (composed of Seq and Range parts)
+    Seq         Completely evaluated (hence immutable) sequence
     Range       Incrementally generated (hence lazy) sequence
-    Set         Unordered Tuples that allow no duplicates
+    Set         Unordered Seqs that allow no duplicates
     Junction    Sets with additional behaviours
-    Pair        Tuple of two elements that serves as an one-element Mapping
+    Pair        Seq of two elements that serves as an one-element Mapping
     Mapping     Pairs with no duplicate keys
     Signature   Function parameters (left-hand side of a binding)
-    Capture   Function call arguments (right-hand side of a binding)
+    Capture     Function call arguments (right-hand side of a binding)
 
 =head2 Mutable types
 
@@ -1354,6 +1352,7 @@
     Array       Perl array
     Hash        Perl hash
     Scalar      Perl scalar
+    Buf         Perl buffer (an stringish array of memory locations)
     IO          Perl filehandle
     Routine     Base class for all wrappable executable objects
     Sub         Perl subroutine

Modified: doc/trunk/design/syn/S09.pod
==============================================================================
--- doc/trunk/design/syn/S09.pod	(original)
+++ doc/trunk/design/syn/S09.pod	Fri Apr 21 13:27:05 2006
@@ -12,9 +12,9 @@
 
   Maintainer: Larry Wall <larry@wall.org>
   Date: 13 Sep 2004
-  Last Modified: 6 Apr 2006
+  Last Modified: 21 Apr 2006
   Number: 9
-  Version: 7
+  Version: 8
 
 =head1 Overview
 
@@ -58,6 +58,11 @@
     complex64	(aka complex on most architectures)
     complex128
 
+    buf8	aka buf, a "normal" byte buffer
+    buf16	a uint16 buffer
+    buf32	a uint32 buffer
+    buf64	a uint64 buffer
+
 Complex sizes indicate the size of each C<num> component rather than
 the total.  This would extend to tensor typenames as well if they're
 built-in types.  Of course, the typical tensor structure is just
@@ -112,6 +117,29 @@
 hard to make these elements look like objects when you treat them
 like objects--this is called autoboxing.)
 
+A compact array is for most purposes interchangeable with the
+corresponding buffer type.  For example, apart from the sigil,
+these are equivalent declarations:
+
+    my uint8 @buffer;
+    my buf8 $buffer;
+
+(Note: If you actually said both of those, you'd still get two
+different names, since the sigil is part of the name.)
+
+So given C<@buffer> you can say
+
+    $piece = substr(@buffer, $beg, $end - $beg);
+
+and given C<$buffer> you can also say
+
+    @pieces = $buffer[$n..^$end];
+
+Note that subscripting still pulls the elements out as numbers,
+but C<substr()> returns the same 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

• [svn:perl6-synopsis] r8902 - doc/trunk/design/syn by larry
• Re: [svn:perl6-synopsis] r8902 - doc/trunk/design/syn by Geoffrey Broadwell