Persister - dump Perl variables

NAME SYNOPSIS AUTHOR DESCRIPTION METHODS NAME Persister - package to dump Perl variables SYNOPSIS use Persister; Persister->save( 'filename', \%somehash, 'somehash' ); Persister->save( 'othername', $object, 'object', 1 ); $object = Persister->readXML( 'othername' ); AUTHOR Robert Quince (robq@fiendish-demon-co-uk) DESCRIPTION This package allows Perl variables to be dumped to a file either in a format that can be read straight back into a script via the eval function, or in an XML tagged format that requires interpretation to reconstruct the variable. The tagged format is more suited to large variables that would otherwise take a significant amount of time to eval. It will only dump a reference to a variable, this is so that any type of variable can be passed and treated in the same manner. The passed in reference can be of any of the following types: * scalar * array * hash * blessed object The package will also print references to typeglobs, but these are not dealt with very well as they are references to all variables of the given name. The output for a glob of the form \*SOMEVAR will look like \*{<package::SOMEVAR}>. Dumping globs should be avoided as they cannot be reconstructed. The Perl eval mode output file is split into two sections, one for the ``body'' of the dumped variable, and one for any circular references within the structure. In the main body, any circular references are indicated by a value 'ref', the actual value of these are then set at the end of the file by a simple assignment statement. The first line of the output file is an assignment statement of the form: $<name> = <val> where the <val> is appropriate to the type of variable referenced, and <name> is whatever was passed to the save method. When the dumped file is read back in to a script, care must be taken to ensure that a variable $<name> is predeclared if the script is using the strict pragma. The XML mode output file makes use of node reference numbers to handle the circular references during reconstruction. For both output modes tabbed indentation is used to indicate levels of array and hash. If a file name of zero length is given then output will be written to the STDOUT stream instead. METHODS Persister->readXML Input: $file - name of the output file This method reads the given XML file and reconstructs the variable contained within. The method depends on the availability of the C<XML::Parser::PerlSAX> module. Return: reconstructed variable upon success, undef otherwise Persister->save Input: $file - name of the output file $thing - reference to a variable $name - name of variable to put in output $mode - undef or 0 for Perl mode, else XML mode This method dumps the referenced variable to the named file, $file, calling it $<$name>. If $file has no length, then output will be written to STDOUT instead of to a file. Return: true upon success, false otherwise