Date::Manip::InterfaceUsermContributed Perl DocumeDate::Manip::Interfaces(3pm)NAMEDate::Manip::Interfaces - A description of functional and OO interfaces
DESCRIPTION
There are three different ways to use Date::Manip . A complete
description of each is included below. They are:
Functional interface (version 5)
Date::Manip version 5 runs on very old versions of perl. If you
need to use Date::Manip with a version of perl older than 5.10,
this is the only interface available.
Functional interface (version 6)
When Date::Manip was rewritten (version 6), it made use of some
features of perl 5.10 . This is the recommended interface if you
are supporting a script that uses the functional interface, but
where a newer version of perl is available.
Object-oriented interface
The OO interface is the recommended interface wherever possible.
It is the only one with access to the full functionality of the
module.
VERSION 5 AND VERSION 6
Date::Manip version 5.xx was available for many years, but suffered
from several weaknesses. It was slow, and did not handle timezones or
daylight saving time correctly. It was written as a functional
interface, even though an object-oriented interface would have been
better. It did have the advantage of running on very old versions of
perl (it is known to work on perl 5.6 and may work on even older
versions of perl).
Date::Manip version 6.00 was a complete rewrite of the module. For
detailed information about the differences, please refer to the
Date::Manip::Changes5to6 document. The rewrite was needed in order to
handle timezone operations, in addition to many other improvements
including much better performance and more robust parsing.
The rewrite made use of features introduced in perl 5.10 which made the
date parsing routines significantly cleaner. In addition, the 6.xx
release was written as an object oriented set of modules which are much
more powerful than the older functional interface. For backward
compatibility, a new functional interface was rewritten (which is
simply a set of wrapper functions which call the OO methods) which is
almost entirely backward compatible with the version 5.xx interface.
The Date::Manip distribution includes all three of these interfaces:
the older version 5 interface, and both the new OO interface and the
backward compatible functional interface. Also, all three are
installed, so you can use whichever interface is appropriate.
Since there are three different interfaces available, choosing the
interface is the necessary.
If you are running on a system with a very old version of perl (older
than 5.10), the version 5 interface is your only option.
If you are on a system running a newer version of perl, but need to
support a script that was written using the functional interface, then
you can use the version 6 functional interface.
For everyone else, it is strongly recommended that you use the object-
oriented interface.
A more detailed description of each interface is included below. If
you already know which interface you want to use, just go to the "SEE
ALSO" in Date::Manip section for documentation for each interface.
FUNCTIONAL INTERFACE (VERSION 5)
When using a version of perl older than 5.10, this is the only
interface available. This interface is documented in the
"Date::Manip::DM5 document". This interface has several weaknesses
that need to be understood when using it:
Limited Support
The version 5 functional interface is no longer being developed,
and only limited support is available for it.
As of December 2012, no development will be done, and I will not
correct any remaining bugs in version 5. If a patch is supplied by
someone else to fix bugs, I will apply it, provided it applies
cleanly, and the resulting code continues to pass all tests. I
will not apply patches to add features.
I will continue to distribute version 5 for several years. I do
not have a date in mind where version 5 will be removed.
Limited Time Zone Support
Time zone support is extremely limited, and is often incorrect. The
lack of time zone support was the primary reason for rewriting
Date::Manip.
The version 5 interface does not handle daylight saving time
changes correctly.
Performance Issues
Considerable time has been spent speeding up Date::Manip, and
fairly simple benchmarks show that version 6 is around twice as
fast as version 5.
Feel free to email me concerns and comments.
FUNCTIONAL INTERFACE (VERSION 6)
The version 6 functional interface is almost completely identical to
the version 5 functional interface, except that it uses the object-
oriented modules to do all the real work.
Time zone support is greatly improved, but is still somewhat limited.
Since the version 6 interface is backward compatible, dates do not
store time zone information in them, so the programmer is responsible
for keeping track of what time zone each date is in. If you want full
access to the time zone support offered in Date::Manip, you have to use
the object-oriented interface.
For the most part, scripts written for older versions of Date::Manip
will continue to work (and scripts written for the version 6 functional
interface will run with the version 5 interface), however in a few
cases, you may need to modify your scripts. Please refer to the
Date::Manip::Migration5to6 document for a list of changes which may be
necessary.
OBJECT-ORIENTED INTERFACE
As of 6.00, Date::Manip consists of a set of OO modules. Each have
their own document (see the "SEE ALSO" in Date::Manip section).
The OO interface consists of the following modules: Date::Manip::Date,
Date::Manip::Delta, Date::Manip::Recur, Date::Manip::TZ, and
Date::Manip::Base.
The object-oriented interface is the only way to get the full
functionality of Date::Manip. It fully support time zones (and daylight
saving time).
SELECTING AN INTERFACE
If you are running an older version of perl, the version 5 functional
interface is the only one available to you, and it will automatically
be used.
If you are running a newer version of perl (5.10 or higher), you can
use the object-oriented modules by loading them directly, or you can
use a functional interface.
If you use a functional interface, it will default to the version 6
interface, but you can choose to run the version 5 interface in one of
three ways:
Using the OO interface
By including any of the following:
use Date::Manip::Date;
use Date::Manip::Delta;
use Date::Manip::Recur;
use Date::Manip::TZ;
use Date::Manip::Base;
you have access to the OO interface for the appropriate types of
objects.
Use the default functional interface
By including:
use Date::Manip;
in your script, one of the functional interfaces will be loaded.
If you are running a version of perl older than 5.10, it will
automatically be the version 5 interface. If you are running a
newer version of perl, it will automatically load the version 6
interface.
DATE_MANIP environment variable
By setting the DATE_MANIP environment variable to 'DM5' before
running the perl script, the version 5 interface will be used.
Date::Manip::Backend variable
Alternately, you can set the Date::Manip::Backend variable to be
'DM5' before loading the module. Typically, this will be done in
the following way:
BEGIN {
$Date::Manip::Backend = 'DM5';
}
use Date::Manip;
Once a functional interface is loaded, you cannot switch between the
version 5 and version 6 interfaces.
SEE ALSO
Date::Manip - main module documentation
LICENSE
This script is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
AUTHOR
Sullivan Beck (sbeck@cpan.org)
perl v5.26.0 2017-10-14 Date::Manip::Interfaces(3pm)
