NAME

       Business::Hours - Calculate business hours in a time period

SYNOPSIS

         use Business::Hours;
         my $hours = Business::Hours->new();

         # Get a Set::IntSpan of all the business hours in the next week.
         # use the default business hours of 9am to 6pm localtime.
         $hours->for_timespan( Start => time(), End => time()+(86400*7) );

DESCRIPTION

       This module is a simple tool for calculating business hours in a time period.  Over time,
       additional functionality will be added to make it easy to calculate the number of business
       hours between arbitrary dates.

USAGE

   new
       Creates a new Business::Hours object.  Takes no arguments.

   business_hours HASH
       Gets / sets the business hours for this object.  Takes a hash (NOT a hash reference) of
       the form:

           my %hours = (
               0 => { Name     => 'Sunday',
                      Start    => 'HH:MM',
                      End      => 'HH:MM' },

               1 => { Name     => 'Monday',
                      Start    => 'HH:MM',
                      End      => 'HH:MM' },
               ....

               6 => { Name     => 'Saturday',
                      Start    => 'HH:MM',
                      End      => 'HH:MM' },
           );

       Start and End times are of the form HH:MM.  Valid times are from 00:00 to 23:59.  If your
       hours are from 9am to 6pm, use Start => '9:00', End => '18:00'.  A given day MUST have a
       start and end time OR may declare both Start and End to be undef, if there are no valid
       hours on that day.

       You can use the array Breaks to mark interruptions between Start/End (for instance lunch
       hour). It's an array of periods, each with a Start and End time:

           my %hours = (
               0 => { Name     => 'Sunday',
                      Start    => 'HH:MM',
                      End      => 'HH:MM',
                      Breaks  => [
                                    { Start    => 'HH:MM',
                                    End      => 'HH:MM' },
                                    { Start    => 'HH:MM',
                                    End      => 'HH:MM' },
                                  ],

               1 => { Name     => 'Monday',
                      Start    => 'HH:MM',
                      End      => 'HH:MM' },
               ....

               6 => { Name     => 'Saturday',
                      Start    => 'HH:MM',
                      End      => 'HH:MM' },
           );

       Note that the ending time is really "what is the first minute we're closed.  If you
       specify an "End" of 18:00, that means that at 6pm, you are closed.  The last business
       second was 17:59:59.

       As well, you can pass information about holidays using key 'holidays' and an array
       reference value, for example:

           $hours->business_hours(
               0 => { Name     => 'Sunday',
                      Start    => 'HH:MM',
                      End      => 'HH:MM' },
               ....
               6 => { Name     => 'Saturday',
                      Start    => 'HH:MM',
                      End      => 'HH:MM' },

               holidays => [qw(01-01 12-25 2009-05-08)],
           );

       Read more about holidays specification below in holidays.

   preprocess_business_hours
       Checks and transforms business hours data. No need to call it.

   holidays ARRAY
       Gets / sets holidays for this object. Takes an array where each element is ether 'MM-DD'
       or 'YYYY-MM-DD'.

       Specification with year defined may be required when a holiday matches Sunday or Saturday.
       In many countries days are shifted in such case.

       Holidays can be set via business_hours method as well, so you can use this feature without
       changing your code.

   for_timespan HASH
       Takes a hash with the following parameters:

       Start
           The start of the period in question in seconds since the epoch

       End The end of the period in question in seconds since the epoch

       Returns a Set::IntSpan of business hours for this period of time.

   between START, END
       Returns the number of business seconds between START and END Both START and END should be
       specified in seconds since the epoch.

       Returns -1 if START or END are outside the calculated business hours.

   first_after START
       Returns START if START is within business hours.  Otherwise, returns the next business
       second after START.  START should be specified in seconds since the epoch.

       Returns -1 if it can't find any business hours within thirty days.

   add_seconds START, SECONDS
       Returns a time SECONDS business seconds after START.  START should be specified in seconds
       since the epoch.

       Returns -1 if it can't find any business hours within thirty days.

BUGS

       Yes, most likely.  Please report them to bug-business-hours@rt.cpan.org.

AUTHOR

       Jesse Vincent, jesse@cpan.org

COPYRIGHT

       Copyright 2003-2008 Best Practical Solutions, LLC.

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

       The full text of the license can be found in the LICENSE file included with this module.