#!/usr/bin/perl -w

#
# dbfilealter.pm
# Copyright (C) 2008-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
# in $dblibdir for details.
#


=head1 NAME

dbfilealter - alter the format of an Fsdb file, changing the row/column separator

=head1 SYNOPSIS

dbfilealter [-c] [-F fs] [-R rs] [-Z compression] [column...]

=head1 DESCRIPTION

This program reformats a Fsdb file,
altering the row (C<-R rs>) or column (C<-F fs>) separator.
It verifies that this action does not violate the
file constraints (for example, if spaces appear in data and 
the new format has space as a separator),
and optionally corrects things.

With C<-Z compression> it controls compression on the file

=head1 OPTIONS

=over 4

=item B<-F> or B<--fs> or B<--fieldseparator> S

Specify the field (column) separator as C<S>.
See below for valid field separators.

=item B<-R> or B<--rs> or B<--rowseparator> S

Specify the row separator as C<S>.
See below for valid row separators.

=item B<-Z> or B<--compression> S

Specify file compression as given by file extension C<S>.
Supported compressions are F<gz> for gzip,
F<bz2> for bzip2,
F<xz> for xz,
or "none" or undef to disable compression.
Default is none.

=item B<-c> or B<--correct>

Correct any inconsistency caused by the new separators,
if possible.

=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

=head2 Valid Field Separators


=over 4

=item B<D>
default: any amount of whitespace on input, tabs on output.

=item B<s>
single space (exactly one space for input and output).

=item B<S>
double space on output; two or more spaces on input.

=item B<t>
single tab character (exactly one tab for input and output).

=item B<XN>
take I<N> as one or more hex digits that specify a unicode character.
Accept one or more of those characters on input,
output exactly one of those characters.

=item B<CA>
take I<A> as a one (unicode) literal character.
Accept one or more of those characters on input, 
output exactly one of those characters.

=back

Potentially in the future C<xN> and C<cA> will support
single-character-on-input equivalents of C<XN> and <CA>.

=head2 Valid Row Seperators

Three row separators are allowed:

=over 4

=item B<D>
the default, one line per row

=item B<C>
complete rowized. 
Each line is a field-labeled and its value,
and a blank line separates "rows".
All fields present in the output.

=item B<I>
incompletely rowized.
Like C<C>, but 
null fields are omitted from the output.

=back


=head1 SAMPLE USAGE

=head2 Input:

    #fsdb name id test1
    a 1 80
    b 2 70
    c 3 65

=head2 Command:

    cat data.fsdb | dbfilealter -F S

=head2 Output:

    #fsdb -F S name id test1
    a  1  80
    b  2  70
    c  3  65
    #  | dbfilealter -F S

=head2 Command 2:

    cat data.fsdb | dbfilealter -R C

=head2 Output:

    #fsdb -R C name id test1
    name: a
    id: 1
    test1: 80
    
    name: b
    id: 2
    test1: 70
    
    name: c
    id: 3
    test1: 65
    
    #   | dbfilealter -R C

=head2 Correction mode input:

    #fsdb -F S name id test1
    a student  1  80
    b nice  2  70
    c all  3  65

=head2 Correction mode command:

    cat correction.fsdb | dbfilealter -c -F D

=head2 Correction mode output:

    #fsdb name id test1
    a_student	1	80
    b_nice	2	70
    c_all	3	65
    #   | dbfilealter -c -F D

=head1 SEE ALSO

L<Fsdb>,
L<dbcoldefine>.


=cut


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

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


=head1 AUTHOR and COPYRIGHT

Copyright (C) 2008-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;