NAME
    Time::Ago - Approximate duration in words

VERSION
    version 1.00

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.

    Currently Arabic, Dutch, 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($secs), "\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 <maurice.aubrey@gmail.com>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2017 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.