                           Tie::ShadowHash 2.01
         (Merge multiple data sources into a hash with overrides)
                Maintained by Russ Allbery <rra@cpan.org>

  Copyright 1999, 2002, 2010, 2022 Russ Allbery <rra@cpan.org>.  This
  software is distributed under the same terms as Perl itself.  Please see
  the section LICENSE below for more information.

BLURB

  Tie::ShadowHash is a Perl module that lets you stack together multiple
  hash-like data structures, including tied hashes such as DB_File
  databases or text files parsed into a hash, and then treat them like a
  merged hash.  Lookups are handled in the order of the added sources.
  You can store additional values, change values, and delete values from
  the hash and those actions will be reflected in later operations, but
  the underlying objects are not changed.

DESCRIPTION

  If you have several key/value data sources in the form of Perl hashes,
  tied hashes (of whatever type, including on-disk databases tied with
  DB_File, GDBM_File, or similar modules), or text files that you want to
  turn into hashes, and you want to be able to query all of those sources
  of data at once for a particular key without having to check each one of
  them individually, this module may be what you're looking for.  If you
  want to use a hash-like data source, even just one, but make
  modifications to its data over the course of your program that override
  its contents while your program runs but which don't have any permanent
  effect on it, this module may be what you're looking for.

  Tie::ShadowHash lets you create a "shadow hash" that looks like a
  regular Perl hash to your program but, behind the scenes, queries a list
  of data sources.  All the data sources must also behave like Perl
  hashes, but that's the only constraint.  They can be regular Perl hashes
  or other tied hashes, including tied DB_File or GDBM_File hashes or the
  like to access on-disk databases.  All data sources are treated as
  read-only; modifications to any data is stored in the shadow hash
  itself, and subsequent accesses reflect any modifications, but none of
  the data sources are changed.

REQUIREMENTS

  The only requirement for this module is Perl 5.024 or later.

BUILDING AND INSTALLATION

  Tie::ShadowHash uses Module::Build and can be installed using the same
  process as any other Module::Build module:

      perl Build.PL
      ./Build
      ./Build install

  You will have to run the last command as root unless you're installing
  into a local Perl module tree in your home directory.

TESTING

  Tie::ShadowHash comes with a test suite, which you can run after
  building with:

      ./Build test

  If a test fails, you can run a single test with verbose output via:

      ./Build test --test_files <path-to-test>

  The following additional Perl modules will be used by the test suite if
  present:

  * Devel::Cover
  * Perl::Critic::Freenode
  * Test::CPAN::Changes (part of CPAN-Changes)
  * Test::Kwalitee
  * Test::MinimumVersion
  * Test::Perl::Critic
  * Test::Pod
  * Test::Pod::Coverage
  * Test::Spelling
  * Test::Strict
  * Test::Synopsis

  To enable tests that don't detect functionality problems but are used to
  sanity-check the release, set the environment variable RELEASE_TESTING
  to a true value.  To enable tests that may be sensitive to the local
  environment or that produce a lot of false positives without uncovering
  many problems, set the environment variable AUTHOR_TESTING to a true
  value.

THANKS

  To Chris Nandor for testing this module on the Mac, pointing out that
  SDBM_File wasn't available there, mentioning that SDBM was
  byte-order-dependent anyway, and suggesting using AnyDBM_File instead.

SUPPORT

  The Tie::ShadowHash web page at:

      https://www.eyrie.org/~eagle/software/shadowhash/

  will always have the current version of this package, the current
  documentation, and pointers to any additional resources.

  For bug tracking, use the issue tracker on GitHub:

      https://github.com/rra/shadowhash/issues

  However, please be aware that I tend to be extremely busy and work
  projects often take priority.  I'll save your report and get to it as
  soon as I can, but it may take me a couple of months.

SOURCE REPOSITORY

  Tie::ShadowHash is maintained using Git.  You can access the current
  source on GitHub at:

      https://github.com/rra/shadowhash

  or by cloning the repository at:

      https://git.eyrie.org/git/perl/shadowhash.git

  or view the repository via the web at:

      https://git.eyrie.org/?p=perl/shadowhash.git

  The eyrie.org repository is the canonical one, maintained by the author,
  but using GitHub is probably more convenient for most purposes.  Pull
  requests are gratefully reviewed and normally accepted.

LICENSE

  The Tie::ShadowHash package as a whole is covered by the following
  copyright statement and license:

    Copyright 1999, 2002, 2010, 2022 Russ Allbery <rra@cpan.org>

    This program is free software; you may redistribute it and/or modify
    it under the same terms as Perl itself.  This means that you may
    choose between the two licenses that Perl is released under: the GNU
    GPL and the Artistic License.  Please see your Perl distribution for
    the details and copies of the licenses.

  Some files in this distribution are individually released under
  different licenses, all of which are compatible with the above general
  package license but which may require preservation of additional
  notices.  All required notices, and detailed information about the
  licensing of each file, are recorded in the LICENSE file.

  Files covered by a license with an assigned SPDX License Identifier
  include SPDX-License-Identifier tags to enable automated processing of
  license information.  See https://spdx.org/licenses/ for more
  information.

  For any copyright range specified by files in this package as YYYY-ZZZZ,
  the range specifies every single year in that closed interval.
