NAME
File::BLOB - A file (with name, and other metadata) you can BLOBify
SYNOPSIS
# Create a File::BLOB object from data or a filehandle
$file = File::BLOB->new( 'data' ); # Copies
$file = File::BLOB->new( \$data ); # Doesn't copy
$file = File::BLOB->new( $filehandle );
# Create from an existing file
$file = File::BLOB->from_file( 'filename.txt' );
# Create from a file uploaded via CGI
$file = File::BLOB->from_cgi( $CGI, 'param' );
# You can assign arbitrary headers/metadata when creating objects
$file = File::BLOB->new( 'filename.txt',
content_type => 'text/plain',
filename => 'myname.txt',
owner => 'ADAMK',
);
if ( $file->get_header('filename') eq 'filename.txt' ) {
$file->set_header( 'filename' => 'yourname.txt' );
}
# Get or change the content
if ( $file->get_content =~ /FOO/ ) {
my $backup = $file->get_content;
$file->set_content( 'data' );
$file->set_content( \$data );
$file->set_content( $filehandle );
}
# Freeze to and thaw from a BLOB
my $blob = $file->freeze;
$file = File::BLOB->thaw( $blob );
DESCRIPTION
One of the most common types of data found in systems ranging from email
to databases is a "file". And yet there is no simple way to create a
store a file is a chunk of data across all of these systems.
Modules designed for email aren't easily reusable in databases, and
while databases often support "BLOB" data types, they don't keep file
names and encoding types attached so that these files are usable beyond
treating them as mere data.
"File::BLOB" is an object that represents a file, Storable as a BLOB in
a database or some other system, but retaining metadata such as file
name, type and any other custom headers people want to attach.
The range of tasks it is intented to span include such things as pulling
a file from the database and sending it straight to the browser, saving
an object from CGI to a database, and so on.
In general, for code that needs to span problem domains without losing
the name of the file or other data.
Storage Format
"File::BLOB" stores its data in a way that is compatible with both
Storable and HTTP. The stored form looks a lot like a HTTP response,
with a series of newline-seperated header lines followed by two newlines
and then file data.
METHODS
new
$file = File::BLOB->new( $data );
$file = File::BLOB->new( \$data );
$file = File::BLOB->new( $iohandle );
$file = File::BLOB->new( $data,
header => 'value',
filename => 'file.txt',
);
Creates a new "File::BLOB" object from data.
It takes as its first param the data, in the form of a normal scalar
string (which will be copied), a "SCALAR" reference (which will not be
copied), or as a filehandle (any subclass of IO::Handle can be used).
While the "content_length" header will be set automatically, you may
wish to provide the "content_type" header yourself if know, to avoid
having to load File::Type to determine the file type.
Returns a "File::BLOB" object, or dies on error.
from_file
$file = File::BLOB->from_file( "/home/me/some_picture.gif" );
$file = File::BLOB->from_file( "foo.txt",
'content_type' => 'text/plain',
'foo' => 'bar',
);
The "from_file" method provides an alternative constructor that creates
an object directly from a file, using that filename and detecting the
MIME type automatically.
The same rules as for the "new" constructor apply regarding additional
parameters.
Returns a new "File::BLOB" object, or dies on error.
from_cgi
my $file = File::BLOB->from_cgi( $CGI, 'param' );
The "from_cgi" constructor allows you to create a "File::BLOB" object
from a named file upload field in a CGI form.
It takes a CGI object and a CGI param name. Only a single file upload
for the param is supported.
When called in list context, the "from_cgi" method will return a list of
"File::BLOB" objects, or the null list of there are no uploaded files
for the param.
When called in scalar context, the "from_cgi" method return a single
"File::BLOB" object (if more than one the first), or false ('') if there
are no file uploads.
An exception will be thrown if an error is encountered.
get_content
my $data = $file->get_content;
my $copy = $$data;
The "get_content" returns the contents of the file as "SCALAR"
reference.
Please note that the reference returned points to the actual data in the
object, so it should not modified. If you want to modify the contents,
you need to copy it first.
set_content
$file->set_content( $data );
$file->set_content( \$data );
$file->set_content( $iohandle );
The "set_content" method sets the contents of the file to a new value.
It takes a single param which should be an ordinary scalar (which will
be copied), a "SCALAR" reference (which will not be copied), or a
filehandle (any object which is a subclass of IO::Handle).
Because you aren't really meant to use this to add in entirely new
content, any "content_type" header will not be changed, although the
"content_length" header will be updated.
So while the modification of content without changing its type is fine,
don't go adding different types of data.
Returns true, or dies on error.
get_header
my $name = $file->get_header('filename');
The "get_header" method gets a named header for the file.
Names are case-insensitive but must be a valid Perl identifier. For
things that have a dash in HTTP (Content-Type:) use an underscore
instead.
Returns the header as a string, "undef" if a header by that name does
not exist, or dies on error.
set_header
# Set a header
$file->set_header('filename', 'foo.txt');
# Delete a header
$file->set_header('filename', undef );
The "set_header" method takes a header name and a value, and sets the
header to that value.
Names are case-insensitive but must be a valid Perl identifier. For
things that have a dash in HTTP (Content-Type:) use an underscore
instead.
Values must be a normal string of non-null length. If the value passed
is "undef", the header will be deleted. Deleting a non-existant header
will not cause an error.
Returns true if header set or dies on error.
freeze
my $string = $file->freeze;
The "freeze" method generates string that will be stored in the
database.
Returns a normal string.
thaw
my $file = File::BLOB->thaw( $string );
The "thaw" method takes a string previous created by the "frozen"
method, and creates the "File::BLOB" object from it.
Returns a "File::BLOB" object, or dies on error.
SUPPORT
Bugs should be reported via the CPAN bug tracker at
For other issues, contact the author.
AUTHOR
Adam Kennedy <adamk@cpan.org>
COPYRIGHT
Copyright 2005 - 2011 Adam Kennedy.
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
The full text of the license can be found in the LICENSE file included
with this module.