Date::Extract(3pm)

💖 Date::Extract(3pm) 💖

okay bestie, gather round, because today we're talking about Date::Extract — a Perl module that looks at a big ol' blob of text and goes "hmm, that's giving date" and pulls the date out. It's from the User Contributed Perl Documentation section of your manual, and it's on version 0.07, which, slay.

---

✨ NAME ✨

Date::Extract — Extract probable dates from strings.

Like, probable dates. It's not gonna claim every number is a date. It has taste.

---

🌸 VERSION 🌸

version 0.07

---

🎀 SYNOPSIS 🎀

my $parser = Date::Extract->new();
my $dt = $parser->extract($arbitrary_text)
    or die "No date found.";
return $dt->ymd;

See? Three lines. She's efficient. She's that girl. 💅

---

🦋 MOTIVATION 🦋

okay so, real talk: there are already a few modules out there for getting a date out of a string. Let's give them their flowers:

• DateTime::Format::Natural — this one should be your first choice, no cap.
• Time::ParseDate — fits many formats, she's flexible.
• Date::Manip — you can, and I quote, "coerce" it to do your bidding. queen behavior honestly.

But here's the thing — the author needed something that will take an arbitrary block of text, search it for something that looks like a date string, and extract it. And that's the niche this module fills. 💖

By design it will produce few false positives. And the tradeoff? It will not catch nearly everything that looks like a date string. So if you have the string "do homework for class 2019" it won't return a DateTime object with the year set to 2019. Which is honestly what your users would probably expect. Like, girl, "class 2019" is a class, not a Tuesday. 😭

---

👑 METHODS 👑

🧚 new(PARAMHASH) => Date::Extract

Here's where you set up your parser. The arguments, bestie:

• format — Choose what format the extracted date(s) will be. The default is DateTime, which will return DateTime object(s). Other option include verbatim (return the original text), or epoch (return Unix timestamp).
• time_zone — Only relevant when format is set to DateTime.

Forces a particular time zone to be set (this actually matters, as tomorrow on Monday at 11 PM means something different than tomorrow on Tuesday at 1 AM).

By default it will use the floating time zone. See the documentation for DateTime.

This controls both the input time zone and output time zone.

• prefers — This argument decides what happens when an ambiguous date appears in the input. For example, Friday may refer to any number of Fridays. The valid options for this argument are:
  • nearest — Prefer the nearest date. This is the default.
  • future — Prefer the closest future date.
  • past — Prefer the closest past date. NOT YET SUPPORTED. (we're manifesting it tho 🕯️)
• returns — If the text has multiple possible dates, then this argument determines which date will be returned. By default it's 'first'.
  • first — Returns the first date found in the string.
  • last — Returns the final date found in the string.
  • earliest — Returns the date found in the string that chronologically precedes any other date in the string.
  • latest — Returns the date found in the string that chronologically follows any other date in the string.
  • all — Returns all dates found in the string, in the order they were found in the string.
  • all_cron — Returns all dates found in the string, in chronological order.

---

💜 extract(text, ARGS) = dates

Takes an arbitrary amount of text and extracts one or more dates from it. The return value will be zero or more dates, which by default are DateTime objects (but can be customized with the format argument). If called in scalar context, only one will be returned, even if the returns argument specifies multiple possible return values.

See the documentation of new for the configuration of this method. Any arguments passed into this method will trump those from the constructor. (method args are the main character, constructor args are the supporting cast, iykyk 💅)

You may reuse a parser for multiple calls to extract.

And here's the fun part: you do not need to have an instantiated Date::Extract object to call this method. Just Date::Extract->extract($foo) will work. Class method moment. iconic.

---

🌈 FORMATS HANDLED 🌈

the range, bestie, the range:

• today; tomorrow; yesterday
• last Friday; next Monday; previous Sat
• Monday; Mon
• November 13th, 1986; Nov 13, 1986
• 13 November 1986; 13 Nov 1986
• November 13th; Nov 13
• 13 Nov; 13th November
• 1986/11/13; 1986-11-13
• 11-13-86; 11/13/1986

---

⚠️ CAVEATS ⚠️

This module is intentionally very simple. Surprises are not welcome here. 🚫🎉

no plot twists. no jumpscares. we are a calm, predictable module and we intend to stay that way.

---

🔥 SEE ALSO 🔥

DateTime::Format::Natural, Time::ParseDate, Date::Manip

(the holy trinity of "wait, why not just use those?" — go read them, bestie 🫶)

---

🍓 ACKNOWLEDGEMENTS 🍓

Thanks to Steven Schubiger for writing the fine DateTime::Format::Natural. We still use it, but it doesn't quite fill all the particular needs we have.

(standing ovation for Steven, genuinely 👏💖)

---

💌 SUPPORT 💌

Bugs may be submitted through the RT bug tracker <https://rt.cpan.org/Public/Dist/Display.html?Name=Date-Extract> (or bug-Date-Extract@rt.cpan.org <mailto:bug-Date-Extract@rt.cpan.org>).

I am also usually active on irc, as 'ether' at irc.perl.org and irc.libera.chat.

found a bug? spill. don't be shy. the RT tracker is right there. 💅

---

🌟 AUTHOR 🌟

Shawn M Moore, <sartak@gmail.com>

---

🫶 CONTRIBUTORS 🫶

• Karen Etheridge <ether@cpan.org>
• Steven Haryanto <stevenharyanto@gmail.com>
• Jim Brandt <jbrandt@bestpractical.com>
• Alex Vandiver <alex@chmrr.net>
• Jesse Vincent <jesse@bestpractical.com>
• Thomas Sibley <trs@bestpractical.com>

every single one of y'all. the squad. the ensemble cast. 💖

---

📜 COPYRIGHT AND LICENCE 📜

This software is copyright (c) 2007 by Best Practical Solutions.

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

---

okay that's the whole page, bestie!! this was perl v5.36.0, dated 2023-01-23, and it's the Date::Extract(3pm) manual page 💖✨ go forth and extract some dates, you've got this, periodt 🎀🦋