# Copyright (c) 1995-2017 Sullivan Beck. All rights reserved.

# This program is free software; you can redistribute it and/or modify it

# under the same terms as Perl itself.

=pod

=head1 NAME

Date::Manip::Interfaces - A description of functional and OO interfaces

=head1 DESCRIPTION

There are three different ways to use Date::Manip .  A complete description

of each is included below.  They are:

=over 4

=item 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.

=item 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.

=item 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.

=back

=head1 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

L<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

L<Date::Manip/"SEE ALSO"> section for documentation for each

interface.

=head1 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

L<Date::Manip::DM5 document>.  This interface has several weaknesses that

need to be understood when using it:

=over 4

=item B<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.

=item B<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.

=item B<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.

=back

Feel free to email me concerns and comments.

=head1 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 L<Date::Manip::Migration5to6> document for a list of changes which

may be necessary.

=head1 OBJECT-ORIENTED INTERFACE

As of 6.00, Date::Manip consists of a set of OO modules. Each have

their own document (see the L<Date::Manip/"SEE ALSO"> section).

The OO interface consists of the following modules: L<Date::Manip::Date>,

L<Date::Manip::Delta>, L<Date::Manip::Recur>, L<Date::Manip::TZ>, and

L<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).

=head1 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:

=over 4

=item 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.

=item 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.

=item 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.

=item 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;

=back

Once a functional interface is loaded, you cannot switch between the

version 5 and version 6 interfaces.

=head1 SEE ALSO

Date::Manip        - main module documentation

=head1 LICENSE

This script is free software; you can redistribute it and/or

modify it under the same terms as Perl itself.

=head1 AUTHOR

Sullivan Beck (sbeck@cpan.org)

=cut