|
Data::Display - Perl extension for formating and displaying array. |
Data::Display - Perl extension for formating and displaying array.
use Data::Display;
$dsp = Data::Display->new($drf, $crf, $ech, %arg); $dsp->skip_first_row; # i,e. 1st row contains col names $dsp->set_skip_first_row(1); # is the same as the above $dsp->set_field_sep($ech); # default is a space $dsp->set_data_ref($drf); # ref to an array containing data $dsp->set_cols_ref($crf); # ref to an array containing col defs $dsp->set_col_width($fld,$wd,$col,$wd,...); $dsp->add_col_def($col,'typ:max:min:dec:dft:req'); # append $dsp->add_col_def($idx,'col:typ:max:min:dec:dft:req'); # isert $dsp->mod_col_def($fld,'typ:max:min:dec:dft:req');
$rc = $dsp->get_skip_first_row; $rc = $dsp->get_first_row; # the same as the above
$ary_ref = $dsp->get_column_defs_arrayref($drf,$ech); @ary = $dsp->get_column_defs(\@ary,$ech); # $yn: display?
$str = $dsp->get_col_width(); # get format string @ary = $dsp->get_col_width($fld,$col,...); # a list of width ($cfs, $dfs) = $dsp->get_col_width(); ($cfs, $dfs) = $dsp->get_format_string($crf,$sep,$ech);
$str = $dsp->get_content($drf,$crf,$typ,$ech); $str = $dsp->get_content($typ,$ech); # use ary refs
$rv = $dsp->get_no_of_fields; $rv = $dsp->get_no_of_columns; $rv = $dsp->get_no_of_rows; $rv = $dsp->get_no_of_records; ($rows, $cols) = $dsp->get_dimension($drf); ($rows, $cols) = $dsp->get_dimension;
Notation and Conventions
$dsp a display object $drf data array reference $crf column definition array reference $ech whether to echo messages or contents $cfs column heading format string $dfs data content format string $sep field separator character $typ output type, text, html, etc.
$drh Driver handle object (rarely seen or used in applications)
$h Any of the $??h handle types above
$rc General Return Code (boolean: true=ok, false=error)
$rv General Return Value (typically an integer)
@ary List of values returned from the database, typically a row
of data
$rows Number of rows processed (if available, else -1)
$fh A filehandle
undef NULL values are represented by undefined values in perl
\%attr Reference to a hash of attribute values passed to methods
This is my first object-oriented Perl program. The Display module will scan through each records and fields in the array to collect information about the content in the array. It creates a column definition array, builds formating strings, and display the contents nicely.
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 passed to the module can have the first row containing column names or have a separate array containing column definitions. It has to be in the same format of the array that we describe in the above if it is referenced to a out side array.
It also creates and tracks a format information. The format information contains in a separate array, which has exactly the same element as the column definition array.
It has many ``set'' and ``get'' methods to assign and to query data contained in the object. Here is the list of methods:
disp_col_defs($crf)get_format_string($crf,$sep,$ech)get_content($drf,$crt,$typ,$ech)get_dimension($drf)
If you have an array @ary and column array @C, you can create a display object as the following:
$dsp = Data::Display->new(\@ary,\@C);
This is equivalent to
$dsp = Data::Display->new(); $dsp->set_data_ref(\@ary); $dsp->set_cols_ref(\@C);
If you do not have column array, you can generate it as the following:
$col_ref = $dsp->get_column_defs_arrayref(\@ary); $dsp->set_cols_ref($col_ref);
You can set a hash to define your object attributes and create it as the following:
%attr = (
'field_sep' => ':', # output field separator
'skip_first_row' => 1, # 1st row has col names
'data_ref' => \@ary, # array_ref for data
'cols_ref' => \@C, # array_ref for col defs
);
$dsp = Data::Display->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 do not contain non-digits, i.e., only [0-9.], the column is defined as numeric ('N'); otherwise, it is defined as character ('C'). No other data types such as date are searched currently.
If the first row does not contain column names and no column definition array is provided, the get_column_defs or get_column_defs_arrayref 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_skip_first_row to set it.
$dsp->skip_first_row;
$dsp->set_skip_first_row(1); # the same as the above
$dsp->set_first_row(1); # the same as the above
$dsp->set_skip_first_row('Y'); # the same effect
$dsp->set_first_row('Y'); # the same as the above
To reverse it, here is how to
$dsp->set_skip_first_row(0); # no column in the first row
$dsp->set_first_row(0); # the same as the above
$dsp->set_skip_first_row(''); # the same effect
$dsp->set_first_row(''); # the same as the above
You can pass data and column definition array references to display objects using the object constructor new or using the set methods:
$dsp = Data::Display->new($arf, $crf); $dsp->set_data_ref(\@new_array); $dsp->set_cols_ref(\@new_defs);
You can get the information from the object through all the get methods described above.
You can add column definitions to the existing definition array using method add_col_def through two ways: append or insert.
$dsp = Data::Display->new($arf, $crf);
$dsp->add_col_def('ColX','D:18:10::YYYY/MM/DD:NOT NULL'); # append
$dsp->add_col_def(2,'max=>18:col=>ColX:typ=>D'); # insert
You can use two formats as you already see from the above examples: list or hash. In the value list format, you must follow the order of 'col:typ:max:min:dec:dft:req'. You can add multiple columns at once. You can pre-create an array and pass the whole array to the method. Here is an example:
@cols = ( 'ColX', 'D:18:10::YYYY/MM/DD:NOT NULL',
'2', 'max=>18:col=>ColX:typ=>D',
'ColY', 'max=>15:typ=>N:dec=>2',
'4', 'C:20:0::::'
);
$dsp->add_col_def(@cols);
The column name and position will be checked before inserting new columns. If the column name exist or the position is out of the range of the existing column definition array, the insertion for the column will be ignored. Please also note that positions are changed based on previous insertions.
You can modify the existing column definitions using method add_col_def through two ways (append and insert) and two formats (list and hash) just as described in the adding column definitons section.
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
Hanming Tu, hanming_tu@yahoo.com
1) added date datatype; 2) added add_col_def method; 3) added mod_col_def method; 4) added disp_col_defs method.
perltoot(1), perlobj(1), perlbot(1), perlsub(1), perldata(1), perlsub(1), perlmod(1), perlmodlib(1), perlref(1), perlreftut(1).
|
Data::Display - Perl extension for formating and displaying array. |