smartmatch(3)

💖 smartmatch — pluggable smart matching backends 💖

okay bestie, so this is smartmatch, a page from the User Contributed Perl Documentation corner of the manual universe, and it is exactly the kind of chaotic little module that makes perl perl. buckle up 🎀

---

✨ VERSION ✨

version 0.05 — yes queen, we're on 0.05, keep up 💅

---

🌸 SYNOPSIS 🌸

here's the whole vibe, verbatim, no notes:

1 ~~ 2; # false
{
    use smartmatch sub { 1 };
    1 ~~ 2; # true

    no smartmatch;
    1 ~~ 2; # false

    use smartmatch 'custom';
    1 ~~ 2; # smartmatch::engine::custom::match(1, 2)
}
1 ~~ 2; # false

see how the truthiness of 1 ~~ 2 keeps flip-flopping depending on which block you're standing in? that's the whole point, and it's giving main character energy ngl 👑

---

🦋 DESCRIPTION 🦋

NOTE: This module is still experimental, and the API may change at any point. You have been warned! 🚨

so basically, this module lets you override the behavior of the smart match operator (~~). when you write use smartmatch $matcher, it hooks into the compiler and swaps out the smartmatch opcode for a call to a custom subroutine instead. that subroutine gets specified either as a coderef, or as a string — and if it's a string, smartmatch::engine:: gets prepended to it, and the result is used as the name of a package where it'll go looking for a subroutine called match. 🔍

that subroutine gets called with two arguments: the values on the left and right sides of the smart match operator. whatever it returns is the result. simple as that, no cap.

also, this module is lexically scoped, which means when you're done with your little custom-match era you can just call no smartmatch and boom — you're back to the core perl smart matching behavior. closure, but make it syntax. 💅

---

🌈 FUNCTIONS 🌈

🫶 callback_at_level($level)

returns a coderef. when you call that coderef with two arguments, it'll do a smartmatch on them — using the smartmatch implementation that was in effect at caller level $level. so like, time-travel but for match semantics. iconic honestly ⏳✨

---

💀 BUGS 💀

no known bugs. she's perfect, she's booked, she's busy. 💅

...okay but fr fr, if you do find one, please report it through RT: email bug-smartmatch at rt.cpan.org, or browse on over to <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=smartmatch>. do it for the culture 🙏

---

⭐ SEE ALSO ⭐

• "Smart matching in detail" in perlsyn — the lore, the canon, the required reading 📚
• smartmatch::engine::core — the original flavor engine 🍓

---

🎀 SUPPORT 🎀

you can find this documentation for this module with the perldoc command:

perldoc smartmatch

you can also go looking for information at:

• AnnoCPAN: Annotated CPAN documentation

<http://annocpan.org/dist/smartmatch>

• CPAN Ratings

<http://cpanratings.perl.org/d/smartmatch>

• RT: CPAN's request tracker

<http://rt.cpan.org/NoAuth/Bugs.html?Dist=smartmatch>

• Search CPAN

<http://search.cpan.org/dist/smartmatch>

four whole places to lurk. we love a supportive ecosystem 🫶

---

👑 AUTHOR 👑

Jesse Luehrs <doy at tozt dot net> — absolute legend, respect the craft 🌟

---

💖 COPYRIGHT AND LICENSE 💖

This software is copyright (c) 2012 by Jesse Luehrs.

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

---

and that's the whole page, bestie! this one ships out of perl v5.42.0, dated 2025-07-25, and it's the smartmatch(3) page we've been yapping about this entire time. go forth and override some operators responsibly 🦋✨💖