Joshua Hoblitt > DateTime-TimeZone-Alias-0.06 > DateTime::TimeZone::Alias

Download:
DateTime-TimeZone-Alias-0.06.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.06   Source  

NAME ^

DateTime::TimeZone::Alias - Create aliases for DateTime timezones

SYNOPSIS ^

    use DateTime::TimeZone::Alias Hawaii => 'Pacific/Honolulu',
                                  EST => 'Australia/Melbourne';

    or

    DateTime::TimeZone::Alias->add( Fun => 'America/Tijuana', %hash );

    or

    DateTime::TimeZone::Alias->set( Pain => 'America/Dawson_Creek', %hash );
    DateTime::TimeZone::Alias->set( boat => 'floating' );
    DateTime::TimeZone::Alias->set( home => 'local' );
    DateTime::TimeZone::Alias->set( lulu => 'Z' );
    DateTime::TimeZone::Alias->set( cut => 'UTC' );
    DateTime::TimeZone::Alias->set( nowhere => '-09:30' );

    or

    DateTime::TimeZone::Alias->remove( qw( Hawaii EST Pain Fun ) );

    or

    DateTime::TimeZone::Alias->value( 'EST' );

    or

    DateTime::TimeZone::Alias->is_defined( 'Hawaii' )
    DateTime::TimeZone::Alias->is_alias( 'EST' )
    DateTime::TimeZone::Alias->is_timezone( 'Antarctica/Vostok' )

    or

    DateTime::TimeZone::Alias->aliases
    DateTime::TimeZone::Alias->timezones

DESCRIPTION ^

Creates and destroys aliases for DateTime timezones. This module violates the encapsulation of the DateTime internals. User _Beware_.

IMPORT PARAMETERS ^

Accepts a hash representing an alias and the timezone it should map too. Import has the exact same behaviors as the set method.

METHODS ^

GOTCHAS ^

Import

Multiple use DateTime::TimeZone::Alias statements in the same package may not have the desired result if attempting to redefine existing aliases. If you want to redefine an alias use the set method instead.

Aliasing

You can _not_ create circular aliases. E.g.

    # TSH actually points to value of HST - 'Pacific/Honolulu'
    # if HST wasn't already defined this would be an exception
    DateTime::TimeZone::Alias->set( TSH => HST );

    # HST still points to 'Pacific/Honolulu'
    DateTime::TimeZone::Alias->set( HST => TSH );

Sorry - no evil here, move along.

Global Behavior

It's important to remember that aliases are global in scope. E.g.

    package Foo;

    DateTime::TimeZone::Alias->set( EST => 'US/Eastern' );

    Bar->bar();

    # this will fail because EST is no longer defined
    my $dt = DateTime->now( time_zone => 'EST' );

    package Bar;

    sub bar {
        DateTime::TimeZone::Alias->set( EST => 'US/Eastern' );
        .
        .

        DateTime::TimeZone::Alias->remove( qw( EST ) );
    }

There are many possible ways to avoid this trap. The best solution is to simply not write code like this. If you insist on this style then you can try one of the suggested work arounds.

Poor Man's DateTime::TimeZone::Alias

Sometimes DateTime::TimeZone::Alias may not be the best solution to your problem. Particularly if your in an environment that has poor sand-boxing such as mod_perl. E.g.

    use constant EST => 'US/Eastern';

    or

    sub EST () { 'US/Eastern' }
    .
    .

    my $dt = DateTime->new( %params, time_zone => EST );

store/restore

This probably isn't thread safe. E.g.

    sub bar {
        my $my_alias = DateTime::TimeZone::Alias->value( 'EST' );
        DateTime::TimeZone::Alias->set( EST => 'US/Eastern' );
        .
        .

        DateTime::TimeZone::Alias->set( EST => $my_alias );
    }

If $my_alias is undefined then the set will fail as an alias must point to a valid timezone.

DEVELOPER NOTES ^

The aliases and timezones methods preserve encapsulation by returning a reference to a copy of the internal data structures instead of a direct reference.

CREDITS ^

Ben Bennett (BBENNETT) for a bug report, some API suggestions, documentation suggestions, and being so darn enthusiastic. (not necessary in that order)

Everyone at the DateTime Asylum.

SUPPORT ^

Support for this module is provided via the datetime@perl.org email list. See http://lists.perl.org/ for more details.

AUTHOR ^

Joshua Hoblitt <jhoblitt@cpan.org>

COPYRIGHT ^

Copyright (c) 2003-2010 Joshua Hoblitt. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.

SEE ALSO ^

datetime@perl.org mailing list

http://datetime.perl.org/

syntax highlighting: