/ 
Time-Verbal-1.1.0
River stage zero No dependents
/ Time::Verbal

NAME

Time::Verbal - Convert time distance to words.

VERSION

version 1.1.0

SYNOPSIS

use Time::Verbal;

my $now = time;

# Print the distance of two times in words.
say Time::Verbal::distance($now, $now);
#=> less the a minute

# The second argument must not be less the the first one.
say Time::Verbal::distance($now, $now + 4200);
#=> about 1 hour

DESCRIPTION

Time::Verbal trys to represent time-related info as verbal text.

METHODS

new( key => value, ... )

The constructor. You may pass arguments as key-value pairs.

The valid keys are:

- locale
- i18n_dir

They are both optional, and are both for i18n purpose.

The value of locale should be one of the ISO language code. The valid ones for the release are:

ar bg bn-IN bs ca cy da de-AT de-CH de dsb el en-AU en-GB en-US eo
es-AR es-CL es-CO es-MX es-PE es et eu fa fi fr-CA fr-CH fr fur gl-ES
gsw-CH he hi-IN hi hr hsb hu id is it ja ko lo lt lv mk mn nb nl nn pl
pt-BR pt-PT rm ro ru sk sl sr-Latn sr sv-SE sw tr uk vi zh-CN zh-TW

However, you may pass something not in this list as long as you also provide a path (string) for i18n_dir pointing to a directory with JSON files that are recongized by Locale::Wolowitz.

distance($from_time, $to_time)

Returns the distance of two timestamp in words.

The possible outputs are:

- less than a minute
- 1 minute
- 3 minutes
- about 1 hour
- 6 hours
- yesterday
- 177 days
- over a year

For time distances larger the a year, it'll always be "over a year".

The returned string is a localized string if the object is constructed with locale parameter:

my $tv = Time::Verbal->new(locale => "zh-TW");
say $tv->distance(time, time + 3600);
#=> 一小時

Internally l10n is done with Locale::Wolowitz, which means the dictionary files are just a bunch of JSON text files that you can locate with this command:

perl -MTime::Verbal -E 'say Time::Verbal->i18n_dir'

In case you need to provide your own translation JSON files, you may specify the value of i18n_dir pointing to your own dir:

my $tv = Time::Verbal->new(locale => "xx", i18n_dir => "/app/awesome/i18n");

Your should start by copying and modify one of the JSON file under Time::Verbal-i18n_dir>. The JSON file should be named after the language code as a good convention, but there is no strict rule for that. As a result, you may create your own language code like "LOLSPEAK" by first creating the translation file <LOLSPEAK.json>, and use "LOLSPEAK" as the value of locale attribute of the object.

Current translations are imported from the rails-i18n project at https://github.com/svenfuchs/rails-i18n

AUTHOR

Kang-min Liu <gugod@gugod.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2020 by Kang-min Liu.

This is free software, licensed under:

The MIT (X11) License