kill DEF* variants

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

S02-bits.pod

@@ -1409,14 +1409,14 @@ or package scoped.  Oddly scoped variables include a secondary sigil
 is subject to:
 
     $foo        ordinary scoping
-    $.foo       object attribute accessor
+    $.foo       object attribute public accessor
     $^foo       self-declared formal positional parameter
     $:foo       self-declared formal named parameter
     $*foo       contextualizable global variable
     $?foo       compiler hint variable
     $=foo       pod variable
     $<foo>      match variable, short for $/{'foo'}
-    $!foo       explicitly private attribute (mapped to $foo though)
+    $!foo       object attribute private storage (mapped to $foo though)
 
 Most variables with twigils are implicitly declared or assumed to
 be declared in some other scope, and don't need a "my" or "our".

S03-operators.pod

@@ -2840,6 +2840,13 @@ also available, as are the C<min=> and C<max=> assignment operators.
 By default C<min> and C<max> use C<cmp> semantics.  As with all C<cmp>-based
 operators, this may be modified by an adverb specifying different semantics.
 
+=item *
+
+Note that, like most other operators, a comparison naturally throws
+an exception if either of its arguments is undefined.  However,
+various parallelizable contexts such as sort and hyper suppress this,
+er, somehow.
+
 =back
 
 =head1 Range semantics

S12-objects.pod

@@ -1298,6 +1298,11 @@ value (an argumentless sub).  The names of the values are specified as a list:
     my enum Day ['Sun','Mon','Tue','Wed','Thu','Fri','Sat'];
     my enum Day <Sun Mon Tue Wed Thu Fri Sat>;
 
+For any enum value the C<.perl> method will return its long name.
+A numeric enum value numifies to its numeric value and stringifies to its short name.
+A string enum value has no special numeric value, and stringifies to its string value
+rather than its name. [XXX inconsistent]
+
 If the first value is unspecified, it defaults to 0.  To specify the
 first value, use pair notation (see below).
 

S16-io.pod

@@ -13,8 +13,8 @@ DRAFT: Synopsis 16: IPC / IO / Signals
                 Tim Nelson <wayland@wayland.id.au>
                 Daniel Ruoso <daniel@ruoso.com>
  Date:          12 Sep 2006
- Last Modified: 19 Feb 2009
- Version:       20
+ Last Modified: 23 Feb 2009
+ Version:       21
 
 This is a draft document. Many of these functions will work as in Perl
 5, except we're trying to rationalize everything into roles.  For
@@ -24,22 +24,46 @@ many of them are really methods on an IO handle, and if there is a
 corresponding global function, it's merely an exported version of
 the method.
 
-=head1 Default IO handles
-
-In Perl 6, there are the I<standard> handles, and the I<default> handles.  
-
-The I<standard> ones are our old familiar friends (with new names).  Standard input 
-changed from STDIN to C<$*IN>, standard output changed from STDOUT to C<$*OUT>, and 
-standard error changed from STDERR to C<$*ERR>.  
-
-However, the I<default> ones replace the single handle set by the Perl 5 select() call 
-with with three new variables.  
-At the start of the program, the default handles (C<$*DEFIN>, C<$*DEFOUT>, and 
-C<$*DEFERR>) are aliased to the standard handles, but may be temporarily or permanently 
-rebound to some other file handle.  
-
-Many of the roles and functions below will operate on the default handles.  To set all 3 
-at once, do C<($*DEFIN, $*DEFOUT, $*DEFERR) ::= ($*IN, $*OUT, $*ERR)>.  
+=head1 Overridable IO handles
+
+In Perl 6, there are the I<standard> IO handles, and any number of overriding
+inner filehandles for the same symbol.  
+
+The I<standard> handles are our old familiar friends (with new names).
+Standard input changed from STDIN to C<$*IN>, standard output changed
+from STDOUT to C<$*OUT>, and standard error changed from STDERR to
+C<$*ERR>.  In Perl 6 these symbols represent more of a concept than
+a given filehandle, since the meaning is contextually determined.
+The process's version of these handles live in the C<PROCESS::>
+namespace, which is more global than the per-interpreter C<GLOBAL::>
+namespace.
+
+When no explicit filehandle is used, the standard IO operators are
+defined in terms of the contextual variables.  So the C<print> function
+prints to C<$*OUT>, while C<warn> warns to C<$*ERR>.  The C<< =<> >>
+term inputs from C<$*IN>.  So any given dynamic scope (interpreter,
+thread, function or method call) may redefine the current meaning of
+any of those filehandles within the dynamic scope of itself and of
+its called routines.
+
+So to put it another way, when you write something like
+
+    say "Howdy, world!"
+
+the C<say> function looks for the current meaning of C<$*OUT>, and
+takes the closest definition it can find in its callers.  If none
+of the callers have overridden the definition, it looks in the
+interpreter's C<GLOBAL> namespace.  If the interpreter hasn't overridden
+the meaning, it takes the meaning from C<PROCESS>.  In essence, any
+dynamic scope in Perl 6 is allowed to do IO redirection much like
+a Unix shell does with its subprocesses, albeit with a different
+syntax:
+
+    {
+	temp $*OUT = open $newfile, :w;
+	foo() # all stdout goes to $newfile
+    }
+    # stdout reverts to outer scope's definition
 
 =head1 Roles and Classes
 

S28-special-variables.pod

@@ -9,7 +9,7 @@
  Contributions: Tim Nelson <wayland@wayland.id.au>
  Date:          23 Feb 2009, created from miscellaneous documents lying around
  Last Modified: 23 Feb 2009
- Version:       1
+ Version:       2
 
 =head1 Introduction
 
@@ -23,53 +23,45 @@ Each main entry is followed by a note containing the corresponding
 Perl 5 variable(s). The list of main entries is also followed by 
 a table showing the 5 and 6 variables side-by-side.
 
-Most/All variables of the form $*SOMETHING should also work in the form
-$SOMETHING (without the '*') unless masked by "my $SOMETHING".
-
 =head1 Overview
 
 =head2 Secondary Sigils (also known as "twigils"):
 
-    $+   # currently compiling scope (see S02)
-    $?   # lexically-scoped (compile time, see S02)
-    $*   # global (run time, see S02)
-    $=   # file-scoped (see S02)
-    $^   # implicit block argument (see S06 placeholder variables)
+    $?   # constants (variable only at compile time, see S02)
+    $*   # context variables and globals (run time, see S02)
+    $=   # pod documents, file-scoped (see S02)
+    $^   # self-declaring block positional parameter (see S06 placeholder variables)
+    $:   # self-declaring block named parameter (see S06 placeholder variables)
     $<   # current $/ scope (see S02)
-    $.   # public attribute (see S12 attributes)
-    $!   # private attribute (see S12 attributes)
+    $.   # public attribute accessor (see S12 attributes)
+    $!   # private attribute storage (see S12 attributes)
 
 
 =head2 Named variables (see S02):
 
-    $/             # match object from last rule (see S05)
-    $0             # first captured value from match: $/.[0]
+    $/             # match object from last match (see S05)
+    $0             # first captured value from match: $/[0]
     @*ARGS         # command-line arguments
     &?BLOCK        # current block (itself, see S06)
     @?BLOCK        # current blocks (themselves, see S06)
-    $?BLOCKLABEL   # label of current block (see S06) 
-                   #   XXX redundant with $?LABEL?
     ::?CLASS       # current class (as package name)
     $?CLASS        # current class (as variable)
     @?CLASS        # current classes
     %?CONFIG	   # configuration hash
     $=DATA         # data block handle (=begin DATA ... =end)
-    $*DEFIN        # Default input file handle (see S16)
-    $*DEFOUT       # Default output file handle (see S16)
-    $*DEFERR       # Default error file handle (see S16)
     $*EGID         # effective group id
     %*ENV          # system environment
     $*ERR          # standard error handle (see S16)
     $*EUID         # effective user id
     $*EXECUTABLE_NAME    # executable name
-    $?FILE         # current file
+    $?FILE         # current filename of source file
     $?GRAMMAR      # current grammar
     @?GRAMMAR      # current grammars
     $*GID          # group id
     $*IN           # standard input handle (see S16)
     $?LABEL        # label of current block
     @?LABEL        # labels of current blocks
-    $?LINE         # current line
+    $?LINE         # current line number in source file
     $?MODULE       # current module
     @?MODULE       # current modules
     $?OS           # operating system compiled for
@@ -84,21 +76,23 @@ $SOMETHING (without the '*') unless masked by "my $SOMETHING".
     $*PERLVER      # perl version running under
     $*PROGRAM_NAME # name of the program being executed
     $*PID          # system process id
-    $?PUGS_VERSION # Pugs version (not canonical)
-    $*PUGS_HAS_HSPLUGINS # True if Pugs was compiled with support for hsplugins
-                         # (not canonical)
     ::?ROLE        # current role (as package name)
     $?ROLE         # current role (as variable)
     @?ROLE         # current roles
     &?ROUTINE      # current sub or method (itself, see S06)
     @?ROUTINE      # current subs or methods (themselves)
     $*UID          # system user id
 
-There were threads on p6l about unifying all variables which concern the OS or
-the VM ($*UID, $*PROGRAM_NAME, etc.) into two variables, $?ENV (compile-time
-environment) and $*ENV (runtime environment). Larry did like the idea, but
-"ENV" is probably to overloaded to mean the hash of environment variables
-(which would be found under $*ENV.environment or some-such).
+
+Note that contextual variables such as C<$*OUT> may have more than
+one current definition in the outer dynamic context, in which case
+the innermost dynamic scope determines the meaning.  For instance,
+C<$PROCESS::OUT> is the stdout for the entire process, but each
+interpreter can set its own C<$GLOBAL::OUT> to make C<$*OUT> mean
+whatever it wants independently of other interpreters.  Any dynamic
+scope may also declare a local meaning of C<$*OUT> that applies only
+to called code.  Likewise each thread could log its own errors
+to its own C<$*ERR>, since a thread is a dynamic scope.
 
 =head1 Special Variables