# 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](https://metacpan.org/pod/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](http://apidock.com/rails/v4.2.1/ActionView/Helpers/DateHelper/distance_of_time_in_words)

Ruby i18n library
[https://github.com/svenfuchs/i18n](https://github.com/svenfuchs/i18n)

# SEE ALSO

Github repository [https://github.com/mla/time-ago](https://github.com/mla/time-ago)

[Time::Duration](https://metacpan.org/pod/Time::Duration), [DateTime::Format::Human::Duration](https://metacpan.org/pod/DateTime::Format::Human::Duration), [Locale::TextDomain](https://metacpan.org/pod/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.

[![Build Status](https://travis-ci.org/mla/time-ago.svg?branch=master)](https://travis-ci.org/mla/time-ago)
