=begin pod

=head1 NAME

Map::Match - Provide a Map where keys are regular expressions

=head1 SYNOPSIS

=begin code :lang<raku>
use Map::Match;

my %m is Map::Match = foo => 42, b16ar => 666, baz18 => 137;

.say for %m<a>;  # 666␤137␤, same as / a /

.say for %m{ / \d >> / };    # 137␤

.say for %m{ / \d >> / }:k;  # baz18␤

.say for %m( / \d >> /, :k);  # baz18␤
=end code

=head1 DESCRIPTION

Map::Match provides an implementation of the C<Map> interface where key values
are interpreted as regular expressions.  This has the following implications
with regards to the normal behaviour of C<Map>s:

=head2 CAN RETURN MORE THAN ONE

Since a regular expression can match multiple times, you can receive more than
one value back from a single key.  Therefore, a C<Slip> will always be returned
as the value.

=head2 ALWAYS A SLIP

The value returned from any C<Map> access is B<always> a C<Slip>, albeit
potentially empty.  This is different from a normal C<Map> where C<Nil> would
be returned when specifying a key that does not exist in the C<Map>.

=head2 NON-REGEX KEY ASSUMED TO BE REGEX

If you specify a C<Str> as a key, or something that can be coerced to a C<Str>,
it will be interpreted as being interpolated in a C<Regex> with C<:ignorecase>
and C<:ignoremark> enabled.

=head2 CAVEATS

This module exports a C<postcircumfix { }> candidate that allows access
to a C<Map::Match> object just like an ordinary C<Hash> or C<Map>.  However,
if C<Map::Match> is used in a module, and that module returns a C<Map::Match>
object, then in that scope, that C<postcircumfix { }> candidate won't be
known, causing C<{"foo"}> using the standard semantics, producing weird
results.

For that situation, you can use the alternate interface, which is to directly
call the C<Map::Match> object with the desired arguments:

=begin code :lang<raku>
# postcircumfix interface
.say for %m{ / \d >> / }:k;  # baz18␤

# alternate interface
.say for %m( / \d >> /, :k);  # baz18␤
=end code

Of course, it is always an option to always use the alternate interface to
prevent confusion, and potential bugs when refactoring code.  And the direct
interface is actually a bit faster, as it has one less level of indirection.

=head1 AUTHOR

Elizabeth Mattijsen <liz@raku.rocks>

Source can be located at: https://codeberg.org/lizmat/Map-Match . Comments and
Pull Requests are welcome.

If you like this module, or what I’m doing more generally, committing to a
L<small sponsorship|https://github.com/sponsors/lizmat/>  would mean a great
deal to me!

=head1 COPYRIGHT AND LICENSE

Copyright 2021, 2022, 2023, 2024, 2026 Elizabeth Mattijsen

This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.

=end pod

# vim: expandtab shiftwidth=4
