package SuperSplit;
use strict;
=head1 NAME
SuperSplit - Provides methods to split/join in two dimensions
=head1 SYNOPSIS
use SuperSplit;
#first example: split on newlines and whitespace and print
#the same data joined on tabs and whitespace. The split works on STDIN
#
print superjoin( supersplit() );
#second: split a table in a text file, and join it to HTML
#
my $array2D = supersplit( \*INPUT ) #filehandle must be open
my $htmltable = superjoin( '
', "
\n
",
$array2D );
$htmltable = "
\n
" . $htmltable . "
\n
";
print $htmltable;
#third: perl allows you to have varying number of columns in a row,
# so don't stop with simple tables. To split a piece of text into
# paragraphs, than words, try this:
#
undef $/;
$_ = <>;
tr/.!();:?/ /; #remove punctiation
my $array = supersplit( '\s+', '\n\s*\n', $_ );
# now you can do something nifty as counting the number of words in each
# paragraph
my @numwords = (); my $i=0;
for my $rowref (@$array) {
push( @numwords, scalar(@$rowref) ); #2D-array: array of refs!
print "Found $numwords[$i] \twords in paragraph \t$i\n";
$i++;
}
=head1 DESCRIPTION
Supersplit is just a consequence of the possibility to use multi-dimensional
arrays in perl. Because that is possible, one also wants a way to
convenienently split data into a nD-array (at least I want to). And vice
versa, of course. Supersplit/join just do that.
Because I intend to use these methods in numerous one-liners and in my
collection of handy filters, an object interface is more often than not
cumbersome. So, this module exports two methods, but it's also all it has.
If you think modules shouldn't do that, period, use the object interface,
SuperSplit::Obj. TIMTOWTDI
=over 4
=item supersplit($colseparator,$rowseparator, (...,) $filehandleref || $string);
The first method, supersplit, returns a nD-array. To do that, it needs
data and the strings to split with. Data may be provided as a reference to
a filehandle, or as a string. If you want use a string for the data, you
MUST provide the strings to split with (3 argument mode). If you don't
provide data, supersplit works on STDIN. If you provide a filehandle (like
\*INPUT) or filename, supersplit doesn't need the splitting strings, and
assumes columns are separated by whitespace, and rows are separated by
newlines. Strings are passed directly to split. If you provide more strings,
they will split the higher dimensions.
Supersplit returns a multi-dimensional array or undef if an error occurred.
=item superjoin( $colseparator, $rowseparator, $array2D );
The second and last method, superjoin, takes a nD-array and returns it as a
string. The default behavior assumes 2D-array. In the string, columns
(adjacent cells) are separated by the first argument provided. Rows
(normally lines) are separated by the second argument. Alternatively, you
may give the 2D-array as the only argument. In that case, superjoin joins
columns with a tab ("\t"), and rows with a newline ("\n"). If you have
more dimensions in your array, all separators for all dimensions should be
provided.
Superjoin returns an undef if an error occurred, for example if you give a
ref to an hash. If your first dimension points to hashes or strings,
superjoin will return undef. Mixed arrays will break the code.
=back
=head1 AUTHOR
Jeroen Elassaiss-Schaap, with great help from tilly, who rewrote most of
the code for version 0.03..
=head1 LICENSE
Perl/ artisitic license
=head1 STATUS
Alpha
=cut
use Exporter;
use vars qw( @EXPORT @ISA @VERSION);
@VERSION = 0.03;
@ISA = qw( Exporter );
@EXPORT = qw( &supersplit &superjoin );
sub supersplit{
my $text = _text( pop );
$_[0] || ( $_[0] = '\s+' );
$_[1] || ( $_[1] = '\n' );
_split($text, @_);
}
sub _text{
my $fh = shift;
unless (defined($fh)) {
$fh = \*STDIN;
}
if (open INPUT, "<$fh" ) {
$fh = join '', ;
close INPUT;
}
no strict 'refs';
(join '', <$fh>) || $fh;
}
sub _split {
my $text = shift;
my $re = pop;
my @res = split($re, $text); # Consider the third arg?
if (@_) {
@res = map { _split( $_, @_) } @res;
}
\@res;
}
sub superjoin{
my $array_ref = pop;
push ( @_, "\t") if @_ < 1;
push ( @_, "\n") if @_ < 2;
return undef unless( ref( $array_ref ) eq 'ARRAY' );
return undef unless( ref( $array_ref->[0] ) =~ /ARRAY/ );
_join( @_, $array_ref);
}
sub _join{
my $array_ref = pop;
my $str = pop;
if (@_) {
@$array_ref = map {_join( @_, $_)} @$array_ref;
}
join $str, @$array_ref;
}
1;