1Date::Manip::InterfacesU(s3e)r Contributed Perl DocumentaDtaitoen::Manip::Interfaces(3)
2
3
4

NAME

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

DESCRIPTION

9       There are three different ways to use Date::Manip .  A complete
10       description of each is included below.  They are:
11
12       Functional interface (version 5)
13           Date::Manip version 5 runs on very old versions of perl.  If you
14           need to use Date::Manip with a version of perl older than 5.10,
15           this is the only interface available.
16
17       Functional interface (version 6)
18           When Date::Manip was rewritten (version 6), it made use of some
19           features of perl 5.10 .  This is the recommended interface if you
20           are supporting a script that uses the functional interface, but
21           where a newer version of perl is available.
22
23       Object-oriented interface
24           The OO interface is the recommended interface wherever possible.
25           It is the only one with access to the full functionality of the
26           module.
27

VERSION 5 AND VERSION 6

29       Date::Manip version 5.xx was available for many years, but suffered
30       from several weaknesses.  It was slow, and did not handle timezones or
31       daylight saving time correctly.  It was written as a functional
32       interface, even though an object-oriented interface would have been
33       better.  It did have the advantage of running on very old versions of
34       perl (it is known to work on perl 5.6 and may work on even older
35       versions of perl).
36
37       Date::Manip version 6.00 was a complete rewrite of the module.  For
38       detailed information about the differences, please refer to the
39       Date::Manip::Changes5to6 document.  The rewrite was needed in order to
40       handle timezone operations, in addition to many other improvements
41       including much better performance and more robust parsing.
42
43       The rewrite made use of features introduced in perl 5.10 which made the
44       date parsing routines significantly cleaner.  In addition, the 6.xx
45       release was written as an object oriented set of modules which are much
46       more powerful than the older functional interface.  For backward
47       compatibility, a new functional interface was rewritten (which is
48       simply a set of wrapper functions which call the OO methods) which is
49       almost entirely backward compatible with the version 5.xx interface.
50
51       The Date::Manip distribution includes all three of these interfaces:
52       the older version 5 interface, and both the new OO interface and the
53       backward compatible functional interface.  Also, all three are
54       installed, so you can use whichever interface is appropriate.
55
56       Since there are three different interfaces available, choosing the
57       interface is the necessary.
58
59       If you are running on a system with a very old version of perl (older
60       than 5.10), the version 5 interface is your only option.
61
62       If you are on a system running a newer version of perl, but need to
63       support a script that was written using the functional interface, then
64       you can use the version 6 functional interface.
65
66       For everyone else, it is strongly recommended that you use the object-
67       oriented interface.
68
69       A more detailed description of each interface is included below.  If
70       you already know which interface you want to use, just go to the "SEE
71       ALSO" in Date::Manip section for documentation for each interface.
72

FUNCTIONAL INTERFACE (VERSION 5)

74       When using a version of perl older than 5.10, this is the only
75       interface available.  This interface is documented in the
76       Date::Manip::DM5 document.  This interface has several weaknesses that
77       need to be understood when using it:
78
79       Limited Support
80           The version 5 functional interface is no longer being developed,
81           and only limited support is available for it.
82
83           As of December 2012, no development will be done, and I will not
84           correct any remaining bugs in version 5.  If a patch is supplied by
85           someone else to fix bugs, I will apply it, provided it applies
86           cleanly, and the resulting code continues to pass all tests.  I
87           will not apply patches to add features.
88
89           I will continue to distribute version 5 for several years.  I do
90           not have a date in mind where version 5 will be removed.
91
92       Limited Time Zone Support
93           Time zone support is extremely limited, and is often incorrect. The
94           lack of time zone support was the primary reason for rewriting
95           Date::Manip.
96
97           The version 5 interface does not handle daylight saving time
98           changes correctly.
99
100       Performance Issues
101           Considerable time has been spent speeding up Date::Manip, and
102           fairly simple benchmarks show that version 6 is around twice as
103           fast as version 5.
104
105       Feel free to email me concerns and comments.
106

FUNCTIONAL INTERFACE (VERSION 6)

108       The version 6 functional interface is almost completely identical to
109       the version 5 functional interface, except that it uses the object-
110       oriented modules to do all the real work.
111
112       Time zone support is greatly improved, but is still somewhat limited.
113       Since the version 6 interface is backward compatible, dates do not
114       store time zone information in them, so the programmer is responsible
115       for keeping track of what time zone each date is in. If you want full
116       access to the time zone support offered in Date::Manip, you have to use
117       the object-oriented interface.
118
119       For the most part, scripts written for older versions of Date::Manip
120       will continue to work (and scripts written for the version 6 functional
121       interface will run with the version 5 interface), however in a few
122       cases, you may need to modify your scripts.  Please refer to the
123       Date::Manip::Migration5to6 document for a list of changes which may be
124       necessary.
125

OBJECT-ORIENTED INTERFACE

127       As of 6.00, Date::Manip consists of a set of OO modules. Each have
128       their own document (see the "SEE ALSO" in Date::Manip section).
129
130       The OO interface consists of the following modules: Date::Manip::Date,
131       Date::Manip::Delta, Date::Manip::Recur, Date::Manip::TZ, and
132       Date::Manip::Base.
133
134       The object-oriented interface is the only way to get the full
135       functionality of Date::Manip. It fully support time zones (and daylight
136       saving time).
137

SELECTING AN INTERFACE

139       If you are running an older version of perl, the version 5 functional
140       interface is the only one available to you, and it will automatically
141       be used.
142
143       If you are running a newer version of perl (5.10 or higher), you can
144       use the object-oriented modules by loading them directly, or you can
145       use a functional interface.
146
147       If you use a functional interface, it will default to the version 6
148       interface, but you can choose to run the version 5 interface in one of
149       three ways:
150
151       Using the OO interface
152           By including any of the following:
153
154              use Date::Manip::Date;
155              use Date::Manip::Delta;
156              use Date::Manip::Recur;
157              use Date::Manip::TZ;
158              use Date::Manip::Base;
159
160           you have access to the OO interface for the appropriate types of
161           objects.
162
163       Use the default functional interface
164           By including:
165
166              use Date::Manip;
167
168           in your script, one of the functional interfaces will be loaded.
169           If you are running a version of perl older than 5.10, it will
170           automatically be the version 5 interface.  If you are running a
171           newer version of perl, it will automatically load the version 6
172           interface.
173
174       DATE_MANIP environment variable
175           By setting the DATE_MANIP environment variable to 'DM5' before
176           running the perl script, the version 5 interface will be used.
177
178       Date::Manip::Backend variable
179           Alternately, you can set the Date::Manip::Backend variable to be
180           'DM5' before loading the module. Typically, this will be done in
181           the following way:
182
183              BEGIN {
184                   $Date::Manip::Backend = 'DM5';
185              }
186              use Date::Manip;
187
188       Once a functional interface is loaded, you cannot switch between the
189       version 5 and version 6 interfaces.
190

SEE ALSO

192       Date::Manip        - main module documentation
193

LICENSE

195       This script is free software; you can redistribute it and/or modify it
196       under the same terms as Perl itself.
197

AUTHOR

199       Sullivan Beck (sbeck@cpan.org)
200
201
202
203perl v5.32.0                      2020-12-15        Date::Manip::Interfaces(3)
Impressum