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 <maurice.aubrey@gmail.com>

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.

