# Copyright (c) 2008-2010 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::Obj - Base class for Date::Manip objects

=head1 SYNOPSIS

The Date::Manip::Obj class is the base class used for the following
Date::Manip classes:

   Date::Manip::Base
   Date::Manip::TZ
   Date::Manip::Date
   Date::Manip::Delta
   Date::Manip::Recur

This module is not intended to be called directly and performs no
useful function by itself. Instead, use the various derived classes
which inherit from it.

=head1 DESCRIPTION

This module contains a set of methods used by all Date::Manip
classes listed above.

You should be familiar with the Date::Manip::Objects and
Date::Manip::Config documentation.

In the examples below, Date::Manip::Date objects will be used
as examples, but (unless otherwise stated), all of the classes
listed above have the same methods, and work in the same fashion.

=head1 METHODS FOR CREATING OBJECTS

=over 4

=item B<new>

   $date = new Date::Manip::Date;
   $date = new Date::Manip::Date \@opts;

   $date = new Date::Manip::Date $string;
   $date = new Date::Manip::Date $string,\@opts;

In order to create the first Date::Manip object, use any of the forms
listed above. They will all create a new Date::Manip::Date object
(with new Date::Manip::Base, and Date::Manip::TZ objects embedded in
it).

The Date::Manip::Date, Date::Manip::Delta, and Date::Manip::Recur
classes work in exactly the same way.

A set of options (described in the Date::Manip::Config documentation)
can be passed to the object to set configuration variables.

In addition, a string can be passed in which will be parsed to form
the initial date stored in the object. Strings can also be passed in
to the Date::Manip::Delta and Date::Manip::Recur objects which will be
parsed to form initial values. In all cases, refer to the parse method
of the class.

   $dmt = new Date::Manip::TZ;
   $dmt = new Date::Manip::TZ \@opts;

If the first Date::Manip object you need is a Date::Manip::TZ object,
use either of the above calls. This will also create a Date::Manip::Base
object which will be embedded in the Date::Manip::TZ object.

A set of options can be passed in as well, but there is no option
for passing in a string.

   $dmb = new Date::Manip::Base;
   $dmb = new Date::Manip::Base \@opts;

If you work with Date::Manip::Base objects directly, no other object
will be created. The options can be passed in here as well.

Once a Date::Manip::Date object (or any object in any other
Date::Manip class) is created, one of calls below should be used in
order to preserve cached data in the interest of performance and
memory usage.

   $date = new Date::Manip::Date $obj;
   $date = new Date::Manip::Date $obj,\@opts;

   $date = new Date::Manip::Date $obj,$string;
   $date = new Date::Manip::Date $obj,$string,\@opts;

$obj can be an object from any of the Date::Manip classes, but in the
interest of making efficient use of cached data, you should pass in
the highest level object available.

In other words, you should always pass in a Date::Manip::Date,
Date::Manip::Delta, or Date::Manip::Recur object if you have one.
In their absence, pass in a Date::Manip::TZ object. Pass in a
Date::Manip::Base object only if that is the only Date::Manip
object available.

The one caveat is if you are working with multiple configurations
as described in the Date::Manip::Objects document. In that case,
additional care should be taken to make sure that the correct object
is passed in.

If $obj is a Date::Manip::Date object, these lines can be
expressed equivalently as:

   $date = $obj->new();
   $date = $obj->new(\@opts);

   $date = $obj->new($string);
   $date = $obj->new($string,\@opts);

If @opts is passed in, new Date::Manip::Base and Date::Manip::TZ
objects will be created with the configuration specified, so you should
only do this if you explicitly want to work with multiple configurations.

If you want to modify an existing configuration, you must use the
config method described below.

=item B<new_config>

   $obj2 = $obj1->new_config();
   $obj2 = $obj1->new_config($string);
   $obj2 = $obj1->new_config($string,@opts);
   $obj2 = $obj1->new_config(@opts);

This creates a new instance with a new Date::Manip::Base object and a
separate set of config options (even if no config options are
included).

=item B<new_date>

=item B<new_delta>

=item B<new_recur>

   $date = $obj->new_date();
   $date = $obj->new_date($string);
   $date = $obj->new_date($string,@opts);
   $date = $obj->new_date(@opts);

These create a new instance of the specified object. In this case, $obj
can be any of the Date::Manip classes, so a date can be created from a
delta:

   $delta = new Date::Manip::Delta;
   $date  = $delta->new_date();

=back

=head1 OTHER METHODS

=over 4

=item B<base>

   $dmb = $obj->base();

This returns the Date::Manip::Base object associated with the
given object.

=item B<config>

   $obj->config($var1,$val1,$var2,$val2,...);

This will set the value of any configuration variables. Please refer to the
Date::Manip::Config manual for a list of all configuration variables and their
description.

=item B<err>

   $err = $obj->err();

This will return the full error message if the previous operation failed
for any reason.

   $obj->err(1);

will clear the error code.

=item B<is_date>

=item B<is_delta>

=item B<is_recur>

   $flag = $obj->is_date();

Returns 0 or 1, depending on the object. For example, a Date::Manip::Date
object returns 1 with the is_date method, and 0 for the other two.

=item B<tz>

   $dmb = $obj->tz();

This returns the Date::Manip::TZ object associated with the
given object.

=item B<version>

   $vers = $obj->version($flag);

This returns the version of Date::Manip.

If $flag is passed in, and $obj is not a Date::Manip::Base object, the
version and timezone information will be passed back.

=back

=head1 KNOWN BUGS

None known.

=head1 BUGS AND QUESTIONS

Please refer to the Date::Manip::Problems documentation for
information on submitting bug reports or questions to the author.

=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
