DWH_File (the Deep 'n' Wide Hash)
- persistence for complex datastructures and objects in Perl

version 0.02

FILES:

The complete DWH_File portfolio consists of the following files
 DWH_File.pm  - the packages that make DWH_File tick
 DWH_Excluder.pl - script controls locking when the muEx: fork option is used
 README - this file

INSTALLATION:

Currently DWH_File is quite compact and it is pure Perl so you just put
it anywhere you like (provided that it's somewhere Perl knows that it should
look for modules). This (combined with the fact that I've no idea how to
make such a thing) is why there's no MakeFile.PL for DWH_File. For the
muEx = fork option to work DWH_Excluder.pl must be setuid.

WHAT IT DOES:

DWH_File is used in a similar manner to NDBM_File, DB_File etc. In fact it
depends on one of these. DWH_File expands the functionality to save not
only the hash that is tied but also all the data that this hash contains
references to - that is it'll save all you list of lists and list of hashes
and so forth. And what's more, it will save objects as well - if they'll
comply with some very simple rules which don't impose any limitations to
their funtionality or structure except that they can't themselves be tied
to anyone else. See the "Models" section of the embedded documentation for
details.

.pod documentation is included in the .pm file.

As the version number (0.02) indicates this is a very early beta state
piece of software. Please contact me if you have any comments or suggestions
- also language corrections or other comments on the documentation.

TO DO:

DWH_File does what I need it to do in it's present form, so i can't promise
to be very eager to develop it further - but here are some of the things I
have in mind:

    * decent tests and due criticism for the mutual exlusion schemes
    * rethink the Excluder.pl trick
    * support for garbage collection despite circular references
    * support for checking file consistency and repair options
    * more error checking and recovery generally
    * make linked-list arrays available as alternative
    * make different hash-key-registry options available
      (array, linked list, bulk)
    * make version-convertion available for archives as new versions appear

REQUESTS FOR COMMENTS AND HELP:

    ? Is it possible to get the "contents" of CODE references instead of
      just executing it? I mean - so that they can be stored as strings.

    ? Also I'm not a native English speaker so do correct.

    ? I don't know how to make a MakeFile.PL

HISTORY

    0.02 - Fixed bug which caused deep recursion when storing structures
           that wich contained reference cycles before storing.

    0.01 - Initially published version

Jakob Schmidt <sumus@aut.dk> 2000 July 31
Visit http://aut.dk/orqwood/dwh for complete info on
DWH_File and it's accomplices
