1Time::OlsonTZ::DownloadU(s3e)r Contributed Perl DocumentaTtiimoen::OlsonTZ::Download(3)
2
3
4

NAME

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

SYNOPSIS

9           use Time::OlsonTZ::Download;
10
11           $version = Time::OlsonTZ::Download->latest_version;
12
13           $download = Time::OlsonTZ::Download->new;
14
15           $version = $download->version;
16           $version = $download->code_version;
17           $version = $download->data_version;
18           $dir = $download->dir;
19           $dir = $download->unpacked_dir;
20
21           $names = $download->canonical_names;
22           $names = $download->link_names;
23           $names = $download->all_names;
24           $links = $download->raw_links;
25           $links = $download->threaded_links;
26           $countries = $download->country_selection;
27
28           $files = $download->source_data_files;
29           $files = $download->zic_input_files;
30           $zic = $download->zic_exe;
31           $dir = $download->zoneinfo_dir;
32

DESCRIPTION

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

CLASS METHODS

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

CONSTRUCTORS

47       Time::OlsonTZ::Download->new([VERSION])
48           Downloads a copy of the source of the Olson database, and returns
49           an object representing that copy.
50
51           VERSION, if supplied, is a version number specifying which version
52           of the database is to be downloaded.  If not supplied, the latest
53           available version will be downloaded.  Version numbers for the
54           Olson database currently consist of a year number and a lowercase
55           letter, such as ""2010k"".  The letter advances with each release
56           in a year.
57
58           Historical vesrions make the version numbers a bit more
59           complicated.  Prior to late 1996 the century portion of the year
60           number was omitted, giving version numbers such as ""96g"".  Prior
61           to 1994 the first release of each year omitted the letter ""a"",
62           giving version numbers such as "93" (with the second release of the
63           year being ""93b"").
64
65           From 1993 to to late 2012 the database was split into `code' and
66           `data' parts that could each be released without releasing a new
67           version of the other part.  Each part had its own version number,
68           sometimes advancing independently of each other, and sometimes
69           skipping sequence letters in order to catch up with the other part.
70           Where the two parts of some version of the database have different
71           version numbers, the version number of the database as a whole is
72           whichever part's version number is higher.  If this would give two
73           database versions the same number, due to multiple releases of one
74           part happening while the other part has a higher version number, a
75           digit "2" or "3" is appended after the letter to distinguish the
76           second and third such versions.
77
78           This module does not currently support downloading database
79           versions earlier than version 93.  One can expect to successfully
80           download most versions from then on, but a handful are missing from
81           the public archive.  The public archive is complete from version
82           2006f onwards.  Details of historical version availability may
83           change in future.
84
85       Time::OlsonTZ::Download->new_from_local_source(ATTR => VALUE, ...)
86           Acquires Olson database source locally, without downloading, and
87           returns an object representing a copy of it ready to use like a
88           download.  This can be used to work with locally-modified versions
89           of the database.  The following attributes may be given:
90
91           source_dir
92               Local directory containing Olson source files.  Must be
93               supplied.  The entire directory will be copied into a temporary
94               location to be worked on.
95
96           version
97               Olson version number to attribute to the source files.  Must be
98               supplied.
99
100           code_version
101           data_version
102               Olson version number to attribute to the code and data parts of
103               the source files.  Both default to the main version number.
104

METHODS

106   Basic information
107       $download->version
108           Returns the version number of the database of which a copy is
109           represented by this object.
110
111           The database consists of code and data parts which are updated
112           semi-independently.  The latest version of the database as a whole
113           consists of the latest version of the code and the latest version
114           of the data.  If both parts are updated at once then they will both
115           get the same version number, and that will be the version number of
116           the database as a whole.  However, in general they may be updated
117           at different times, and a single version of the database may be
118           made up of code and data parts that have different version numbers.
119           The version number of the database as a whole will then be the
120           version number of the most recently updated part.
121
122       $download->code_version
123           Returns the version number of the code part of the database of
124           which a copy is represented by this object.
125
126       $download->data_version
127           Returns the version number of the data part of the database of
128           which a copy is represented by this object.
129
130       $download->dir
131           Returns the pathname of the directory in which the files of this
132           download are located.  With this method, there is no guarantee of
133           particular files being available in the directory; see other
134           directory-related methods below that establish particular directory
135           contents.
136
137           The directory does not move during the lifetime of the download
138           object: this method will always return the same pathname.  The
139           directory and all of its contents, including subdirectories, will
140           be automatically deleted when this object is destroyed.  This will
141           be when the main program terminates, if it is not otherwise
142           destroyed.  Any files that it is desired to keep must be copied to
143           a permanent location.
144
145       $download->unpacked_dir
146           Returns the pathname of the directory in which the downloaded
147           source files have been unpacked.  This is the local temporary
148           directory used by this download.  This method will unpack the files
149           there if they have not already been unpacked.
150
151   Zone metadata
152       $download->canonical_names
153           Returns the set of timezone names that this version of the database
154           defines as canonical.  These are the timezone names that are
155           directly associated with a set of observance data.  The return
156           value is a reference to a hash, in which the keys are the canonical
157           timezone names and the values are all "undef".
158
159       $download->link_names
160           Returns the set of timezone names that this version of the database
161           defines as links.  These are the timezone names that are aliases
162           for other names.  The return value is a reference to a hash, in
163           which the keys are the link timezone names and the values are all
164           "undef".
165
166       $download->all_names
167           Returns the set of timezone names that this version of the database
168           defines.  These are the "canonical_names" and the "link_names".
169           The return value is a reference to a hash, in which the keys are
170           the timezone names and the values are all "undef".
171
172       $download->raw_links
173           Returns details of the timezone name links in this version of the
174           database.  Each link defines one timezone name as an alias for some
175           other timezone name.  The return value is a reference to a hash, in
176           which the keys are the aliases and each value is the preferred
177           timezone name to which that alias directly refers.  It is possible
178           for an alias to point to another alias, or to point to a non-
179           existent name.  For a more processed view of links, see
180           "threaded_links".
181
182       $download->threaded_links
183           Returns details of the timezone name links in this version of the
184           database.  Each link defines one timezone name as an alias for some
185           other timezone name.  The return value is a reference to a hash, in
186           which the keys are the aliases and each value is the canonical name
187           of the timezone to which that alias refers.  All such canonical
188           names can be found in the "canonical_names" hash.
189
190       $download->country_selection
191           Returns information about how timezones relate to countries,
192           intended to aid humans in selecting a geographical timezone.  This
193           information is derived from the "zone.tab" and "iso3166.tab" files
194           in the database source.
195
196           The return value is a reference to a hash, keyed by (ISO 3166
197           alpha-2 uppercase) country code.  The value for each country is a
198           hash containing these values:
199
200           alpha2_code
201               The ISO 3166 alpha-2 uppercase country code.
202
203           olson_name
204               An English name for the country, possibly in a modified form,
205               optimised to help humans find the right entry in alphabetical
206               lists.  This is not necessarily identical to the country's
207               standard short or long name.  (For other forms of the name,
208               consult a database of countries, keying by the country code.)
209
210           regions
211               Information about the regions of the country that use distinct
212               timezones.  This is a hash, keyed by English description of the
213               region.  The description is empty if there is only one region.
214               The value for each region is a hash containing these values:
215
216               olson_description
217                   Brief English description of the region, used to
218                   distinguish between the regions of a single country.  Empty
219                   string if the country has only one region for timezone
220                   purposes.  (This is the same string used as the key in the
221                   regions hash.)
222
223               timezone_name
224                   Name of the Olson timezone used in this region.  This is
225                   not necessarily a canonical name (it may be a link).
226                   Typically, where there are aliases or identical canonical
227                   zones, a name is chosen that refers to a location in the
228                   country of interest.  It is not guaranteed that the named
229                   timezone exists in the database (though it always should).
230
231               location_coords
232                   Geographical coordinates of some point within the location
233                   referred to in the timezone name.  This is a latitude and
234                   longitude, in ISO 6709 format.
235
236           This data structure is intended to help a human select the
237           appropriate timezone based on political geography, specifically
238           working from a selection of country.  It is of essentially no use
239           for any other purpose.  It is not strictly guaranteed that every
240           geographical timezone in the database is listed somewhere in this
241           structure, so it is of limited use in providing information about
242           an already-selected timezone.  It does not include non-geographic
243           timezones at all.  It also does not claim to be a comprehensive
244           list of countries, and does not make any claims regarding the
245           political status of any entity listed: the "country" classification
246           is loose, and used only for identification purposes.
247
248   Compiling zone data
249       $download->source_data_files
250           Returns a reference to an array containing the pathnames of all the
251           source data files.  These express the database's data (i.e., a
252           description of known civil timezones) in a textual format, and are
253           intended for human editing.  They are located in the local
254           temporary directory used by this download.
255
256           There is normally approximately one source data file per continent,
257           though this arrangement could change in the future.  The textual
258           format is machine parseable, the same format intended for input to
259           "zic", but when interpreted this way the files do not necessarily
260           correspond to the the official content of the database.  There may
261           be transformations that the database code would normally apply
262           between the source data files and the actual input to "zic".
263
264           If you intend to parse the source, taking the place of "zic", then
265           you should prefer to use the "zic_input_files" method, which
266           provides the input that "zic" would actually see.
267
268       $download->zic_input_files
269           Returns a reference to an array containing the pathnames of all the
270           data files that would normally be fed to "zic".  These express the
271           database's data (i.e., a description of known civil timezones) in
272           the format expected by "zic", and are suitable for machine parsing.
273           They are located in the local temporary directory used by this
274           download.  This method will build the files if they didn't already
275           exist.
276
277           The "zic" input files are not necessarily source files intended for
278           human editing.  In older versions of the database they are such
279           source files, but from database version "2017c" onwards there is a
280           single "zic" input file, which is generated from the source files
281           and omits the niceties of the source files.  From database version
282           "2018d" onwards there is some transformation between the source
283           files and the "zic" input, such that they do not necessarily
284           express the same data when parsed by "zic".  These arrangements
285           could change again in the future.
286
287           The textual format of "zic" input is not standardised, and is
288           peculiar to the Olson database.  Parsing it directly is in
289           principle a dubious proposition, but in practice it is very stable.
290
291           If you want the human-editable source form of the data, use the
292           "source_data_files" method instead.
293
294       $download->data_files
295           Returns a reference to an array containing the pathnames of all the
296           source data files, provided that the database code would feed the
297           same data to "zic".  This method is deprecated: you should use
298           either "source_data_files" or "zic_input_files" depending on which
299           aspect of the data files you are interested in.  In older versions
300           of the database the same files were both human-editable and used as
301           "zic" input, so this single method served both roles.  From
302           database version "2018d" onwards there is some transformation
303           between the source files and the "zic" input, so the two roles of
304           the files need to be distinguished.
305
306       $download->zic_exe
307           Returns the pathname of the "zic" executable that has been built
308           from the downloaded source.  This is located in the local temporary
309           directory used by this download.  This method will build "zic" if
310           it has not already been built.
311
312       $download->zoneinfo_dir([OPTIONS])
313           Returns the pathname of the directory containing binary tzfiles (in
314           tzfile(5) format) that have been generated from the downloaded
315           source.  This is located in the local temporary directory used by
316           this download, and the files within it have names that match the
317           timezone names (as returned by "all_names").  This method will
318           generate the tzfiles if they have not already been generated.
319
320           The optional parameter OPTIONS controls which kind of tzfiles are
321           desired.  If supplied, it must be a reference to a hash, in which
322           these keys are permitted:
323
324           leaps
325               Truth value, controls whether the tzfiles incorporate
326               information about known leap seconds offsets that account for
327               the known leap seconds.  If false (which is the default), the
328               tzfiles have no knowledge of leap seconds, and are intended to
329               be used on a system where "time_t" is some flavour of UT (as is
330               conventional on Unix and is the POSIX standard).  If true, the
331               tzfiles know about leap seconds that have occurred between 1972
332               and the date of the database, and are intended to be used on a
333               system where "time_t" is (from 1972 onwards) a linear count of
334               TAI seconds (which is a non-standard arrangement).
335

BUGS

337       Most of what this class does will only work on Unix platforms.  This is
338       largely because the Olson database source is heavily Unix-oriented.
339
340       This class also depends on the availability of some tools beyond
341       baseline Unix.  Specifically, it requires GNU "gpgv2", GNU "tar",
342       "lzip", "sha512sum", and GNU "make".
343
344       It also won't be much good if you're not connected to the Internet.
345
346       This class is liable to break if the format of the Olson database
347       source ever changes substantially.  If that happens, an update of this
348       class will be required.  It should at least recognise that it can't
349       perform, rather than do the wrong thing.
350

SEE ALSO

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

AUTHOR

355       Andrew Main (Zefram) <zefram@fysh.org>
356
358       Copyright (C) 2010, 2011, 2012, 2017, 2018 Andrew Main (Zefram)
359       <zefram@fysh.org>
360

LICENSE

362       This module is free software; you can redistribute it and/or modify it
363       under the same terms as Perl itself.
364
365
366
367perl v5.36.0                      2023-01-20        Time::OlsonTZ::Download(3)
Impressum