NAME

LRpt::Collection - A container for rows returned by select statement.

DESCRIPTION

This class is a part of LRpt (LReport) library. This module is a container for one csv file. Rows are stored in a form of hashes returned by DBI's fetch_arrayref( {} ) . Keys of a hash are column names, values are column values. References to all rows are kept in a list, in an order in which they are kept in csv file. Collection provides a notion of a row key. You can use row keys for ordering rows and for quick searches of row with a particular key value (like in databases). Collection may have several keys defined. Each key has a name, columns, which compose a key and a function, which basing on key fields' values, generates a string, which can be used as a hash key.

METHODS

init_keys_data

  $coll->init_keys_data( $keys_info );

Initializes internal structure, storing information about keys. The meaning of fields is as follows:

$self-{ keys }>

Hash. Key in a hash is a key name. Value is a reference to a hash with the following key-value pairs:

columns => reference to array of names of columns which are part of the key

function => reference to a function, which creates a key value from the columns' values. If not defined generate_key is used.

After initialization, current key is set to the first specified key.

build_keys

  $coll->build_keys();

Builds all data structures needed for efficient use of keys for rows retrieval. It generates a key value for each row. Then creates the following structure:

  $self->{ 'keyed_rows' } => Reference to a hash. Key of a hash is a name 
                             of a key. Value is a reference to a hash in 
                             which key is a value of row key, and hash 
                             value is reference to a row.

Accesing a row with key = xxx would require to use the following reference:

  $self->{ 'keyed_rows' }->{ 'rows' }->{ 'xxx' }

build_one_key

  $coll->build_one_key();

Builds a structure described in build_keys for one row key. All rows, which do not have values for all columns from the key, are moved to a list of 'unkeyed' rows.

get_unkeyed_coll

  $unk_rows = $coll->get_unkeyed_coll();

Returns a reference to a collection of 'unkeyed' rows (LRpt::CollUnkeyed).

has_all_key_columns

  $coll->has_all_key_columns($row );

Checks if a rows has values in columns, which are part of a key

dump_rows

  $coll->dump_rows( $path );

Dumps rows from the collections to the text file (tab separated)

upload_from_csv

  $coll->upload_from_csv( $path );

Uploads rows from the text file (tab separated)

get_name

  $coll->get_name();

Gets the name of the collection.

get_columns

  $coll->get_columns();

Returns all columns names returned by the select

generate_key

  my $key_value = LRpt::Collection::generate_keys( $row, $key );

Default function for generating row key values. It simply joins all key columns using '#' as a separator

get_key_value

  my $key_value = $coll->get_key_value( $row );

Returns value of the current key for a given row.

get_key_columns

  my @cols = $coll->get_key_columns();

For a given key (or the current key, of no key name given) returns all columns, which are part of the a key.

order_columns

  my $cols = $coll->order_columns( $unord_cols );

Orders and returns columns by their appearance in the table

generate_fmt_key

  my $key_str = LRpt::Collection::generate_fmt_key( $row, $key );

Generates a key string, which can be used as a key in a hash.

get_keyed_rows

  my $rows = $coll->get_keyed_rows();

Returns a reference to a hash were keys are values of key and values are reference to rows with those keys.

get_key_values

  my @values = $coll->get_key_values();

Returns all values of a given key.

get_row

  my $row = $coll->get_row( $key_value )

Using a key value $key_value for key retrieves a row.

no_rows

  my $res = $coll->no_rows();

Returns 1 if collection is empty

adopt_rows

  $coll->adopt_rows( $rows );

Appends a set of rows to the collection ( $rows should be a reference to and array of references to hashes, each representing one row ).

get_all_rows

  $coll->get_all_rows();

Returns a reference to a list containing all rows in the order returned by select.

INTERNAL DATA STRUCTURE

Below you can find something, which is my pathetic attempt to create a readable diagram. It is supposed to show a hierarchy of internal data structure. I am open to suggestions how to make it look more readable

  $self->
      |
      |->{ name }
      |->{ data_file }
      |->{ key }
      |   |->{ columns }  = [ $col1, $col2, ... ]
      |   |->{ function } = $fmt_string   
      |->{ columns } = $sth->{ 'NAME' }
      |->{ col_idxs } = $sth->{ 'NAME_hash' }
      |->{ rows }      = [ $row1, $row2, ... , $rown ]
      |->{ unkeyed_coll } = LRpt::CollUnkeyed object
      |->{ keyed_rows }
      |   |->{ $key_value1 } = $self->{ rows }->[ ... ]
      |   |->{ $key_value2 } = $self->{ rows }->[ ... ]
      |   |->{ ........... } = $self->{ rows }->[ ... ]
      |   |->{ $key_valueN } = $self->{ rows }->[ ... ]
      |->{ select_stmt }
      |   |->{ statement } --> obsolete

name

Name of a collection. Does not have a particular meaning for Collection object itself, but is helpful for managing a group of collections and is used by other LRpt modules

data_file

Name of a csv file used as a data source

key

A structure keeping an information about row key used by a collection. Key entry contains 'columns' which is a reference to list of columns which are parts of a key (order matters), and a function, which specifies some additional formatting, which should be applied to key columns in order to get a key value. Currently it's a formatting string used by sprintf to build one string from all key columns. If function is not given, it is a simple concatenation.

columns

equivalent of DBI's $sth->{ 'NAME' } - A list of columns in the order from the row

col_idxs

equivalent of DBI's $sth->{ 'NAME_hash' } - A hash in which a key is column name and value is an index of a column in a row.

rows

A reference to a list of all rows returned by the select/uploaded from csv file

unkeyed_coll

collection of rows, for which not all columns being part of a row key are defined.

keyed_rows

Additional structure used for performance when accessing single rows using row keys. For each row key name it defines a hash. Each key in this hash is a key value, hash value is a reference to a row having this key value.

SEE ALSO

The project is maintained on Source Forge http://lreport.sourceforge.net. You can find there links to some helpful documentation like tutorial.

AUTHORS

Piotr Kaluski <pkaluski@piotrkaluski.com>

COPYRIGHT

Copyright (c) 2004-2006 Piotr Kaluski. Poland. All rights reserved.

You may distribute under the terms of either the GNU General Public License or the Artistic License, as specified in the Perl README file.

cpanm LRpt

perl -MCPAN -e shell
install LRpt