=begin pod

=head1 NAME

Map::Agnostic - be a Map without knowing how

=head1 SYNOPSIS

=begin code :lang<raku>
use Map::Agnostic;
class MyMap does Map::Agnostic {
    method INIT-KEY($key,$value) { ... }
    method AT-KEY($key)          { ... }
    method EXISTS-KEY($key)      { ... }
    method keys()                { ... }
}

my %m is MyMap = a => 42, b => 666;

my %m is Map::Agnostic = ...;
=end code

=head1 DESCRIPTION

This module makes a C<Map::Agnostic> role available for those classes that
wish to implement the C<Associative> role as an immutable C<Map>.  It
provides all of the C<Map> functionality while only needing to implement
4 methods:

=head2 Required Methods

=head3 method INIT-KEY

=begin code :lang<raku>
method INIT-KEY($key, $value) { ... }
=end code

Bind the given value to the given key in the map, and return the value.
This will only be called during initialization of the C<Map>.  The functionality
is the same as the C<BIND-KEY> method, but it will only be called at
initialization time, whereas C<BIND-KEY> can be called at any time and will
fail.

=head3 method AT-KEY

=begin code :lang<raku>
method AT-KEY($key) { ... }
=end code

Return the value at the given key in the map.

=head3 method EXISTS-KEY

=begin code :lang<raku>
method EXISTS-KEY($key) { ... }
=end code

Return C<Bool> indicating whether the key exists in the map.

=head3 method keys

=begin code :lang<raku>
method keys() { ... }
=end code

Return the keys that currently exist in the map, in any order that is
most convenient.

=head2 Optional Methods (provided by role)

You may implement these methods out of performance reasons yourself, but you
don't have to as an implementation is provided by this role.  They follow the
same semantics as the methods on the
L<Map object|https://docs.perl6.org/type/Map>.

In alphabetical order:
C<elems>, C<end>, C<gist>, C<Hash>, C<iterator>, C<kv>, C<list>, C<List>,
C<new>, C<pairs>, C<perl>, C<Slip>, C<STORE>, C<Str>, C<values>

=head1 AUTHOR

Elizabeth Mattijsen <liz@raku.rocks>

Source can be located at: https://codeberg.org/lizmat/Map-Agnostic .
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 2018, 2019, 2021, 2023, 2024, 2025, 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
