Author: masak
Date: 2010-04-08 23:31:08 +0200 (Thu, 08 Apr 2010)
New Revision: 30346
Modified:
docs/Perl6/Spec/S32-setting-library/Temporal.pod
Log:
[S32::Temporal] big change, based on much discussion
A number of people spent last Sunday discussing various solutions to
the Temporal module. This is the result; probably a better idea to read
the new file rather than the diff. Briefly, the Temporal you're seeing
here is a stripped-down version of CPAN's DateTime; simple, yet powerful.
Modified: docs/Perl6/Spec/S32-setting-library/Temporal.pod
===
--- docs/Perl6/Spec/S32-setting-library/Temporal.pod2010-04-08 19:28:35 UTC
(rev 30345)
+++ docs/Perl6/Spec/S32-setting-library/Temporal.pod2010-04-08 21:31:08 UTC
(rev 30346)
@@ -7,170 +7,218 @@
=head1 AUTHORS
-The authors of the related Perl 5 docs
-Rod Adams r...@rodadams.net
-Larry Wall la...@wall.org
-Aaron Sherman a...@ajs.com
-Mark Stosberg m...@summersault.com
Carl Mäsak cma...@gmail.com
-Moritz Lenz mor...@faui2k3.org
-Tim Nelson wayl...@wayland.id.au
-Daniel Ruoso dan...@ruoso.com
-Dave Rolsky auta...@urth.org
-Matthew (lue) rnd...@gmail.com
+Martin Berends mbere...@autoexec.demon.nl
+(but see FOOTNOTE at bottom)
=head1 VERSION
-Created: 19 Mar 2009 extracted from S29-functions.pod and S16-IO.pod
+Created: 19 Mar 2009
-Last Modified: 2 Apr 2010
-Version: 6
+Last Modified: 5 Apr 2010
+Version: 7
The document is a draft.
If you read the HTML version, it is generated from the Pod in the pugs
-repository under /docs/Perl6/Spec/S32-setting-library/Temporal.pod so edit it
there in
-the SVN repository if you would like to make changes.
+repository under /docs/Perl6/Spec/S32-setting-library/Temporal.pod -- if you
+would like to make changes to the document, that's the place to look.
-=head1 Temporal
+=head1 Time and time again
-Time is just a jumbled iTem.
+Two chief aspects of a Perl 6 synopsis seem to contribute to it having some
+extra volatility: how far it sits from the rest of the data model of the
+language, and how everyday the topic in question is. CS32 has always been
+volatile for these reasons; CS32::Temporal doubly so.
-Temporal is divided into two parts: date and time.
+The truth is that while there are many interests to satisfy in the case of a
+CTemporal module, and many details to take into account, there's also the
+danger of putting too much in. Therefore, Perl 6's CTemporal module takes
+the CDateTime module on CPAN as a starting point, adapts it to the Perl 6
+OO system, and boils it down to bare essentials.
-=head2 Time
+One of the unfortunate traditions that Perl 6 aims to break is that of having a
+set of core modules which could better serve the community on CPAN than in
+the Perl core. For this reason, this module doesn't handle all the world's
+time zones, locales, date formatters or calendars. Instead, it handles a number
+of natural operations well enough for most people to be happy, and shows how
+those who want more than that can load a module, or roll their own variants.
+Put differently, the below are the aspects of time that are felt to be stable
+enough to belong in the core.
-Time is called upon as such:
+=head1 Ctime
-=over
+Returns an CInstant representing the current time as measured in atomic
+second since the epoch, suitable for feeding to some of the CDateTime
+constructors.
-=item Time.new($timesystem = $*CLOCK, $time = $*NOW)
+=head1 CDateTime
-Creates a new Time object. $timesystem is what clock you wish to use. If
unspecified, whatever is in $*CLOCK is used. $time specifies the $time, it
defaults to what is in $*NOW. What you enter in $time should match the format
that $timesystem is in. $*NOW and $*CLOCK should be specified in the same
format (i.e., if $*CLOCK is 'unixepoch', $*NOW should be something like
127666216.432)
-Possible (string!) values for $timesystem (and therefore $*CLOCK) are:
+A CDateTime object describes the time as it would appear on someone's
+calendar and someone's clock. You can create a CDateTime object from the
+CInstant returned by the Ctime function:
-=over
+my $now = DateTime.from_epoch(time);
-=item * 12hour
+This is such a common use case, that there's a CDateTime.now constructor
+that does this for you:
-=item * 24hour (this and 12hour are essentialy the same system, but for
simplicity they are separate)
+my $now = DateTime.now();
-=item * hextime
+If you're interested in the current date but not the time, you can use
+the Ctoday method instead:
-=item * unixepoch
+my $today = DateTime.today();
-=item * tai
+This has the same effect as doing CDateTime.now().truncate('day'); see
+'Set methods' below.
-=back
+General dates can be specified through the Cnew constructor:
-If the time system you want is not up on the list, you are at the mercy of the
implementation
