view release on metacpan or  search on metacpan

bin/olson  view on Meta::CPAN

sorts after

=item B<!E<gt>>

does not sort after

=item B<E<gt>=>

sorts after or equal

=item B<!E<gt>=>

does not sort after or equal

=back

The positive comparisons never match when the attribute has an exception
rather than a normal value, whereas the negative comparisons always
match on exception.  That is, exceptions don't sort relative to normal
values for matching purposes.  This is the difference between B<!E<lt>>
and B<E<gt>=>, and the other pairs that otherwise seem equivalent.
Normal values always have a defined total ordering.

=item I<attribute> B<?>

Match if the attribute has a normal (non-exception) value.

=item I<attribute> B<!?>

Match if the attribute has an exception value.

=back

=head2 Output

A command-line argument requesting that an attribute be displayed consists
only of the attribute name.  A command-line argument controlling sorting
consists of the name of an attribute to sort on, preceded by a "B<+>"
for standard sorting or "B<->" for reversed sorting.  (Spaces are
permitted between the sign and the attribute name.)  Items are sorted
first according to the supplied sorting directives, first supplied being
the most significant.  Where the sorting directives don't distinguish
items, they are sorted according to the attributes being displayed.

Each line of output describes one combination of entities matching
all the specified criteria.  Within each line, the values of the
attributes requested for display are stated in the order requested,
separated by spaces.  Most attribute values are expressed without using
spaces internally, so splitting the line on spaces suffices to separate
the attributes.  Watch out for the abnormal `initialism' used by the
"Factory" timezone, which, unlike all real initialisms, has internal
spaces.  Spacing is varied so that in most cases each attribute is a
visually distinct column, but wide values will break the column format
for a particular line.

Where multiple matching combinations of entities are identical in all
the attributes selected for display and sorting, they are merged into one
line.  As a result, if all the sorting is on attributes being displayed,
all the output lines are necessarily different.  (Sorting on attributes
that are algebraically distant from all those being displayed can result
in many identical output lines, which looks strange.  The ability to do
this may be curtailed in the future.)  Any item where all the display
and sort attributes have only B<!!!> exceptions (unmatched entities)
is suppressed.

Most attribute values are intended to be parseable by computer programs,
and therefore the notation is intended to be very stable.  The amount
of spacing used, however, should not be relied upon.

=head2 Entities and relationships

The listing facility can be well understood in terms of the relational
algebra commonly seen in databases with SQL.  The relevant entity types
and their relatioships are:

=over

=item timezone

A named context in which there is an agreed set of behaviour for local
clocks.  A timezone is primarily identified by its hierarchical name.

A timezone is related to zero or one area, as determined by its name.
It is also related to zero or more regions; currently this is never more
than one region, but there's no rule requiring such a limit.  Via regions,
a timezone is related to zero or more (in practice zero or one) countries.

A timezone is related to exactly one canonical timezone, which is
what defines the behaviour of local clocks.  The algebra is slightly
muddled here, because the Olson database uses the same namespace for
clock contexts (timezones) and clock behaviour (canonical timezones).
In Olson terminology, a timezone is related to a canonical timezone
either by being the canonical timezone (if it has behaviour defined in
its own right) or by being a link to the canonical timezone.

=item area

A broad geographical area, either a continent or an ocean.  An area is
primarily identified by its monomial name.

An area is related to one or more timezones.  This relationship is
determined by the timezone's name, of which the area (if any) is the
first segment.  Via timezones, an area is related to zero or more regions,
zero or more countries, and one or more canonical timezones.

=item country

A political entity claiming authority over some geographical area.
The existence and geographical extent of countries is relatively volatile,
and in places controversial, which is why the Olson database doesn't
use countries as a primary means to identify timezones.  A country
is primarily identified by its ISO 3166 alpha-2 code, and it is this
assignment by the ISO 3166 Maintenance Agency that determines what
is a country, for the purposes of the Olson database.  A country also
has a name.  Formal country names vary between languages and are often
rather long; the Olson database maintains only a short English name for
each country.

A country is related to zero or more (in practice always one or more)
regions.  Via regions, it is related to zero or more (in practice always
one or more) timezones, zero or more (in practice always one or more)