Data::Describe - Perl extension for scanning/describing a text file or array.
use Data::Describe; $dsp = Data::Describe->new; # create an empty object my %arg = ( input_file_name => 'input.txt', # the same as 'ifn' skip_first_row => 'Y', # the same as 'sfr' input_field_sep => ',', # the same as 'ifs' ofs=>'|', # the same as 'output_field_sep' ofn=>'out.dat', # the same as 'output_file_name' odf=>'out.def', # the same as 'output_def_file' ); $dsp = Data::Describe->new(%arg); # with arguments $dsp->skip_first_row; # i,e. 1st row contains col names $dsp->set_sfr(1); # is the same as the above $dsp->set_ifs('\t'); # set input field separator to tab $dsp->input_field_separator('|'); # set input field separator to '|' $dsp->set_ofs('|'); # set output field separator to | $dsp->output_field_separator('|');# set output field separator to | $dsp->set_ifn('input.txt'); # set input file name $dsp->input_file_name('input.txt'); # set input file name $dsp->input_file_name($arf); # it can be array ref $dsp->set_ofn('out.dat'); # set output file name $dsp->output_file_name('out.dat');# set output file name $dsp->output_file_name('Y'); # it can be array ref $dsp->set_odf('out.def'); # set output def file name $dsp->output_def_file('output.def');# set output definition file name $dsp->output_def_file('Y'); # default to '${in}.def" # all the set method has its corresponding get method $rc = $dsp->get_sfr; $rc = $dsp->get_ifs; $rc = $dsp->input_field_separator; # the same as get_ifs $dsp->debug(5); # set debug level to 5 $dsp->echoMSG('This message', 1); # tag the message as level 1 my $crf = $dsp->get_def_arrayref; my $drf = $dsp->get_dat_arrayref; $dsp->output($crf, "", 'def'); # output def file to STDOUT $dsp->outptu($drf, 'out.dat', 'dat');
This class contains a describe method that scans through each records or number of records sepcified and fields in those records in the array or a file to collect information about the content in the array or the file. It creates a column definition array and a data array containing all the data without the column record.
The column definition array built by the module is actually an array with hash members. It contains these hash elements ('col', 'typ', 'max', 'min', 'dec', 'req' and 'dsp') for each column. The subscripts in the array are in the format of $ary[$col_seq]{$hash_ele}. The hash elements are:
col - column name typ - column type, 'N' for numeric, 'C' for characters, and 'D' for date max - maximum length of the records in the column (could use 'wid' to record the max length of the records.) min - minimum length of the record in the column (When 'wid' is used, no 'min' is needed.) dft - date format such as YYYY/MM/DD, MON/DD/YYYY, etc. dec - maximun decimal length of the record in the column req - whether there is null or zero length records in the column only 'NOT NULL is shown dsp - description of the columns
The array or records passed to the module can have the first row containing column names.
This class contains many methods to "set" and/or "get" parameters. Here is the list of methods:
the constructor new(%arg)
Without any input, i.e., new(), the constructor generates an empty object. If any argument is provided, the constructor expects them in the right order.
[set|get]_sfr/skip_first_row(1)
This method tells whether the first row in the array or a file containing column names. If it is true, the describe method will skip it. The get method allows you to query current condition. The default is false.
[set|get]_ifs/input_field_sep/input_field_separator
This method sets/gets input field separator. The default separator is vertical bar ('|').
[set|get]_ofs/output_field_sep/output_field_separator
This method sets/gets output field separator. The default separator is a vertical bar ('|').
[set|get]_ifn/input_file_name
This method sets/gets input file name. It can also be an array reference to a two-dimension array. If it contains an array ref, an array will be scanned and described instead of a text file.
[set|get]_ofn/output_file_name
This method sets/gets output file file name. It defaults to undef. It can be a 'Y', then the output file name will be defaulted to 'dsbf.dat' or the same as input file name with extension as '.dat'.
[set|get]_odf/output_def_file
This method sets/gets output file name for column definition. It defaults to undef. It can be 'Y', then the file name will be defaulted to the same as input file name with extension as '.def'; if the input is an array, then it defaults to 'dsbf.def'.
get_def_arrayref
This method gets the reference pointing to the column definition array. The column definition array contains column name, column type, column max length, column min length, column decimal length, and column constraints.
get_dat_arrayref
This method gets data array reference. It does not change the internal attributes defined for the object, so you can pass any data array reference to this method without touching the internal attributes in the object. Actually, all the get methods do not change anything in the object.
describe($inf,$def,$out,$sfr,$ifs,$ofs,$nrc,$owt,$chr)
Input variables:
$inf - input file name, full path to a ASCII file $def - output file name for column definitions, default to "*.def" while $def = undef or 'Y' $out - output file name for data, default to "*.dat" while $out = 'Y' $sfr - skip first row, i.e., the first row contains column names $ifs - input field separator, default is '|' $ofs - output field separator, default is '|' $nrc - first number of lines to be read, default is to read all $owt - overwrite existing files, default to 'N' $chr - quote characters to be removed.
Variables used or routines called:
echoMSG - print debug messages
How to use:
use Data::Describe; my $dsb= Data::Describe->new; my ($crf,$drf) = $dsp->describe($inf,'Y','',$sfr);
Return: none.
You can get the output through method get_def_arrayref and get_dat_arrayref, or specify output file names and call output method.
This routine reads in a text file, search its content and create column definitons. The $crf contains the column definiton, i.e., ${$crf}[$j]{$itm}, where $j is column sequence and $itm includes: 'col', 'typ', 'wid', 'dec', 'dft', 'dsp', etc.
The $drf contains the data, ${$drf}[$i][$j], where $i is record number and $j is column name. The first row contains column names. The rest rows are data.
output($arf,$out,$otp,$ifn,$ofs,$owt)
$arf - array ref $out - output file name $otp - output type: data or definition $ifn - input file name as name reference $ofs - output field separator $owr - whether to overwrite existing file
get_def_arrayref - get column definition array reference get_dat_arrayref - get data array reference get_odf - get definition output file name get_ofn - get data output file name get_ofs - get output field separator get_ifn - get input file name fileparse - parse file name
my $crf = $self->get_def_arrayref; # output $crf to standard output device - STDOUT $self->output($crf, "", 'def'); my $drf = $self->get_dat_arrayref; # output $drf to 'out.dat' $self->output($drf, "out.dat", 'dat');
Return: None.
debug($n)
$n - a number between 0 and 100. It specifies the level of messages that you would like to display. The higher the number, the more detailed messages that you will get.
Variables used or routines called: None.
$self->debug(2); # set the message level to 2 print $self->debug; # print current message level
Return: the debug level or set the debug level.
echoMSG($msg, $lvl, $yn)
$msg - the message to be displayed. No newline is needed in the end of the message. It will add the newline code at the end of the message. $lvl - the message level is assigned to the message. If it is higher than the debug level, then the message will not be displayed. $yn - whether to return the message
debug - get debug level.
# default msg level to 0 $self->echoMSG('This is a test"); # set the msg level to 2 $self->echoMSG('This is a test", 2);
This method will display message or a hash array based on debug level. If debug is set to '0', no message or array will be displayed. If debug is set to '2', it will only display the message level ($lvl) is less than or equal to '2'. If you call this method without providing a message level, the message level ($lvl) is default to '0'. Of course, if no message is provided to the method, it will be quietly returned.
This is how you can call echoMSG:
my $df = Data::Describe->new; $df->echoMSG("This is a test"); # default the msg to level 0 $df->echoMSG("This is a test",1); # assign the msg as level 1 msg $df->echoMSG("Test again",2); # assign the msg as level 2 msg $df->echoMSG($hrf,1); # assign $hrf as level 1 msg $df->echoMSG($hrf,2); # assign $hrf as level 2 msg
If debug is set to '1', all the messages with default message levels 0 and 1 will be displayed. The higher level messages will not be displayed.
get_date_format($r1, $r2, $r3, $ds)
$r1 - date range 1: 'min:max' $r2 - date range 2: 'min:max' $r3 - date range 3: 'min:max' $ds - date separator
None.
# the $dft = 'MM/DD/YY' my $dft = $self->get_date_format('1:12','1:31','1:2'); # the $dft = 'MM/DD/YYYY' $dft = $self->get_date_format('1:12','1:31','0:2002');
Return: the date format.
You can create a describe object as the following:
$dsc = Data::Describe->new; # an empty object
You can set a hash to define your object attributes and create it as the following:
%attr = ( input_field_sep => ':', # output field separator skip_first_row' => 1, # 1st row has col names ); $dsp = Data::Describe->new(%attr);
If the first row in the data array contains column names, it uses the column names in the row to define the column definition array. The column type is determined by searching all the records in the data array. If all the records in the column only contain digits, i.e., only [0-9.], the column is defined as numeric ('N'); otherwise, it is defined as character ('C'). In type 'C', it checks whether the string is a date type. If the field only contains digits and '/', then it consider the field as a date field. It calls to get_date_foramt to determine the date format.
If the first row does not contain column names, it will generate field names as "FLD###". The "###" is a sequential number starting with 1. If the minimum length of a column is zero, then the value in the column can be null; if the minimum length is greater than zero, then it is a required column.
The default indicator for the first row is false, i.e., the first row does not contain column names. You can indicate whether the first row in the data array is column names by using skip_first_row or set_sfr to set it.
$dsp->skip_first_row('Y'); # first row contains column names $dsp->set_sfr('Y'); # the same as the above $dsp->set_sfr(1); # the same as the above
To reverse it, here is how to
$dsp->set_sfr('N'); # no column in the first row $dsp->skip_first_row(0); # the same as the above
Although it seems a simple task, it requires a lot of thinking to get it working in an object-oriented frame. Intented future implementation includes
add a sampling function
Instead of scanning all the records, just randomly sample portion of the records. It can be specified as percentage or number of records.
add a statistic function
This function will help to analyze the quality of the data.
any more function?
The column definition array will be used in other classes to generate control file and sql*loader codes for uploading the data into Oracle. The class I temporarily name it Data::Loader. It may be changed based on the name approval from PAUSE.
You are welcome to give me suggestions.
Hanming Tu, hanming_tu@yahoo.com
Version 1.03: 11/06/2002 - fixed a bug in output method with fileparse(): need a valid pathname.
Version 1.02: 11/03/2002 - add Makefile.PL to include required classes for testing.
Version 1.01: 10/30/2002 - ported get_date_format from Fax::DataFax::DateTime.
Version 1.00: 10/26/2002 - Ported to this class
I ported from the initial class and just keep the describing/scanning capability in this class..
Version 0.01: 06/10/1999 - Initial coding
This is part of initial class Data::Display. I coded a while ago - probably in 1999.
perltoot(1), perlobj(1), perlbot(1), perlsub(1), perldata(1), perlsub(1), perlmod(1), perlmodlib(1), perlref(1), perlreftut(1).
To install Data::Describe, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Data::Describe
CPAN shell
perl -MCPAN -e shell install Data::Describe
For more information on module installation, please visit the detailed CPAN module installation guide.