view release on metacpan or  search on metacpan

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

package Date::Cmp;

# Compare two genealogy-style date strings with approximate-date support.
# TODO: handle when only months are known (no year).

use strict;
use warnings;

use autodie 2.06 qw(:all);
use Carp       qw(croak);
use DateTime::Format::Genealogy 0.11;
use Readonly;
use Scalar::Util qw(blessed);
use Term::ANSIColor;

use Exporter qw(import);
our @EXPORT_OK = qw(datecmp);

=encoding utf-8

=head1 NAME

Date::Cmp - Compare two dates with approximate parsing support

=head1 VERSION

Version 0.06

=cut

our $VERSION = '0.06';

# Singleton DFG parser reused across calls for speed.  Tests may swap it
# with a mock under "local $Date::Cmp::dfg = MockDFG->new()".
our $dfg = DateTime::Format::Genealogy->new();

=head1 SYNOPSIS

  use Date::Cmp qw(datecmp);

  my $cmp = datecmp('1914', '1918');            # -1 (1914 is earlier)
  my $cmp = datecmp('Abt. 1850', '1855');       # -1
  my $cmp = datecmp('BET 1830 AND 1832', '1831'); # 0 (within range)

  # Optional complaint callback for ambiguous range edge-cases:
  $cmp = datecmp('1996-2000', '1996',
      sub { warn "ambiguous: @_" });

=head1 DESCRIPTION

C<Date::Cmp> provides a single exported function, C<datecmp>, which compares
two date strings or date-like objects, returning a numeric result like Perl's
C<< <=> >> operator.

The comparison handles approximate dates (C<Abt. 1902>, C<BET 1830 AND 1832>,
C<Oct/Nov/Dec 1950>), partial dates (year-only), and the common genealogy
qualifiers C<BEF> and C<AFT>.  Exact parsing delegates to
L<DateTime::Format::Genealogy>; a cascade of fast-path heuristics handles
the most common year-only comparisons without invoking the heavier parser.

=head1 FUNCTIONS

=head2 datecmp

=head3 Purpose

Compare two genealogy-style date strings (or date-like objects) and return
a value equivalent to Perl's spaceship operator (C<< <=> >>): C<-1> if the
left operand is earlier, C<0> if equivalent, or C<1> if later.

=head3 Arguments

=over 4

=item C<$left> (required)

The left-hand date.  Accepted types:

=over 8

=item * A string in any format listed under L</SUPPORTED FORMATS>.

=item * A blessed object with a C<date()> method returning a date string.

=item * A hash reference with a C<date> key whose value is a date string.

=back

=item C<$right> (required)

The right-hand date.  Accepts the same types as C<$left>.

=item C<$complain> (optional)

A CODE reference invoked with a diagnostic string for ambiguous conditions:
equal range endpoints or an inverted range.  C<undef> and other falsy values
are silently ignored (the guard is never triggered).  A truthy non-CODE
value causes an immediate C<croak>.

=back

=head3 Returns

=over 4

=item * C<-1> — C<$left> is earlier than C<$right>

=item * C<0>  — the two dates are considered equivalent

=item * C<1>  — C<$left> is later than C<$right>

=back

When either argument is C<undef> (or resolves to C<undef> after unwrapping),
the function prints a diagnostic to STDERR and returns C<0> rather than dying.
On a fatal parse failure it dies; the exception string begins with
C<"Date parse failure: ">.