.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "DateTime::TimeZone::Alias 3"
.TH DateTime::TimeZone::Alias 3 "2008-01-07" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
DateTime::TimeZone::Alias \- Create aliases for DateTime timezones
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&    use DateTime::TimeZone::Alias Hawaii => 'Pacific/Honolulu',
\&                                  EST => 'Australia/Melbourne';
.Ve
.PP
.Vb 1
\&    or
.Ve
.PP
.Vb 1
\&    DateTime::TimeZone::Alias->add( Fun => 'America/Tijuana', %hash );
.Ve
.PP
.Vb 1
\&    or
.Ve
.PP
.Vb 6
\&    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' );
.Ve
.PP
.Vb 1
\&    or
.Ve
.PP
.Vb 1
\&    DateTime::TimeZone::Alias->remove( qw( Hawaii EST Pain Fun ) );
.Ve
.PP
.Vb 1
\&    or
.Ve
.PP
.Vb 1
\&    DateTime::TimeZone::Alias->value( 'EST' );
.Ve
.PP
.Vb 1
\&    or
.Ve
.PP
.Vb 3
\&    DateTime::TimeZone::Alias->is_defined( 'Hawaii' )
\&    DateTime::TimeZone::Alias->is_alias( 'EST' )
\&    DateTime::TimeZone::Alias->is_timezone( 'Antarctica/Vostok' )
.Ve
.PP
.Vb 1
\&    or
.Ve
.PP
.Vb 2
\&    DateTime::TimeZone::Alias->aliases
\&    DateTime::TimeZone::Alias->timezones
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Creates and destroys aliases for DateTime timezones.  This module violates 
the encapsulation of the DateTime internals.  User _Beware_.
.SH "IMPORT PARAMETERS"
.IX Header "IMPORT PARAMETERS"
Accepts a hash representing an alias and the timezone it should map too.
Import has the exact same behaviors as the \f(CW\*(C`set\*(C'\fR method.
.SH "METHODS"
.IX Header "METHODS"
.IP "* set( alias => timezone, ... )" 4
.IX Item "set( alias => timezone, ... )"
Accepts a hash representing an alias and the timezone it should map too.
If an invalid timezone value or no parameters are passed an exception is thrown.
It is possible to create an alias to another alias.  This method will
redefine an existing alias or add a new alias that overrides an existing
timezone.
.Sp
What may be aliased:
.Sp
.Vb 7
\&    aliases
\&    floating
\&    local
\&    OffsetOnly
\&    Olson time zones
\&    UTC
\&    Z
.Ve
.IP "* add( alias => timezone, ... )" 4
.IX Item "add( alias => timezone, ... )"
Accepts a hash representing an alias and the timezone it should map too.
If an invalid timezone value or no parameters are passed an exception is thrown.
It is possible to create an alias to another alias.
This method will _not_ redefine an existing alias or allow you remap a
timezone.  For redefinitions see the \f(CW\*(C`set\*(C'\fR method.
.IP "* remove( alias, ... )" 4
.IX Item "remove( alias, ... )"
Accepts a list of aliases to be removed.  If an the name of an aliases that
doesn't exist is passed in then an exception is thrown.  It's important to 
note that you can remove aliases but not timezones.  However, a redefined timezone
is actually an alias and can be removed.
.ie n .IP "* value( $str )" 4
.el .IP "* value( \f(CW$str\fR )" 4
.IX Item "value( $str )"
If \f(CW$str\fR is a known alias then the timezone being aliased is returned, otherwise undef.
.ie n .IP "* is_defined( $str )" 4
.el .IP "* is_defined( \f(CW$str\fR )" 4
.IX Item "is_defined( $str )"
If \f(CW$str\fR is a known timezone or alias this method returns 1, otherwise undef is returned. 
.ie n .IP "* is_alias( $str )" 4
.el .IP "* is_alias( \f(CW$str\fR )" 4
.IX Item "is_alias( $str )"
If \f(CW$str\fR is a known alias this method returns 1, otherwise undef is returned. 
.ie n .IP "* is_timezone( $str )" 4
.el .IP "* is_timezone( \f(CW$str\fR )" 4
.IX Item "is_timezone( $str )"
If \f(CW$str\fR is a known timezone this method returns 1, otherwise undef is returned. 
.IP "* aliases" 4
.IX Item "aliases"
In list context a hash of all known aliases and their values is returned.
In scalar context a reference to a hash is returned.
.IP "* timezones" 4
.IX Item "timezones"
In list context an array of all known timezones is returned.
In scalar context a reference to an array is returned.
.SH "GOTCHAS"
.IX Header "GOTCHAS"
.Sh "Import"
.IX Subsection "Import"
Multiple \f(CW\*(C`use DateTime::TimeZone::Alias\*(C'\fR 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 \f(CW\*(C`set\*(C'\fR method instead.
.Sh "Aliasing"
.IX Subsection "Aliasing"
You can _not_ create circular aliases.  E.g.
.PP
.Vb 3
\&    # 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 );
.Ve
.PP
.Vb 2
\&    # HST still points to 'Pacific/Honolulu'
\&    DateTime::TimeZone::Alias->set( HST => TSH );
.Ve
.PP
Sorry \- no evil here, move along.
.Sh "Global Behavior"
.IX Subsection "Global Behavior"
It's important to remember that aliases are global in scope. E.g.
.PP
.Vb 1
\&    package Foo;
.Ve
.PP
.Vb 1
\&    DateTime::TimeZone::Alias->set( EST => 'US/Eastern' );
.Ve
.PP
.Vb 1
\&    Bar->bar();
.Ve
.PP
.Vb 2
\&    # this will fail because EST is no longer defined
\&    my $dt = DateTime->now( time_zone => 'EST' );
.Ve
.PP
.Vb 1
\&    package Bar;
.Ve
.PP
.Vb 4
\&    sub bar {
\&        DateTime::TimeZone::Alias->set( EST => 'US/Eastern' );
\&        .
\&        .
.Ve
.PP
.Vb 2
\&        DateTime::TimeZone::Alias->remove( qw( EST ) );
\&    }
.Ve
.PP
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.
.PP
\fIPoor Man's DateTime::TimeZone::Alias\fR
.IX Subsection "Poor Man's DateTime::TimeZone::Alias"
.PP
Sometimes DateTime::TimeZone::Alias may not be the best solution to your
problem.  Particularly if your in an environment that has poor \f(CW\*(C`sand\-boxing\*(C'\fR
such as \f(CW\*(C`mod_perl\*(C'\fR.  E.g.
.PP
.Vb 1
\&    use constant EST => 'US/Eastern';
.Ve
.PP
.Vb 1
\&    or
.Ve
.PP
.Vb 3
\&    sub EST () { 'US/Eastern' }
\&    .
\&    .
.Ve
.PP
.Vb 1
\&    my $dt = DateTime->new( %params, time_zone => EST );
.Ve
.PP
\fIstore/restore\fR
.IX Subsection "store/restore"
.PP
This probably isn't thread safe.  E.g.
.PP
.Vb 5
\&    sub bar {
\&        my $my_alias = DateTime::TimeZone::Alias->value( 'EST' );
\&        DateTime::TimeZone::Alias->set( EST => 'US/Eastern' );
\&        .
\&        .
.Ve
.PP
.Vb 2
\&        DateTime::TimeZone::Alias->set( EST => $my_alias );
\&    }
.Ve
.PP
If \f(CW$my_alias\fR is undefined then the \f(CW\*(C`set\*(C'\fR will fail as an alias must point to a
valid timezone.
.SH "DEVELOPER NOTES"
.IX Header "DEVELOPER NOTES"
The \f(CW\*(C`aliases\*(C'\fR and \f(CW\*(C`timezones\*(C'\fR methods preserve encapsulation by returning a
reference to a copy of the internal data structures instead of a direct
reference.
.SH "CREDITS"
.IX Header "CREDITS"
Ben Bennett (\s-1BBENNETT\s0) for a bug report, some \s-1API\s0 suggestions,
documentation suggestions, and being so darn enthusiastic.
(not necessary in that order)
.PP
Everyone at the DateTime \f(CW\*(C`Asylum\*(C'\fR.
.SH "SUPPORT"
.IX Header "SUPPORT"
Support for this module is provided via the datetime@perl.org email
list. See http://lists.perl.org/ for more details.
.SH "AUTHOR"
.IX Header "AUTHOR"
Joshua Hoblitt <jhoblitt@cpan.org>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 2003 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.
.PP
The full text of the license can be found in the \s-1LICENSE\s0 file included
with this module.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
datetime@perl.org mailing list
.PP
http://datetime.perl.org/