NAME

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

SYNOPSIS

       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
          }

DESCRIPTION

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

BUGS

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

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

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.

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.

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