1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
|
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.
|
