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

http://rt.cpan.org/NoAuth/ReportBug.html?Queue=File-BLOB

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.

cpanm File::BLOB

perl -MCPAN -e shell
install File::BLOB