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
     $fil  e = 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 <[email protected]>, <http://ali.as/>

COPYRIGHT
   Copyright 2005, 2006 Adam Kennedy. All rights reserved.

   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.

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.