1Time::OlsonTZ::DownloadU(s3e)r Contributed Perl DocumentaTtiimoen::OlsonTZ::Download(3)
2
6 Time::OlsonTZ::Download - Olson timezone database from source
7
9 use Time::OlsonTZ::Download;
10 $version = Time::OlsonTZ::Download->latest_version;
12 $download = Time::OlsonTZ::Download->new;
14 $version = $download->version;
16 $version = $download->code_version;
17 $version = $download->data_version;
18 $dir = $download->dir;
19 $dir = $download->unpacked_dir;
20 $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 $files = $download->source_data_files;
29 $files = $download->zic_input_files;
30 $zic = $download->zic_exe;
31 $dir = $download->zoneinfo_dir;
32
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
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
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 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 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 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 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 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 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 version
97 Olson version number to attribute to the source files. Must be
98 supplied.
99 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
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 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 $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 $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 $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 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 $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 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 $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 $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 $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 $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 $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 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 alpha2_code
201 The ISO 3166 alpha-2 uppercase country code.
202 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 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 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 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 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 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 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 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 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 $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 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 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 If you want the human-editable source form of the data, use the
292 "source_data_files" method instead.
293 $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 $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 $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 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 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
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 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 It also won't be much good if you're not connected to the Internet.
345 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
352 DateTime::TimeZone::Tzfile, Time::OlsonTZ::Data, tzfile(5)
353
355 Andrew Main (Zefram) <zefram@fysh.org>
356
358 Copyright (C) 2010, 2011, 2012, 2017, 2018 Andrew Main (Zefram)
359 <zefram@fysh.org>
360
362 This module is free software; you can redistribute it and/or modify it
363 under the same terms as Perl itself.
364perl v5.36.0 2023-01-20 Time::OlsonTZ::Download(3)