Index: Functions.pod
===================================================================
--- Functions.pod	(revision 11216)
+++ Functions.pod	(working copy)
@@ -39,7 +39,15 @@
 Where code is given here, it is intended to define semantics, not to
 dictate implementation.
 
+=head2 Operators vs. Functions
 
+There is no particular difference between an operator and a function,
+but for the sake of documentation, only functions declared without
+specifying a grammatical category or with a category of C<term:>
+(see L<Synopsis 2: Bits and Pieces>) will be described as "functions",
+and everything else as "operators" which are outside of the scope
+of this document.
+
 =head1 Type Declarations
 
 The following type declarations are assumed:
@@ -155,6 +163,7 @@
 
  &log10 := &log.assuming:base(10);
 
+A base C<10> logarithm.
 
 =item rand
 
@@ -168,19 +177,10 @@
 
  our Int multi Num::sign ( Num  $x )
  our Int multi Math::Basic::sign ( Num $x )
-   if !defined($x) { return undef };
-   if $x < 0       { return -1    };
-   if $x > 0       { return  1    };
-   if $x == 0      { return  0    };
-   fail;
- }
 
-or more succinctly:
+Returns 1 when C<$x> is greater than 0, -1 when it is less than 0, 0 when it
+is equal to 0, or undefined when the value passed is undefined.
 
- our Int multi Math::Basic::sign ( Num $x )
-   $x <=> 0;
- }
-
 =item srand
 
  multi Math::Basic::srand ( Num $seed = default_seed_algorithm())
@@ -199,26 +199,38 @@
  our Complex multi Complex::sqrt ( Complex  $x )
  our Num     multi Math::Basic::sqrt ( Num $x )
 
-C<$x ** 0.5>
+Returns the square root of the parameter.
 
 =item e
 
- constant Num Num::e = exp(1);
+ our Num multi term:Num::<e> ()
 
+The constant I<e>, roughly equal to C<2.71828182845905>.
 
 =item pi
 
- constant Num Num::pi = atan(1,1) * 4;
- constant Int Int::pi = 3;
+ our Num multi term:Num::<pi> ()
 
+The constant I<pi>, roughtly equal to C<3.14159265358979>.
+
 =item i
 
- constant Complex Complex::i = Complex::sqrt(-1);
+ our Num multi term:Num::<i> ()
 
+The constant I<i>, which is defined as the square root of C<-1>.
+
 =item one
 
- constant Int Int::one = round(-e ** (-i * pi));	# :-)
+ our Num multi term:Num::<one> ()
 
+The constant value C<1>.
+
+=item zero
+
+ our Num multi term:Num::<zero> ()
+
+The constant value C<0>.
+
 =back
 
 
@@ -256,7 +268,7 @@
 
 This overrides the default of "radians".
 
-=item atan
+=item atan2
 
  our Num multi Math::Trig::atan2 ( Num $y, Num $x = 1 ; Num :$base )
 
@@ -268,6 +280,66 @@
 
 =back
 
+=head2 General Utilities
+
+=over 
+
+=item defined
+
+  our Bool multi Scalar::defined ( Any $thing )
+  our Bool multi Scalar::defined ( Any $thing, ::role )
+  our Bool multi method Scalar::defined ( Scalar $thing: )
+  our Bool multi method Scalar::defined ( Scalar $thing: ::role )
+
+C<defined> returns true if the parameter has a value and that value is
+not the undefined value (per C<undef>), otherwise false is returned.
+
+Same as Perl 5, only takes extra optional argument to ask if value is defined
+with respect to a particular role:
+
+    $x.defined(SomeRole);
+
+A value may be defined according to one role and undefined according to another.
+Without the extra argument, defaults to the definition of defined supplied by
+the type of the object.
+
+=item undefine
+
+  our multi Any::undefine( Any $thing )
+  our multi method Any::undefine ( Any $thing: )
+
+Takes any variable as a parameter and attempts to "remove" its
+definition. For simple scalar variables this means assigning
+the undefined value to the variable. For objects, this is equivalent
+to invoking their undefine method. For arrays, hashes and other
+complex data, this might require emptying the structures associated
+with the object.
+
+In all cases, calling C<undefine> on a variable
+should place the object in the same state as if it was just
+declared.
+
+=item undef
+
+  our Scalar sub term:Scalar::undef()
+
+Perl 5's unary C<undef> function is renamed C<undefine> to avoid
+confusion with the value C<undef> (which is always 0-ary now).
+
+Returns the undefined scalar object. All undef.id are guaranteed
+to be the same, though it is possible to create variants, e.g.:
+
+	my $foo = undef but true;
+	say "Undef has a new id!" unless $foo.id == undef.id;
+
+=item want
+
+TODO
+
+=item caller
+
+TODO
+
 =head2 Array
 
 =over
@@ -441,19 +513,19 @@
 
 =item reverse
 
- our Hash multi Hash::reverse ( %hash )
+ our Hash multi Hash::reverse ( %hash ) {
    (my %result){%hash.values} = %hash.keys;
    %result;
  }
 
  multi Lazy Array::reverse ( @values )
- multi Lazy List::reverse ( *@values )
+ multi Lazy List::reverse ( *@values ) {
     gather {
         1 while take pop @values;
     }
  }
 
- multi Str Str::reverse ( $str )
+ multi Str Str::reverse ( $str ) {
     split('', $str).reverse.join
  )
 
@@ -607,6 +679,15 @@
 The lvalue form of C<keys> is not longer supported. Use the C<.buckets>
 property instead.
 
+=item each
+
+Unlike Perl 5's each, C<each> is a general method that traverses any
+composite container in a type-specific manner.
+
+For P5-like traversal, see C<Hash::kv> or C<Hash::pairs> instead,
+and put into C<for> instead of C<while>.  Perhaps there is a
+C<Perl5::p5each> emulation.
+
 =back
 
 
@@ -639,6 +720,23 @@
 
 =over
 
+=item as
+
+ our Str multi method Str::as ( Scalar $thing: Str $format )
+ our Str multi infix:<as>     ( Scalar $thing, Str $format )
+
+Formats the scalar C<$thing> according to the C<sprintf> format string
+in C<$format> and returns the resulting string.
+
+[ Refs:
+	Message-ID: <20060704163720.GB8942@wall.org>
+	From: Larry Wall <larry@wall.org>
+	Date: Tue, 4 Jul 2006 09:37:20 -0700  (12:37 EDT)
+	To: perl6language, <perl6-language@perl.org>
+
+  Notes: This may be at odds with L<Synopsis 13: Overloading>
+]
+
 =item p5chop
 
  our Char multi P5emul::Str::p5chop ( Str  $string is rw )
@@ -766,8 +864,6 @@
 
 =back
 
-
-
 =head2 Control::Basic
 
 =over
@@ -781,8 +877,6 @@
 
 Returns whatever C<$code> returns, or undef on error.
 
-
-
 =item evalfile
 
  multi Control::Basic::evalfile (Str $filename ; Grammar :$lang = Perl6)
@@ -797,7 +891,6 @@
 
 Stops all program execution, and returns C<$status> to the calling environment.
 
-
 =item nothing
 
  multi Control::Basic::nothing ()
@@ -812,11 +905,30 @@
 Attempt to sleep for up to C<$for> seconds. Implementations are obligated
 to support subsecond resolutions if that is at all possible.
 
-[Q: what about multithreading?  do we just sleep this thread?  need
-to coordinate with entire async model.  -law]
+This is exactly the same as:
 
-=item die 
+ $$.sleep($for)
 
+See C<Synopsis 17: Concurrency> for more details.
+
+=item word
+
+C<word> is almost exactly the same as C<macro>, but always defines
+its macros as C<term:> (see L<Synopsis 2: Bits and Pieces>). Its usage
+might appear as:
+
+ word foo { "'foo'.say" }
+ foo;
+
+[ Refs:
+	Message-ID: <20050614164447.GA14958@wall.org> 
+	Date: Tue, 14 Jun 2005 09:44:47 -0700  (12:44 EDT)
+	From: Larry Wall <larry@wall.org>
+	To: perl6-language@perl.org
+]
+
+=item die
+
 =item fail
 
 B<TODO>: Research the exception handling system.
@@ -898,45 +1010,81 @@
 
 =back
 
+=head2 Concurrency
 
-=head2 I<TODO>
+There are higher-level models of concurrency management in Perl (see
+L<Synopsis 17: Concurrency>). These functions are simply the lowest level
+tools
 
-=over 4
+=over
 
-=item defined
+=item fork
 
-Same as Perl 5, only takes extra optional argument to ask if value is defined
-with respect to a particular role:
+ our Conc::Proc sub Conc::Processes::fork()
 
-    $x.defined(SomeRole);
+Creates a copy of the current process. Both processes return from
+C<fork>. The original process returns
+the I<child> process as a C<Conc::Proc> object. The newly created process
+returns the I<parent> process as a C<Conc::Proc> object. As with
+any Conc::Proc object, the child process object numifies to the
+process ID (OS dependent integer). However, the parent process object
+numifies to C<0> so that the child and parent can distinguish each other.
 
-A value may be defined according to one role and undefined according to another.
-Without the extra argument, defaults to the definition of defined supplied by
-the type of the object.
+Typical usage would be:
 
-=item undefine
+ if !defined(my $pid = fork) {
+   die "Error calling fork: $!";
+ } elsif $pid == 0 {
+   say "I am the new child!";
+   exit 0;
+ } else {
+   say "I am the parent of {+$pid}";
+   wait();
+ }
 
-Perl 5's unary C<undef> function is renamed C<undefine> to avoid
-confusion with the value C<undef> (which is always 0-ary now).
+=item wait
 
-=item want
+ our Conc::Proc::Status multi method Conc::Processes::wait( Conc::Proc $process: *%options )
 
-=item caller
+ our Conc::Proc::Status multi Conc::Processes::wait ( Conc::Proc $process = -1, *%options )
 
-=item each
+Waits for a child process to terminate and returns the status
+object for the child. Important Conc::Proc::Status mehtods:
 
-Unlike Perl 5's each, C<each> is a general method that traverses any
-composite container in a type-specific manner.
+ .exit - Numeric exit value
+ .pid - Process ID
+ .signal - Signal number if any, otherwise 0
 
-For P5-like traversal, see C<Hash::kv> or C<Hash::pairs> instead,
-and put into C<for> instead of C<while>.  Perhaps there is a
-C<Perl5::p5each> emulation.
+For historical reasons there is a C<.status> method which is equal to:
 
+ ($status.exit +< 8) +| $status.signal
 
+If C<$process> is supplied, then wait will only return when the given process
+has exited. Either a full C<Conc::Proc> object can be passed, or just a
+numeric process ID. A C<-1> explicitly indicates that wait should return
+immediately if any child process exits.
+
+When called in this way, the returned C<Conc::Proc::Status> object
+will have a C<.pid> of C<-1> (which is also what it numifies to) if
+there was no such process to wait for.
+
+The named options include:
+
+=over
+
+=item blocking
+
+Defaults to true. If set to false, this forces wait to return immediately.
+
+=item WNOHANG
+
+Exists for historical compatibility. C<WNOHANG => 1> is identical to
+C<blocking => False>.
+
 =back
 
+=back
 
-
 =head2 Obsolete
 
 =over 4
@@ -946,7 +1094,6 @@
 
  use DB_File;
 
-
 =item dump
 
 Dumped.
@@ -966,6 +1113,11 @@
 
 Replaced by C<temp> which, unlike C<local>, defaults to not changing the value.
 
+=item lock
+
+See L<Synopsis 17: Concurrency>. C<lock> has been replaced by
+C<is atomic>.
+
 =item ref
 
 There is no ref() any more, since it was almost always used to get
@@ -992,9 +1144,12 @@
 
 Algorithm was too anglo-centric.  Could be brought back if generalized somehow.
 
+=item waitpid
+
+C<wait> can now be called with or without an optional process/pid.
+
 =back
 
-
 =item %
 
  $num1 % $num2
@@ -1047,12 +1202,6 @@
 and huffmanly longer.  I'm thinking runinstead().  And maybe the
 function behind qq:x should be rungather() rather than readpipe().  -law
 
-=item A/S17: Threads and Multiprocessing
-
-fork lock wait waitpid
-
-# FIXME audrey drafted synopsis 17
-
 =back
 
 
