Re: S26 - The Next Generation
Jon Lang wrote: An unrelated possibility would be to allow empty A tags in a declarator block, with 'A' being replaced with the name of the declarator to which the block is attached: And then I think: A_ -- Ruud (indoctrinated)
Re: S26 - The Next Generation
Jon Lang elaborated:
I don't think that there will be a problem. First, #= is easy enough
to distinguish from #=; I don't foresee any confusion.
I'm not so sure. #= is a lot more like #= that =alias is. And the one
character of difference is on the non-significant (right-hand) side.
Need to think about it and role-play it a little.
With the ability to attach multiple declarator blocks to a single
declarator, it should be trivial to replace any one of them with a
declarator alias:
#=
class Foo {
#= Class Foo
#= a sample class used to illustrate.
#= This particular class has nothing in it.
}
See that's precisely my problem. I don't think the #= stands out at all
there as being an alias.
#= Class Aclass
class Foo {
#= a sample class used to illustrate.
#= This particular class has nothing in it.
#= Xthis assigns to the 'class' declarator alias.
And this illustrates my other qualm, that the two forms are just too similar.
And, yes, having the aliasing mechanism be something postfix(able) creates
issues of when the aliases come into existence.
I tend to agree. I only proposed numbering as a way of being able to
access different declarators without having to explicitly label them.
I can definitely understand if this option gets dropped as being too
error-prone with regard to maintenance.
That's my plan.
=alias
class Database::Handle {
=alias
has IO $!handle;
=alias open
my Bool method open ($filename) {...}
=alias close
my Bool method close() {...}
=for para
Note that the Aopen method of class Aclass
stores the resulting low-level database handle
in its private Ahas attribute, while the Aclose
method closes that handle.
}
The problem with this example is that '=alias name' isn't a declarator
alias; it's a block alias.
I'm proposing to change that and allow explicit names on declarator
aliases as well.
Or, rather, to unify the two into a block-or-declarator alias.
my Bool method open ($filename) {...} #=[m1] #= Here's a
block for Am1.
my Bool method close () {...} #=m2
And given that brief names are going to be preferred, this could
result in very compact, yet still readable, combinations of declarator
aliases and blocks.
Yes, this is a definite advantage of the proposal. No question.
But I'm still concerned that the two syntaxes are just so similar.
I'll continue pondering the trade-off.
Damian
Re: S26 - The Next Generation
Jon Lang huh'd: Huh. Would you be able to do something like: =begin pod Welcome to $?FILE. ...and have it interpolate the file's name? Or would you need some special markup for this, such as: =begin pod Welcome to A$?FILE. The latter. Variables are just too common in documentation to have (some of) them interpolate automagically. Or would you have to alias the variable and then refer to it? No. I envisage that A would recognize an alias starting with a sigil, and auto-alias it for you. Damian
r28208 - docs/Perl6/Spec/S32-setting-library
Author: ruoso
Date: 2009-09-09 04:26:50 +0200 (Wed, 09 Sep 2009)
New Revision: 28208
Modified:
docs/Perl6/Spec/S32-setting-library/Temporal.pod
Log:
[spec-S32-Temporal] Complete rewrite of Temporal.pod taking into account today
IRC talks, TAI time, alternative calendars, time-zone information and, most
importantly, the perl 5 DateTime API
Modified: docs/Perl6/Spec/S32-setting-library/Temporal.pod
===
--- docs/Perl6/Spec/S32-setting-library/Temporal.pod2009-09-08 16:22:13 UTC
(rev 28207)
+++ docs/Perl6/Spec/S32-setting-library/Temporal.pod2009-09-09 02:26:50 UTC
(rev 28208)
@@ -21,8 +21,8 @@
=head1 VERSION
Created: 19 Mar 2009 extracted from S29-functions.pod and S16-IO.pod
-Last Modified: 23 Feb 2009
-Version: 3
+Last Modified: 8 Sep 2009
+Version: 4
The document is a draft.
@@ -30,169 +30,216 @@
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.
-=head2 Time
+=head1 Current Time
+The epoch used in Perl 6 to represent time instants is the
+International Atomic Time - TAI - which is independent of calendars,
+timezones as well as leap seconds. Of course Perl can't go beyond the
+machine to get a real TAI value, but it should perform any
+platform-specific transformation to give you the most precise value it
+can for the TAI.
+
+ our Rat sub time()
+
+Returns a TAI epoch value for the current time.
+
+=head1 Roles
+
+=head2 Calendar
+
+Every DateTime needs to follow the rules of a given calendar. The
+default is the Gregorian calendar, but several other calendars exist
+in the real world.
+
+The current default calendar is stored in $*CALENDAR.
+
=over
-=item gmtime
+=item method calendartime($epoch = time(), *%options)
+=item multi calendartime($epoch = time(), $calendar = $*CALENDAR, *%options)
- our Temporal::DateTime multi gmtime ( Num $epoch )
- our Temporal::DateTime multi gmtime ( Rat $epoch = time() )
+Returns a DateTime object in the current calendar for the given TAI
+epoch time. Each calendar type might accept different options.
-Identical to:
+Note that simply changing the current calendar is not magically going
+to make any code portable to different calendars. The code using it
+should either use only the methods in the generic Calendar and
+DateTime roles, or special case for the known Calendars.
- Time::localtime(:$time,:tzGMT)
+=item method formatter is rw
-=item localtime
+The default formatter object used for DateTime objects in this
+calendar.
- our Temporal::DateTime multi localtime ( Num $epoch )
- our Temporal::DateTime multi localtime ( Rat $epoch = time() )
+=back
-These functions take an epoch value and return a CTemporal::DateTime
-object. For Clocaltime the time zone is taken from the local
-system. For Cgmtime the time zone is aways UTC.
+=head2 Calendar::TimeZoneObservant
-If no time is provided, the current time is used.
+This is a generic role used to identify all calendars that observe the
+time zones. Not all calendars are time-zone observants. One way or
+another, two multi subs will be available that depend on a time-zone
+observant calendar. They will fail if you try to call them with a
+non-tz calendar.
-=item time
+This role also implies that the calendartime method might receive a
+time-zone named parameter.
- our Rat time()
+=over
-Returns an epoch value for the current time.
+=item method gmtime($epoch = time(), *%options )
+=item multi gmtime($epoch = time(), $calendar = $*CALENDAR, *%options)
+Returns a DateTime object in the GMT timezone, considering $epoch to
+be TAI. Same as:
+
+ calendartime($epoch, $calendar, :time-zone('GMT'))
+
+=item method localtime($epoch = time(), *%options )
+=item multi localtime($epoch = time(), $calendar = $*CALENDAR, *%options)
+
+Returns a DateTime object in the local timezone taken from the system,
+considering $epoch to be TAI. Same as:
+
+ calendartime($epoch, $calendar, :time-zone('local'))
+
=back
-=head1 Roles
+=head2 DateTime
-The intent behind these classes is to provide an absolutely minimal,
-but still useful, set of core behavior. The assumption is that the
-core will ship with a simple set of classes so that Cgmtime and
-Clocaltime have something to return.
+The generic DateTime role specifies the basic operations that should
+be possible independent of the Calendar being used, and are,
+therefore, considerably restricted.
-=head2 Temporal::Date
+In order to make it easier to deal with the most common scenario, the
+contructor of the bare DateTime type will delegate to
+Gregorian::DateTime.
-You probably want to use the Temporal::DateTime object instead.
+It defines the following attributes.
-role Temporal::Date {
-my subset Month of Int where { 1 = $^a = 12 };
-my subset Day of Int where { 1 = $^a = 31 };
-my subset DayOfWeek of Int where { 1 = $^a = 7
r28209 - docs/Perl6/Spec/S32-setting-library
Author: ruoso
Date: 2009-09-09 04:32:41 +0200 (Wed, 09 Sep 2009)
New Revision: 28209
Modified:
docs/Perl6/Spec/S32-setting-library/Temporal.pod
Log:
[spec-S32-Temporal] minor pod fixes
Modified: docs/Perl6/Spec/S32-setting-library/Temporal.pod
===
--- docs/Perl6/Spec/S32-setting-library/Temporal.pod2009-09-09 02:26:50 UTC
(rev 28208)
+++ docs/Perl6/Spec/S32-setting-library/Temporal.pod2009-09-09 02:32:41 UTC
(rev 28209)
@@ -56,6 +56,7 @@
=over
=item method calendartime($epoch = time(), *%options)
+
=item multi calendartime($epoch = time(), $calendar = $*CALENDAR, *%options)
Returns a DateTime object in the current calendar for the given TAI
@@ -87,6 +88,7 @@
=over
=item method gmtime($epoch = time(), *%options )
+
=item multi gmtime($epoch = time(), $calendar = $*CALENDAR, *%options)
Returns a DateTime object in the GMT timezone, considering $epoch to
@@ -95,6 +97,7 @@
calendartime($epoch, $calendar, :time-zone('GMT'))
=item method localtime($epoch = time(), *%options )
+
=item multi localtime($epoch = time(), $calendar = $*CALENDAR, *%options)
Returns a DateTime object in the local timezone taken from the system,
@@ -150,6 +153,8 @@
The following method is implemented by all Duration objects.
+=over
+
=item tai
Returns the amount of TAI seconds described in this duration. Note
@@ -158,6 +163,8 @@
be an estimated value for Duration types that depend on an anchor date
(i.e.: 1 month).
+=back
+
=head2 TimeZone
This is the base for the entire time-zone database with the complete
@@ -174,7 +181,9 @@
=over
=item Start and end DateTime
+
=item Start DateTime and Duration
+
=item Duration and end DateTime
=back
r28210 - docs/Perl6/Spec/S32-setting-library
Author: ruoso Date: 2009-09-09 04:41:31 +0200 (Wed, 09 Sep 2009) New Revision: 28210 Modified: docs/Perl6/Spec/S32-setting-library/Temporal.pod Log: [spec-S32-Temporal] Gregorian::Duration doesnt have a time-zone. Modified: docs/Perl6/Spec/S32-setting-library/Temporal.pod === --- docs/Perl6/Spec/S32-setting-library/Temporal.pod2009-09-09 02:32:41 UTC (rev 28209) +++ docs/Perl6/Spec/S32-setting-library/Temporal.pod2009-09-09 02:41:31 UTC (rev 28210) @@ -244,8 +244,6 @@ =item nanosecond -=item time-zone - =back
Re: r28208 - docs/Perl6/Spec/S32-setting-library
pugs-comm...@feather.perl6.nl wrote: -=head2 Time +=head1 Current Time +The epoch used in Perl 6 to represent time instants is the +International Atomic Time - TAI - which is independent of calendars, +timezones as well as leap seconds. Of course Perl can't go beyond the +machine to get a real TAI value, but it should perform any +platform-specific transformation to give you the most precise value it +can for the TAI. + + our Rat sub time() + +Returns a TAI epoch value for the current time. Shouldn't the result type of time() be an Instant object (Instant and Duration are defined in S02) rather than a Rat? Temporal routines should always be using temporal types when talking about instants or durations, not more generic types like numbers or strings except when explicitly converting or extracting a temporal value into one of those types, such as when displaying it. -- Darren Duncan
