This package consists of a C library and a Perl module (which uses the
C library, internally) for all kinds of date calculations based on the
Gregorian calendar (the one used in all western countries today),
thereby complying with all relevant norms and standards: ISO/R
2015-1971, DIN 1355 and, to some extent, ISO 8601 (where applicable).

(See also http://www.engelschall.com/u/sb/download/Date-Calc/DIN1355/
for a scan of part of the "DIN 1355" document (in German)).

The module of course handles year numbers of 2000 and above correctly
("Year 2000" or "Y2K" compliance) -- actually all year numbers from 1
to the largest positive integer representable on your system (which is
at least 32767) can be dealt with.

Note that this package EXTRAPOLATES the Gregorian calendar BACK until
the year 1 A.D. -- even though the Gregorian calendar was only adopted
in 1582 by most (not all) European countries, in obedience to the
corresponding decree of catholic pope Gregor I in that year.

Some (mainly protestant) countries continued to use the Julian calendar
(used until then) until as late as the beginning of the 20th century.

Finally, note that this package is not intended to do everything you
could ever imagine automagically for you; it is rather intended to
serve as a toolbox (in the best of UNIX spirit and traditions) which
should, however, always get you where you want to go.

Date::Manip is a series of modules designed to make any common date/time
manipulation easy to do. Operations such as comparing two times,
calculating a time a given amount of time from another, or parsing
international times are all easily done. From the very beginning, the main
focus of Date::Manip has been to be able to do ANY desired date/time
operation easily, not necessarily quickly. Also, it is definitely oriented
towards the type of operations we (as people) tend to think of rather than
those operations used routinely by computers. There are other modules that
can do a subset of the operations available in Date::Manip much quicker
than those presented here, so be sure to read the section SHOULD I USE
DATE::MANIP in the Date::Manip::Misc document before deciding which of the
Date and Time modules from CPAN is for you.

DateTime::Locale is primarily a factory for the various locale subclasses.
It also provides some functions for getting information on all the
available locales.

If you want to know what methods are available for locale objects,
then please read the DateTime::Locale::Base documentation.

This class is the base class for all time zone objects. A time zone is
represented internally as a set of observances, each of which describes the
offset from GMT for a given time period.

Note that without the 'DateTime.pm' module, this module does not do much.
It's primary interface is through a 'DateTime' object, and most users will
not need to directly use 'DateTime::TimeZone' methods.

DBD::mysql is the Perl5 Database Interface driver for the MySQL database.
In other words: DBD::mysql is an interface between the Perl programming
language and the MySQL programming API that comes with the MySQL relational
database management system. Most functions provided by this programming API
are supported. Some rarely used functions are missing, mainly because noone
ever requested them. :-)

This module is needed to access ODBC databases from within Perl. The
module uses the unixODBC manager to connect to the database.

Module XBase provides access to XBase (dBase, Fox*) database files,
namely dbf, dbt, fpt, ndx, ntx, mdx, idx and cdx.

The DBI is a database access module for the Perl programming language.
It defines a set of methods, variables, and conventions that provide a
consistent database interface, independent of the actual database
being used.

DBIx::Transaction is a wrapper around DBI that helps you manage your
database transactions.

This module attempts to generate a stack dump from a core file by
locating the best available debugger (if any) and running it with the
appropriate arguments and command script.

Devel::StackTrace::AsHTML adds 'as_html' method to the Devel::StackTrace
manpage which displays the stack trace in beautiful HTML, with code snippet
context and function parameters. If you call it on an instance of the
Devel::StackTrace::WithLexicals manpage, you even get to see the lexical
variables of each stack frame.

Devel::Symdump is a Perl module that provides a convenient way to
inspect Perl's symbol table and the class hierarchy within a running
program.

HMAC is used for message integrity checks between two parties that share a
secret key, and works in combination with some other Digest algorithm,
usually MD5 or SHA-1. The HMAC mechanism is described in RFC 2104.

HMAC follow the common 'Digest::' interface, but the constructor takes the
secret key and the name of some other simple 'Digest::' as argument.

Perl interface to the RSA Data Security Inc. MD4 Message-Digest
Algorithm.

The Digest::SHA1 module allows the use of the NIST SHA-1 message digest
algorithm from within Perl programs. The algorithm takes a message of
arbitrary length as input and produces a 160-bit fingerprint or message
digest of the input as output.

One shortcoming of the CPAN clients that currently exist is that they have
no way of specifying conflicting downstream dependencies of modules. This
module attempts to work around this issue by allowing you to specify
conflicting versions of modules separately, and deal with them after the
module is done installing.

For instance, say you have a module 'Foo', and some other module 'Bar' uses
'Foo'. If 'Foo' were to change its API in a non-backwards-compatible way,
this would cause 'Bar' to break until it is updated to use the new API.
'Foo' can't just depend on the fixed version of 'Bar', because this will
cause a circular dependency (because 'Bar' is already depending on 'Foo'),
and this doesn't express intent properly anyway - 'Foo' doesn't use 'Bar'
at all. The ideal solution would be for there to be a way to specify
conflicting versions of modules in a way that would let CPAN clients update
conflicting modules automatically after an existing module is upgraded, but
until that happens, this module will allow users to do this manually.

This module accepts a hash of options passed to its 'use' statement, with
these keys being valid:

* -conflicts

A hashref of conflict specifications, where keys are module names, and
values are the last broken version - any version greater than the
specified version should work.

* -also

Additional modules to get conflicts from (potentially recursively). This
should generally be a list of modules which use Dist::CheckConflicts,
which correspond to the dists that your dist depends on. (In an ideal
world, this would be intuited directly from your dependency list, but the
dependency list isn't available outside of build time).

* -dist

The name of the distribution, to make the error message from
check_conflicts more user-friendly.

The methods listed below are exported by this module into the module that
uses it, so you should call these methods on your module, not
Dist::CheckConflicts.

As an example, this command line can be used to update your modules, after
installing the 'Foo' dist (assuming that 'Foo::Conflicts' is the module in
the 'Foo' dist which uses Dist::CheckConflicts):

perl -MFoo::Conflicts -e'print "$_\n"
for map { $_->{package} } Foo::Conflicts->calculate_conflicts' | cpanm

In many applications it's wise to let Perl use Unicode for the strings it
processes. Most of the interfaces Perl has to the outside world are still
byte based. Programs therefore needs to decode byte strings that enter the
program from the outside and encode them again on the way out.

The POSIX locale system is used to specify both the language conventions
requested by the user and the preferred character set to consume and
output. The 'Encode::Locale' module looks up the charset and encoding
(called a CODESET in the locale jargon) and arrange for the Encode
module to know this encoding under the name "locale". It means
bytes obtained from the environment can be converted to Unicode strings by
calling 'Encode::encode(locale => $bytes)' and converted back again with
'Encode::decode(locale => $string)'.

Where file systems interfaces pass file names in and out of the program we
also need care. The trend is for operating systems to use a fixed file
encoding that doesn't actually depend on the locale; and this module
determines the most appropriate encoding for file names. The Encode
module will know this encoding under the name "locale_fs". For
traditional Unix systems this will be an alias to the same encoding as
"locale".

For programs running in a terminal window (called a "Console" on some
systems) the "locale" encoding is usually a good choice for what to expect
as input and output. Some systems allow us to query the encoding set for
the terminal and 'Encode::Locale' will do that if available and make these
encodings known under the 'Encode' aliases "console_in" and "console_out".
For systems where we can't determine the terminal encoding these will be
aliased as the same encoding as "locale". The advice is to use "console_in"
for input known to come from the terminal and "console_out" for output
known to go from the terminal.

In addition to arranging for various Encode aliases the following functions
and variables are provided:

* decode_argv( )

* decode_argv( Encode::FB_CROAK )

This will decode the command line arguments to perl (the '@ARGV' array)
in-place.

The function will by default replace characters that can't be decoded by
"\x{FFFD}", the Unicode replacement character.

Any argument provided is passed as CHECK to underlying Encode::decode()
call. Pass the value 'Encode::FB_CROAK' to have the decoding croak if not
all the command line arguments can be decoded. See the Encode/"Handling
Malformed Data" manpage for details on other options for CHECK.

* env( $uni_key )

* env( $uni_key => $uni_value )

Interface to get/set environment variables. Returns the current value as
a Unicode string. The $uni_key and $uni_value arguments are expected to
be Unicode strings as well. Passing 'undef' as $uni_value deletes the
environment variable named $uni_key.

The returned value will have the characters that can't be decoded
replaced by "\x{FFFD}", the Unicode replacement character.

There is no interface to request alternative CHECK behavior as for
decode_argv(). If you need that you need to call encode/decode yourself.
For example:

my $key = Encode::encode(locale => $uni_key, Encode::FB_CROAK);
my $uni_value = Encode::decode(locale => $ENV{$key}, Encode::FB_CROAK);

* reinit( )

* reinit( $encoding )

Reinitialize the encodings from the locale. You want to call this
function if you changed anything in the environment that might influence
the locale.

This function will croak if the determined encoding isn't recognized by
the Encode module.

With argument force $ENCODING_... variables to set to the given value.

* $ENCODING_LOCALE

The encoding name determined to be suitable for the current locale. The
Encode manpage knows this encoding as "locale".

* $ENCODING_LOCALE_FS

The encoding name determined to be suiteable for file system interfaces
involving file names. The Encode manpage knows this encoding as
"locale_fs".

* $ENCODING_CONSOLE_IN

* $ENCODING_CONSOLE_OUT

The encodings to be used for reading and writing output to the a console.
The Encode manpage knows these encodings as "console_in" and
"console_out".

The 'Error' package provides two interfaces. Firstly 'Error' provides a
procedural interface to exception handling. Secondly 'Error' is a base
class for errors/exceptions that can either be thrown, for subsequent
catch, or can simply be recorded.

Errors in the class 'Error' should not be thrown directly, but the user
should throw errors from a sub-class of 'Error'.

ALERT: Marc Lehmann may have taken over the future of event loops in Perl.
Check out his libev library and EV Perl module. 25 Aug 2009

The Event module provide a central facility to watch for various types of
events and invoke a callback when these events occur. The idea is to delay
the handling of events so that they may be dispatched in priority order
when it is safe for callbacks to execute.

Events (in the ordinary sense of the word) are detected by *watchers*,
which reify them as *events* (in the special Event module sense). For
clarity, the former type of events may be called "source events", and the
latter "target events". Source events, such as signals arriving, happen
whether or not they are being watched. If a source event occurs which a
watcher is actively watching then the watcher generates a corresponding
target event. Target events are only created by watchers. If several
watchers are interested in the same source event then each will generate
their own target event. Hence, any particular source event may result in
zero, one, two, or any number of target events: the same as the number of
watchers which were actively watching for it.

Target events are queued to be processed in priority order (priority being
determined by the creating watcher) and in FIFO order among events of the
same priority. Queued ("pending") events can, in some cases, be cancelled
before being processed. A queued event is processed by being passed to the
callback function (or method on a particular object or class) which was
specified to the watcher.

A watcher, once created, operates autonomously without the Event user
having to retain any reference to it. However, keeping a reference makes it
possible to modify most of the watcher's characteristics. A watcher can be
switched between active and inactive states. When inactive, it does not
generate target events.

Some types of source event are not reified as target events immediately.
Signals received, for example, are counted initially. The counted signals
are reified at certain execution points. Hence, signal events may be
processed out of order, and if handled carelessly, on the wrong side of a
state change in event handling. A useful way to view this is that
occurrence of the source event is not actually the arrival of the signal
but is triggered by the counting of the signal.

Reification can be forced when necessary. The schedule on which some other
events are created is non-obvious. This is especially the case with
watchers that watch for a condition rather than an event. In some cases,
target events are generated on a schedule that depends on the operation of
the event loop.

This module can build the C portions of Perl modules by invoking the
appropriate compilers and linkers in a cross-platform manner. It was
motivated by the Module::Build project, but may be useful for other
purposes as well. However, it is not intended as a general cross-platform
interface to all your C building needs. That would have been a much more
ambitious goal!