VERSION
    Version 0.01

SYNOPSIS
        use Time::Zone::Olson();

        my $time_zone = Time::Zone::Olson->new({ timezone => 'Australia/Melbourne' }); # set timezone at creation time
        my $now = $time_zone->time_local($seconds, $minutes, $hours, $day, $month, $year); # convert from Australia/Melbourne time
        foreach my $area (Time::Zone::Olson->areas()) {
            foreach my $location (Time::Zone::Olson->locations($area)) {
                $time_zone->timezone("$area/$location");
                print scalar $time_zone->local_time($now); # output time in $area/$location local time
                warn scalar localtime($now) . " log message for sysadmin"; # but log in system local time
            }
        }

DESCRIPTION
    Time::Zone::Olson is intended to provide a simple but well tested
    interface to the Olson database that is available on most UNIX systems.
    It provides an interface to list common time zones, such as
    Australia/Melbourne that are stored in the zone.tab file, and
    localtime/Time::Local::timelocal replacements to translate times to and
    from the users timezone, without changing the timezone used by Perl.
    This allows logging/etc to be conducted in the system's local time.

    Time::Zone::Olson was designed to produce the same result as a 64bit
    copy of the date(1) command.

SUBROUTINES/METHODS
  new
    Time::Zone::Olson->new() will return a new timezone object. It accepts a
    hash reference as a parameter with an optional `timezone' key, which
    contains an Olson timezone value, such as 'Australia/Melbourne'. The
    hash reference also allows a `directory' key, with the file system
    location of the Olson timezone database as a value.

    Both of these parameters default to `$ENV{TZ}' and `$ENV{TZDIR}'
    respectively.

  areas
    Time::Zone::Olson->areas() will return a list of the areas (such as
    Asia, Australia, Africa, America, Europe) from the zone.tab file. The
    areas will be sorted alphabetically.

  locations
    Time::Zone::Olson->locations($area) will return a list of the locations
    (such as Melbourne, Perth, Hobart) for a specified area from the
    zone.tab file. The locations will be sorted alphabetically.

  comment
    Time::Zone::Olson->comment($timezone) will return the matching comment
    from the zone.tab file for the timezone parameter. For example, if
    `"Australia/Melbourne"' was passed as a parameter, the comment function
    would return `"Victoria"'

  directory
    This object method can be used to get or set the root directory of the
    Olson database, usually located at /usr/share/zoneinfo.

  timezone
    This object method can be used to get or set the timezone, which will
    affect all future calls to local_time or time_local. The parameter for
    this method should be in the Olson format of a timezone, such as
    `"Australia/Melbourne"'.

  local_time
    This object method has the same signature as the 64 bit version of the
    `localtime' function. That is, it accepts up to a 64 bit signed integer
    as the sole argument and returns the `(seconds, minutes, hours, day,
    month, year, wday, yday, isdst)' definition for the timezone for the
    object. The timezone used to calculate the local_time may be specified
    as a parameter to the new method or via the timezone method.

  time_local
    This object method has the same signature as the 64 bit version of the
    `Time::Local::timelocal' function. That is, it accepts `(seconds,
    minutes, hours, day, month, year, wday, yday, isdst)' as parameters in a
    list and returns the correct UNIX time in seconds according to the
    current timezone for the object. The timezone used to calculate the
    local_time may be specified as a parameter to the new method or via the
    timezone method. It may not return the same values as
    Time::Local::timelocal though, especially during timezone changes.

  transition_times
    This object method can be used to get the list of transition times for
    the current timezone. This method is only intended for testing the
    results of Time::Zone::Olson.

  leap_seconds
    This object method can be used to get the list of leap seconds for the
    current timezone. This method is only intended for testing the results
    of Time::Zone::Olson.

DIAGNOSTICS
    `%s is not a TZ file'
        The designated path did not have the `TZif' prefix at the start of
        the file. Maybe either the directory or the timezone name is
        incorrect?

    `Failed to read header from %s:%s'
        The designated file encountered an error reading either the V1 or V2
        headers

    `Failed to read entire header from %s. %d bytes were read instead of the
    expected %d'
        The designated file is shorter than expected

    `%s is not an timezone in the existing Olson database'
        The designated timezone could not be found on the file system. The
        timezone is expected to be in the designated directory + the
        timezone name, for example, /usr/share/zoneinfo/Australia/Melbourne

    `%s does not have a valid format for a TZ timezone'
        The designated timezone name could not be matched by the regular
        expression for a timezone in Time::Zone::Olson

    `Failed to close %s:%s'
        There has been a file system error while reading or closing the
        designated path

    `Failed to open %s for reading:%s'
        There has been a file system error while opening the the designated
        path. This could be permissions related, or the timezone in question
        doesn't exist?

    `Failed to read %s from %s:%s'
        There has been a file system error while reading from the designated
        path. The file could be corrupt?

    `Failed to read all the %s from %s. %d bytes were read instead of the
    expected %d'
        The designated file is shorter than expected. The file could be
        corrupt?

    `The tz defintion at the end of %s could not be read in %d bytes'
        The designated file is longer than expected. Maybe the timezone
        version is greater than the currently recognized 3?

    `Failed to read tz definition from %s:%'
        There has been a file system error while reading from the designated
        path. The file could be corrupt?

    `Failed to parse the tz defintion of %s from %s'
        This is probably a bug in Time::Zone::Olson in failing to parse the
        `TZ' variable at the end of the file.

CONFIGURATION AND ENVIRONMENT
    Time::Zone::Olson requires no configuration files or environment
    variables. However, it will use the values of `$ENV{TZ}' and
    `$ENV{TZDIR}' as defaults for missing parameters.

DEPENDENCIES
    Time::Zone::Olson requires Perl 5.10 or better. For environments where
    the unpack 'q' parameter is not supported, the following module is also
    required

    * Math::Int64

INCOMPATIBILITIES
    None reported

BUGS AND LIMITATIONS
    Please report any bugs or feature requests to `bug-time-zone-olson at
    rt.cpan.org', or through the web interface at
    http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Time-Zone-Olson. I will
    be notified, and then you'll automatically be notified of progress on
    your bug as I make changes.

SEE ALSO
    * DateTime::TimeZone
    * DateTime::TimeZone::Tzfile

AUTHOR
    David Dick, `<ddick at cpan.org>'

LICENSE AND COPYRIGHT
    Copyright 2015 David Dick.

    This program is free software; you can redistribute it and/or modify it
    under the terms of either: the GNU General Public License as published
    by the Free Software Foundation; or the Artistic License.

    See http://dev.perl.org/licenses/ for more information.

