Boulder::Util - Utility methods for simple Boulder IO interactions.

NAME

Boulder::Util - Utility methods for simple Boulder IO interactions.

SYNOPSIS


 #!/usr/bin/perl -w
 use strict;


 use Boulder::Util qw( boulder_save boulder_load );


 my $file ='pixies.txt';


 my $data = { 
     vocals => ['frank', 'kim'],
     guitar => ['frank', 'joey'],
     bass => 'kim',
     drums => 'david'
 };


 my $fh;
 open ($fh,">$file");
 boulder_save($fh,$data);
 close $fh;


 my $fh2;
 open ($fh2,"$file");
 while(my $q = boulder_load($fh2,Boulder::Util::QUERY)) {
     print "$q\n";
 }
 close $fh2;

DESCRIPTION

Boulder::Util is a utility package for manipulating simple Boulder IO records in a lightweight fashion.

Boulder IO is the native format output by the CGI package's save method. While working on a project I used that method to serialize the state of a query for later use. That later use did not involve a CGI request though. I wanted to avoid loading up the CGI package just to read in the file memory and the the Boulder manpage package itself seemed like a bit much. What I wished I had was a quick way of reading those records without incurring the overhead of either package.

The package provides two exportable methods for reading and writing. The load method works like a quasi-iterator were only one record is loaded at a time to allow developers to control memory consumption as they see fit.

This package does not support the entire Boulder IO format and makes a few asusmptions in the name of simplicity. Heirarchical records are not supported. Also the = character is assumed to always be the record delimiter. All data is always URL encoded. If you are working with data that was serialized by CGI as I was these are not a problem. If you do need these features then perhaps the the Boulder manpage package is for you.

METHODS

A file handle is required for all methods. When working with a HASH, multi-valued keys (field names) are represented as an ARRAY reference.

boulder_load(HANDLE,[$mode])

Loads one record from the handle provided and returns either an HTTP query string or HASH reference depending upon the mode. If no mode is specified or its value is unrecognized, HASH is assumed. Two constans of HASH and QUERY have been defined for use with the mode parameter.

HASH: In this mode boulder_load reads one record from the handle provided and returns the key/value pairs as a HASH reference. This mode is used as the default if no mode is specified.
QUERY: In this mode boulder_load reads one record from the handle provided and returns the key/value pairs as an HTTP query string.

boulder_save(HANDLE,\%hash)

Writes the HASH reference to the file. How it writes (append, overwrite/create) is entirely up to the handle that it is passed.

DEPENDENCIES

the CGI::Util manpage

LICENSE

The software is released under the Artistic License. The terms of the Artistic License are described at http://www.perl.com/language/misc/Artistic.html.

AUTHOR & COPYRIGHT

Boulder::Util - Utility methods for simple Boulder IO interactions.