NAME

SPOPS::HashFile - Implement as objects files containing perl hashrefs dumped to text

SYNOPSIS

 my $config = SPOPS::HashFile->new({ filename => '/home/httpd/myapp/server.perl',
                                     perm     => 'read' } );
 print "My SMTP host is $config->{smtp_host}";

 # Setting a different value is ok...
 $config->{smtp_host} = 'smtp.microsoft.com';

 # ...but this will throw an exception since you set the permission to
 # read-only 'read' in the 'new' call
 $config->save;

DESCRIPTION

Implement a simple interface that allows you to use a perl data structure dumped to disk as an object. This is often used for configuration files, since the key/value, and the flexibility of the 'value' part of the equation, maps well to varied configuration directives.

METHODS

new( { filename => $, [ perm => $ ] } )

Create a new SPOPS::HashFile object that uses the given filename and, optionally, the given permission. The permission can be one of three values: 'read', 'write' or 'new'. If you try to create a new object without passing the 'new' permission, the action will die because it cannot find a filename to open. Any value passed in that is not 'read', 'write' or 'new' will get changed to 'read', and if no value is passed in it will also be 'read'.

Note that the 'new' permission does not mean that a new file will overwrite an existing file automatically. It simply means that a new file will be created if one does not already exist; if one does exist, it will be used.

The 'read' permission only forbids you from saving the object or removing it entirely. You can still make modifications to the data in the object.

This overrides the new() method from SPOPS.

fetch( $filename, [ { perm => $ } ] )

Retrieve an existing config object (just a perl hashref data structure) from a file. The action will result in a 'die' if you do not pass a filename, if the file does not exist or for any reason you cannot open it.

save

Saves the object to the file you read it from.

remove

Deletes the file you read the object from, and blanks out all data in the object.

clone( { filename => $, [ perm => $ ] } )

Create a new object from the old, but you can change the filename and permission at the same time. Example:

 my $config = SPOPS::HashFile->new( { filename => '~/myapp/spops.perl' } );
 my $new_config = $config->clone( { filename => '~/otherapp/spops.perl',
                                    perm => 'write' } );
 $new_config->{base_dir} = '~/otherapp/spops.perl';
 $new_config->save;

This overrides the clone() method from SPOPS.

NOTES

No use of SPOPS::Tie

TO DO

Use SPOPS::Tie

This is one of the few SPOPS implementations that will never use the SPOPS::Tie class to implement its data holding. We still use a tied hash, but it is much simpler -- no field checking, no ensuring that the keys match in case, etc. This just stores some information about the object (filename, permission, and data) and lets you go on your merry way.

However, since we recently changed SPOPS::Tie to make field-checking optional we might be able to use it.

BUGS

SEE ALSO

SPOPS

Data::Dumper

COPYRIGHT

Copyright (c) 2001-2004 intes.net, inc.. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHORS

Chris Winters <chris@cwinters.com>

cpanm SPOPS

perl -MCPAN -e shell
install SPOPS