match::simple::sugar - a few extras for match::simple

       Toby Inkster <tobyink@cpan.org>.

       This module is inspired by a talk I gave to Boston.PM <https://boston-pm.github.io/>.

       Please report any bugs to <https://github.com/tobyink/p5-match-simple/issues>.

       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.

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

   "when"and"then"
       The "when" and "then" functions are intended to be used together, inside a "for ( SCALAR ) { ... }"
       block. The 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.

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

       "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.)

   "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 ) {
             ...;
          }

       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.

perl v5.38.2                                       2024-07-24                          match::simple::sugar(3pm)

       match::simple::sugar - a few extras for match::simple

       match::simple.

       This module uses Exporter::Tiny.

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

          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).

          use match::simple::sugar;

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