NAME

       Badger::Duration - simple class for representing durations

SYNOPSIS

           use Badger::Duration 'Duration';

           my $d = Duration('7 days 4 hours 20 minutes');

           print "$d is ", $d->seconds, " seconds\n";

DESCRIPTION

       This is a simple module for parsing durations.

       It is ideally suited for things like the calculation of expiry times (e.g.  for cookies,
       items in a cache, etc) allowing them to be specified in human-friendly format, e.g. "4
       minutes 20 seconds" (or various alternatives).

EXPORTABLE SUBROUTINES

   DURATION
       This is a shortcut alias to "Badger::Duration".

           use Badger::Duration 'DURATION';

           my $duration = DURATION->new(
               hours   => 4,
               minutes => 20,
           );              # same as Badger::Duration->new(...);

   Duration()
       This subroutine returns the name of the "Badger::Duration" class when called without
       arguments. Thus it can be used as an alias for "Badger::Duration" as per DURATION.

           use Badger::Duration 'Duration';

           my $duration = Duration->new(...);  # same as Badger::Duration->new(...);

       When called with arguments, it creates a new "Badger::Duration" object.

           my $duration = Duration(...);       # same as Badger::Duration->new(...);

METHODS

       The following methods are defined in addition to those inherited from the
       Badger::Comparable and Badger::Base base classes.

   new()
       Constructor method to create a new "Badger::Duration" object.  The duration can be
       specified as a single "duration" parameter.

           my $d = Badger::Duration->new(
               duration => '4 minutes 20 seconds'
           );

       The duration string can contain any number of "<number> <duration>" sequences separate by
       whitespace, commas or the word "and".  The following  are all valid:

           4 minutes 20 seconds
           4 minutes,20 seconds
           4 minutes, 20 seconds
           4 minutes and 20 seconds

       The canonical names for durations are: "year", "month", "day", "hour", "minute" and
       "second".  The following aliases may be used:

       second
               s sec secs seconds

       minute
               m min mins minutes

       hour
               h hr hrs hours

       day
               d days

       week
               w wk weeks

       month
               M mon mons months

       year
               y yr yrs years

       A duration can also be specified using named parameters:

           my $d = Badger::Duration->new(
               minutes => 4,
               seconds => 20,
           );

       Or by reference to a hash array:

           my $d = Badger::Duration->new({
               minutes => 4,
               seconds => 20,
           });

       This can also be specified as an explicit "duration" option if you prefer:

           my $d = Badger::Duration->new(
               duration => {
                   minutes => 4,
                   seconds => 20,
               }
           );

       In all cases, any of the valid aliases for durations may be used, e.g.

           my $d = Badger::Duration->new(
               h => 1,
               m => 4,
               s => 20,
           );

   duration()
       Returns a reference to a hash array containing the canonical values of the duration.

           my $d = Badger::Duration->new(
               duration => '4 hours 20 minutes'
           );
           my $h = $d->duration;
           print $h->{ hour   };     # 4
           print $h->{ minute };     # 20

   seconds()
       Returns the total number of seconds for the duration.

           my $d = Badger::Duration->new(
               duration => '4 hours 20 minutes'
           );
           print $d->seconds;      # 15600

   compare($that)
       This method is defined to enable the functionality provided by the Badger::Comparable base
       class.

           use Badger::Duration 'Duration';

           my $d1 = Duration('4 hours 20 minutes');
           my $d2 = Duration('270 minutes');

           if ($d1 < $d2) {
               # ...do something...
           }

   text()
       Returns a canonical text representation of the duration.

           use Badger::Duration 'Duration';
           my $d1 = Duration('4 hrs 20 mins');
           print $d1->text;            # 4 hours 20 minutes

       Note that the units will be pluralised appropriately.  e.g.

           1 hour 1 minute 1 second
           2 hours 2 minutes 2 seconds

       This method is bound to the auto-stringification operation which is a fancy way of saying
       it gets called automatically when you simply print a "Badger::Duration" object.

           print $d1;                  # 4 hours 20 minutes

INTERNAL METHODS

   init($config)
       Object initialisation method called automatically by the new() constructor method
       inherited from the Badger::Base base class.

   parse_text($text)
       Internal method to parse a text string and return a hash reference of canonical values.

   parse_hash($hash)
       Internal method to parse a hash reference and return another hash reference of canonical
       values (e.g. after mapping aliases to canonical names).

   count_seconds($hash)
       Counts the total number of seconds in a duration passed by reference to a hash array.

AUTHOR

       Andy Wardley <http://wardley.org>

COPYRIGHT

       Copyright (C) 2013 Andy Wardley.  All Rights Reserved.

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