view release on metacpan or  search on metacpan

lib/Date/Calc/Object.pod  view on Meta::CPAN

This sets our handler to take care of all automatic conversions,
such as needed when comparing dates or when interpolating a string
in double quotes which contains a date object.

To deactivate a handler, simply pass a valid format number to the
method in question, e.g.:

  Date::Calc->number_format(0);
  Date::Calc->delta_format(2);
  Date::Calc->date_format(3);

When calling the "number()" or "string()" method explicitly, you can
pass a different format number (than the global setting), like this:

  $number = $date->number(2);
  $string = $date->string(1);

You can also pass a handler's reference, like so:

  $number = $date->number(\&handler);
  $string = $date->string(\&handler);

This overrides the global setting and the individual object's local
setting for the duration of the call of "number()" or "string()"
(but doesn't change the global or local settings themselves).

Moreover, you can also define individual overrides for the date and
the delta vector formats (but not the number format) for individual
objects, e.g.:

  $date->delta_format(1);
  $date->date_format(2);

  $date->delta_format(\&handler);
  $date->date_format(\&handler);

In order to deactivate an individual handler for an object, and/or
in order to deactivate any override altogether (so that the global
settings apply again), you have to pass "undef" explicitly to the
method in question:

  $date->delta_format(undef);
  $date->date_format(undef);

You can also define a language for individual objects (see the
next section immediately below for more details).

If such an individual language override has been set, it will
be passed to your callback handlers as the third parameter (in
the case of "string" conversions, but not in the case of "number"
conversions).

Otherwise, the global settings as defined by C<Language($lang);>
or C<Date::Calc->language($lang);> will be passed to your handler.

=item *

Languages

Note that this module is completely transparent to the setting
of a language in "Date::Calc". This means that you can choose a
language in "Date::Calc" (with the "Language()" function) and all
dates subsequently printed by this module will automatically be
in that language - provided that you use the built-in formats of
this module, or that you pass the third parameter of the callback
funtion to the funtions of the "Date::Calc" module which accept it.

However, this global language setting can be overridden for
individual date (or delta) objects by using the B<OBJECT> method

    $oldlang = $date->language($newlang);

(The global setting is not altered by this in any way.)

In order to deactivate such an individual language setting
(so that the global setting applies again), simply pass the
value "undef" explicitly to the "language()" object method:

  $date->language(undef);

The B<CLASS> method

    $oldlang = Date::Calc->language($newlang);

is just a convenient wrapper around the "Language()" function,
which allows you to enter language numbers (as returned by the
"Decode_Language()" function) or strings (as returned by the
"Language_to_Text()" function), whatever you prefer.

The "language()" method (both class and object) always returns
the B<NAME> (one of "C<Language_to_Text(1..Languages())>") of
the current setting (and never its number).

BEWARE that in order to avoid possible conflicts between threads
or modules running concurrently, you should NEVER use the global
function C<Language($lang);> or the class method
C<Date::Calc->language($lang);> in this module!

The class method is retained only for backward compatibility
and for convenience in stand-alone applications when it is
guaranteed that no such conflicts can arise.

But you should probably avoid to use global settings anyway,
because it may be especially troublesome to fix your code later
when suddenly the need arises to use your code with threads
or when your code needs to use other modules which also use
"Date::Calc" (with different settings!).

By exclusively using local settings, you are making your code
invulnerable against other, concurrent modules also using
"Date::Calc" which still use global settings.

=item *

Exported Functions

The "Date::Calc::Object" package imports ":all" functions exported
by the "Date::Calc" module and re-exports them, for conveniency.

This allows you to write