NAME

MooseX::Timestamp - simple timestamp type for Moose

SYNOPSIS

use MooseX::Timestamp;

print timestamp;          # 2007-12-06 23:15:42
print timestamp 0;        # 1970-01-01 12:00:00
print timestamp gmtime 0; # 1970-01-01 00:00:00

use POSIX qw(strftime);
print strftime("%a", posixtime "2007-12-06 23:15"); # Thu

#...

package MyClass;
use Moose;
has 'stamp' =>
        isa => "Timestamp",
        is => "rw",
        coerce => 1;

package main;
my $obj = MyClass->new(stamp => "2007-01-02 12:00:12"); # ok
$obj->stamp("2007-01-02 12:01");
$obj->stamp("2007-01-02 12");
$obj->stamp("2007-01-02 12:00:00Gibbons");  #fail

DESCRIPTION

Tired of bulky date modules? Don't put up with them any longer.

This module provides floating dates on the Gregorian calendar without much code. It operates in (one or two particular variants of) ISO-8601 date format, and POSIX-style 6-number lists.

Note: you probably want the functions provided by MooseX::TimestampTZ most of the time, as they deal in unix epoch times.

FUNCTIONS

The following functions are available for import. If you want to import them all, use the :all import group, as below:

use MooseX::Timestamp qw(:all);

timestamp(time_t $time = time())

timestamp(@posixtime)

Converts from a POSIX-style array of time components, or an epoch time, into a Timestamp. If an epoch time is passed, the local timezone rules are used for conversion into a wallclock time. See "timestamptz" in TimestampTZ for a version which returns the time zone as well.

posixtime()

Alias for the built-in localtime

posixtime(Timestamp)

Converts a Timestamp into a POSIX-style array of time components. They are NOT guaranteed to be valid.

This accepts a similar set of input values to TimestampTZ::epoch; see its documentation ("epoch" in TimestampTZ) for a list. The defining difference is that Timestamps passed into this function MUST NOT have a time zone (or "Z") attached.

valid_posixtime(@posixtime)

This function croaks with an error if the passed POSIX-style array of time components are found to be out of range in any way. This function contains leap year rules and passes through leap seconds.

TYPES AND COERCIONS

One type is defined by this module.

Timestamp

This is a subtype of Str which conforms to the normalized form of a Timestamp.

Rules exist to coerce Str objects to this type, and are available by using the coerce => 1 flag on a Moose attribute declaration:

package Widget;
use MooseX::Timestamp;
has 'created' =>
        isa => Timestamp,
        is => "rw",
        coerce => 1;

package main;
my $widget = new Widget;
$widget->created("2007-12-07");
print $widget->created;  # 2007-12-07 00:00:00

With the above, if you set created to a value such as automatically get converted into a TimestampTZ in the current time zone.

EXPORTS

The default exporting action of this module is to export the posixtime and timestamp methods. To avoid this, pass an empty argument list to the use statement:

use MooseX::Timestamp ();

BUGS

This module is relatively slow, as conversions and calls to timegm and friends happen far too often, really - especially with coercion.

AUTHOR AND LICENSE

Sam Vilain, <samv@cpan.org>

Copyright 2007, Sam Vilain. All Rights Reserved. This program is Free Software; you may use it and/or redistribute it under the terms of Perl itself.

cpanm MooseX::Timestamp

perl -MCPAN -e shell
install MooseX::Timestamp