NAME

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

SYNOPSIS

  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"

DESCRIPTION

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.

METHODS

new()

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()

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);
        

CONFIGURATION

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

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"

display

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"

order

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"

AUTHOR

Luke Hutscal <hybrid.basis@gmail.com<gt>

COPYRIGHT AND LICENSE

Copyright (C) 2007 by Luke Hutscal <hybrid.basis@gmail.com<gt>. All rights reserved.

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

cpanm DateTime::NaturalLanguage

perl -MCPAN -e shell
install DateTime::NaturalLanguage