James E Keenan > Text-CSV-Hashify-0.05 > Text::CSV::Hashify

Download:
Text-CSV-Hashify-0.05.tar.gz

Dependencies

Annotate this POD

CPAN RT

Open  0
View/Report Bugs
Module Version: 0.05   Source   Latest Release: Text-CSV-Hashify-0.06

NAME ^

Text::CSV::Hashify - Turn a CSV file into a Perl hash

SYNOPSIS ^

    # Simple functional interface
    use Text::CSV::Hashify;
    $hash_ref = hashify('/path/to/file.csv', 'primary_key');

    # Object-oriented interface
    use Text::CSV::Hashify;
    $obj = Text::CSV::Hashify->new( {
        file        => '/path/to/file.csv',
        format      => 'hoh', # hash of hashes, which is default
        key         => 'id',  # needed except when format is 'aoh'
        max_rows    => 20,    # number of records to read; defaults to all
        ... # other key-value pairs possible for Text::CSV
    } );

    # all records requested
    $hash_ref       = $obj->all;

    # arrayref of fields input
    $fields_ref     = $obj->fields;

    # hashref of specified record
    $record_ref     = $obj->record('value_of_key');

    # value of one field in one record
    $datum          = $obj->datum('value_of_key', 'field');

    # arrayref of all unique keys seen
    $keys_ref       = $obj->keys;

DESCRIPTION ^

The Comma-Separated-Value ('CSV') format is the most common way to store spreadsheets or the output of relational database queries in plain-text format. However, since commas (or other designated field-separator characters) may be embedded within data entries, the parsing of delimited records is non-trivial. Fortunately, in Perl this parsing is well handled by CPAN distribution Text::CSV. This permits us to address more specific data manipulation problems by building modules on top of Text::CSV.

Note: In this document we will use CSV as a catch-all for tab-delimited files, pipe-delimited files, and so forth. Please refer to the documentation for Text::CSV to learn how to handle field separator characters other than the comma.

Primary Case: CSV (with primary key) to Hash of Hashes

Text::CSV::Hashify is designed for the case where you simply want to turn a CSV file into a Perl hash. In particular, it is designed for the case where (a) the CSV file's first record is a list of fields in the ancestral database table and (b) one field (column) of which functions as a primary key, i.e., each record's entry in that field is distinct from every other record's entry therein.

Text::CSV::Hashify turns that kind of CSV file into one big hash of hashes. Elements of this hash are keyed on the entries in the designated primary key field and the value for each element is a hash reference of all the data in a particular database record (including the primary key field and its value).

Secondary Case: CSV (lacking primary key) to Array of Hashes

You may, however, encounter cases where a CSV file's header row contains the list of database fields but no field is capable of serving as a primary key, i.e., there is no field in which the entry for that field in any record is guaranteed to be distinct from the entries in that field for all other records.

In this case, while an individual record can be turned into a hash, the CSV file as a whole cannot accurately be turned into a hash of hashes. As a fallback, Text::CSV::Hashify can, upon request, turn this into an array of hashes. In this case, you will not be able to look up a particular record by its primary key. You will instead have to know its index position within the array (which is equivalent to knowing its record number in the original CSV file minus 1).

Interfaces

Text::CSV::Hashify provides two interfaces: one functional, one object-oriented.

Use the functional interface when all you want is to turn a CSV file with a primary key field into a hash of hashes.

Use the object-oriented interface for any more sophisticated manipulation of the CSV file. This includes:

Note: On the recommendation of the authors/maintainers of Text::CSV, Text::CSV::Hashify will internally always set Text::CSV's binary => 1 option.

FUNCTIONAL INTERFACE ^

Text::CSV::Hashify by default exports one function: hashify().

    $hash_ref = hashify('/path/to/file.csv', 'primary_key');

Function takes two arguments: path to CSV file; field in that file which serves as primary key.

Returns a reference to a hash of hash references.

OBJECT-ORIENTED INTERFACE ^

new()

all()

fields()

record()

datum()

keys()

AUTHOR ^

    James E Keenan
    CPAN ID: jkeenan
    jkeenan@cpan.org
    http://thenceforward.net/perl/modules/Text-CSV-Hashify

COPYRIGHT ^

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

The full text of the license can be found in the LICENSE file included with this module.

Copyright 2012, James E Keenan. All rights reserved.

OTHER CPAN DISTRIBUTIONS ^

Text-CSV and Text-CSV_XS

These distributions underlie Text-CSV-Hashify and provide all of its file-parsing functionality. Where possible, install both. That will enable you to process a file with a single, shared interface but have access to the faster processing speeds of XS where available.

Text-CSV-Slurp

Like Text-CSV-Hashify, Text-CSV-Slurp slurps an entire CSV file into memory, but stores it as an array of hashes instead.

Text-CSV-Auto

This distribution inspired the max_rows option to new().

syntax highlighting: