README
1DWH_File (the Deep 'n' Wide Hash)
2- persistence for complex datastructures and objects in Perl
3
4version 0.24
5
6INSTALLATION:
7
8$ perl Makefile.PL
9$ make
10$ make test
11$ make intall
12
13DWH_File consists of the DWH_File.pm module and a number of modules
14under the DHW_File::* name space. It's all pure perl and every module
15contains one package. Every package defines a perl class.
16
17WHAT IT DOES:
18
19DWH_File is used in a similar manner to NDBM_File, DB_File etc. In fact it
20depends on one of these. DWH_File expands the functionality to save not
21only the hash that is tied but also all the data that this hash contains
22references to - that is it'll save all you list of lists and list of hashes
23and so forth. And what's more, it will save objects as well - if they'll
24comply with some very simple rules which don't impose any limitations to
25their functionality or structure except that they can't themselves be tied
26to anyone else. See the "Models" section of the embedded documentation for
27details.
28
29.pod documentation is included in the DWH_File.pm file.
30
31NOTE:
32
33From version 0.1 on and again from version 0.22, the file format has
34changed.
35
36File conversions should not be that complicated though, but I haven't
37written any converter myself. It wouldn't surprise me if it works to
38dump the contents of at DWH_File-tied hash to a file using Storable
39or the like and then read it back in a hash tied to the new version of
40DWH_File.
41
42The old versions are available from CPAN at
43
44http://www.cpan.org/authors/id/S/SU/SUMUS/
45
46TO DO:
47
48DWH_File does what I need it to do in it's present form, so i can't promise
49to be very eager to develop it further - but here are some of the things I
50have in mind:
51
52 * support for garbage collection despite circular references
53 * support for checking file consistency and repair options
54 * more error checking and recovery generally
55 * make a logging facility (existed in pre-0.1 versions)
56 * make linked-list arrays available as alternative
57 * make different hash-key-registry options available
58 (array, linked list, bulk)
59 * make version-convertion available for archives as new versions appear
60 * test whether 0.1 format is actually more efficient than
61 0.03 format
62 * adding developer-oriented documentation and building a decent
63 DWH_File site under www.orqwood.dk
64
65Moreover I've changed the design in 0.22 in order to be able to support
66distribution of data and behaviour. Actually implementing this
67will probably take me a while...
68
69HISTORY
70
71 0.24 - This release doesn't fix anu bugs or add to the functionality
72 of DWH_File. It only contains techical additions for the
73 benefit of extension libraries (like the DWH_Lib::Harrashy
74 about to be published through www.orqwood.dk):
75 Added value parameter to
76 DWH_File::Tie::Subscripted::handle_new_noded() for DWH_Lib use
77 and subscript memory to nodes
78
79 0.23 - Added a skeleton mechanism for classes who declare themselves
80 "DWH_File::Aware" (by including this abstract class in their
81 heritage) to control the way their data is tied to DWH_File.
82 Also made the internal tieing process more dynamic to
83 promote reuse in special tieing-classes external to DWH_File
84 core. And a bugfix: The return value of delete() operations
85 on hashes was errouneous. This is fixed. Also added a couple
86 of testcases to verify this.
87
88 0.22 - Now references used as keys anywhere in a DWH_Filed structure
89 are real live references (and not just textual representations
90 which are meaningful only in the very first runtime invication
91 of the application using DWH_File). This has certain
92 consequences. See the .pod. Besides there has been an internal
93 change of design and formats. (Registry has changed it's meaning,
94 kernel properties feature added and used by registries and
95 class pools. Tied hashes now identify themselves using
96 URIs (file://....) in stead of by regeistering globally
97 in a (singleton) dictionary. This also has certain consequences
98 which are briefly summarized in the .pod.
99
100 0.21 - Fixed bug in push() to arrays (reference values were stored
101 as flat strings). Also added a digit in version number
102 so we're back on track and comply with CPAN conventions :-)
103
104 0.2 - Slight revision of untie management. Now allows selecting
105 specific DBM-module (a feature, that never came into
106 the rewrite 0.1, though documentation still claimed it
107 was there).
108
109 0.1 - Complete rewrite. New version much more OO-based. New
110 file-format using binary encodings in stead of
111 decimal strings (supposedly more efficient). More
112 comme il faut distribution with MakeFile.pl and
113 automated tests etc.
114
115 0.03 - Fixed bug introduced in 0.02 which caused wild duplication
116 of blessed references (objects)
117
118 0.02 - Fixed bug which caused deep recursion when storing structures
119 that wich contained reference cycles before storing.
120
121 0.01 - Initially published version
122
123Jakob Schmidt <schmidt@orqwood.dk> 2003 January 25
124Visit http://www.orqwood.dk/perl5/dwh for complete info on
125DWH_File and it's accomplices
126
127LOG
128
129 $Log: README,v $
130 Revision 1.8 2003/03/31 18:08:04 schmidt
131 Ready for release 0.24
132
133 Revision 1.7 2003/01/25 21:12:13 schmidt
134 Changes for 0.23 added, date and version nos updated
135
136 Revision 1.6 2003/01/04 23:29:54 schmidt
137 Updated for version 0.22
138
139 Revision 1.5 2002/11/02 22:51:04 schmidt
140 Update date
141
142 Revision 1.4 2002/11/02 22:49:18 schmidt
143 History and version for 0.21
144
145 Revision 1.3 2002/10/25 20:50:08 schmidt
146 History entry for version 0.2 entered
147
148 Revision 1.2 2002/09/29 23:05:10 schmidt
149 Made a few changes to get ready for release version 0.1 on CPAN
150
151 Revision 1.1.1.1 2002/09/27 22:41:49 schmidt
152 Imported
153