NAME

Time::Duration::LocaleObject - time duration string in language chosen by an object

SYNOPSIS

 use Time::Duration::LocaleObject;
 my $tdl = Time::Duration::LocaleObject->new;
 print "next update: ", $tdl->duration(120) ,"\n";

DESCRIPTION

Time::Duration::LocaleObject is an object-oriented wrapper around possible language-specific Time::Duration modules. The methods correspond to the function calls in those modules. The target module is established from the user's locale, or can be set explicitly.

Most of the time this module is unnecessary. A single global language choice based on the locale is usually enough, as per Time::Duration::Locale. But some OOPery is not much more trouble than plain functions and it's handy if your program works with multiple locales simultaneously (something fairly painful with POSIX global-only things).

METHODS

In the following methods TDLObj means either a LocaleObject instance or the class name Time::Duration::Locale.

    print Time::Duration::LocaleObject->ago(120),"\n";
    print $tdl->ago(120),"\n";

The class name form operates on a global singleton instance which is used by Time::Duration::Locale.

Creation

$tdl = Time::Duration::LocaleObject->new (key => $value, ...)

Create and return a new LocaleObject. Optional key/value pairs can give an explicit module or language to be applied per the "Settings Methods" below.

    # locale settings
    my $tdl = Time::Duration::LocaleObject->new;

    # explicit language
    my $tdl = Time::Duration::LocaleObject->new (language => 'ja');

    # explicit language specified by module
    my $tdl = Time::Duration::LocaleObject->new
                (module => 'Time::Duration::en_PIGLATIN');

Duration Methods

As per the Time::Duration functions. Any new future functions should work too since methods pass through transparently.

TDLObj->later ($seconds, [$precision])

TDLObj->later_exact ($seconds, [$precision])

TDLObj->earlier ($seconds, [$precision])

TDLObj->earlier_exact ($seconds, [$precision])

TDLObj->ago ($seconds, [$precision])

TDLObj->ago_exact ($seconds, [$precision])

TDLObj->from_now ($seconds, [$precision])

TDLObj->from_now_exact ($seconds, [$precision])

TDLObj->duration ($seconds, [$precision])

TDLObj->duration_exact ($seconds, [$precision])

TDLObj->concise ($str)

For example,

    # instance method using selected language
    my $tdl = Time::Duration::LocaleObject->new (language => 'ja');
    print $tdl->duration(120),"\n";

    # class method using locale language
    print Time::Duration::LocaleObject->later(10),"\n";

Settings Methods

$lang = TDLObj->language ()

$module = TDLObj->module ()

TDLObj->language ($lang)

TDLObj->module ($module)

Get or set the language to use, either in the form of a language code like "en" or "ja", or a module name like "Time::Duration" or "Time::Duration::ja".

A setting undef means no language has yet been selected. When setting the language the necessary module must exist and is loaded if not already loaded.

TDLObj->setlocale ()

Set the language according to the user's locale settings. The current implementation uses I18N::LangTags::Detect.

This is called automatically by the duration methods above if no language has otherwise been set, so there's normally no need to explicitly setlocale. Call it if you change the environment variables and want TDLObj to follow.

OTHER NOTES

In the current implementation TDLObj->can() checks whether its target module has such a function. This is probably what you want, though if you later select a different language in the TDLObj object then it might suddenly reveal extra funcs in another module.

A TDLObj->can() subr returned is stored as a method in the Time::Duration::LocaleObject symbol table. This caches it ready for future can() calls and avoids AUTOLOAD if invoked directly. Not certain if this is worth the trouble, but it's probably sensible to have repeated can() calls return the same coderef each time.

ENVIRONMENT VARIABLES

LANGUAGE, LANG, LC_MESSAGES etc, as per I18N::LangTags::Detect.

SEE ALSO

Time::Duration::Locale, Time::Duration, Time::Duration::es, Time::Duration::fr, Time::Duration::id, Time::Duration::ja, Time::Duration::pl, Time::Duration::pt, Time::Duration::sv, I18N::LangTags::Detect

HOME PAGE

http://user42.tuxfamily.org/time-duration-locale/index.html

COPYRIGHT

Copyright 2009, 2010, 2011, 2013, 2016, 2017 Kevin Ryde

Time-Duration-Locale is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3, or (at your option) any later version.

Time-Duration-Locale is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with Time-Duration-Locale. If not, see <http://www.gnu.org/licenses/>.

cpanm Time::Duration::Locale

perl -MCPAN -e shell
install Time::Duration::Locale