Adding first version of Records::Split

NAME
Records::Split - Splits a file or a list of records into smaller sets.

VERSION
0.01

SYNOPSIS
# Split the records and dump them into smaller files under log
directory.
# Each file would contain max of 100 records.
my $split = Records::Split->new( records => [ @records ], identifier =>
'set', split_into_records => 100 );
$split->dump;

# Split the records given in the file and dump them under log directory.
# There would be max 20 files.
# The number of records is equal to the number of records divided by
number of files.
my $split = Records::Split->new( file => $file, split_into_files => 20
);
$split->dump;

# Split the records given in the file and dump them under log directory.
# Based on the weight of each record, each set will contain the
# records whose cumulative sum does not exceeds 500.
my $split = Records::Split->new( records => [ @records ], wrecords => {
%records_weight }, split_by_weight => 500 );
$split->dump;

DESCRIPTION
This module will split a file/records into smaller sets based on the
arguments passed to the constructor.

It first creates one or more groups, one default group(also called
parent group) is always present.

If split_by_pattern is present in any of the groups, then that group is
broken into smaller sub-groups.

For each sub-group and using the group's configuration, the sub-groups
is split into sets.

If no split_by_pattern is present then a sub group is equal to the
group.

The sub groups can be split into sets in the following different ways.

* split_into_records
Split based on the number of records each set can hold.

* split_into_files
* split_by_weight
Split based on the maximum weight each set can hold.  Weight of a set
being the sum of each weight of the set's records.

CONSTRUCTOR
new ( CONSTRUCTOR ARGUMENTS )

Following are the constructor arguments

Top level arguments

identifier
Name for the parent group. By default, it is set.

records
List of records in a list.

file
List of records in a file.

Note: Only file or records should be specified in a group. But it is not
a mandatory parameter.
wrecords
A list of record, weight pairs. Used by split_by_weight parameter.

split_by_pattern
A regular expression. Sub groups will be created based on the different
values of $1.

split_into_records
Each set should not hold more than 'split_into_records' records.

split_into_files
There should not be more than 'split_into_files' sets.

split_by_weight
Each set's total weight should not exceed 'split_by_weight'.  Total
weight of each set being the sum of the weight of each
records in that set.

max_records
Valid only for split_by_weight. Records in a set should not exceed
ma_records no matter what is the total_weight of each set.

delimeter
Valid only if file is specified. By default the record separator is
"\n". If it is something else then specify a different
delimeter.

group arguments

One of group_by_pattern, file, or records should be specified to each
group.

All the records specified above can be used in each of the group's
configuration as well.

* identifier
If not specified then the parent group's identifier is taken and the
group number is suffixed to it.

METHODS
Following are the public methods

Will return the list of Records::Group objects which is created based on
the arguments provided.  Look at the documentation of
Records::Group for more details.

Note that number of groups created is number of groups defined in the
groups parameter plus the default(parent) group.

group

Returns a list of Records::Group objects. These group objects also have
the records assigned to them.

While the method 'groups' just create a Records::Group object, method
'group' groups the records into each group.

split

Does the actual task of splitting the groups after the groups are
created.  It returns a hash whose key is the identifer for each
subset and its value is reference to a list.

If you want to dump the sets into the files, then it would be better if
you use the dump method which internally calls this before
dumping the subsets into smaller fies.

You can use the hash in whatever way you wish. For eg. I am using it in
a simple way to print its contents.

my %subsets = $split->split;
while( my ($identifer, $record) = each %subsets ) {
print " $identifier ---> \n";
foreach my $rec ( @$record ) {
print $rec, "\n";
}
print "\n";
}

dump

Dumps the subsets under the dumpdir/dump_sets by default.  If you do not
like the dump_sets name, then pass your favorite sub-
directory name, For eg.

$split->dump('test_gen')

It will delete the dump dir before dumping the subsets into it.  Each
record in the file will be separated by the value of the
delimeter.

dumpdir

Returns the dumpdir which is going to be used to dump the subsets.  By
default, it is the current working directory if no argument
is specified.  You can edither set the dumpdir in the constructor or
change it by passing the new dumpdir to the method

$split->dumpdir('/my/log/dir/for/dumping/of/subsets')

records ( @records )

Returns the list of records which are going to split.  Pass the list of
records to set new list of records.

file ( $filename )

Returns the filename which stores the record. If filename is passed then
sets the filename.

delimeter

Returns the delimeter used by the module. Is read-only so always pass it
with the constructor.  The default value is the default
value of $/ which is "\n"
AUTHOR
Ankur Gupta ankur2012@inbox.com