Badger::Storage::Filesystem
use Badger::Storage::Filesystem; # create a storage object - path is required, codec is optional my $storage = Badger::Storage::Filesystem->new( path => '/path/to/dir', codec => 'yaml', # default codec is Storable ); # some sample data my $data = { message => 'Hello World!', numbers => [1.618, 2.718, 3.142], }; # create a new record my $id = $storage->create($data); # fetch data for identifier - returns undef if not found $data = $storage->fetch($id) || die $storage->error; # insert/update data using identifier $storage->store($id, $data); # delete data using identifier $storage->store($id, $data);
The Badger::Storage::Filesystem module is a subclass of Badger::Storage for storing data in files on your local filesystem.
The following methods are implemented in addition to those inherited from the Badger::Storage, Badger::Prototype and Badger::Base base classes.
All the methods listed below raise errors by throwing Badger::Exception objects (as is
the convention for all Badger
modules). Note that in the specific cases of the fetch() and delete() methods, it is not considered
an error to attempt to fetch or delete a record that does not exists. In
this case, the methods will call decline() and return undef
.
If your application logic dictates that a particular resource must exist then you should add your own code to test the return value and upgrade it to an error if necessary.
my $data = $storage->fetch($id) || die "Could not fetch data: ", $storage->error;
In all other cases you can effectively ignore error handling at the lower level. For example, there is no need to check the return value of the store() method. If it returns then it has succeeded. If it fails then an exception will be thrown.
$storage->store;
Depending on the environment you're programming in, you can either let
the exception terminate the program with the error message (e.g. for a
command line script), or trap it at a higher level using
eval
or try() and present it to the user in an appropriate
way (e.g. generating an error page for a web application).
The create()
method first calls the the generate_id() method to generate a new
identifier for the data. It then call the store() method, passing the identifier along
with the data passed to it as an argument. It returns the newly created
identifier.
my $id = $storage->create($data);
It returns the newly created identifier for the data record. Errors are thrown as exceptions. You can use the try() method inherited from Badger::Base if you want to catch any exceptions.
my $id = $storage->try->create($data) || warn $storage->error;
This is equivalent to:
my $id = eval { $storage->create($data) } || warn $storage->error;
This method is used to store data. The first argument is a unique identifier for the data. The second argument should be a reference to the data to be stored (e.g. a hash or list reference).
$storage->store($id, $data);
It returns a true value which you can test if you want the warm glow of satisfaction that it performed its job as expected.
if ($storage->store($id, $data)) { # phew! }
However, all errors are thrown as exceptions so there's no need to
test the return value at all. If the method returns, then it succeeded.
You can use eval { }
if you want to trap errors, or the try() method, as
shown in the documentation for create().
This method is used to fetch data. The single argument is a unique identifier for the data, such as that returned by a previous call to the create() method, or passed as the first argument in a call to the store() method.
my $data = $storage->fetch($id);
If the data cannot be found then the method returns undef
by
calling its own decline() method (inherited from Badger::Base). You can call the error() method to
view the message generated.
my $data = $storage->fetch('foo') || print $storage->error; # e.g. File not found: foo
It is important to understand the difference between the method
declining to return a value and an error. If the data for
the requested identifier cannot be found then the method returns
undef
by calling its own decline() method. This is
considered part of its normal operation. It is not an error to ask
for something that doesn't exists. The method will politely turn you
away.
On the other hand, if the method is prevented from looking for the data and either returning it or declining, for whatever reason, then an exceptions will be thrown. It could be that the the file contents got mangled, the database is offline, the network is down, or maybe you forgot to pass an identifier as a parameter. These are all error conditions that are considered outside of normal operation.
If your application dictates that a missing resource is an error
then you should add the appropriate code to any call to
fetch()
. For example, if your application is loading a
configuration file then you probably want to know right away if the
configuration file is missing, misnamed, or otherwise unloaded for
whatever reason.
my $config = $storage->fetch( $config_file_name ) || die $storage->error;
Permanently deletes the data associated with the identifier passed as an argument.
$storage->delete($id);
Returns a true value on success. If the data does not exist then it
returns undef
. All errors are thrown as exceptions. As with fetch(), deleting a resource that does not
exists is not considered an error. The method will decline() gracefully.
This method should be redefined by subclasses to perform any storage-specific initialisation.
Andy Wardley http://wardley.org