libdate-manip-perl 6.25-1 / usr / share / perl5 / Date / Manip.pod

# Copyright (c) 1995-2011 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 - Date manipulation routines

=head1 DESCRIPTION

Date::Manip is a series of modules designed to make any common
date/time operation 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.  It deals with time
as it is used in the Gregorian calendar (the one currently in use)
with full support for time changes due to daylight saving time.

From the very beginning, the main focus of Date::Manip has been to be
able to do ANY desired date/time operation easily.  Many other modules
exist which may do a subset of these operations quicker or more
efficiently, but no other module can do all of the operations
available in Date::Manip.

Since many other date/time modules exist, some of which may do the
specific operation(s) you need faster, 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.
However, if you want one module to do it all, Date::Manip is the
one to use.

Date::Manip has functionality to work with several fundamental types
of data.

=over 4

=item B<dates>

The word date is used extensively here and is somewhat misleading. In
Date::Manip, a date consists of three pieces of information: a
calendar date, a time of day, and time zone information. Calendar
dates and times are fully handled. Time zones are handled as well, but
depending on how you use Date::Manip, there may be some limitations as
discussed below.

=item B<delta>

A delta is an amount of time (i.e. the amount of time between two different
dates). A delta refers only to an amount of time. It includes no information
about a starting or ending date/time.

=item B<recurrence>

A recurring event is something which occurs on a regular recurring
basis.

=item B<holidays> and B<events>

Holidays and events are basically named dates or recurrences.

=back

Among other things, Date::Manip allow you to:

=over 4

=item B<*>

Enter a date in practically any format you choose.

=item B<*>

Compare two dates, entered in widely different formats to determine
which is earlier.

=item B<*>

Extract any information you want from a date using a format string
similar to the Unix date command.

=item B<*>

Determine the amount of time between two dates, or add an amount of
time to a date to get a second date.

=item B<*>

Work with dates with dates using international formats (foreign month
names, 12/10/95 referring to October rather than December, etc.).

=item B<*>

To find a list of dates where a recurring event happens.

=back

Each of these tasks is trivial (one or two lines at most) with this package.

=head1 B<VERSION 5 AND VERSION 6>

Date::Manip version 6.00 was a complete rewrite of the module (for more
information, please refer to the Date::Manip::Changes5to6 document).
The rewrite made use of features introduced in perl 5.10 which made
the date parsing routines significantly more robust. However, since
not everyone has access to a new version of perl where Date::Manip
is needed, the Date::Manip distribution actually includes two different
versions of the module.  It includes the older (5.xx) release and the
newer (6.xx) release.

In addition, the 6.xx release was written with both a functional and
an object-oriented interface, so there are actually three different
ways to use Date::Manip (though only one is available if you have a
version of perl older than 5.10).

For those who still run an older version of perl, the 5.xx functional
interface is still available. It is known to work with perl 5.6 (and probably
works with even older versions of perl).  There are some limitations
to this as described below.

Version 6.xx was rewritten as a series of object-oriented modules, but
a functional interface (which is mostly backward compatible with the
version 5 functional interface) is included. The functional interface
is simply wrapper functions which call the OO modules.

A more detailed description of each interface is included below (to
help you decide which interface is right for you).  If you already
know which interface you want to use, just go to the SEE ALSO section
below for instructions on using each interface.

It should be noted that all three interfaces will be installed, but they
will only all be usable with a recent version of perl.

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

I will continue to do limited bug fixes provided they do not require
a lot of changes. Anything to do with time zone handling will not
be fixed, and other problems (especially those that have already been
fixed in the 6.xx release) may not be patched if they require
significant changes to 5.xx.

Limited bug fixes will be supported until December 2012. At that
point, I will reevaluate things and decide whether or not to continue
this or not. My prediction is that, at that point, I will cease
providing bug fixes for the 5.xx release entirely.

Whether or not I continue to do bug fixes, I will continue to
distribute the version 5 functional interface until at least December
2013. After that, I will evaluate the need for a perl 5.6/5.8 version
of Date::Manip in order to decide whether or not to continue
distributing it.

=item B<Limited Time Zone Support>

Time zone support is extremely limited, and is often broken. The lack
of good time zone support was the primary reason for rewriting
Date::Manip .

Time zone information for 5.xx is now automatically generated from the
6.xx time zone list, and every time time zones are updated in 6.xx,
the 5.xx release will be similarly updated.

Prior to the release of 6.00, time zones were added manually to
Date::Manip upon request. Since time zone information in 5.xx is now
automatically generated, I no longer take requests for time zones.

The version 5 interface does not handle daylight saving time changes
properly.

=item B<No Further Development>

No functionality will be added to 5.xx .

=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 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 SEE ALSO section below).

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

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

The following documents describe various parts of Date::Manip. The
following documents describe the basic operation of the Date::Manip
package:

A description of the functional interfaces:

  Date::Manip::DM5        - the version 5 functional interface
  Date::Manip::DM6        - the version 6 functional interface

An introduction to the Date::Manip classes used by the object-oriented
interface and how to configure them:

  Date::Manip::Objects 	  - an overview of the various
                       	    Date::Manip modules, and how
                            to use them
  Date::Manip::Config  	  - information for configuring
                            Date::Manip

The methods available in each class:

  Date::Manip::Obj     	  - base class (modules listed below
                       	    inherit the methods defined in this
                            class)
  Date::Manip::Base    	  - module for doing low-level date
                            operations
  Date::Manip::TZ      	  - module for working with time zones
  Date::Manip::Date    	  - date operations
  Date::Manip::Delta   	  - delta operations
  Date::Manip::Recur   	  - recurrence operations

Timezone information:

  Date::Manip::DM5abbrevs - time zone abbreviations used in the
                            version 5 interface
  Date::Manip::Zones   	  - time zone data included in Date::Manip
                            used in the version 6 interface and
                            the object-oriented interface

Miscellaneous information:

  Date::Manip::Calc    	  - date calculations
  Date::Manip::Holidays   - information on defining and using
                            holidays and events
  Date::Manip::ConfigFile - sample config file

Information about the module and administrative things:

  Date::Manip::Migration5to6
                          - information on changes necessary
                            to scripts when upgrading from
                            5.xx to 6.xx
  Date::Manip::Changes5	  - change log for Date::Manip 5.xx
  Date::Manip::Changes5to6- differences between version 5.xx
                            and 6.00 (including information
                            on upgrading)
  Date::Manip::Changes6	  - change log for Date::Manip 6.xx

  Date::Manip::Misc    	  - miscellaneous information about
                            Date::Manip (who should use it;
                            acknowledgements)
  Date::Manip::Problems	  - common problems and instructions
                            for reporting bugs
  Date::Manip::Examples	  - examples of how to use Date::Manip

=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