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

Author: audreyt
Date: Wed Jul 19 13:12:50 2006
New Revision: 10308

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

Log:
* S02 proof-editing with Uri Guttman: Batch #1.

  These edits introduce no semantic changes to the spec;
  it's all strictly English cleanups.

Modified: doc/trunk/design/syn/S02.pod
==============================================================================
--- doc/trunk/design/syn/S02.pod	(original)
+++ doc/trunk/design/syn/S02.pod	Wed Jul 19 13:12:50 2006
@@ -14,7 +14,7 @@
   Date: 10 Aug 2004
   Last Modified: 19 July 2006
   Number: 2
-  Version: 53
+  Version: 54
 
 This document summarizes Apocalypse 2, which covers small-scale
 lexical items and typological issues.  (These Synopses also contain
@@ -57,8 +57,8 @@
 since they're bidirectional but not in the Ps/Pe set.
 
 Characters with no corresponding closing character do not qualify
-as opening brackets.  This includes the second section of the BidiMirroring
-data table, as well as C<U+201A> and C<U+201E>.
+as opening brackets.  This includes the second section of the Unicode
+BidiMirroring data table, as well as C<U+201A> and C<U+201E>.
 
 If a character is already used in Ps/Pe mappings, then its entry in
 BidiMirroring is ignored.  Therefore C<U+298D> maps to C<U+298E>,
@@ -86,10 +86,10 @@
 
 Multiline comments are provided by extending the syntax of POD
 to nest C<=begin comment>/C<=end comment> correctly without the need
-for C<=cut>.  (Doesn't have to be "comment"--any unrecognized POD
-stream will do to make it a comment.  Bare C<=begin> and C<=end>
-probably aren't good enough though, unless you want all your comments
-to end up in the manpage...)
+for C<=cut>.  The format name does not have to be C<comment> -- any
+unrecognized format name will do to make it a comment.  (However,
+bare C<=begin> and C<=end> probably aren't good enough, because all
+comments in them will show up in the formatted output.)
 
 We have single paragraph comments with C<=for comment> as well.
 That lets C<=for> keep its meaning as the equivalent of a C<=begin>
@@ -102,7 +102,8 @@
 =item *
 
 Embedded comments are supported as a variant on quoting syntax, introduced
-by C<#> plus any user-selected bracket characters (see definition above):
+by C<#> plus any user-selected bracket characters (as defined in
+L</Lexical Conventions> above):
 
     say #( embedded comment ) "hello, world!";
 
@@ -112,25 +113,29 @@
 	embedded comments
     」.say;
 
-There must be no space between the # and the opening bracket character.
-(There may be the I<appearance> of space for some double-wide
-characters, however, such as the corner quotes above.)  Brackets may
-be nested following the same policy as ordinary quote brackets.
+Brackets may be nested, following the same policy as ordinary quote brackets.
+
+There must be no space between the C<#> and the opening bracket character.
+(There may be the I<visual appearance> of space for some double-wide
+characters, however, such as the corner quotes above.)
+
+=item *
 
 As a special case to facilitate commenting out sections of code with
-C<s/^/#/>, C<#> on the left margin is always considered a line-end
-comment rather than an embedded comment, even if followed by a
-bracketing character.
+C<s/^/#/>, C<#> on the beginning of line is always considered a line-end
+comment rather than an embedded comment, even if followed by a bracketing
+character.
 
 =item *
 
-For all quoting constructs that use user-selected brackets, multiple,
-adjacent, identical opening brackets must always be matched by an
-equal number of adjacent closing brackets.  Bracket counting naturally
-applies only to sets of brackets of the same length:
+For all quoting constructs that use user-selected brackets, you can open
+with multiple identical bracket characters, which must by closed by the
+same number of closing brackets.  Counting of nested brackets applies only
+to pairs of brackets of the same length as the opening brackets:
 
     say #{{
-	Comment contains unmatched } and { { { { plus a counted {{ ... }} pair.
+        This comment contains unmatched } and { { { {   (ignored)
+        Plus a nested {{ ... }} pair                    (counted)
     }} q<< <<woot>> >>   # says "<<woot>>"
 
 Note however that bare circumfix or postcircumfix C<<< <<...>> >>> is
@@ -187,8 +192,8 @@
 In general, whitespace is optional in Perl 6 except where it is needed
 to separate constructs that would be misconstrued as a single token or
 other syntactic unit.  (In other words, Perl 6 follows the standard
-"longest-token" principle, or in the cases of large constructs, a
-"prefer shifting to reducing" principle.  See Grammatical Categories
+I<longest-token> principle, or in the cases of large constructs, a
+I<prefer shifting to reducing> principle.  See L</Grammatical Categories>
 below for more on how a Perl program is analyzed into tokens.)
 
 This is an unchanging deep rule, but the surface ramifications of it
@@ -315,10 +320,10 @@
 
 =item *
 
-Properties applied to compile-time objects such as variables and
-classes are also called B<traits>.  Traits are not expected to change
-at run time.  Changing run-time properties should be done via mixin
-instead, so that the compiler can optimize based on declared traits.
+Properties applied to objects constructed at compile-time, such as
+variables and classes, are also called B<traits>.  Traits cannot be
+changed at run-time.  Changes to run-time properties are done via
+mixin instead, so that the compiler can optimize based on declared traits.
 
 =item *
 
@@ -329,29 +334,51 @@
 
 =item *
 
-A variable's type is an interface contract indicating what sorts
-of values the variable may contain. More precisely, it's a promise
-that the object or objects contained in the variable are capable of
-responding to the methods of the indicated "role".  See S12 for more
-about roles.  A variable object may itself be bound to a container
-type that specifies how the container works without necessarily
-specifying what kinds of things it contains.
+A variable's type is a constraint indicating what sorts of values the
+variable may contain.  More precisely, it's a promise that the object
+or objects contained in the variable are capable of responding to the
+methods of the indicated "role".  See S12 for more about roles.
 
-=item *
+    # $x can contain only Int objects
+    my Int $x;
+
+A variable may itself be bound to a container type that specifies how
+the container works, without specifying what kinds of things it contains.
+
+    # $x is implemented by the MyScalar class
+    my $x is MyScalar;
 
-You'll be able to ask for the length of an array, but it won't be
-called that, because C<length> does not specify units.  So
-C<.elems> is the number of array elements.  You can also
-ask for the length of an array in bytes or codepoints or graphemes.
-The same methods apply to strings as well: there is no C<.length> on
-strings either.
+Constraints and container types can be used together:
+
+    # $x can contain only Int objects,
+    # and is implemented by the MyScalar class
+    my Int $x is MyScalar;
+
+Note that C<$x> is also initialized to C<::Int>.  See below for more on this.
 
 =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.
+It merely assigns an undefined C<Dog> prototype object to C<$spot>:
+
+    my Dog $spot;           # $spot is initialized with ::Dog
+    my Dog $spot = Dog;     # same thing
+
+    $spot.defined;          # False
+    say $spot;              # "Dog"
+
+Any class name used as a value by itself is an undefined instance of that
+class's prototype.  See S12 for more on that.
+
+To get a real C<Dog> object, call a constructor method such as C<new>:
+
+    my Dog $spot .= new;
+    my Dog $spot = $spot.new;   # .= is rewritten into this
+
+You can pass in arguments to the constructor as well:
+
+    my Dog $cerberus .= new(heads => 3);
+    my Dog $cerberus = $cerberus.new(heads => 3);   # same thing
 
 =item *
 
@@ -366,6 +393,16 @@
 
 =item *
 
+To get the number of elements in an array, use the C<.elems> method.  You can
+also ask for the total string length of an array's elements, in bytes,
+codepoints or graphemes, using these methods C<.bytes>, C<.codes> or C<.graphs>
+respectively on the array.  The same methods apply to strings as well.
+
+There is no C<.length> method for either arrays or strings, because C<length>
+does not specify an unit.
+
+=item *
+
 Built-in object types start with an uppercase letter. This includes
 immutable types (e.g. C<Int>, C<Num>, C<Complex>, C<Rational>, C<Str>,
 C<Bit>, C<Regex>, C<Set>, C<Junction>, C<Code>, C<Block>, C<List>,
@@ -382,18 +419,27 @@
 
 =item *
 
-All Object types support the C<undefined> role, and may contain an
-alternate set of attributes when undefined, such as the unthrown
-exception explaining why the value is undefined.  Non-object types
-are not required to support undefinedness, but it is an error to
-assign an undefined value to such a location.
+Variables with non-native types can always contain I<undefined> values,
+such as C<Undef>, C<Whatever> and C<Failure> objects.  See S04 for more
+about failures (i.e. unthrown exceptions):
+
+    my Int $x = undef;    # works
+
+Variables with native types does not support undefinedness: it is an error
+to assign an undefined value to them:
+
+    my int $y = undef;    # dies
 
 =item *
 
-Regardless of whether they are defined, all objects support a C<.meta>
-method that returns the class instance managing the current kind of object.
-Any object (whether defined, undefined, or somewhere between) can be
-used as a "kind" when the context requires it.
+All objects support a C<.meta> method that returns the class instance
+managing it, regardless of whether the object is defined:
+
+    'x'.meta.get_method_list;   # get available methods for strings
+    Str.meta.get_method_list;   # same thing with the prototype object Str
+
+    'x'.get_method_list;        # this is an error - not a meta object
+    Str.get_method_list;        # same thing
 
 =item *
 
@@ -1352,7 +1398,7 @@
     :t          :to             Interpret result as heredoc terminator
     :n          :none           No escapes at all (unless otherwise adverbed)
     :q          :single         Interpolate \\, \q and \' (or whatever)
-    :qq         :double         Interpolate all the following
+    :qq         :double         Interpolate with :s, :a, :h, :f, :c, :b
     :s          :scalar         Interpolate $ vars
     :a          :array          Interpolate @ vars
     :h          :hash           Interpolate % vars

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