lib/Time/R.pm - metacpan.org

use strict;
use warnings;
package Time::R;
$Time::R::VERSION = '0.024';
# ABSTRACT: Handle recurrences.

use overload (
    '""' => sub { shift->to_string; },
    bool => sub { 1 },
    fallback => 1,
);

use Carp qw/ croak /;
use Time::C;
use Time::C::Sentinel;
use Function::Parameters qw/ :strict /;



method new ($c: $start, :$end = undef, :$years = 0, :$months = 0, :$weeks = 0, :$days = 0, :$hours = 0, :$minutes = 0, :$seconds = 0) {
    bless({
        start   => $start,
        end     => $end,
        years   => $years,
        months  => $months,
        weeks   => $weeks,
        days    => $days,
        hours   => $hours,
        minutes => $minutes,
        seconds => $seconds,
    }, $c)->_validate_start($start);
}

method _validate_start ($r: $new_start) {
    croak "->start(): Not a Time::C object: $new_start" unless ref $new_start and $new_start->isa('Time::C');

    return $r;
}



method start ($r: $new_start = undef) :lvalue {
    my $setter = sub {
        $r->_validate_start($_[0])->{start} = $_[0];

        return $r if defined $new_start;
        return $_[0];
    };

    return $setter->($new_start) if defined $new_start;

    sentinel value => $r->{start}, set => $setter;
}


method current ($r: $new_current = undef) :lvalue {
    my $current = $r->{current} // $r->start->clone();

    my $setter = sub {
        $r->{current} = $_[0];

        return $r if defined $new_current;
        return $_[0];
    };

    return $setter->($new_current) if defined $new_current;

    sentinel value => $current, set => $setter;
}


method end ($r: $new_end = undef) :lvalue {
    my $setter = sub {
        $r->{end} = $_[0];

        return $r if defined $new_end;
        return $_[0];
    };

    return $setter->($new_end) if defined $new_end;

    sentinel value => $r->{end}, set => $setter;
}


method years ($r: $new_years = undef) :lvalue {
    my $setter = sub {
        return $r->{years} = $_[0];
    };

    if (defined $new_years) { $setter->($new_years); return $r; }

    sentinel value => $r->{years}, set => $setter;
}


method months ($r: $new_months = undef) :lvalue {
    my $setter = sub {
        return $r->{months} = $_[0];
    };

    if (defined $new_months) { $setter->($new_months); return $r; }

    sentinel value => $r->{months}, set => $setter;
}


method weeks ($r: $new_weeks = undef) :lvalue {
    my $setter = sub {
        return $r->{weeks} = $_[0];
    };

    if (defined $new_weeks) { $setter->($new_weeks); return $r; }

    sentinel value => $r->{weeks}, set => $setter;
}


method days ($r: $new_days = undef) :lvalue {
    my $setter = sub {
        return $r->{days} = $_[0];
    };

    if (defined $new_days) { $setter->($new_days); return $r; }

    sentinel value => $r->{days}, set => $setter;
}


method hours ($r: $new_hours = undef) :lvalue {
    my $setter = sub {
        return $r->{hours} = $_[0];
    };

    if (defined $new_hours) { $setter->($new_hours); return $r; }

    sentinel value => $r->{hours}, set => $setter;
}


method minutes ($r: $new_minutes = undef) :lvalue {
    my $setter = sub {
        return $r->{minutes} = $_[0];
    };

    if (defined $new_minutes) { $setter->($new_minutes); return $r; }

    sentinel value => $r->{minutes}, set => $setter;
}


method seconds ($r: $new_seconds = undef) :lvalue {
    my $setter = sub {
        return $r->{seconds} = $_[0];
    };

    if (defined $new_seconds) { $setter->($new_seconds); return $r; }

    sentinel value => $r->{seconds}, set => $setter;
}



method next ($r:) {
    my $c = $r->current;
    my $n = $r->start->clone;

    if ($r->years) {
        my $i = 1;
        LOOP: {
            my $y = $n->clone;
            $y->year += ($r->years * $i++);
            redo LOOP if $y->epoch <= $c->epoch;

            $n = $y;
        }
    }
    if ($r->months) {
        my $i = 1;
        LOOP: {
            my $m = $n->clone;
            $m->month += ($r->months * $i++);
            redo LOOP if $m->epoch <= $c->epoch;

            $n = $m;
        }
    }
    if ($r->weeks)   { do { $n->week   += $r->weeks   } until $n->epoch > $c->epoch; }
    if ($r->days)    { do { $n->day    += $r->days    } until $n->epoch > $c->epoch; }
    if ($r->hours)   { do { $n->hour   += $r->hours   } until $n->epoch > $c->epoch; }
    if ($r->minutes) { do { $n->minute += $r->minutes } until $n->epoch > $c->epoch; }
    if ($r->seconds) { do { $n->second += $r->seconds } until $n->epoch > $c->epoch; }
    return undef if defined $r->end and $n->epoch > $r->end->epoch;

    $r->current = $n;
    return $n;
}


method upcoming ($r:) {
    my $c = $r->current->clone;
    $r->latest();
    my $n = $r->next();
    $r->current = $c if not defined $n;
    return $n;
}


method latest ($r:) {
    my @until = $r->reset->until(Time::C->now($r->start->tz));

    return $until[-1];
}


method until ($r: $end) {
    croak "\$end is not a Time::C object" unless ref $end and $end->isa('Time::C');
    $end = $r->end if defined $r->end and $r->end->epoch < $end->epoch;

    my @results = $r->current();
    push @results, $_ while ($_ = $r->next() and $_->epoch <= $end->epoch);
    $r->current = $results[-1] if @results;

    return @results;
}


method reset ($r:) {
    $r->current = $r->start->clone();
    return $r;
}

1;

__END__

=pod

=encoding UTF-8

=head1 NAME

Time::R - Handle recurrences.

=head1 VERSION

version 0.024

=head1 SYNOPSIS

  use Time::C;
  use Time::R;

  my $start = Time::C->new(2016,1,31);
  my $r = Time::R->new($start, months => 1);

  # "2016-02-29T00:00:00Z"
  my $first = $r->next();

  # "2016-03-31T00:00:00Z
  my $second = $r->next();

  # resets $r->next()
  $r->reset();

  # 2016-10-31T00:00:00Z" (depending on current time)
  my $upcoming = $r->upcoming();

  # "2016-09-30T00:00:00Z" (depending on current time)
  my $latest = $r->latest();

  # ("2016-09-30T00:00:00Z", "2016-10-31T00:00:00Z", "2016-11-30T00:00:00Z",
  #  "2016-12-31T00:00:00Z")
  my @dates = $r->until(Time::C->new(2017,1,1));

  # "2017-01-31T00:00:00Z"
  my $next = $r->next();

  # print out the first thursday of every month until January 2017
  my $m = Time::R->new(Time::C->new(2016), months => 1, end => Time::C->new(2017));
  while (my $n = $m->next()) {
    $n->day++ while $n->day_of_week != 4;
    print $n->strftime('%A %d %B %Y') . "\n"; #ex: Thursday 4 February 2016
  }

=head1 DESCRIPTION

Convenient ways of handling recurrences.

=head1 CONSTRUCTORS

=head2 new

  my $r = Time::R->new($start);
  my $r = Time::R->new($start, end => $end, years => $year, months => $months,
    weeks => $weeks, days => $days, hours => $hours, minutes => $minutes,
    seconds => $seconds);

Creates a Time::R object starting at C<$start>, and optionally ending at C<$end>. Every argument except C<$start> is optional and can be in any order.

=over

=item C<$start>

This should be a L<Time::C> object representing the starting time.

=item C<< end => $end >>

This should be a L<Time::C> object optionally specifying the ending time. Defaults to C<undef>.

=item C<< years => $years >>

This should be the number of years between each recurrence. Defaults to C<0>.

=item C<< months => $months >>

This should be the number of months between each recurrence. Defaults to C<0>.

=item C<< weeks => $weeks >>

This should be the number of weeks between each recurrence. Defaults to C<0>.

=item C<< days => $days >>

This should be the number of days between each recurrence. Defaults to C<0>.

=item C<< hours => $hours >>

This should be the number of hours between each recurrence. Defaults to C<0>.

=item C<< minutes => $minutes >>

This should be the number of minutes between each recurrence. Defaults to C<0>.

=item C<< seconds => $seconds >>

This should be the number of seconds between each recurrence. Defaults to C<0>.

=back

=head1 ACCESSORS

=head2 start

  my $start = $r->start;
  $r->start = $start;

  $r = $r->start($new_start);

Returns or sets the L<Time::C> object representing the starting time of the recurrence. Setting this also calls C<< $r->reset() >>.

If the form C<< $r->start($new_start) >> is used, it likewise updates the start but returns the entire object.

=head2 current

  my $current = $r->current;
  $r->current = $current;

Returns or sets the L<Time::C> object representing the current time of the current recurrence.

This may get changed by C<< $r->next >>, C<< $r->upcoming >>, C<< $r->latest >>, C<< $r->until >>, and C<< $r->reset >>.

=head2 end

  my $end = $r->end;
  $r->end = $end;

Returns or sets the L<Time::C> object representing the end time of the recurrence.

=head2 years

  my $years = $r->years;
  $r->years = $years;
  $r->years += 10;
  $r->years++;
  $r->years--;

Returns or sets the number of years between each recurrence. Setting this also calls C<< $r->reset() >>.

=head2 months

  my $months = $r->months;
  $r->months = $months;
  $r->months += 12;
  $r->months++;
  $r->months--;

Returns or sets the number of months between each recurrence. Setting this also calls C<< $r->reset() >>.

=head2 weeks

  my $weeks = $r->weeks;
  $r->weeks = $weeks;
  $r->weeks += 52;
  $r->weeks++;
  $r->weeks--;

Returns or sets the number of weeks between each recurrence. Setting this also calls C<< $r->reset() >>.

=head2 days

  my $days = $r->days;
  $r->days = $days;
  $r->days += 7;
  $r->days++;
  $r->days--;

Returns or sets the number of days between each recurrence. Setting this also calls C<< $r->reset() >>.

=head2 hours

  my $hours = $r->hours;
  $r->hours = $hours;
  $r->hours += 24;
  $r->hours++;
  $r->hours--;

Returns or sets the number of hours between each recurrence. Setting this also calls C<< $r->reset() >>.

=head2 minutes

  my $minutes = $r->minutes;
  $r->minutes = $minutes;
  $r->minutes += 60;
  $r->minutes++;
  $r->minutes--;

Returns or sets the number of minutes between each recurrence. Setting this also calls C<< $r->reset() >>.

=head2 seconds

  my $seconds = $r->seconds;
  $r->seconds = $seconds;
  $r->seconds += 60;
  $r->seconds++;
  $r->seconds--;

Returns or sets the number of seconds between each recurrence. Setting this also calls C<< $r->reset() >>.

=head1 METHODS

=head2 next

  my $next = $r->next();

Sets C<< $r->current >> to and returns the next recurrence as a L<Time::C> object. If the next time would happen after the C<< $r->end >>, it instead returns C<undef> and leaves C<< $r->current >> alone.

=head2 upcoming

  my $upcoming = $r->upcoming();

Sets C<< $r->current >> to and returns the next time the recurrence occurs as a L<Time::C> object based on the current time. If the next time would happen after the C<< $r->end >>, it instead returns C<undef> and leaves C<< $r->current >> alone.

=head2 latest

  my $latest = $r->latest();

Sets C<< $r->current >> to and returns the latest time the recurrence occurs as a L<Time::C> object based on the current time.

=head2 until

  my @until = $r->until($end);

Returns all the recurrences that will happen from C<< $r->current >> until C<$end> (which should be a L<Time::C> object), and updates C<< $r->current >> to the last one returned if any. If C<< $r->end >> is defined and C<$end> is after, it will instead use C<< $r->end >> as the limit.

=head2 reset

  $r->reset();

Resets C<< $r->current >> to C<< $r->start >>.

=head1 SEE ALSO

=over

=item L<Time::C>

=item L<Time::D>

=back

=head1 AUTHOR

Andreas Guldstrand <andreas.guldstrand@gmail.com>

=head1 COPYRIGHT AND LICENSE

This software is Copyright (c) 2016 by Andreas Guldstrand.

This is free software, licensed under:

  The MIT (X11) License

=cut
	Global
`s`	Focus search bar
`?`	Bring up this help dialog
	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)
	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse
	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)