DateTime::NaturalLanguage - Perl extension for converting seconds to "natural" time values.


  use DateTime::NaturalLanguage;
  my $foo = DateTime::NaturalLanguage->new();
  print $foo->parse_seconds(60);                # prints "1 minute"
  my $bar = DateTime::NaturalLanguage->new(day => 'sleep',days => 'sleeps');
  print $bar->parse_seconds(86400);             # prints "1 sleep"
  print $bar->parse_seconds(86400*2);   # prints "2 sleeps"
  my $foobar = DateTime::NaturalLanguage->new(display => 3);
  print $foobar->parse_seconds(3661);   # prints "1 hour, 1 minute, 1 second"
  print $foobar->parse_seconds(3661,2); # prints "1 hour, 1 minute"


This module is for converting raw second values(like those returned by localtime()) into fuzzier, more "natural" values - like minutes, hours, and days. It allows you to convert a given number of seconds into a natural value - 3661, for example, becomes something like "1 hour, 1 minute" (or "1 hour, 1 minute, 1 second" if you send a different display value).

This module is licensed under the GPL. See the LICENSE section below for more details.



Call new() to create a new DateTime::NaturalLanguage object:

        my $t = DateTime::NaturalLanguage->new();

You can pass values into new() to specify how many items to display after converting a second-value(from largest to smallest), along with substitutions for the words it uses by default. See DEFAULTS for more information on what the default words are.


parse_seconds() takes a seconds value, along with an (optional) display value - which defines how many converted elements to display. It is called on already created DateTime::NaturalLanguage objects.

        my $converted_time = $t->parse_seconds(3661,2);


There are a number of default values that get set when DateTime::NaturalLanguage objects are created - most of them are words.


The default words that DateTime::NaturalLanguage uses are all english - they are "second,seconds,minute,minutes,hour,hours,day,days,week,weeks,year,years". To change any of them, simply change them in your call to new():

        my $t = DateTime::NaturalLanguage->new(second => "foo", seconds => "bar");
        print $t->parse_seconds(1);             # prints "1 foo"
        print $t->parse_seconds(2);             # prints "2 bar"


The 'display' attribute determines how many elements 'wide' the string returned from parse_seconds() is. Its default is 2, and it can be set either at initialization, or in the call to parse_seconds:

        my $t = DateTime::NaturalLanguage->new(display => 1);
        print $t->parse_seconds(3661);          # prints "1 hour"
        print $t->parse_seconds(3661,2);        # prints "1 hour, 1 minute"
        print $t->parse_seconds(3661,3);        # prints "1 hour, 1 minute, 1 second"


The order attribute defines the order results are displayed in. The default is descending order(largest natural value(years) to smallest(seconds)). However, it can be set to ascending or descending, respectively.It is set at initialization:

        my $t = DateTime::NaturalLanguage->new(order="asc");
        print $t->parse_seconds(3661);          # prints "1 second, 1 hour"
        my $t = DateTime::NaturalLanguage->new(order="desc");   # this is default behavior
        print $t->parse_seconds(3661);          # prints "1 hour, 2 minute"


Luke Hutscal <<gt>


Copyright (C) 2007 by Luke Hutscal <<gt>. All rights reserved.

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