NAME
   Time::Ago - Approximate duration in words

VERSION
   version 0.07

SYNOPSIS
     use Time::Ago;

     print Time::Ago->in_words(0), "\n";
     # prints "less than a minute"

     print Time::Ago->in_words(3600 * 4.6), "\n";
     # prints "about 5 hours"

     print Time::Ago->in_words(86400 * 360 * 2), "\n";
     # prints "almost 2 years"

     print Time::Ago->in_words(86400 * 365 * 11.3), "\n";
     # prints "over 11 years"

DESCRIPTION
   Given a duration, in seconds, returns a readable approximation. This a
   Perl port of the time_ago_in_words() helper from Rails.

   From Rails' docs:

     0 <-> 29 secs
       less than a minute

     30 secs <-> 1 min, 29 secs
       1 minute

     1 min, 30 secs <-> 44 mins, 29 secs
       [2..44] minutes

     44 mins, 30 secs <-> 89 mins, 29 secs
       about 1 hour

     89 mins, 30 secs <-> 23 hrs, 59 mins, 29 secs
       about [2..24] hours

     23 hrs, 59 mins, 30 secs <-> 41 hrs, 59 mins, 29 secs
       1 day

     41 hrs, 59 mins, 30 secs <-> 29 days, 23 hrs, 59 mins, 29 secs
       [2..29] days

     29 days, 23 hrs, 59 mins, 30 secs <-> 44 days, 23 hrs, 59 mins, 29 secs
       about 1 month

     44 days, 23 hrs, 59 mins, 30 secs <-> 59 days, 23 hrs, 59 mins, 29 secs
       about 2 months

     59 days, 23 hrs, 59 mins, 30 secs <-> 1 yr minus 1 sec
       [2..12] months

     1 yr <-> 1 yr, 3 months
       about 1 year

     1 yr, 3 months <-> 1 yr, 9 months
       over 1 year

     1 yr, 9 months <-> 2 yr minus 1 sec
       almost 2 years

     2 yrs <-> max time or date
       (same rules as 1 yr)

METHODS
   in_words
         Time::Ago->in_words(30); # returns "1 minute"
         Time::Ago->in_words(3600 * 24 * 365 * 10); # returns "about 10 years"

       Given a duration, in seconds, returns a readable approximation in
       words.

       If an include_seconds parameter is supplied, durations under one
       minute generate more granular phrases:

         foreach (4, 9, 19, 39, 59) {
           print Time::Ago->in_words($_, include_seconds => 1), "\n";
         }

         # less than 5 seconds
         # less than 10 seconds
         # less than 20 seconds
         # half a minute
         # less than a minute

       As a convenience, if the duration is an object with an epoch()
       interface (as provided by Time::Piece or DateTime), the current time
       minus the object's epoch() seconds is used.

       Passing the duration as a DateTime::Duration instance is also
       supported.

LOCALIZATION
   Locale::TextDomain is used for localization. Translations were taken
   from the Ruby i18n library.

   Currently English, French, German, Italian, Japanese, Russian, and
   Spanish translations are available. Contact me if you need another
   language.

   See Locale::TextDomain for how to specify a language.

     #!/usr/bin/env perl

     use strict;
     use warnings;
     use open qw/ :std :utf8 /;
     use POSIX ':locale_h';
     use Time::Ago;

     my $secs = 86400 * 365 * 10.4;

     foreach (qw/ en fr de it ja ru es /) {
       setlocale(LC_ALL, '');
       $ENV{LANGUAGE} = $_;
       print Time::Ago->in_words(86400 * 365 * 10.4), "\n";
     }

   Output:

     over 10 years
     plus de 10 ans
     vor mehr als 10 Jahren
     oltre 10 anni
     10年以上
     больше 10 лет
     más de 10 años

BUGS
   The rails' implementation includes some logic for leap years that is not
   implemented here.

CREDITS
   Ruby on Rails DateHelper
   <http://apidock.com/rails/v4.2.1/ActionView/Helpers/DateHelper/distance_
   of_time_in_words>

   Ruby i18n library <https://github.com/svenfuchs/i18n>

SEE ALSO
   Github repository <https://github.com/mla/time-ago>

   Time::Duration, DateTime::Format::Human::Duration, Locale::TextDomain

AUTHOR
   Maurice Aubrey <[email protected]>

COPYRIGHT AND LICENSE
   This software is copyright (c) 2015 by Maurice Aubrey.

   This is free software; you can redistribute it and/or modify it under
   the same terms as the Perl 5 programming language system itself.