view release on metacpan or  search on metacpan

lib/App/combinesheets.pm  view on Meta::CPAN

#-----------------------------------------------------------------
# App::combinesheets
# Author: Martin Senger <martin.senger@gmail.com>
# For copyright and disclaimer se below.
#
# ABSTRACT: command-line tool merging CSV and TSV spreadsheets
# PODNAME: App::combinesheets
#-----------------------------------------------------------------
use warnings;
use strict;

package App::combinesheets;

our $VERSION = '0.2.14'; # VERSION

use base 'App::Cmd::Simple';

use Pod::Usage;
use Pod::Find qw(pod_where);

use Text::CSV::Simple;
use Text::CSV_XS;
use File::Spec;
use File::Temp;
use File::Which;
use File::BOM qw( :all );
use Algorithm::Loops qw( NestedLoops );
use autouse 'IO::CaptureOutput' => qw(capture_exec);

# reserved keywords in the configuration
use constant {
    CFG_MATCH => 'MATCH',
    CFG_PROG  => 'PROG',
    CFG_PROGS => 'PROGS',
    CFG_PERL  => 'PERL',
};

# types of input files
use constant {
    TYPE_CSV => 'csv',
    TYPE_TSV => 'tsv',
#    TYPE_XSL => 'xsl',    # not-yet-supported
};

# hash keys describing an input ($inputs)
use constant {
    INPUT_FILE              => 'file',
    INPUT_TYPE              => 'type',
    INPUT_MATCHED_BY        => 'matched_by',
    INPUT_MATCHED_BY_INDEX  => 'matched_by_index',
    INPUT_HEADERS           => 'headers',
    INPUT_CONTENT           => 'content',
};

# hash keys describing wanted fields ($wanted_columns)
use constant {
    CFG_TYPE     => 'type',   # what kind of input (MATCH, PROG, PROGS or PERL)
    CFG_OUT_COL  => 'ocol',   # a name for this column used in the output
    # keys used for the normal (MATCH) columns
    CFG_ID       => 'id',     # which input
    CFG_IN_COL   => 'icol',   # a column in such input
    # keys used for the calculated columns (i.e. of type PROG, PROGS or PERL)
    CFG_EXT      => 'id',     # name of the external program or Perl external subroutine
    PERL_DETAILS => '_perl_details_', # added during the config processing
};

# ----------------------------------------------------------------
# Command-line arguments and script usage
# ----------------------------------------------------------------
sub usage_desc {
     my $self = shift;
     return "%c -config <config-file> -inputs <inputs> [other otions...]";
}
sub opt_spec {
    return (
        [ 'h'               => "display a short usage message" ],
        [ 'help'            => "display a full usage message"  ],
        [ 'man|m'           => "display a full manual page"    ],
        [ 'version|v'       => "display a version"             ],
        [],
        [ 'config|cfg=s'    => "<configuration file>"          ],
        [ 'inputs|i=s@{1,}' => "<input files> in the form: <input-ID>=<filename>[,<input-ID>=<filename>...] (e.g. PERSON=<persons.tsv>,CAR=<cars.csv>)"                                  ],
        [ 'outfile|o=s'     => "<output file>"                 ],
        [ 'check|c'         => "only check the configuration"  ],

        { getopt_conf => ['no_bundling', 'no_ignore_case', 'auto_abbrev'] }

lib/App/combinesheets.pm  view on Meta::CPAN

=item B<-outfile <output-file>>

An optional parameter specifying a filename of the combined result. By
default, it is created on STDOUT. It is always in the TAB-separated
format.

=item B<-check>

This option causes that the configuration file and the input files
(only their header lines will be read) will be checked for errors but
no resulting spreadsheet will be created.

=item B<-ignorecases>

Not yet implemented.

=item B<General options>

=over 8

=item B<-h>

Print a brief usage message and exits.

=item B<-help>

Print a brief usage message with options and exit.

=item B<-man>

Print a full usage message and exit.

=item B<-version>

Print the version and exit.

=back

=back

=head1 ENVIRONMENT VARIABLES

=head3 COMBINE_SHEETS_EXT_PATH

It contains a path that is used when looking for external programs
(when the reserved words PROG or PROGS are used). For example, the
C<examples> directory in the source distribution of this package has an
external program C<age.sh>. The full invocation can be done by:

   COMBINE_SHEETS_EXT_PATH=examples bin/combinesheets -cfg examples/cars.cfg --inputs CAR=examples/cars.csv

=head1 DEPENDENCIES

In order to run this tool you need Perl and the following Perl modules
to be installed:

   App::Cmd::Simple
   Text::CSV::Simple
   Text::CSV_XS
   File::BOM
   Getopt::Long::Descriptive
   Pod::Usage
   Algorithm::Loops

Optionally (if your configuration file uses the reserved word PROG or
PROGS for calculated columns):

   IO::CaptureOutput

=head1 KNOWN BUGS, MISSING FEATURES

=over

=item *

Columns are identified by their header names. There is no way
to identify them simply by their order (column number).

=item *

The input spreadsheet are read first into memory. Which may be
a problem with really huge spreadsheets.

=item *

The inputs can be COMMA-separated or TAB-separated. It would
be perhaps nice to allow also the Excel spreadsheets.

=item *

Comparing header names and rows is case-sensitive only. There
is a plan to implement the option C<-ignorecases>,

=back

Some of these missing features may be implemented later.

=head1 SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc App::combinesheets

You can also look for information at:

=over 4

=item * RT: CPAN's request tracker

L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=App-combinesheets>

=item * AnnoCPAN: Annotated CPAN documentation

L<http://annocpan.org/dist/App-combinesheets>

=item * CPAN Ratings

L<http://cpanratings.perl.org/d/App-combinesheets>

=item * Search CPAN