NAME

Time::Frame - objects to store a length of time

VERSION

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

SYNOPSIS

  use Time::Frame;
  
  my $f = Time::Frame->new('verbose' => '2 weeks');
  print 'Number of days is ', $f->day(), "\n";

DESCRIPTION

This module has been adapted from the Time::Seconds module written by Matt Sergeant <matt@sergeant.org> && Jarkko Hietaniemi <jhi@iki.fi>. Time::Frame inherits base data structure && object methods from Time::Fields. Frame was written to simplify storage && calculation of encoded, yet distinct && human-readable, time data objects.

The title of this Perl module has dual meaning. Frame means both the span of time the whole object represents as well as the (default) smallest unit of measurement.

2DO

- copy total_frames into AUTOLOAD for (in|as|total)_(CYMDhmsfj) functions which convert to any field

- better ways to specify common verbose sizes

- What else does Frame need?

WHY?

The reason I created Frame 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 )

USAGE

Many of Time::Frame's methods have been patterned after the excellent Time::Piece module written by Matt Sergeant <matt@sergeant.org> && Jarkko Hietaniemi <jhi@iki.fi>.

new(<InitType>, <InitData>)

Time::Frame'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 Frame objects in the following ways:

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

total_frames()

total_frames simply returns the total number of frames a Time::Frame object specifies.

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">
    'Simp'  # eg. RbobYbGbCbUbPb

The following methods allow access to individual fields of Time::Frame 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 a more thorough description of field accessor methods.

NOTES

Whenever individual Time::Frame 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.

I hope you find Time::Frame 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::Frame:

- 1.2.565EHOV Sun Jun 5 14:17:24:31 2005

* combined Fields, Frame, && PT into one pkg (so see PT CHANGES section for updates to Fields or Frame)

- 1.0.3CCA3bG Fri Dec 12 10:03:37:16 2003

* removed indenting from POD NAME field

- 1.0.3CB7RLu Thu Dec 11 07:27:21:56 2003

* added HTML color option && prepared for release

- 1.0.3CA8thM Wed Dec 10 08:55:43:22 2003

* built class to inherit from Time::Fields

- 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::Frame requires:

Carp to allow errors to croak() from calling sub

Math::BaseCnv to handle number-base conversion

Time::Fields to provide underlying object structure

SEE ALSO

Time::PT

LICENSE

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

AUTHOR

Pip Stuart <Pip@CPAN.Org>

cpanm Time::PT

perl -MCPAN -e shell
install Time::PT