Larry (bless his wire-photographing heart) took the time to re-vamp S29.
Of course, this threw off all of my collating of S29, but that's fine
since he's actually answered more of my questions than I could have
hoped.
The fourth of July weekend was fairly slow for me, so I started with
Larry's S29 and went forward.
My first pass at a revised S29 is attached. This is a combination of
some of what was left from my original work, some suggested changes to
Larry's version, and some newly incorporated bits. Where possible I'm
footnoting the summary or mailing list and message ID that my changes
are based on. There's a lot more of the mailing-list based work to go,
but before someone overhauls S29 again, I thought I should make some of
my work public. My diff is against pugs/docs/Perl6/Spec circa revision
11216.
A quick summary for discussion:
Operators vs. Functions
Before Larry's update, I had decided that simple functions and term:'s
were the only things that made sense for S29, even though EVERYTHING is
really a function. I've codified this as part of the intro. Thoughts?
Removing code
I've begun the process of removing some of the code from S29. It's not
that code is bad, it's just that it's not actually documentation. To
that end, I'm writing real documentation for functions like sign and
sqrt instead of example implementations.
Constants as functions
Since this is S29, I think it makes sense to unify every entry with a
leading subroutine/function signature, not to use the otherwise very
nice and convenient C<constant type type::name> notation. To this end,
I've re-written constants as C<our type multi term:type::<name> ()>
which I assert means the exact same thing (please correct me if that
assertion fails). Of course the implementation might use C<constant>,
but the documentation doesn't have to agree with the implementation
details as long as it agrees with the implementation interface.
TODO
Two major TODO sections were in there: defined/undefine/want/caller and
fork/lock/wait/waitpid. I moved all of these into the body of the
Summary and defined defined, undefine, fork and wait. I left the body of
want and caller as TODO, and put lock and waitpid in the Obsolete
section (per S17 Draft and the simple fact that waitpid is no longer
required).
For wait I've defined a new object called Conc::Proc::Status (no more
bit shifting, yay!) and some behavior of S17's Conc::Proc which is
probably fine, but others should look it over. If this is OK, some notes
should probably be added back into S17 as well.
There are some notes on waitpid in Perl 5's perlfunc, which probably
need to be moved into S29, but some analysis of parrot's wait facilities
will be required to be sure how they play in.
word to your macro
Larry proposed word as an operator a while back. This is one of the
(many) things that was in my note bin for transcription. Let me know if
this is still relevant.
word probably violates my intro on the scope of the document, but it's a
pretty strange one, so I don't think anyone's going to complain too
much.
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 ( [EMAIL PROTECTED] )
+ multi Lazy List::reverse ( [EMAIL PROTECTED] ) {
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: <[EMAIL PROTECTED]>
+ From: Larry Wall <[EMAIL PROTECTED]>
+ 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: <[EMAIL PROTECTED]>
+ Date: Tue, 14 Jun 2005 09:44:47 -0700 (12:44 EDT)
+ From: Larry Wall <[EMAIL PROTECTED]>
+ 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
