File Coverage

blib/lib/Tie/Scalar/Timestamp.pm

Criterion	Covered	Total	%
statement	27	27	100.0
branch	4	6	66.6
condition	2	5	40.0
subroutine	9	9	100.0
pod			n/a
total	42	47	89.3

package Tie::Scalar::Timestamp;

use strict;
use warnings;

use base qw(Tie::Scalar);
use vars qw($VERSION $DEFAULT_STRFTIME);
use Carp;
use POSIX qw(strftime);

$VERSION = '0.01';

$DEFAULT_STRFTIME = '%Y-%m-%dT%H:%M:%S';

sub TIESCALAR {
    my $class = shift;
    my $options = shift || {};
    return bless $options, $class;
}

sub STORE {
    my $self = shift;
    # die unless asked not to (by having no_die in the tie statement)
    croak "Can't store to a Tie::Scalar::Timestamp variable" unless $self->{no_die};
    carp "Can't store to a Tie::Scalar::Timestamp variable" if $^W;
}

sub FETCH {
    my $self = shift;
    my $pattern = $self->{strftime} || $DEFAULT_STRFTIME;
    strftime $pattern, ($self->{utc} ? gmtime : localtime );
}

# module return
1;

=head1 NAME

Tie::Scalar::Timestamp - Create a scalar that always returns the current timestamp

=head1 SYNOPSIS

    # create a timestamp variable that uses localtime
    # and yyyy-mm-ddThh:mm:ss (ISO8601) format
    tie my $timestamp, 'Tie::Scalar::Timestamp';

    print "$timestamp\n";    # e.g. 2005-02-25T11:02:34
    sleep 2;                 # wait 2 seconds...
    print "$timestamp\n";    # ...  2005-02-25T11:02:36

    # this will die; $timestamp is a readonly variable
    $timestamp = '2004';

    # create a timestamp variable that returns just the time in UTC
    tie my $utc_timestamp, 'Tie::Scalar::Timestamp', { strftime => '%H:%M:%S', utc => 1 };

    # set the default format
    $Tie::Scalar::Timestamp::DEFAULT_STRFTIME = '%H:%M:%S';

=head1 DESCRIPTION

This is a B simple class that creates readonly scalars
that always return the current timestamp. By default, it uses
the format C (or, in strftime notation,
C<%Y-%m-%dT%H:%M:%S>) and local time. You can optionally pass
a hashref of options to the call to C to specify a pattern
and whether to use UTC time instead of local time.

A variables tied to this class is readonly, and attempting to
assign to it will raise an exception.

=head1 OPTIONS

The following options can be passed in a hashref to C.

=over

=item C

The strftime pattern to fromat the timestamp as. The default
pattern is C<%Y-%m-%dT%H:%M:%S>. To change the default, set
C<$Tie::Scalar::Timestamp::DEFAULT_STRFTIME> to your prefered
pattern.

=item C

Use UTC time instead of local time.

=item C

Do not throw an exception when attempting to assign to a
timestamp. This module will still emit a warning if you
have warnings enabled.

=back

=head1 SEE ALSO

L, L, L

=head1 AUTHOR

Peter Eichman, C<<  >>

=head1 COPYRIGHT AND LICENSE

Copyright E2005 by Peter Eichman.

This program is free software; you can redistribute it
and/or modify it under the same terms as Perl itself.

=cut