view release on metacpan or  search on metacpan

lib/Date/RetentionPolicy.pm  view on Meta::CPAN

to allow it to work with other Date classes.

=head1 ATTRIBUTES

=head2 retain

An arrayref of specifications for what to preserve.  Each element should be a
hashref containing C<history> and C<interval>.  C<history> specifies how far
backward from L</reference_date> to apply the intervals, and C<interval>
specifies the time difference between the backups that need preserved.

As an example, consider

  retain => [
    { interval => { days => 1 }, history => { days => 20 } },
    { interval => { hours => 1 }, history => { hours => 48 } },
  ]

This will attempt to preserve timestamps near the marks of L</reference_date>,
an hour before that, an hour before that, and so on for the past 48 hours.
It will also attempt to preserve L</reference_date>, a day before that, a day
before that, and so on for the past 20 days.

There is another setting called L</reach_factor> that determines how far from
the desired timestamp the algorithm will look for something to preserve.  The
default C<reach_factor> of C<0.5> means that it will scan from half an interval
back in time until half an interval forward in time looking for the closest
timestamp to preserve.  In some cases, you may want a narrower or wider search
distance, and you can set C<reach_factor> accordingly.  You can also supply it
as another hash key for a retain rule for per-rule customization.

  retain => [
    { interval => { days => 1 }, history => { days => 20 }, reach_factor => .75 }
  ]

=head2 time_zone

When date strings are involved, parse them as this time zone before converting
to an epoch value used in the calculations.  The default is C<'floating'>.

=head2 reach_factor

The multiplier for how far to look in each direction from an interval point.
See discussion in L</retain>.

=head2 reference_date

The end-point from which all intervals will be calculated.  There is no
default, to allow L</reference_date_or_default> to always pick up the current
time when called.

=head2 reference_date_or_default

Read-only.  Return (a clone of) L</reference_date>, or if it isn't set, return
the current date in the designated L</time_zone> rounded up to the next day
boundary.

=head2 auto_sync

While walking backward through time intervals looking for backups, adjust the
interval endpoint to be closer to whatever match it found.  This might allow
the algorithm to essentially adjust the C<reference_date> to match whatever
schedule your backups are running on.  This is not enabled by default.

=head1 METHODS

=head1 prune

  my $pruned_arrayref= $self->prune( \@times );

C<@times> may be an array of epoch numbers, DateTime objects, or date strings
in any format recognized by L<DateTime::Format::Flexible>.  Epochs are
currently the most efficient type of argument since that's what the algorithm
operates on.

=head2 visualize

  print $rp->visualize( \@list );

This method takes a list of timestamps, sorts and marks them for retention,
and then returns printable text showing the retention intervals and which
increment it decided to keep.  The text is simple ascii-art, and requires
a monospace font to display correctly.

=head1 AUTHOR

Michael Conrad <mconrad@intellitree.com>

=head1 COPYRIGHT AND LICENSE

This software is copyright (c) 2018 by IntelliTree Solutions llc.

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

=cut