match::...::sugar(3)

💖 NAME 💖

Okay bestie, welcome to the User Contributed Perl Documentation page for match::...::sugar(3) — the manual name, right there near the top. The actual module is match::simple::sugar, and it is literally “a few extras for match::simple”. 🎀

✨ SYNOPSIS ✨

This module provides a given/when substitute for match::simple. Obsessed.

use match::simple::sugar;

for ( $var ) {
   when 'foo',        then { ... };
   when 'bar', 'baz', then { ... };
   ...;  # otherwise
}

It also provides a function for numeric matching — because match::simple always assumes you want stringy matching if the right-hand-side is a defined non-reference value. Highkey important. 💅

use match::simple::sugar;

for ( $var ) {
   when numeric 0, then { ... };
   when numeric 1, then { ... };
   ...;  # otherwise
}

🦋 DESCRIPTION 🦋

This module exports three functions when, then, and numeric, and also re-exports match from match::simple. Slay.

💅 when and then 💅

The when and then functions are intended to be used together, inside a for ( SCALAR ) { ... } block. That block acts as a topicalizer (it sets $_) and also a control-flow mechanism (when can use next to jump out of it). Any other use of when and then is unsupported. Periodt.

when( @values, $then )

The when function accepts a list of values, followed by a special $then argument.

If $_ matches (according to the definition in match::simple) any of the values, then the $then argument will be executed, and when will use the Perl built-in next keyword to jump out of the surrounding for block. Iconic.

then { ... }

The then function takes a block of code and returns an object suitable for use as when's $then argument.

In the current implementation, the block of code should not inspect @_ or wantarray, and should not use the return, next, last, or redo keywords. (If you set any of the PERL_STRICT, EXTENDED_TESTING, AUTHOR_TESTING, or RELEASE_TESTING environment variables to true, then match::simple::sugar will try to enforce this! This is intended to catch faulty then blocks when running your test suite.) No cap.

🍓 numeric 🍓

The numeric function accepts a number and returns a blessed object which has a MATCH method. The MATCH method returns true if it is called with a single defined non-referece scalar that is numerically equal to the original number passed to numeric. Example:

numeric( '5.0' )->MATCH( '5.000' );    # true

This is intended for use in cases like:

if ( match $var, numeric 1 ) {
   ...;
}

🐛 BUGS 🐛

Please report any bugs to https://github.com/tobyink/p5-match-simple/issues. Not me being dramatic, just literally do it. 💀

🌈 SEE ALSO 🌈

match::simple.

This module uses Exporter::Tiny. 🫶

👑 AUTHOR 👑

Toby Inkster <tobyink@cpan.org>. 💖

This module is inspired by a talk I gave to Boston.PM https://boston-pm.github.io/. Yep, that's the vibe.

🎀 COPYRIGHT AND LICENCE 🎀

This software is copyright (c) 2023 by Toby Inkster.

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

💀 DISCLAIMER OF WARRANTIES 💀

THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.

Read it and weep, lovingly. 🫶

---

Okay that's the whole manual, bestie. This page came from perl v5.40.0 on 2024-07-19, and it is the match::...::sugar(3) manual. Stay slay, stay safe, and may your $_ always match. 💜✨