[Spec] slaughter various confusing overloadings of the term 'context'

contextual variables are now dynamic variables
specific dynamic contexts are now just call frames
(for now we've left alone 'context' used as in 'context switching')


git-svn-id: http://svn.pugscode.org/pugs@29142 c213334d-75ef-0310-aa23-eaa082d1ae64

S02-bits.pod

@@ -13,8 +13,8 @@ Synopsis 2: Bits and Pieces
 
     Created: 10 Aug 2004
 
-    Last Modified: 18 Nov 2009
-    Version: 190
+    Last Modified: 19 Nov 2009
+    Version: 191
 
 This document summarizes Apocalypse 2, which covers small-scale
 lexical items and typological issues.  (These Synopses also contain
@@ -996,7 +996,7 @@ that is to say, every element of the array, no matter how many dimensions.
 (However, C<@array[**]> means the same thing because (as with C<...>
 above), the subscript operator will interpret bare C<**> as meaning
 all the subscripts, not the list of dimension sizes.  The meaning of
-C<Whatever> is always controlled by its immediate context.)
+C<Whatever> is always controlled by the first context it is bound into.)
 
 Other uses for C<*> and C<**> will doubtless suggest themselves
 over time.  These can be given meaning via the MMD system, if not
@@ -1640,7 +1640,7 @@ is subject to:
     $.foo       object attribute public accessor
     $^foo       self-declared formal positional parameter
     $:foo       self-declared formal named parameter
-    $*foo       contextualizable global variable
+    $*foo       dynamically overridable global variable
     $?foo       compiler hint variable
     $=foo       Pod variable
     $<foo>      match variable, short for $/{'foo'}
@@ -1740,9 +1740,7 @@ Sigils used either as functions or as list prefix operators also
 force context, so these also work:
 
     @x[$(g())]         # item context for g()
-    @x[$ g()]          # item context for g()
     %x{$(g())}         # item context for g()
-    %x{$ g()}          # item context for g()
 
 But note that these don't do the same thing:
 
@@ -1779,16 +1777,25 @@ the C<Parcel> is translated (at compile time, in this case)
 into a C<Capture> with 3 positionals and one named argument
 in preparation for binding.
 
-=item *
-
-An argument list may be captured into an object with backslashed parens:
+A parcel may be captured into an object with backslashed parens:
 
     $args = \(1,2,3,:mice<blind>)
 
-Values in a C<Capture> object are parsed as ordinary expressions, then marked as
-positional or named.  If the first positional is followed by a colon instead of
-a comma, it is marked as the invocant in case it finds itself in a context
-that cares.
+Values in the C<Parcel> object are parsed as ordinary expressions,
+and any functions mentioned are called, with their results placed
+as a single subparcel within the outer parcel.  Whether they
+are subsequently flattened will depend on the eventual binding.
+
+=item *
+
+If a C<Parcel> is used as a list of arguments, it will be transformed
+into a C<Capture> objects, which is much like a C<Parcel> but has its
+arguments divvied up into positional and named subsets for faster
+binding.  (Usually this transformation happens at compile time.)
+If the first positional is followed by a colon instead of a comma,
+it is marked as the invocant in case it finds itself in a context
+that cares.  It's illegal to use the colon in place of the comma
+anywhere except after the first argument.
 
 Like C<List> objects, C<Capture> objects are immutable in the abstract, but
 evaluate their arguments lazily.  Before everything inside a C<Capture> is
@@ -1816,7 +1823,7 @@ parentheses.  The special syntax form C<$()> translates into C<$( $.ast // Str($
 to operate on the current match object; similarly C<@()> and C<%()> can
 extract positional and named submatches.
 
-C<Capture> objects fill the ecological niche of references in Perl 6.
+C<Parcel> and C<Capture> objects fill the ecological niche of references in Perl 6.
 You can think of them as "fat" references, that is, references that
 can capture not only the current identity of a single object, but
 also the relative identities of several related objects.  Conversely,
@@ -2030,13 +2037,13 @@ operators:
     print $( foo() )    # foo called in item context
     print @@( foo() )   # foo called in slice context
 
-In declarative contexts bare sigils may be used as placeholders for
+In declarative constructs bare sigils may be used as placeholders for
 anonymous variables:
 
     my ($a, $, $c) = 1..3;
     print unless (state $)++;
 
-Outside of declarative contexts you may use C<*> for a placeholder:
+Outside of declarative constructs you may use C<*> for a placeholder:
 
     ($a, *, $c) = 1..3;
 
@@ -2139,7 +2146,7 @@ so there's no need to also put such things into C<GLOBAL>.
 The C<GLOBAL> package itself is accessible via C<UNIT::GLOBAL>.
 The C<PROCESS> package is accessible via C<UNIT::PROCESS>.
 The C<PROCESS> package is not the parent of C<GLOBAL>.  However, searching
-up the dynamic stack for context variables will look in all nested
+up the dynamic stack for dynamic variables will look in all nested
 dynamic scopes (mapped automatically to each call's lexical scope,
 not package scope) out to the main dynamic scope; once all the dynamic scopes are
 exhausted, it also looks in the C<GLOBAL> package and then in the
@@ -2173,10 +2180,10 @@ the underspecified type.  Alternately, the compiler is allowed to recompile or
 re-examine the unit with the new type constraints to see if any issues are
 certain to arise at run time, in which case the compiler is free to complain.)
 
-Any context variable declared with C<our> in the user's main program
+Any dynamic variable declared with C<our> in the user's main program
 (specifically, the part compiled with C<GLOBAL> as the current package)
-is accessible (by virtue of being in C<GLOBAL>) as a context variable
-even if not directly in the dynamic call chain.  Note that context
+is accessible (by virtue of being in C<GLOBAL>) as a dynamic variable
+even if not directly in the dynamic call chain.  Note that dynamic
 vars do *not* look in C<CORE> for anything.  (They I<might> look in
 C<SETTING> if you're running under a setting distinct from C<CORE>,
 if that setting defines a dynamic scope outside your main program,
@@ -2304,19 +2311,19 @@ by reference, to add symbols to a lexical scope that is done compiling.
 The C<CALLER> package refers to the lexical scope of the (dynamically
 scoped) caller.  The caller's lexical scope is allowed to hide any
 user-defined variable from you.  In fact, that's the default, and a
-lexical variable must have the trait "C<is context>" to be
+lexical variable must have the trait "C<is dynamic>" to be
 visible via C<CALLER>.  (C<$_>, C<$!> and C<$/> are always
-contextual, as are any variables whose declared names contain a C<*> twigil.)
+dynamic, as are any variables whose declared names contain a C<*> twigil.)
 If the variable is not visible in the caller, it returns
 failure.  Variables whose names are visible at the point of the call but that
 come from outside that lexical scope are controlled by the scope
-in which they were originally declared as contextual.
+in which they were originally declared as dynamic.
 Hence the visibility of C<< CALLER::<$*foo> >> is determined where
 C<$*foo> is actually declared, not by the caller's scope (unless that's where
 it happens to be declared).  Likewise C<< CALLER::CALLER::<$x> >>
 depends only on the declaration of C<$x> visible in your caller's caller.
 
-User-defined contextual variables should generally be initialized with
+User-defined dynamic variables should generally be initialized with
 C<::=> unless it is necessary for variable to be modified.  (Marking
 dynamic variables as readonly is very helpful in terms of sharing
 the same value among competing threads, since a readonly variable
@@ -2326,31 +2333,31 @@ need not be locked.)
 
 The C<DYNAMIC> pseudo-package is just like C<CALLER> except that
 it starts in the current dynamic scope and from there scans outward
-through all dynamic scopes until it finds a contextual variable of that
-name in that dynamic context's associated lexical pad.  (This search
+through all dynamic scopes (frames) until it finds a dynamic variable of that
+name in that dynamic frame's associated lexical pad.  (This search
 is implied for variables with the C<*> twigil; hence C<$*FOO> is
 equivalent to C<< DYNAMIC::<$*FOO> >>.)  If, after scanning outward
 through all those dynamic scopes, there is no variable of that name
 in any immediately associated lexical pad, it strips the C<*> twigil
 out of the name and looks in the C<GLOBAL> package followed by the
 C<PROCESS> package.  If the value is not found, it returns failure.
 
-Unlike C<CALLER>, C<DYNAMIC> will see a contextual variable that is
+Unlike C<CALLER>, C<DYNAMIC> will see a dynamic variable that is
 declared in the current scope, since it starts search 0 scopes up the
 stack rather than 1.  You may, however, use C<< CALLER::<$*foo> >>
-to bypass a contextual definition of C<$*foo> in your current context,
-such as to initialize it with the outer contextual value:
+to bypass a dynamic definition of C<$*foo> in your current scope,
+such as to initialize it with the outer dynamic value:
 
     my $*foo ::= CALLER::<$*foo>;
 
 The C<temp> declarator may be used (without an initializer) on a
-contextual variable to perform a similar operation:
+dynamic variable to perform a similar operation:
 
     temp $*foo;
 
 The main difference is that by default it initializes the new
 C<$*foo> with its current value, rather than the caller's value.
-Also, it is allowed only on read/write contextual variables, since
+Also, it is allowed only on read/write dynamic variables, since
 the only reason to make a copy of the outer value would be
 because you'd want to override it later and then forget the
 changes at the end of the current dynamic scope.
@@ -2401,12 +2408,12 @@ that properly belong to the individual virtual process, while the
 C<PROCESS> namespace holds variables that properly belong to the actual
 process as a whole.  From the viewpoint of the program
 there is little difference as long as all global variables are accessed
-as if they were context variables (by using the C<*> twigil).
+as if they were dynamic variables (by using the C<*> twigil).
 The process as a whole may place restrictions on the
 mutability of process variables as seen by the individual subprocesses.
 Also, individual subprocesses may not create new process variables.
 If the process wishes to grant subprocesses the ability to communicate
-via the C<PROCESS> namespace, it must supply a writeable context variable
+via the C<PROCESS> namespace, it must supply a writeable dynamic variable
 to all the subprocesses granted that privilege.
 
 =item *
@@ -2504,9 +2511,9 @@ when the compile-time code was itself compiled).  The compiler can
 talk about these compiler-dynamic values using the C<COMPILING> pseudopackage.
 
 References to C<COMPILING> variables are automatically hoisted into the
-context currently being compiled.  Setting or temporizing a C<COMPILING>
+lexical scope currently being compiled.  Setting or temporizing a C<COMPILING>
 variable sets or temporizes the incipient C<$?> variable in the
-surrounding lexical context that is being compiled.  If nothing in
+surrounding lexical scope that is being compiled.  If nothing in
 the context is being compiled, an exception is thrown.
 
     $?FOO // say "undefined";   # probably says undefined
@@ -2525,7 +2532,7 @@ the context is being compiled, an exception is thrown.
     COMPILING::<$?FOO> = 45;    # an error unless we are compiling something
 
 Note that C<< CALLER::<$?FOO> >> might discover the same variable
-as C<COMPILING::<$?FOO>>, but only if the compiling context is the
+as C<COMPILING::<$?FOO>>, but only if the compiling scope is the
 immediate caller.  Likewise C<< OUTER::<$?FOO> >> might or might not
 get you to the right place.  In the abstract, C<COMPILING::<$?FOO>>
 goes outwards dynamically until it finds a compiling scope, and so is
@@ -3651,8 +3658,10 @@ The lexical routine itself is C<&?ROUTINE>; you can get its name with
 C<&?ROUTINE.name>.  The current block is C<&?BLOCK>.  If the block has any
 labels, those shows up in C<&?BLOCK.labels>.  Within the lexical scope of
 a statement with a label, the label is a pseudo-object representing
-the dynamic context of that statement.  (If inside multiple dynamic
-instances of that statement, the label represents the innermost one.)
+the I<dynamically> visible instance of that statement.  (If inside multiple
+dynamic instances of that statement, the label represents the innermost one.)
+This is known as I<lexotic> semantics.
+
 When you say:
 
     next LINE;
@@ -3805,18 +3814,18 @@ such as a system that sorts "delta" after "gamma".
 
 =item *
 
-Perl still has the three main contexts: sink (void), item (scalar), and list.
+Perl still has the three main contexts: sink (aka void), item (aka scalar), and list.
 
 =item *
 
 In addition to undifferentiated items, we also have these item contexts:
 
-    Context     Type    OOtype  Operator
-    -------     ----    ------  --------
-    boolean     bit     Bit     ?
-    integer     int     Int     int
-    numeric     num     Num     +
-    string      buf     Str     ~
+    Context     Type    OOtype   Operator
+    -------     ----    ------   --------
+    boolean     bit     Bit      ?
+    integer     int     Integral int
+    numeric     num     Num      +
+    string      buf     Str      ~
 
 There are also various container contexts that require particular kinds of
 containers (such as slice and hash context; see S03 for details).
@@ -3930,9 +3939,9 @@ themselves in any event, which may or may not be lazily flattened.
 
 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 an item
-context operator.
+know which signature to check against.  Such return values are
+bundled up into a "parcel" for later delivery to a context that
+will determine its context lazily.
 
 =item *
 

S03-operators.pod

@@ -15,8 +15,8 @@ Synopsis 3: Perl 6 Operators
 
     Created: 8 Mar 2004
 
-    Last Modified: 5 Oct 2009
-    Version: 175
+    Last Modified: 19 Nov 2009
+    Version: 176
 
 =head1 Overview
 
@@ -1467,7 +1467,7 @@ C<< infix:<::=> >>, bind and make readonly
 This does the same as C<:=>, then marks any destination parameters as
 readonly (unless the individual parameter overrides this with either
 the C<rw> trait or the C<copy> trait).  It's particularly useful
-for establishing readonly context variables for a dynamic scope:
+for establishing readonly dynamic variables for a dynamic scope:
 
     {
         my $*OUT ::= open($file, :w) || die $!;
@@ -1476,7 +1476,7 @@ for establishing readonly context variables for a dynamic scope:
     doit();     # runs with original stdout
 
 If C<doit> wants to change C<$*OUT>, it must declare its own
-contextual variable.  It may not simply assign to C<$*OUT>.
+dynamic variable.  It may not simply assign to C<$*OUT>.
 
 Note that the semantics of C<::=> are virtually identical to
 the normal binding of arguments to formal subroutine parameters
@@ -1939,7 +1939,7 @@ uses the function:
 
 =back
 
-Many of these operators return a list of C<Capture>s, which depending on
+Many of these operators return a list of C<Parcel>s, which depending on
 context may or may not flatten them all out into one flat list.  The
 default is to flatten, but see the contextualizers below.
 
@@ -2222,7 +2222,7 @@ C<< infix:<or> >>, short-circuit inclusive or
 
 Returns the first argument that evaluates to true, otherwise returns
 the result of the last argument.  In list context forces a false return
-to mean C<()>.  See C<||> above for high-precedence version.
+to mean C<()>, or C<Nil>.  See C<||> above for high-precedence version.
 
 =item *
 
@@ -2232,7 +2232,7 @@ C<< infix:<xor> >>, exclusive or
 
 Returns the true argument if there is one (and only one).  Returns
 C<Bool::False> if all arguments are false or if more than one argument is true.
-In list context forces a false return to mean C<()>.
+In list context forces a false return to mean C<()>, or C<Nil>.
 See C<^^> above for high-precedence version.
 
 =item *
@@ -2283,7 +2283,7 @@ Semicolon: ;
 
 The context determines how the expressions terminated by semicolon
 are interpreted.  At statement level they are statements.  Within a
-bracketing construct they are interpreted as lists of C<Capture>s,
+bracketing construct they are interpreted as lists of C<Parcel>s,
 which in slice context will be treated as the multiple dimensions of a
 multidimensional slice.  (Other contexts may have other interpretations
 or disallow semicolons entirely.)
@@ -2471,11 +2471,11 @@ Writing C<$object.'='> will call your prefix operator.
 
 =item *
 
-Unary C<~> now imposes a string (C<Str>) context on its
-argument, and C<+> imposes a numeric (C<Num>) context (as opposed
+Unary C<~> now imposes a string (C<Stringy>) context on its
+argument, and C<+> imposes a numeric (C<Numeric>) context (as opposed
 to being a no-op in Perl 5).  Along the same lines, C<?> imposes
 a boolean (C<Bool>) context, and the C<|> unary operator imposes
-a function-arguments (C<Capture>) context on its argument.
+a function-arguments (C<Parcel> or C<Capture>) context on its argument.
 Unary sigils are allowed when followed by a C<$> sigil on a scalar variable;
 they impose the container context implied by their sigil.
 As with Perl 5, however, C<$$foo[bar]> parses as C<( $($foo) )[bar]>,
@@ -2538,8 +2538,8 @@ written: C<<< << ... >> >>>.
 
 =item *
 
-In item context comma C<,> now constructs a C<List> object from its
-operands.  You have to use a C<[*-1]> subscript to get the last one.
+Comma C<,> now constructs a C<Parcel> object from its
+operands.  In item context this turns into a C<List> object.  You have to use a C<[*-1]> subscript to get the last one.
 (Note the C<*>.  Negative subscripts no longer implicitly count from
 the end; in fact, the compiler may complain if you use C<[-1]> on an
 object known at compile time not to have negative subscripts.)
@@ -3192,7 +3192,7 @@ means "what is this thing's domain" in an abstract sort of way.
 Since use of C<Range> objects in item context is usually
 non-sensical, a C<Range> object used as an operand for scalar operators
 will generally attempt to distribute the operator to its endpoints and
-return another suitably modified C<Range> instead.  (Notable exceptions
+return another suitably modified C<Range> instead, much like a junction of two items.  (Notable exceptions
 include C<< infix:<~~> >>, which does smart matching, and C<< prefix:<+> >>
 which returns the length of the range.)  Therefore if you wish to
 write a slice using a length instead of an endpoint, you can say