File Coverage

=head1 NAME

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

=head1 VERSION

Version 0.06

=cut

=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: ">.

=head3 Side Effects

May print coloured diagnostics to STDERR when dates cannot be parsed, when a
range is inverted, or when an argument is undefined.  The C<$complain>
callback is invoked (instead of STDERR output) for selected ambiguous
conditions.

=head3 EXAMPLE

  use Date::Cmp qw(datecmp);

  # Plain years
  datecmp('1900', '1950');              # -1

  # Approximate prefixes are stripped
  datecmp('Abt. 1850', '1850');        # 0
  datecmp('ca. 1799',  '1800');        # -1

  # Year ranges — any year within the range is "equal"
  datecmp('1 Jan 1831', '1830-1832');  # 0
  datecmp('BET 1830 AND 1832', '1829'); # 1  (range is later)

  # Blessed object with date() method
  package MyDate;
  sub new  { bless { d => $_[1] }, $_[0] }
  sub date { $_[0]->{d} }
  package main;
  datecmp(MyDate->new('1900'), '1950'); # -1

  # Hash ref with 'date' key
  datecmp({ date => '1900' }, '1950'); # -1

  # Sort a list of dates
  my @sorted = sort { datecmp($a, $b) } qw(1832 Abt. 1800 1756 BET 1815 AND 1820);

=head3 API SPECIFICATION

=head4 Input

  $left    : Str | Object(date) | HashRef(date => Str)   # required
  $right   : Str | Object(date) | HashRef(date => Str)   # required
  $complain: CodeRef | undef | false                      # optional

Valid string formats (see L</SUPPORTED FORMATS>):

  exact    => qr/^\d{4}-\d{2}-\d{2}(?:T\d{2}:\d{2}:\d{2})?$/
  slash    => qr{^\d+/\d+/\d{4}$}
  year     => qr/^\d{3,4}$/
  approx   => qr/^(?:Abt\.?|ca?\.?)\s+.+/i  |  qr/.+\s?\?$/
  range    => qr/^\d{3,4}-\d{3,4}$/  |  qr/^BET \d+ AND \d+$/i
  month_rng=> qr/^[a-z\/]+\s+\d{3,4}$/i
  before   => qr/^bef\b/i
  after    => qr/^aft\b/i

=head4 Output

  Int: -1 | 0 | 1

  Or croaks("Date parse failure: ...") when a date cannot be parsed.
  Returns 0 (after STDERR output) when either argument is undef.

=head3 MESSAGES

The following diagnostics may be emitted.  B<[STDERR]> entries print a
message and stack trace then return 0.  B<[croak]> entries die (catchable
with C<eval {}>).

=over 4

=item B<[STDERR]> "left not defined" / "right not defined"

C<$left> or C<$right> was C<undef> on entry.

=item B<[STDERR]> "left date is undefined after input normalisation" / "right ..."

A hashref was passed with no C<date> key, or C<date =E<gt> undef>.

=item B<[croak]> "Third argument to datecmp() must be a CODE reference"

C<$complain> was truthy but not a C<CODE> reference (e.g. a string or
array-ref).

=item B<[croak]> "Date parse failure: left is an unsupported reference type (...)"

C<$left> was a reference that could not be unwrapped (not a blessed
C<date()>-capable object and not a hash).

=item B<[croak]> "Date parse failure: right is an unsupported reference type (...)"

Same for C<$right>.

=item B<[croak]> "Date parse failure: left contains characters not permitted in a date string"

C<$left> contained a character outside the allowed set
C<[A-Za-z0-9 .,/-?:]>.  The string is rejected before any parsing.

=item B<[croak]> "Date parse failure: right contains characters not permitted in a date string"

Same for C<$right>.

=item B<[croak]> "Date parse failure: left = ... (year must be 3-4 digits)"

C<$left> was a bare integer with 5 or more digits.

=item B<[croak]> "Date parse failure: right = ... (year must be 3-4 digits)"

Same for C<$right>.

=item B<[croak]> "Date parse failure: left = ..."

C<$left> failed the first-character semantic check or could not be parsed
by DFG.

=item B<[croak]> "Date parse failure: right = ..."

C<$right> could not be parsed by DFG (and no year suffix was extractable).

=item B<[STDERR]> "... <=> ...: not handled yet"

A C<BEF>/C<AFT> qualifier on the left with a right-hand value that does not
fit any handled pattern.  Returns 0.

=item B<[STDERR]> "... <=> ...: Before not handled"

A C<BEF> qualifier on the right with a left-hand value that is not a plain
integer.  Returns 0.

=item B<[STDERR]> "datecmp(): N > M in daterange ..."

The right-hand year range was inverted (C<from E<gt> to>).  Returns 0.

=back

=head3 PSEUDOCODE

  1.  Validate $complain: croak if truthy but not a CODE reference.
  2.  Guard undef: if either input is undef → STDERR + stack trace + return 0.
  3.  Normalise: blessed date()-objects → call date(); hash refs → 'date' key.
  4.  Guard post-normalise undef → STDERR + stack trace + return 0.
  5.  Reject surviving reference types (croak).
  6.  Identity short-circuit: return 0 if left eq right (no parsing needed).
  7.  Taint-scrub: validate all characters against $DATE_CHARS;
      also produces untainted copies safe for use under perl -T.
  8.  First-char semantic check: first char must be [A-S0-9] (croak if not).
  9.  Reject 5+ digit bare integers (croak).
  10. Fast path 1: 4-digit year in both non-range strings → return if differ.
  11. Fast path 2: trailing 3-4 digit year in both → return if differ.
  12. Normalise LEFT (if string):
      a.  Strip trailing ISO T-timestamp.
      b.  Fast path 3: trailing 4-digit years in both → return if differ.
      c.  BEF/AFT on left: numeric-right or BEF-with-4-digit-right handled;
          otherwise STDERR + stack trace + return 0.
      d.  Strip approximate prefix (Abt./ca.) or suffix (?) or month-range.
      e.  Fast path 4: digit-starting years on both sides → return if differ.
      f.  Fast path 5: left year vs right starting with lowercase "bet".
      g.  "YEAR or YEAR" form: use first year; fire $complain if both equal.
      h.  Dash / BET range on left: compare $right against [from, to].
      i.  Complex date string: parse via DFG (croak if DFG returns nothing).
  13. Normalise RIGHT (if string):
      a.  BEF on right: numeric left → compare; otherwise STDERR + return 0.
      b.  Strip approximate prefix/suffix/month-range.
      c.  Bare 3-4 digit year: compare directly with left (unwrap if ref).
      d.  Dash / BET range on right: compare $left against [from, to].
      e.  Fast path 6: matching year in both → return if differ.
      f.  Parse right via DFG (croak if DFG returns nothing).
  14. Final comparison: unwrap any remaining DateTime objects via ->year(); <=>.

=head1 SUPPORTED FORMATS

=over 4

=item * Exact dates: C<1941-08-02>, C<5/27/1872>

=item * Years only: C<1828>, C<822>

=item * Approximate dates: C<Abt. 1802>, C<ca. 1802>, C<1802 ?>

=item * Date ranges: C<1802-1803>, C<BET 1830 AND 1832>

=item * Month ranges: C<Oct/Nov/Dec 1950>

=item * Qualifiers: C<BEF 1940>, C<AFT 1855>

=back

=head1 ERROR HANDLING

When a date cannot be parsed, diagnostic messages are printed to STDERR and
the function either returns 0 (for recoverable conditions such as undef
input) or C<croak>s with a string beginning C<"Date parse failure: ">.
All C<croak> exceptions are catchable via C<eval {}>.

=head1 LIMITATIONS

=over 4

=item * B<Month-only dates>

Dates where only the month is known (no year) are not supported.

=item * B<Incomplete BEF/AFT handling>

Many C<BEF>/C<AFT> combinations—especially C<AFT> on the left or C<BEF>
against a non-integer right—are not implemented and fall back to returning
0 with a STDERR diagnostic.

=item * B<Dead fast-path code>

Certain fast-path branches and a redundant C<ref($right)> guard inside the
left-side range handler are unreachable at runtime (documented in
C<t/extended_tests.t> subtest 10).

=item * B<Public singleton>

C<$Date::Cmp::dfg> is a package variable.  Concurrent threads replacing it
with different mocks are not safe.

=item * B<No Sub::Private enforcement>

The C<_sanitize_for_diag> and C<_emit_stack_trace> private helpers rely on
naming convention only.  Runtime enforcement via C<Sub::Private> is not yet
declared as a dependency.

=back

=cut

=head1 AUTHOR

Nigel Horne, C<< <njh at nigelhorne.com> >>

=head1 SEE ALSO

=over 4

=item * L<Test Dashboard|https://nigelhorne.github.io/Date-Cmp/coverage/>

=item * L<Sort::Key::DateTime>

=back

=head1 SUPPORT

This module is provided as-is without any warranty.

Please report bugs to C<bug-date-cmp at rt.cpan.org> or via
L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Date-Cmp>.

    perldoc Date::Cmp

=head1 FORMAL SPECIFICATION

=head2 datecmp

    [DATESTR, DIAGMSG]

    DATE ::= exact⟨year: ℕ⟩
           | approx⟨year: ℕ⟩
           | before⟨year: ℕ⟩
           | after⟨year: ℕ⟩
           | range⟨from: â„•; to: ℕ⟩
           | invalid

    COMPARISON ::= lt | eq | gt | error

    DateCmp
    left?, right?: DATESTR
    diagnostic!: â„™ DIAGMSG
    result!: COMPARISON

    âˆ€d: DATESTR @ validDate(d)

    â‰™
    âˆƒ l, r: DATE •
        l = parse(left?) ∧ r = parse(right?) ∧
        (
          (l = invalid ∨ r = invalid ⇒ result! = error) ∧
          (l = r ⇒ result! = eq) ∧
          (compare(l, r, diagnostic!) = -1 ⇒ result! = lt) ∧
          (compare(l, r, diagnostic!) = 0  â‡’ result! = eq) ∧
          (compare(l, r, diagnostic!) = 1  â‡’ result! = gt)
        )

=head1 LICENCE AND COPYRIGHT

Copyright 2025-2026 Nigel Horne.

Usage is subject to the GPL2 licence terms.
If you use it,
please let me know.

=cut