NAME

Time::Verbal - Convert time distance to words.

VERSION

version 1.0.1

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) 2017 by Kang-min Liu.

This is free software, licensed under:

  The MIT (X11) License

cpanm Time::Verbal

perl -MCPAN -e shell
install Time::Verbal