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

Author: audreyt
Date: Wed Jul 19 15:10:38 2006
New Revision: 10312

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

Log:
* S02 proof-editing with Uri Guttman: Batch #2.
* One semantic change to address an unspecified point:
  plural magicals like @?BLOCK etc are ordered from innermost
  to outermost (i.e. in the same order as lookups.)

Modified: doc/trunk/design/syn/S02.pod
==============================================================================
--- doc/trunk/design/syn/S02.pod	(original)
+++ doc/trunk/design/syn/S02.pod	Wed Jul 19 15:10:38 2006
@@ -14,7 +14,7 @@
   Date: 10 Aug 2004
   Last Modified: 19 July 2006
   Number: 2
-  Version: 54
+  Version: 55
 
 This document summarizes Apocalypse 2, which covers small-scale
 lexical items and typological issues.  (These Synopses also contain
@@ -461,9 +461,10 @@
 respectively, and do not promote to arbitrary precision, though
 larger representations are always allowed for temporary values.
 Unless qualified with a number of bits, C<int> and C<num> types default
-to the largest native types that run at full speed.  Untyped numeric
-scalars use C<Int> and C<Num> semantics rather than C<int> and C<num>.
+to the largest native types that run at full speed.
 
+Numeric values in untyped variables use C<Int> and C<Num> semantics
+rather than C<int> and C<num>.
 
 =item *
 
@@ -586,7 +587,7 @@
 
 =item *
 
-The C<$pkg'var> syntax is dead.  Use C<$pkg::var> instead.
+The C<$Package'var> syntax is gone.  Use C<$Package::var> instead.
 
 =item *
 
@@ -601,15 +602,19 @@
     @@  multislice view of @
 
 Within a declaration, the C<&> sigil also declares the visibility of the
-subroutine name without the sigil within the scope of the declaration.
+subroutine name without the sigil within the scope of the declaration:
+
+    my &func := sub { say "Hi" };
+    func;   # calls &func
 
 Within a signature or other declaration, the C<::> sigil followed by an
-identifier marks a parametric type that also declares the visibility
+identifier marks a type variable that also declares the visibility
 of a package/type name without the sigil within the scope of the
 declaration.  The first such declaration within a scope is assumed
 to be an unbound type, and takes the actual type of its associated
 argument.  With subsequent declarations in the same scope the use of
 the sigil is optional, since the bare type name is also declared.
+
 A declaration nested within must not use the sigil if it wishes to
 refer to the same type, since the inner declaration would rebind
 the type.  (Note that the signature of a pointy block counts as part
@@ -658,15 +663,17 @@
 
 =item *
 
-To get a Perlish representation of any data value, use the C<.perl>
-method.  This will put quotes around strings, square brackets around
-list values, curlies around hash values, constructors around objects,
-etc., such that standard Perl could reparse the result.
+To get a Perlish representation of any object, use the C<.perl> method.
+Like the C<Data::Dumper> module in Perl 5, the C<.perl> method will put
+quotes around strings, square brackets around list values, curlies around
+hash values, constructors around objects, etc., so that Perl can evaluate
+the result back to the same object.
 
 =item *
 
-To get a formatted representation of any scalar data value, use
-the C<.fmt('%03d')> method to do an implicit sprintf on the value.
+To get a formatted representation of any scalar value, use the
+C<.fmt('%03d')> method to do an implicit C<sprintf> on the value.
+
 To format an array value separated by commas, supply a second argument:
 C<.fmt('%03d', ', ')>.  To format a hash value or list of pairs, include
 formats for both key and value in the first string: C<< .fmt('%s: %s', "\n") >>.
@@ -710,16 +717,16 @@
 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
-for more about parameter binding.
+for more about binding.
 
 =item *
 
-An argument list object (C<Capture>) may be created with backslashed parens:
+An argument list may be captured into an object with backslashed parens:
 
     $args = \(1,2,3,:mice<blind>)
 
-Values in C<Capture> are parsed as ordinary expressions, marked as invocant,
-positional, named, and so on.
+Values in a C<Capture> object are parsed as ordinary expressions, marked as
+invocant, positional, named, and so on.
 
 Like C<List> objects, C<Capture> objects are immutable in the abstract, but
 evaluate their arguments lazily.  Before everything inside a C<Capture> is
@@ -757,22 +764,20 @@
 
 =item *
 
-A signature object (C<Signature>) may be created with coloned parens:
+A signature object (C<Signature>) may be created with colon-prefixed parens:
 
-    my ::MySig = :(Int,Num,Complex, Status :mice)
+    my ::MySig ::= :(Int, Num, Complex, Status :mice)
 
-A signature's values are parsed as declarations rather than ordinary
-expressions.  You may not put arbitrary expressions, but you may, for
-instance stack multiple types that all must match:
+Expressions inside the signature are parsed as parameter declarations
+rather than ordinary expressions.  See S06 for more details on the syntax
+for parameters.
 
-    :(Any Num Dog|Cat $numdog)
+Signature objects bound to C<::t> variables may be used within another
+signature to apply additional type constraints.  When applied to a
+C<Capture> argument of form C<\$x>, the signature allows you to specify
+the types of parameters that would otherwise be untyped:
 
-Such a signature may be used within another signature to apply
-additional type constraints.  When applied to a C<Capture> argument, the
-signature allows you to specify the types of parameters that would
-otherwise be untyped:
-
-    :(Any Num Dog|Cat $numdog, MySig \$a ($i,$j,$k,$mousestatus))
+    :(Num Dog|Cat $numdog, MySig \$a ($i,$j,$k,$mousestatus))
 
 =item *
 
@@ -867,7 +872,7 @@
 
 =item *
 
-The C<$#foo> notation is dead.  Use C<@foo.end> or C<[-1]> instead.
+The C<$#foo> notation is dead.  Use C<@foo.end> or C<@foo[-1]> instead.
 (Or C<@foo.shape[$dimension]> for multidimensional arrays.)
 
 =back
@@ -893,14 +898,14 @@
 
 The following pseudo-package names are reserved in the first position:
 
-    MY
-    OUR
-    GLOBAL
-    OUTER
-    CALLER
-    CONTEXT
-    SUPER
-    COMPILING
+    MY          # Lexical variables declared in the current scope
+    OUR         # Package variables declared in the current package
+    GLOBAL      # Builtin variables and functions
+    OUTER       # Lexical variables declared in the outer scope
+    CALLER      # Contextual variables in the caller's scope
+    CONTEXT     # Contextual variables in any caller's scope
+    SUPER       # Package variables declared in inherited classes
+    COMPILING   # Lexical variables in the scope being compiled
 
 Other all-caps names are semi-reserved.  We may add more of them in
 the future, so you can protect yourself from future collisions by using
@@ -918,14 +923,14 @@
 immediately or is continued with another C<::> outside the curlies.
 Most symbolic references are done with this notation:
 
-    $foo = "Foo";
+    $foo = "Bar";
     $foobar = "Foo::Bar";
-    $::($foo)           # package-scoped $Foo
-    $::("MY::$foo")     # lexically-scoped $Foo
-    $::("*::$foo")      # global $Foo
+    $::($foo)           # package-scoped $Bar
+    $::("MY::$foo")     # lexically-scoped $Bar
+    $::("*::$foo")      # global $Bar
     $::($foobar)        # $Foo::Bar
     $::($foobar)::baz   # $Foo::Bar::baz
-    $::($foo)::Bar::baz # $Foo::Bar::baz
+    $::($foo)::Bar::baz # $Bar::Bar::baz
     $::($foobar)baz     # ILLEGAL at compile time (no operator baz)
 
 Note that unlike in Perl 5, initial C<::> doesn't imply global.
@@ -1120,30 +1125,31 @@
 
 Here are some possibilities:
 
-    $?OS        Which os am I compiled for?
-    $?OSVER     Which os version am I compiled for?
+    $?OS        Which operating system am I compiled for?
+    $?OSVER     Which operating system version am I compiled for?
     $?PERLVER   Which Perl version am I compiled for?
     $?FILE      Which file am I in?
     $?LINE      Which line am I at?
     $?PACKAGE   Which package am I in?
-    @?PACKAGE   Which packages am I in?
+    @?PACKAGE   Which nested packages am I in?
     $?MODULE    Which module am I in?
-    @?MODULE    Which modules am I in?
-    ::?CLASS    Which class am I in? (as package name)
+    @?MODULE    Which nested modules am I in?
     $?CLASS     Which class am I in? (as variable)
-    @?CLASS     Which classes am I in?
-    ::?ROLE     Which role am I in? (as package name)
+    @?CLASS     Which nested classes am I in?
     $?ROLE      Which role am I in? (as variable)
-    @?ROLE      Which roles am I in?
+    @?ROLE      Which nested roles am I in?
     $?GRAMMAR   Which grammar am I in?
-    @?GRAMMAR   Which grammars am I in?
+    @?GRAMMAR   Which nested grammars am I in?
     $?PARSER    Which Perl grammar was used to parse this statement?
     &?ROUTINE   Which routine am I in?
-    @?ROUTINE   Which routines am I in?
+    @?ROUTINE   Which nested routines am I in?
     &?BLOCK     Which block am I in?
-    @?BLOCK     Which blocks am I in?
+    @?BLOCK     Which nested blocks am I in?
     $?LABEL     Which block label am I in?
-    @?LABEL     Which block labels am I in?
+    @?LABEL     Which nested block labels am I in?
+
+All the nested C<@?> variables are ordered from the innermost to the
+outermost, so C<@?BLOCK[0]> is always the same as C<$?BLOCK>.
 
 Note that some of these things have parallels in the C<*> space at run time:
 
@@ -1244,13 +1250,13 @@
 in adverbial form:
 
     :10<42>             same as 0d42 or 42
-    :16<dead_beef>      same as 0xdeadbeef
+    :16<DEAD_BEEF>      same as 0xDEADBEEF
     :8<177777>          same as 0o177777 (65535)
     :2<1.1>             same as 0b1.1 (0d1.5)
 
-Extra digits are assumed to be represented by 'a'..'z', so you can go up
-to base 36.  (Use 'a' and 'b' for base twelve, not 't' and 'e'.)  Alternately
-you can use a list of digits in decimal:
+Extra digits are assumed to be represented by C<a>..C<z> and C<A>..C<Z>, so you
+can go up to base 36.  (Use C<A> and C<B> for base twelve, not C<T> and C<E>.)
+Alternately you can use a list of digits in decimal:
 
     :60[12,34,56]       # 12 * 3600 + 34 * 60 + 56
     :100[3,'.',14,16]   # pi
@@ -1310,7 +1316,7 @@
 
 =item *
 
-Characters indexed by hex, octal, and decimal can be interpolated
+Characters indexed by hex, octal, and decimal numbers can be interpolated
 into strings using either C<"\x123"> (with C<\o> and C<\d> behaving
 respectively) or using square brackets: C<"\x[123]">.  Multiple
 characters may be specified within any of the bracketed forms by

• [svn:perl6-synopsis] r10312 - doc/trunk/design/syn by audreyt