Text::CSV::Merge - Fill in gaps in a CSV file from another CSV file


version 0.05


    my $merger = Text::CSV::Merge->new({
        base    => 'into.csv',
        merge   => 'from.csv',
        output  => 'output.csv',  # optional
        columns => [q/email name age/],
        search  => 'email',
        first_row_is_headers => 1  # optional

    ## Now, there is a new CSV file named 'merged_output.csv' by default, 
    #  in the same directory as the code which called C<$merger->merge();>.


The use case for this module is when one has two CSV files of largely the same structure. Yet, the 'from.csv' has data which 'into.csv' lacks.

In this initial release, Text::CSV::Merge only fills in empty cells; it does not overwrite data in 'into.csv' which also exists in 'from.csv'.


Text::CSV::Merge may be subclassed. In the subclass, the following attributes may be overridden:

  • csv_parser

  • dbh

  • logger



The logger for all operations in this module.

The logger records data gaps in the base CSV file, and records which data from the merge CSV file was used fill the gaps in the base CSV file.


The CSV parser used internally is an immutable class property.

The internal CSV parser is the XS version of Text::CSV: Text::CSV_XS. You may use Text::CSV::PP if you wish, but using any other parser which does not duplicate Text::CSV's API will probably not work without modifying the source of this module.

Text::CSV_XS is also used, hard-coded, as the parser for DBD::CSV. This is configurable, however, and may be made configurable by the end-user in a future release. It can be overridden in a subclass.


Create reusable DBI connection to the CSV data to be merged in to base file.

This method is overridable in a subclass. A good use of this would be to merge data into an existing CSV file from a database, or XML file. It must conform to the DBI's API, however.

DBD::CSV is a base requirement for this module.


The CSV file into which new data will be merged.

The base file is readonly, not read-write. This prevents accidental trashing of the original data.


The CSV file used to find data to merge into base_file.


The output file into which the merge results are written.

I felt it imperative not to alter the original data files. I may make this a configurable option in the future, but wold likely set its default to 'false'.


The columns to be merged.

A column to be merged must exist in both base_file and merge_file. Other than that requirement, each file may have other columns which do not exist in the other.


The column/field to match rows in merge_file.

This column must exist in both files and be identically cased.


1 if the CSV files' first row are its headers; 0 if not.

If there are no headers, then the column names supplied by the columns argument/property are applied to the columns in each file virtually, in numerical orders as they were passed in the list.



Main method and is public.

merge() performs the actual merge of the two CSV files.


This method locally overrides a Moo built-in.

It close out all file handles, which will only occur after a call to merge().



Michael Gatto <>


This software is copyright (c) 2013 by Michael Gatto.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.