=head1 NAME

HTTP::File - Routines to deal with HTML input type file.


=cut

=head1 SYNOPSIS 

=head2 CGI.pm example

C<savepage.html> looks like this:

<H1>Upload a webpage</H1>

<FORM METHOD=POST ENCTYPE="multipart/form-data" action="/cgi-bin/webplugin/savepage.cgi"> 

<INPUT TYPE=file name=FILE_UPLOAD size=35> 

<INPUT TYPE=submit NAME=Action VALUE="Upload Ahoy!">

</FORM>


C<savepage.cgi> looks like this:

#!/usr/bin/perl

use CGI;
use HTTP::File;

$cgi = new CGI;

$upload_path='/tmp';

$raw_file = $cgi->param('FILE_UPLOAD');
$basename = HTTP::File::upload($raw_file,$upload_path);


print $cgi->header;
print $cgi->start_html;

print "$basename upload successfully.<BR>Upload path: ";
print $upload_path ? $upload_path : '/tmp';

print $cgi->end_html;

=head2 HTML::Mason example

<FORM METHOD=POST ENCTYPE="multipart/form-data" action="receive-upload.html">
<INPUT TYPE=file name=PHOTO_FILE size=35>
</FORM>

... then in receive-upload.html

<%init>
    use HTTP::File;
</%init>

<%perl>
$output_path="/var/spool";
$raw_file=$ARGS{PHOTO_FILE};
HTTP::File::upload($raw_file, $output_path);
</%perl>


=head1 DESCRIPTION

HTTP::File is a module to facilitate file uploads from HTML file input.It 
detects the basename of the raw file across MacOS, Windows, and Unix/Linux 
platforms.

=cut

=head2 sub platform

Uses a subset of the functionality of HTTP::Headers::UserAgent to determine
the type of machine that uploaded the file.



=head2 sub upload

Upload RAW_FILE to the local disk to a specified PATH, or to /tmp if PATH
is not specified.

    Returns the basename of the uploaded file;


As of version 3.1, there are two new args to upload():

=over 4 

=item * $debug

A third argument, C<$debug>, if non-zero will send
debugging information to STDERR. 

=item * $kludge

A fourth argument, C<$kludge>, if non-zero, will also write
the read data to a file in the temp directory.

=back

=head1 THIS FUNCTIONALITY EXISTS IN CGI.pm NOW

This module exists for backwards-compatibility. CGI.pm now has an C<upload()>
function which serves the same purpose.

=head1 AUTHOR

Terrence Brannon E<gt>tbone@cpan.orgE<lt>

binmode support for Windows 
added by Mark Zellers: (reverse com dot docent at mzellers

Perl 5.8.x taint compatibility added by Rodd Clarkson
rodd at redfishbluefish dot com dot au

Rodd also suggested that I refer people to a more modern and popular solution
to the problem of uploading files --- CGI.pm

=head1 SEE ALSO

L<CGI::Upload> - a newer and more secure version of this module. I
tried to use CGI::Upload, but after staring at the docs and pinging on
IRC, I still had no clue of how to do what I wanted. Thus the return
of my insecure, naive approach to the same problem. Caveat emptor,
whatever that means.


=cut


