Author: lue Date: 2010-04-03 20:18:43 +0200 (Sat, 03 Apr 2010) New Revision: 30293
Modified: docs/Perl6/Spec/S32-setting-library/Temporal.pod Log: [P6 Spec] completely changed S32::Temporal Modified: docs/Perl6/Spec/S32-setting-library/Temporal.pod =================================================================== --- docs/Perl6/Spec/S32-setting-library/Temporal.pod 2010-04-03 13:03:58 UTC (rev 30292) +++ docs/Perl6/Spec/S32-setting-library/Temporal.pod 2010-04-03 18:18:43 UTC (rev 30293) @@ -17,12 +17,13 @@ Tim Nelson <wayl...@wayland.id.au> Daniel Ruoso <dan...@ruoso.com> Dave Rolsky <auta...@urth.org> + Matthew (lue) <rnd...@gmail.com> =head1 VERSION Created: 19 Mar 2009 extracted from S29-functions.pod and S16-IO.pod - Last Modified: 18 Feb 2010 + Last Modified: 2 Apr 2010 Version: 6 The document is a draft. @@ -31,224 +32,144 @@ 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. -=head1 Roles +=head1 Temporal -=head2 Instant +Time is just a jumbled iTem. -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. +Temporal is divided into two parts: date and time. - our Instant sub time() +=head2 Time -Returns a TAI epoch value for the current time. +Time is called upon as such: -=head2 Duration - -Duration objects describe an amount of time, it's the fundamental type -for time math. The base Duration object is only TAI-seconds aware, but -if you use its constructor with any other parameters it will delegate -to Gregorian::Duration in order to make the most common cases easier. - -The following attribute is declared: - =over -=item tai +=item Time.new($timesystem = $*CLOCK, $time = $*NOW) -Returns the amount of TAI seconds described in this duration. Note -that usually you shouldn't be doing math with the result of .tai for -different datetime and duration objects. The result of .tai might also -be an estimated value for Duration types that depend on an anchor date -(i.e.: 1 month). +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: -=back - -=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 method calendartime($epoch = time(), *%options) +=item * 12hour -=item multi calendartime($epoch = time(), $calendar = $*CALENDAR, *%options) +=item * 24hour (this and 12hour are essentialy the same system, but for simplicity they are separate) -Returns a DateTime object in the current calendar for the given TAI -epoch time. Each calendar type might accept different options. +=item * hextime -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. +=item * unixepoch -=item method formatter is rw +=item * tai -The default formatter object used for DateTime objects in this -calendar. - =back -=head2 Calendar::TimeZoneObservant +If the time system you want is not up on the list, you are at the mercy of the implementation (which can, of course, add in rarer time systems) and/or available libraries and other addons. A shortcut to the time (in the default as defined by $*CLOCK) is through the $*TIME variable. -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.convert($convertto = $*CLOCK) -This role also implies that the calendartime method might receive a -time-zone named parameter. +returns the time converted to the time system specified in $convertto. If you were to call convert(), then it would default to what's in $*CLOCK -=over +=item Time.format($formatto) -=item method gmtime($epoch = time(), *%options ) +returns the time formatted to the way specified in $formatto. If the time has no options for formatting (for example hextime can be either 3_A0_9 or .3A09, but a 24 hour clock is typically only formatted as 15:17), or $formatto is left blank, it is sent back without processing. -=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 -=head2 DateTime +=head2 Date -The generic DateTime role specifies the basic operations that should -be possible independent of the Calendar being used, and are, -therefore, considerably restricted. +Date is called in a similar fashion: -In order to make it easier to deal with the most common scenario, the -constructor of the bare DateTime type will delegate to -Gregorian::DateTime. - -It defines the following attributes. - =over -=item formatter +=item Date.new($datesystem = $*CALENDAR, $date = $*TODAY) -The object that will stringify this specific object. +Defines a new Date object. $datesystem defines the calendar to use. If not specified, it defaults to what is in $*CALENDAR. $date specifies the date. If not specified, then the date used is the one in $*TODAY. Make sure $date is in the same format as specified in $datesystem. $*CALENDAR and $*TODAY should be specified in the same calendar (i.e. if $*CALENDAR is 'Gregorian' $*TODAY should be something like '12-31-10', depending on how things are formatted) +Possible string values for $datesystem (and therefore $*CALENDAR) are: -=item calendar - -Returns the calendar that governs this datetime. - -=back - -And the following methods - =over -=item tai +=item * Gregorian -Returns the TAI value for this specific datetime, useful for -inter-calendar comparison and conversion. +=item * Julian (the predecessor of Gregorian. NOT the astronomical Julian Year) +=item * Discordian + =back -=head2 TimeZone +There aren't that many calendar in use today (heck, Discordian is up there only because you can get it using ddate, a command found on almost every Linux distribution). If you need something different from what is on the list, you are at the mercy of the implementation and any available libraries/modules. You can shortcut to the current date in the default calendar (in $*CALENDAR), by using the $*DATE variable. -This is the base for the entire time-zone database with the complete -information about daylight-saving-time and other variations that can -happen. +=item Date.convert($convertto = $*CALENDAR) -This should be a straight port from perl 5 DateTime::TimeZone module. +Returns the date in the format specified in $convertto (defaults to what's in $*CALENDAR) -=head2 TimeRange +=item Date.format($formatto) -This object represents a given period of time, and may exclude either endpoint. -It might be composed by: +Formats the date (i.e. 4/2/10 or 2 April 2010 in Gregorian) to what's specified in $formatto. If unspecified, it returns the date without any processing. - $datetime1 .. $datetime2 - $datetime1 ^.. $datetime2 - $datetime1 ..^ $datetime2 +=back -These may be iterated, but only on seconds. To iterate with some -other duration, you may use the series operator to produce a series -of datetimes: +=head2 Duration - $datetime1, *+$duration ... $datetime2 +A duration is a certain length of time (i.e. from 12:00 to 14:15, the duration can be said to be 2:15). -=head2 Gregorian::Calendar +=over -Also known as the "civil" calendar. This is the calendar used in most -of the world, specially in the western countries. +=item Duration.new($begin = 0, $end, $format) -=head2 Gregorian::DateTime +Specifies a new Duration object. $begin is at the beginning of duration (i.e. 4 seconds), $end is the end of the duration (i.e. 72 seconds), and $format is in what format $begin and $end are in. $format can be anything that either $*CLOCK or $*CALENDAR can be. -The gregorian DateTime declares the following additional attributes. +=item Duration.convert($convertto) -=over +returns the Duration in the format as specified by $convertto. It defaults to doing nothing. -=item year +=item Duration.format($formatto) -=item month +Returns the Duration formatted as specified in $formatto. If the time given cannot be formatted (i.e. 13:47, which has no common alternative format), it returns the duration as it was entered. -=item day +=back -=item minute +=head2 Arithmetic -=item second +Any sort of arithmetic between Time, Date, and Duration objects require these objects to give the equivalent of that object's data (13:15 or 3/4/10) in TAI seconds first. What's returned is a Duration object, because it can be formatted however you wish using Duration's convert and format. -=item nanosecond +=head2 Specifics on formats -=item time-zone +Whenever a date/time format is added/removed to/from the spec, please update this listing. This listing describes how each date/time format stores information, and available formatting. -=back +Formatting options are those used in the unix utility date (search for Date_(Unix) on wikipedia for the formatting options), mapped to the current date/time as best as possible. -The following methods provide additional information - =over -=item week-of-year +=item Twelve Hour -=item day-of-week +The twelve-hour format should store the data as an array, containing the hour, minute, second, AM/PM, and if the interpreter chooses, parts less than a second. The only format it can be in is 12:31:07 AM) -=item week-of-month +=item Twenty-Four Hour -=item year-of-week +The twenty-four-hour format is the same as 12 Hour, except for the the fact that AM/PM is not needed. -=back +=item Hextime -=head2 Gregorian::Duration +Hextime should be stored as an array of strings, consisting of the hexhour, hexminute, and hexsecond (alternatively, it could also be held as a hex hour, hex maxime, hex minute, and hex second). The time can be formatted either as .3A02 or 3_A0_2 (if stored as maxime & hexminute, they must combine as one. i.e in 3_A0_2, A is the maxime, and 0 is the hexminute. If stored as hex-hour/minute/second, then A0 is the minute.) -The gregorian Duration declares the following attributes. +=item Unix Epoch & TAI -=over +Both are stored as a # of seconds, and only shown/formatted as such. -=item year +=item Gregorian -=item month +Gregorian ought to be stored in an array as the day, month, and year, along with the name of the day. Year can either be a +/- number, or you can add another element for AD and BC. It can be formatted in any myriad of ways, including: "Sunday, April 4th, 2010", or "4/2/10". -=item day +=item Julian -=item minute +Same as Gregorian in terms of storage and formatting. (Just remember that Julian != Gregorian) -=item second +=item Discordian -=item nanosecond +Stored in an array as the year, the season, and the day of the season. Formatting is similar to Gregorian & Julian (see the man page for ddate for a list of Discordian format options) =back - =head1 Additions Please post errors and feedback to perl6-language. If you are making