Provided by: libtime-olsontz-download-perl_0.004-1_all bug

NAME

       Time::OlsonTZ::Download - Olson timezone database from source

SYNOPSIS

               use Time::OlsonTZ::Download;

               $version = Time::OlsonTZ::Download->latest_version;

               $download = Time::OlsonTZ::Download->new;

               $version = $download->version;
               $version = $download->code_version;
               $version = $download->data_version;
               $dir = $download->dir;
               $dir = $download->unpacked_dir;

               $names = $download->canonical_names;
               $names = $download->link_names;
               $names = $download->all_names;
               $links = $download->raw_links;
               $links = $download->threaded_links;
               $countries = $download->country_selection;

               $files = $download->data_files;
               $zic = $download->zic_exe;
               $dir = $download->zoneinfo_dir;

DESCRIPTION

       An object of this class represents a local copy of the source of the Olson timezone
       database, possibly used to build binary tzfiles.  The source copy always begins by being
       downloaded from the canonical repository of the Olson database.  This class provides
       methods to help with extracting useful information from the source.

CLASS METHODS

       Time::OlsonTZ::Download->latest_version
           Returns the version number of the latest available version of the Olson timezone
           database.  This requires consulting the repository, but is much cheaper than actually
           downloading the database.

CONSTRUCTORS

       Time::OlsonTZ::Download->new([VERSION])
           Downloads a copy of the source of the Olson database, and returns an object
           representing that copy.

           VERSION, if supplied, is a version number specifying which version of the database is
           to be downloaded.  If not supplied, the latest available version will be downloaded.
           Version numbers for the Olson database currently consist of a year number and a
           lowercase letter, such as ""2010k"".  Availability of versions other than the latest
           is limited: until 2011 there was no official archive, so this module is at the mercy
           of historical mirror administrators' whims.

       Time::OlsonTZ::Download->new_from_local_source(ATTR => VALUE)
           Acquires Olson database source locally, without downloading, and returns an object
           representing a copy of it ready to use like a download.  This can be used to work with
           locally-modified versions of the database.  The following attributes may be given:

           source_dir
               Local directory containing Olson source files.  Must be supplied.  The entire
               directory will be copied into a temporary location to be worked on.

           version
               Olson version number to attribute to the source files.  Must be supplied.

           code_version
           data_version
               Olson version number to attribute to the code and data parts of the source files.
               Both default to the main version number.

METHODS

   Basic information
       $download->version
           Returns the version number of the database of which a copy is represented by this
           object.

           The database consists of code and data parts which are updated semi-independently.
           The latest version of the database as a whole consists of the latest version of the
           code and the latest version of the data.  If both parts are updated at once then they
           will both get the same version number, and that will be the version number of the
           database as a whole.  However, in general they may be updated at different times, and
           a single version of the database may be made up of code and data parts that have
           different version numbers.  The version number of the database as a whole will then be
           the version number of the most recently updated part.

       $download->code_version
           Returns the version number of the code part of the database of which a copy is
           represented by this object.

       $download->data_version
           Returns the version number of the data part of the database of which a copy is
           represented by this object.

       $download->dir
           Returns the pathname of the directory in which the files of this download are located.
           With this method, there is no guarantee of particular files being available in the
           directory; see other directory-related methods below that establish particular
           directory contents.

           The directory does not move during the lifetime of the download object: this method
           will always return the same pathname.  The directory and all of its contents,
           including subdirectories, will be automatically deleted when this object is destroyed.
           This will be when the main program terminates, if it is not otherwise destroyed.  Any
           files that it is desired to keep must be copied to a permanent location.

       $download->unpacked_dir
           Returns the pathname of the directory in which the downloaded source files have been
           unpacked.  This is the local temporary directory used by this download.  This method
           will unpack the files there if they have not already been unpacked.

   Zone metadata
       $download->canonical_names
           Returns the set of timezone names that this version of the database defines as
           canonical.  These are the timezone names that are directly associated with a set of
           observance data.  The return value is a reference to a hash, in which the keys are the
           canonical timezone names and the values are all "undef".

       $download->link_names
           Returns the set of timezone names that this version of the database defines as links.
           These are the timezone names that are aliases for other names.  The return value is a
           reference to a hash, in which the keys are the link timezone names and the values are
           all "undef".

       $download->all_names
           Returns the set of timezone names that this version of the database defines.  These
           are the "canonical_names" and the "link_names".  The return value is a reference to a
           hash, in which the keys are the timezone names and the values are all "undef".

       $download->raw_links
           Returns details of the timezone name links in this version of the database.  Each link
           defines one timezone name as an alias for some other timezone name.  The return value
           is a reference to a hash, in which the keys are the aliases and each value is the
           preferred timezone name to which that alias directly refers.  It is possible for an
           alias to point to another alias, or to point to a non-existent name.  For a more
           processed view of links, see "threaded_links".

       $download->threaded_links
           Returns details of the timezone name links in this version of the database.  Each link
           defines one timezone name as an alias for some other timezone name.  The return value
           is a reference to a hash, in which the keys are the aliases and each value is the
           canonical name of the timezone to which that alias refers.  All such canonical names
           can be found in the "canonical_names" hash.

       $download->country_selection
           Returns information about how timezones relate to countries, intended to aid humans in
           selecting a geographical timezone.  This information is derived from the "zone.tab"
           and "iso3166.tab" files in the database source.

           The return value is a reference to a hash, keyed by (ISO 3166 alpha-2 uppercase)
           country code.  The value for each country is a hash containing these values:

           alpha2_code
               The ISO 3166 alpha-2 uppercase country code.

           olson_name
               An English name for the country, possibly in a modified form, optimised to help
               humans find the right entry in alphabetical lists.  This is not necessarily
               identical to the country's standard short or long name.  (For other forms of the
               name, consult a database of countries, keying by the country code.)

           regions
               Information about the regions of the country that use distinct timezones.  This is
               a hash, keyed by English description of the region.  The description is empty if
               there is only one region.  The value for each region is a hash containing these
               values:

               olson_description
                   Brief English description of the region, used to distinguish between the
                   regions of a single country.  Empty string if the country has only one region
                   for timezone purposes.  (This is the same string used as the key in the
                   regions hash.)

               timezone_name
                   Name of the Olson timezone used in this region.  This is not necessarily a
                   canonical name (it may be a link).  Typically, where there are aliases or
                   identical canonical zones, a name is chosen that refers to a location in the
                   country of interest.  It is not guaranteed that the named timezone exists in
                   the database (though it always should).

               location_coords
                   Geographical coordinates of some point within the location referred to in the
                   timezone name.  This is a latitude and longitude, in ISO 6709 format.

           This data structure is intended to help a human select the appropriate timezone based
           on political geography, specifically working from a selection of country.  It is of
           essentially no use for any other purpose.  It is not strictly guaranteed that every
           geographical timezone in the database is listed somewhere in this structure, so it is
           of limited use in providing information about an already-selected timezone.  It does
           not include non-geographic timezones at all.  It also does not claim to be a
           comprehensive list of countries, and does not make any claims regarding the political
           status of any entity listed: the "country" classification is loose, and used only for
           identification purposes.

   Compiling zone data
       $download->data_files
           Returns a reference to an array containing the pathnames of all the source data files
           in the database.  These are located in the local temporary directory used by this
           download.

           There is approximately one source data file per continent.  Each data file, in a
           human-editable textual format, describes the known civil timezones used on the file's
           continent.  The textual format is not standardised, and is peculiar to the Olson
           database, so parsing it directly is in principle a dubious proposition, but in
           practice it is very stable.

       $download->zic_exe
           Returns the pathname of the "zic" executable that has been built from the downloaded
           source.  This is located in the local temporary directory used by this download.  This
           method will build "zic" if it has not already been built.

       $download->zoneinfo_dir([OPTIONS])
           Returns the pathname of the directory containing binary tzfiles (in tzfile(5) format)
           that have been generated from the downloaded source.  This is located in the local
           temporary directory used by this download, and the files within it have names that
           match the timezone names (as returned by "all_names").  This method will generate the
           tzfiles if they have not already been generated.

           The optional parameter OPTIONS controls which kind of tzfiles are desired.  If
           supplied, it must be a reference to a hash, in which these keys are permitted:

           leaps
               Truth value, controls whether the tzfiles incorporate information about known leap
               seconds offsets that account for the known leap seconds.  If false (which is the
               default), the tzfiles have no knowledge of leap seconds, and are intended to be
               used on a system where "time_t" is some flavour of UT (as is conventional on Unix
               and is the POSIX standard).  If true, the tzfiles know about leap seconds that
               have occurred between 1972 and the date of the database, and are intended to be
               used on a system where "time_t" is (from 1972 onwards) a linear count of TAI
               seconds (which is a non-standard arrangement).

BUGS

       Most of what this class does will only work on Unix platforms.  This is largely because
       the Olson database source is heavily Unix-oriented.

       It also won't be much good if you're not connected to the Internet.

       This class is liable to break if the format of the Olson database source ever changes
       substantially.  If that happens, an update of this class will be required.  It should at
       least recognise that it can't perform, rather than do the wrong thing.

SEE ALSO

       DateTime::TimeZone::Tzfile, Time::OlsonTZ::Data, tzfile(5)

AUTHOR

       Andrew Main (Zefram) <zefram@fysh.org>

COPYRIGHT

       Copyright (C) 2010, 2011, 2012 Andrew Main (Zefram) <zefram@fysh.org>

LICENSE

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