NAME
   Time::PT - objects to store an instant in time

VERSION
   This documentation refers to version 1.2.565EHOV of Time::PT, which was
   released on Sun Jun 5 14:17:24:31 2005.

SYNOPSIS
     use Time::PT;

     my $f = Time::PT->new();

     print "PipTime is: $f\n";
     print 'The Day-of-Week today is: ', $f->dow(), "\n";

DESCRIPTION
   By default, Time::PT stores time descriptions precise to 60ths-
   of-a-second (0.016667 seconds). The groundwork has been laid for
   sub-millisecond precision to be included later.

   This module has been adapted from the Time::Piece module written by Matt
   Sergeant <[email protected]> && Jarkko Hietaniemi <[email protected]>. Time::PT
   inherits base data structure && object methods from Time::Fields. PT was
   written to simplify storage && calculation of encoded, yet distinct &&
   human-readable, time data objects.

   This module (Time::PT) does not replace the standard localtime && gmtime
   functions like Time::Piece but Time::PT objects behave almost
   identically to Time::Piece objects otherwise (since it was adapted
   from... I said that already =) ).

2DO
   - mk interoperable w/ Time::Seconds objects
   - add Time::Zone stuff to use && match zone field reasonably
   - replace legacy pt() with tested new() wrapper && fix all apps to use
   objs instead of local pt()
   - flesh out constructor init data parsing && formats supported
   - consider epoch functions like _epoch([which epoch]) or individuals
   like _jinx_epoch()
   - mk PT->new able to create from different 'epoch' init types
   - fix weird 0 month && 0 day problems
   - What else does PT need?

WHY?
   The reason I created PT was that I have grown so enamored with Base64
   representations of everything around me that I was compelled to write a
   simple clock utility ( `pt` ) using Base64. This demonstrated the
   benefit to be gained from time objects with distinct fields &&
   configurable precision. Thus, Time::Fields was written to be the
   abstract base class for:

     Time::Frame  ( creates objects which represent spans    of time )
         &&
     Time::PT     ( creates objects which represent instants in time )

 HOW?
   I've made up some silly sentences as mnemonic devices to help me
   remember every 4th uppercase Base64 character:

     Can      12   Noon       MonthOfYear will be less or equal to 'C'.
     Goats    16   4 PM
     Keep     20   8 PM
     Oats     24   Midnight   HourOfDay   will be less than        'O'.
     Some     28
     Where?   32              DayOfMonth  will be less than        'W'.

     Cool    COW (Month Hour Day thresholds)
     Guys    Girls
     Keep    Keep
     On      On                   Off
     Sayin'  Sayin'      Sippin'  Sea
     Wassup  WeeDoggies  Water    Water

USAGE
   Many of Time::PT's methods have been patterned after the excellent
   Time::Piece module written by Matt Sergeant <[email protected]> &&
   Jarkko Hietaniemi <[email protected]>.

 new(<InitType>, <InitData>)
   Time::PT's constructor can be called as a class method to create a brand
   new object or as an object method to copy an existing object. Beyond
   that, new() can initialize PT objects 3 different ways:

     * <packedB64InitStringImplies'str'>
       eg. Time::PT->new('3C79jo0');
     * 'str'  => <packedB64InitString>
       eg. Time::PT->new('str'  => '0A1B2C3D4E');
     * 'list' => <arrayRef>
       eg. Time::PT->new('list' => [0, 1, 2..9]);
     * 'hash' => <hashRef>
       eg. Time::PT->new('hash' => {'jink' => 8, 'year' => 2003})

 color(<DestinationColorTypeFormat>)
   This is an object member which will join Base64 representations of each
   field that has been specified in use() && joins them with color-codes or
   color escape sequences with formats for varied uses. Currently available
   DestinationColorTypeFormats are:

     'ANSI'  # eg. \e[1;32m
     'zsh'   # eg. %{\e[1;33m%}
     'HTML'  # eg. <a href="http://Ax9.Org/pt?"><font color="#FF1B2B">
     '4NT'   # eg. color 09 &
     'Simp'  # eg. RbobYbGbCbUbPb

 pt
   This function is the legacy procedural version of my command-line
   PipTime utility. It will be removed in the near future when the object
   methods fully replace all the old behavior && have been tested
   sufficiently.

   This function && the following ptcc() are the only functions exported
   when Time::PT is used.

 ptcc(<DestinationColorTypeFormat>)
   Returns the Simp color code string appropriate for pt (PipTime) data.

     Format   Returned color code string
      'k'     the background will change along with the foreground for standard
                time-of day elements (ie. hms on a dark blue background)
      'f'     color codes for the expanded pt format
                (eg. color codes corresponding to Sun Jan  4 12:41:48:13 2004)

   This function && the previous legacy pt() are the only functions
   exported when Time::PT is used.

   The following methods allow access to individual fields of Time::PT
   objects:

     $t->C  or  $t->century
     $t->Y  or  $t->year
     $t->M  or  $t->month
     $t->D  or  $t->day
     $t->h  or  $t->hour
     $t->m  or  $t->minute
     $t->s  or  $t->second
     $t->f  or  $t->frame
     $t->j  or  $t->jink
     $t->z  or  $t->zone

   Please see Time::Fields for further description of field accessor
   methods.

   After importing this module, when you use localtime or gmtime in a
   scalar context, you DO NOT get a special Time::PT object like you would
   when using Time::Piece. This module relies on a new() constructor
   instead. The following methods are available on Time::PT objects though
   && remain as similar to Time::Piece functionality as makes sense.

     $t->frm                 # also as $t->frame && $t->subsecond
     $t->sec                 # also available as $t->second
     $t->min                 # also available as $t->minute
     $t->hour                # 24 hour
     $t->mday                # also available as $t->day_of_month
     $t->mon                 # 1 = January
     $t->_mon                # 0 = January
     $t->monname             # Feb
     $t->month               # same as $t->mon
                    # *NOTE* The above definition ( of $t->month() ) is
                    # different from the Time::Piece interface which defines
                    # month() the same as monname() instead of mon().
     $t->fullmonth           # February
     $t->year                # based at 0 (year 0 AD is, of course 1 BC)
     $t->_year               # year minus 1900
     $t->yy                  # 2 digit year
     $t->wday                # 1 = Sunday
     $t->_wday               # 0 = Sunday
     $t->day_of_week         # 0 = Sunday
     $t->wdayname            # Tue
     $t->day                 # same as mday
                    # *NOTE* Similar to month(), I've defined day()
                    # differently from Time::Piece which makes it the same
                    # as wdayname() instead of mday().
     $t->fullday             # Tuesday
     $t->yday                # also available as $t->day_of_year, 0 = Jan 01
     $t->isdst               # also available as $t->daylight_savings

   The following functions return a list of the named fields. The return
   value can be joined with any desirable delimiter like:

     join(':', $t->hms);
     join($t->time_separator, $t->hms);

   but the functions also can take a list of parameters to update the
   corresponding named fields like:

     $t->YMD( 2003, 12, 8 ) # assigns new date of December 8th, 2003 to $t

   Following are some useful functions && comments of sample return values:

     $t->hms                 # [12, 34, 56]
     $t->hmsf                # [12, 34, 56, 12]
     $t->time                # same as $t->hmsf

     $t->ymd                 # [2000,  2, 29]
     $t->date                # same as $t->ymd
     $t->mdy                 # [ 2, 29, 2000]
     $t->dmy                 # [29,  2, 2000]
     $t->datetime            # 2000-02-29T12:34:56            (ISO 8601)
     $t->expand              # Tue Feb 29 12:34:56:12 2000
     $t->cdate               # same as $t->expand
     $t->compress            # 02TCYuC
     "$t"                    # same as $t->compress

     $t->is_leap_year        # true if it is
     $t->month_last_day      # 28-31

     $t->time_separator($s)  # set the default separator (default ":")
     $t->date_separator($s)  # set the default separator (default "-")
     $t->day_list(@days)     # set the default weekdays
     $t->mon_list(@days)     # set the default months

 Local Locales
   Both wdayname() && monname() can accept the same list parameter as
   day_list() && mon_list() respectively for temporary help with simple
   localization.

     my @days = ( 'Yom Rishone', 'Yom Shayni', 'Yom Shlishi', 'Yom Revi\'i',
                  'Yom Khahmishi', 'Yom Hashishi', 'Shabbat' );

     my $hebrew_day = pt->wdayname(@days);
                    # pt->monname() can be used similarly

   To update the global lists, use:

     Time::PT::day_list(@days);
       &&
     Time::PT::mon_list(@months);

 Calculations
   PT object strings (both in normal initialization && printing) grow
   left-to-right starting from the Year to specify whatever precision you
   need while Frame objects grow right-to-left from the frame field.

   It's possible to use simple addition and subtraction of objects:

     use Time::Frame;

     my $cur_pt       = Time::PT->new();# Dhmsf
     my $one_week     = Time::Frame->new('70000');
     my $one_week_ago = $cur_pt - $one_week;

   If a calculation is done with a raw string parameter instead of an
   instantiated object, the most likely appropriate object constructor is
   called on it. These init strings must adhere to the implied 'str' format
   for auto-creating objects; I aim to support a much wider array of
   operations && to make this module smoothly interoperate with both
   Time::Piece && Time::Seconds someday but not yet.

     my $cur_pt             = Time::PT->new();
     my $half_hour_from_now = $cur_pt + 'U00';

   The following are valid (where $t0 and $t1 are Time::PT objects && $f is
   a Time::Frame object):

     $t0 - $t1;  # returns Time::Frame object
     $t0 - '63'; # returns Time::PT object
     $t0 + $f;   # returns Time::PT object

 Comparisons
   All normal numerical && string comparisons should work reasonably on
   Time::PT objects:

     "<",  ">",  "<=", ">=", "<=>", "==" &&  "!="
     "lt", "gt", "le", "ge", "cmp", "eq" and "ne"

 YYYY-MM-DDThh:mm:ss
   The ISO 8601 standard defines the date format to be YYYY-MM-DD, and the
   time format to be hh:mm:ss (24 hour clock), and if combined, they should
   be concatenated with date first and with a capital 'T' in front of the
   time.

 Week Number
   The ISO 8601 standard specifies that weeks begin on Monday and the first
   week of the year is the one that includes both January 4th and the first
   Thursday of the year. In other words, if the first Monday of January is
   the 2nd, 3rd, or 4th, the preceding days are part of the final week of
   the prior year. Week numbers range from 1 to 53.

NOTES
   Whenever individual Time::PT attributes are going to be printed or an
   entire object can be printed with multi-colors, the following mapping
   should be employed whenever possible:

              D      Century -> DarkRed
              A      Year    -> Red
              T      Month   -> Orange
              E      Day     -> Yellow
                      hour   -> Green
               t      minute -> Cyan
               i      second -> Blue
               m      frame  -> Purple
               e      jink   -> DarkPurple
                      zone   -> Grey or White

   Please see the color() member function in the USAGE section.

   There's some weird behavior for PipTimes created with a zero month or
   day field since both are 1-based. I aim to fix all these bugs but be
   warned that this issue may be causing math errors for a bit.

   I hope you find Time::PT useful. Please feel free to e-mail me any
   suggestions || coding tips || notes of appreciation
   ("app-ree-see-ay-shun"). Thank you. TTFN.

CHANGES
   Revision history for Perl extension Time::PT:

   - 1.2.565EHOV Sun Jun 5 14:17:24:31 2005
       * updated test.pl to work properly with Build.PL as well as
       Makefile.PL

       * updated License, minor version, && precision description

   - 1.0.42M3ChX Sun Feb 22 03:12:43:33 2004
       * added 4NT option to color codes in Fields && color() members in
       Frame && PT

       * updated POD links && CHANGES chronology

   - 1.0.41M4cZH Thu Jan 22 04:38:35:17 2004
       * moved pt, fpt, && lspt into bin/ for packaging as EXE_FILES

       * added Time::Frame::total_frames method

   - 1.0.418BGcv Thu Jan 8 11:16:38:57 2004
       * moved Curses::Simp::ptCC into Time::PT::ptcc for PipTime-specific
       Simp Color Codes

       * created Time::Fields::_field_colors (centralized base class color
       codes) && updated Frame && PT _color_fields

       * added HOW? POD section for mnemonics

   - 1.0.3CVL3V4 Wed Dec 31 21:03:31:04 2003
       * changed PREREQ to not have lib files from this pkg

   - 1.0.3CQ8ibf Fri Dec 26 08:44:37:41 2003
       * fixed typo && hardcoded path in VERSION_FROM of gen'd Makefile.PL

   - 1.0.3CNNQHc Tue Dec 23 23:26:17:38 2003
       * combined Fields, Frame, && PT into one pkg

   - 1.0.3CCA2VC Fri Dec 12 10:02:31:12 2003
       * removed indenting from POD NAME section

   - 1.0.3CBIQv7 Thu Dec 11 18:26:57:07 2003
       * updated test.pl to use normal comments

   - 1.0.3CB7Vxh Thu Dec 11 07:31:59:43 2003
       * added HTML color option && prepared for release

   - 1.0.3CA8ipi Wed Dec 10 08:44:51:44 2003
       * built class to inherit from Time::Fields && mimic Time::Piece

   - 1.0.37VG26k Thu Jul 31 16:02:06:46 2003
       * original version

INSTALL
   Please run:

       `perl -MCPAN -e "install Time::PT"`

   or uncompress the package && run the standard:

       `perl Makefile.PL; make; make test; make install`

FILES
   Time::PT requires:

   Carp to allow errors to croak() from calling sub

   Math::BaseCnv to handle simple number-base conversion

   Time::DayOfWeek also stores global day && month names

   Time::DaysInMonth

   Time::Fields to provide underlying object structure

   Time::Frame to represent spans of time

   Time::PT uses (if available):

   Time::HiRes to provide subsecond time precision

   Time::Local to turn epoch seconds back into a real date

   Time::Zone not utilized yet

SEE ALSO
   Time::Frame

LICENSE
   Most source code should be Free! Code I have lawful authority over is &&
   shall be! Copyright: (c) 2002-2005, Pip Stuart. Copyleft : This software
   is licensed under the GNU General Public License (version 2). Please
   consult the Free Software Foundation (http://FSF.Org) for important
   information about your freedom.

AUTHOR
   Pip Stuart <[email protected]>

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.