NAME

MusicRoom::Text::CSV - Comma seperated files

DESCRIPTION

Read and write text files in a particular format

FORMAT

For the purposes of this module a CSV file looks like this:

    artist,name,year
    "Elvis Costello","Alison","1977"
    "Riuichi Sakamoto","23rd Psalm","1983"
    "Duane Eddy","Forty Miles of Bad Road","1959"

In particular the first line has the names of the attribites then each following line has a data entry. Multi-line entries can be dealt with provided they are quoted

scan($fh,%flags)

A routine that reads in CSV data from an IO filehandle. The standard way to use this function is like:

    use MusicRoom::Text::CSV;

    my $fh = IO::File->new("source.csv");
    MusicRoom::Text::CSV::scan($fh,action => \&process_entry);

    sub process_entry
      {
        my(%attribs) = @_;

        my $this_artist = $attribs{artist};
        my $this_name = $attribs{name};

        print "Next entry is $this_artist \"$this_name\"\n";
      }

The valid flags are:

    action: A routine to call for each line
    carp_msg: A routine to call to report problems
    allowed: List of attributes that are allowed
    required: List of attributes required
    required_quiet: List of attributes required

The allowed and required flags need either an array of hash reference, for example:

    MusicRoom::Text::CSV::scan($fh,action => \&process_entry,
                        required => ["name"]);

The required_quiet flag tells the routine that we require a group of columns to be present before proceeding, but that if they are missing we just want to fail silently. This is a good option if you want to process a bunch of CSV files some of which have the data you need but you don't know in advance which ones, a call like:

    MusicRoom::Text::CSV::scan($fh,action => \&process_entry,
                        required_quiet => ["id","format"]);

will silently skip over the CSV file if it does not have both a "format" and "id" column.

scan($fh,$cols_ref,$flags_ref,%data)

Output data to a CSV file. Here is an example:

    my @to_columns = ("year","name");

    my @order;
    foreach my $id (sort by_year keys %local_data)
      {
        push @order,$id;
      }
    my $fh = IO::File->new(">$target_file");
    MusicRoom::Text::CSV::write($fh,\@to_columns,
                     {order => \@order, replace => 's/\~\|/, /g'},
                     %local_data);

The flags are:

    sort_fun: A function to call to sort entries
    order: Array of keys selecting the entries
    replace: A rexeg pattern to apply before outputting