The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
DateTime-NaturalLanguage-0.02
/ DateTime::NaturalLanguage

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

DEFAULTS

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

default 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"

other default values

The only other default value is display - it 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"

INSTALLATION

To install this module type the following:

        perl Makefile.PL
        make
        make test
        make install

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.