#!/usr/pkg/bin/perl

#
# cgi_to_db.pm
# Copyright (C) 1998-2018 by John Heidemann
#
# This program is free software; you can redistribute it and/or
# modify it under the terms of the GNU General Public License,
# version 2, as published by the Free Software Foundation.
# 
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
# 
# You should have received a copy of the GNU General Public License along
# with this program; if not, write to the Free Software Foundation, Inc.,
# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
#


=head1 NAME

cgi_to_db - convert stored CGI files (from CGI.pm) to fsdb

=head1 SYNOPSIS

    cgi_to_db [-duU] [-e EmptyValue] [cgi-files...]

=head1 DESCRIPTION

Converts all stored CGI files (from CGI.pm) to fsdb,
optionally unescaping the contents.
When contents are unescaped, CR NL is recoded as ``\n''.

Output is always in fsdb list format with double space (type ``S'')
field separator.

Unlike most Fsdb programs, the input to this program is 
I<not> usually from standard input.  However, the program will take 
C<-i> options.

This program requires temporary storage equal to the size of the data
(so that it can handle the case of different entries having different
headers).

=head1 OPTIONS

=over 4

=item B<-u> or B<--unescape>

do unescape data, converting CGI escape codes like %xx
to regular characters (default)

=item B<-U> or B<--nounescape>

do I<not> unescape data, but leave it CGI-encoded

=item B<-e E> or B<--empty E>

give value E as the value for empty (null) records

=item B<-T TmpDir>

where to put tmp files.
Also uses environment variable TMPDIR, if -T is 
not specified.
Default is /tmp.

=back

=for comment
begin_standard_fsdb_options

This module also supports the standard fsdb options:

=over 4

=item B<-d>

Enable debugging output.

=item B<-i> or B<--input> InputSource

Read from InputSource, typically a file name, or C<-> for standard input,
or (if in Perl) a IO::Handle, Fsdb::IO or Fsdb::BoundedQueue objects.

=item B<-o> or B<--output> OutputDestination

Write to OutputDestination, typically a file name, or C<-> for standard output,
or (if in Perl) a IO::Handle, Fsdb::IO or Fsdb::BoundedQueue objects.

=item B<--autorun> or B<--noautorun>

By default, programs process automatically,
but Fsdb::Filter objects in Perl do not run until you invoke
the run() method.
The C<--(no)autorun> option controls that behavior within Perl.

=item B<--help>

Show help.

=item B<--man>

Show full manual.

=back

=for comment
end_standard_fsdb_options


=head1 SAMPLE USAGE

=head2 Input:

file A (TEST/cgi_to_db_ex.in):

    name=test
    id=111-11-1111
    email=test%40usc.edu
    submit_time=Tue%20Jan%2014%2011%3A32%3A39%202003
    =

file B (TEST/cgi_to_db_ex.in-2):

    name=test2
    id=222-22-2222
    email=test2%40usc.edu
    newfield=foo
    emptyfield=
    submit_time=Tue%20Jan%2024%2022%3A32%3A39%202003
    =


=head2 Command:

    cgi_to_db TEST/cgi_to_db_ex.in TEST/cgi_to_db_ex.in-2


=head2 Output:

    #fsdb -R C -F S name id email submit_time newfield emptyfield
    name:  test
    id:  111-11-1111
    email:  test\@usc.edu
    submit_time:  Tue Jan 14 11:32:39 2003

    name:  test2
    id:  222-22-2222
    email:  test2\@usc.edu
    newfield:  foo
    emptyfield:  -
    submit_time:  Tue Jan 24 22:32:39 2003

    #  | cgi_to_db TEST/cgi_to_db_ex.in TEST/cgi_to_db_ex.in-2


=head1 SEE ALSO

L<Fsdb>.
L<CGI(3pm)>.
L<http://stein.cshl.org/boulder/>.
L<http://stein.cshl.org/WWW/software/CGI/>

=cut


# WARNING: This code is derived from cgi_to_db.pm; that is the master copy.

use Fsdb::Filter::cgi_to_db;
my $f = new Fsdb::Filter::cgi_to_db(@ARGV);
$f->setup_run_finish;  # or could just --autorun
exit 0;


=head1 AUTHOR and COPYRIGHT

Copyright (C) 1991-2018 by John Heidemann <johnh@isi.edu>

This program is distributed under terms of the GNU general
public license, version 2.  See the file COPYING
with the distribution for details.

=cut

1;
