.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "ShadowHash 3"
.TH ShadowHash 3 "2010-04-04" "perl v5.16.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Tie::ShadowHash \- Merge multiple data sources into a hash
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 4
\&    use Tie::ShadowHash;
\&    use DB_File;
\&    tie (%db, \*(AqDB_File\*(Aq, \*(Aqfile.db\*(Aq);
\&    $obj = tie (%hash, \*(AqTie::ShadowHash\*(Aq, \e%db, "otherdata.txt");
\&
\&    # Accesses search %db first, then the hashed "otherdata.txt".
\&    print "$hash{key}\en";
\&
\&    # Changes override data sources, but don\*(Aqt change them.
\&    $hash{key} = \*(Aqfoo\*(Aq;
\&    delete $hash{bar};
\&
\&    # Add more data sources on the fly.
\&    %extra = (fee => \*(Aqfi\*(Aq, foe => \*(Aqfum\*(Aq);
\&    $obj\->add (\e%extra);
\&
\&    # Add a text file as a data source, taking the first "word" up
\&    # to whitespace on each line as the key and the rest of the line
\&    # as the value.
\&    $split = sub { split (\*(Aq \*(Aq, $_[0], 2) };
\&    $obj\->add ([text => "pairs.txt", $split]);
\&
\&    # Add a text file as a data source, splitting each line on
\&    # whitespace and taking the first "word" to be the key and an
\&    # anonymous array consisting of the remaining words to be the
\&    # data.
\&    $split = sub { split (\*(Aq \*(Aq, $_[0]) };
\&    $obj\->add ([text => "triples.txt", $split]);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module merges together multiple sets of data in the form of hashes
into a data structure that looks to Perl like a single simple hash.  When
that hash is accessed, the data structures managed by that shadow hash are
searched in order they were added for that key.  This allows the rest of a
program simple and convenient access to a disparate set of data sources.
.PP
Tie::ShadowHash can handle anything that looks like a hash; just give it a
reference as one of the additional arguments to \fItie()\fR.  This includes
other tied hashes, so you can include \s-1DB\s0 and \s-1DBM\s0 files as data sources for
a shadow hash.  If given a plain file name instead of a reference, it will
build a hash to use internally, with each chomped line of the file being
the key and the number of times that line is seen in the file being the
value.
.PP
Tie::Shadowhash also supports special tagged data sources that can take
options specifying their behavior.  The only tagged data source currently
supported is \f(CW\*(C`text\*(C'\fR, which takes a file name of a text file and a
reference to a sub.  The sub is called for every line of the file, with
that line as an argument, and is expected to return a list.  The first
element of the list will be the key, and the second and subsequent
elements will be the value or values.  If there is more than one value,
the value stored in the hash and associated with that key is an anonymous
array containing all of them.
.PP
Tagged data sources are distinguished from normal data sources by passing
them to \fItie()\fR (or to \fIadd()\fR \*(-- see below) as an anonymous array.  The first
element is the data source tag and the remaining elements are arguments
for that data source.  For a text data source, see the usage summary above
for examples.
.PP
The shadow hash can be modified, and the modifications override the data
sources, but modifications aren't propagated back to the data sources.  In
other words, the shadow hash treats all data sources as read-only and
saves your modifications only in internal memory.  This lets you make
changes to the shadow hash for the rest of your program without affecting
the underlying data in any way (and this behavior is the main reason why
this is called a shadow hash).
.PP
If the shadow hash is cleared, by assigning the empty list to it, by
explicitly calling \s-1\fICLEAR\s0()\fR, or by some other method, all data sources are
dropped from the shadow hash.  There is no other way of removing a data
source from a shadow hash after it's been added (you can, of course,
always untie the shadow hash and dispose of the underlying object if you
saved it to destroy the shadow hash completely).
.SH "INSTANCE METHODS"
.IX Header "INSTANCE METHODS"
.IP "add(\s-1SOURCE\s0 [, \s-1SOURCE ...\s0])" 4
.IX Item "add(SOURCE [, SOURCE ...])"
Adds the given sources to an existing shadow hash.  This method can be
called on the object returned by the initial \fItie()\fR call.  It takes the
same arguments as the initial \fItie()\fR and interprets them the same way.
.SH "DIAGNOSTICS"
.IX Header "DIAGNOSTICS"
.ie n .IP "Can't open file %s: %s" 4
.el .IP "Can't open file \f(CW%s:\fR \f(CW%s\fR" 4
.IX Item "Can't open file %s: %s"
Tie::ShadowHash was given a file name to use as a source, but when it
tried to open that file, the open failed with that system error message.
.ie n .IP "Invalid source type %s" 4
.el .IP "Invalid source type \f(CW%s\fR" 4
.IX Item "Invalid source type %s"
Tie::Shadowhash was given a tagged data source of an unknown type.  The
only currently supported tagged data source is \f(CW\*(C`text\*(C'\fR.
.SH "CAVEATS"
.IX Header "CAVEATS"
It's worth paying very careful attention to \*(L"The untie Gotcha\*(R" in perltie
when using this module.  It's also important to be careful about what you
do with tied hashes that are included in a shadow hash.  Tie::ShadowHash
stores a reference to such arrays; if you untie them out from under a
shadow hash, you may not get the results you expect.  Remember that if you
put something in a shadow hash, you'll need to clean out the shadow hash
as well as everything else that references a variable if you want to free
it completely.
.PP
Not all tied hashes implement \s-1EXISTS\s0; in particular, ODBM_File, NDBM_File,
and some old versions of GDBM_File don't, and therefore AnyDBM_File
doesn't either.  Calling exists on a shadow hash that includes one of
those tied hashes as a data source may therefore result in an exception.
Tie::ShadowHash doesn't use exists except to implement the \s-1EXISTS\s0 method
because of this.
.PP
Because it can't use \s-1EXISTS\s0 due to the above problem, Tie::ShadowHash
cannot correctly distinguish between a non-existent key and an existing
key associated with an undefined value.  This isn't a large problem, since
many tied hashes can't store undefined values anyway, but it means that if
one of your data sources contains a given key associated with an undefined
value and one of your later data sources contains the same key but with a
defined value, when the shadow hash is accessed using that key, it will
return the first defined value it finds.  This is an exception to the
normal rule that all data sources are searched in order and the value
returned by an access is the first value found.  (Tie::ShadowHash does
correctly handle undefined values stored directly in the shadow hash.)
.SH "AUTHOR"
.IX Header "AUTHOR"
Russ Allbery <rra@stanford.edu>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright 1999, 2002, 2010 by Russ Allbery <rra@stanford.edu>
.PP
This program is free software; you may redistribute it and/or modify it
under the same terms as Perl itself.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
perltie
.PP
The current version of this module is always available from its web site
at <http://www.eyrie.org/~eagle/software/shadowhash/>.