Tie::ShadowHash version 1.0

(Merge multiple data sources into a hash with overrides)

Copyright 1999, 2002, 2010 by 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.

I welcome all bug reports and patches for this package (and in particular, if you're looking for a project, see TODO). However, please be aware that I tend to be extremely busy and to get a lot of mail. I'll save your mail and get to it as soon as I can, but depending on how busy I am it may take me a couple of months.


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.


If you have a bunch of separate sources of data 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 each time, this module is 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, then 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 whole list of data sources. All the data sources underneath have to 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.

See the POD documentation for complete details, features, and usage.


Perl 5.006 or later is the only requirement for this module.

To run the test suite, Test::More is required. It is available from CPAN and part of Perl core as of 5.6.2.

The test suite includes a formatting and spelling check of all of the POD documentation. To check formatting, Test::Pod is required. To check spelling, Pod::Spell and either aspell or ispell with the american dictionary are also required. The user's path is searched for aspell or ispell and aspell is preferred. Spelling tests are disabled by default since spelling dictionaries differ too much between systems. To enable those tests, set RRA_MAINTAINER_TESTS to a true value.


Follow the standard installation procedure for Perl modules, which is to type the following commands:

    perl Makefile.PL
    make test
    make install

You'll probably need to do the "make install" as root. If instead you wish to install the module by hand, simply copy ShadowHash.pm into a directory named Tie in your Perl library directory.


The podlators web page at:


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

Tie::ShadowHash is maintained using Git. You can access the current source by cloning the repository at:


or view the repository on the web at:



To Chris Nandor <pudge@pobox.com> 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.

Converted to XHTML by faq2html version 1.32