Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
ShowTable(3)	      User Contributed Perl Documentation	  ShowTable(3)

NAME
       ShowTable - routines to display tabular data in several formats.

USAGE
       "use Data::ShowTable;"

       ShowTable { parameter =>	value, ... };

       ShowTable \@titles, \@types, \@widths, \_row_sub	[, \_fmt_sub ];

       ShowDatabases \@dbnames;

       ShowDatabases { parameter => value, ... };

       ShowTables \@tblnames;

       ShowTables { parameter => value,	... };

       ShowColumns \@columns, \@col_types, \@col_lengths, \@col_attrs;

       ShowColumns { parameter => value, ... };

       ShowBoxTable \@titles, \@types, \@widths, \_row_sub [, \_fmt_sub	];

       ShowBoxTable { parameter	=> value, ... };

       ShowSimpleTable \@titles, \@types, \@widths, \_row_sub [, \_fmt_sub];

       ShowSimpleTable { parameter => value, ... };

       ShowHTMLTable \@titles, \@types,	\@widths, \_row_sub [, \_fmt_sub];

       ShowHTMLTable { parameter => value, ... };

       ShowListTable \@titles, \@types,	\@widths, \_row_sub [, \_fmt_sub];

       ShowListTable { parameter => value, ... };

       "package	Data::ShowTable";

       $Show_Mode = 'mode';

       $Max_Table_Width	= number;

       $Max_List_Width = number;

       $No_Escape = flag;

       %URL_Keys = { "$colname"	=> "$col_URL", ... };

       @Title_Formats =	( fmt1_html, <fmt2_html>, ... );

       @Data_Formats = ( fmt1_html, <fmt2_html>, ... );

       ShowRow $rewindflag, \$index, $col_array_1 [, $col_array_2, ...;]

       $fmt = ShowTableValue $value, $type, $max_width,	$width,	$precision,
       $showmode;

       [$plaintext = ] PlainText [$htmltext];

DESCRIPTION
       The ShowTable module provides subroutines to display tabular data,
       typially	from a database, in nicely formatted columns, in several
       formats.	 Its arguments can either be given in a	fixed order, or, as a
       single, anonymous hash-array.

       The output format for any one invocation	can be one of four possible
       styles:

       Box	 A tabular format, with	the column titles and the entire table
		 surrounded by a "box" of ""+"", ""-"",	and ""|"" characters.
		 See "ShowBoxTable" for	details.

       Table	 A simple tabular format, with columns automatically aligned,
		 with column titles.  See "ShowSimpleTable".

       List	 A list	style, where columns of	data are listed	as a
		 name:value pair, one pair per line, with rows being one or
		 more column values, separated by an empty line.  See
		 "ShowListTable".

       HTML	 The data is output as an HTML TABLE, suitable for display
		 through a Web-client.	See "ShowHTMLTable".  Input can	either
		 be plain ASCII	text, or text with embedded HTML elements,
		 depending upon	an argument or global parameter.

       The subroutines which perform these displays are	listed below.

EXPORTED NAMES
       This module exports the following subroutines:

	ShowDatabases	 - show	list of	databases
	ShowTables	 - show	list of	tables
	ShowColumns	 - show	table of column	info
	ShowTable	 - show	a table	of data
	ShowRow		 - show	a row from one or more columns
	ShowTableValue	 - show	a single column's value
	ShowBoxTable	 - show	a table	of data	in a box
	ShowListTable	 - show	a table	of data	in a list
	ShowSimpleTable	 - show	a table	of data	in a simple table
	ShowHTMLTable	 - show	a table	of data	using HTML
	PlainText	 - convert HTML	text into plain	text

       All of these subroutines, and others, are described in detail in	the
       following sections.

MODULES
ShowTable
       Format and display the contents of one or more rows of data.

       A A ShowTable { parameter => value, ... };

       A A ShowTable \@titles, \@types,	\@widths, \_row_sub [, \_fmt_sub [,
       $max_width ] [, $show_mode ] ];

       The ShowTable subroutine	displays tabular data aligned in columns, with
       headers.	 ShowTable supports four modes of display: Box,	Table, List,
       and HTML.  Each mode is described separately below.

       The arguments to	ShowTable may be given in one of two ways: as a
       hashed-array, or	by a combination of fixed order	arguments, and some
       package-global variable settings.  The hash-array parameters correspond
       to the fixed arguments and the global-parameter settings.

       In the list below, both the hash-array parameter	name and the fixed-
       order argument name is given as the value.  In the case where there is
       no fixed-order argument for a given parameter-value pair, then the
       corresponding global variable name is given.

       "titles"	=> \@titles
		 A reference to	an array of column names, or titles.  If a
		 particular column name	is null, then the string "Field_num"
		 is used by default.  To have a	column have no title, use the
		 empty string.

       "types" => \@types
		 A reference to	an array of types, one for each	column.	 These
		 types are passed to the fmt_sub for appropriate formatting.
		 Also, if a column type	matches	the regexp
		 ""/text|char|string/i"", then the column alignment will be
		 left-justified, otherwise it will be right-justified.

       "widths"	=> \@widths
		 A reference to	an array of column widths, which may be	given
		 as an integer,	or as a	string of the form: "width.precision".

       "row_sub" => \_row_sub
		 A reference to	a subroutine which successively	returns	rows
		 of values in an array.	 It is called for two purposes,	each
		 described separately:

		 * To fetch successive rows of data:

		     @row = &$row_sub(0);

		 When given a null, zero, or empty argument, the next row is
		 returned.

		 * To initialize or rewind the data traversal.

		     $rewindable = &$row_sub(1);

		 When invoked with a non-null argument,	the subroutine should
		 rewind	its row	pointer	to start at the	first row of data.  If
		 the data which	row_sub	is traversing is not rewindable, it
		 must return zero or null.  If the data	is rewindable, a non-
		 null, non-zero	value should be	returned.

		 The row_sub must expect to be invoked once with a non-null
		 argument, in order to discover	whether	or not the data	is
		 rewindable.  If the data cannot be rewound, row_sub will
		 thereafter only be called with	a zero argument.

		 Specifically, row_sub subroutine is used in this manner:

		     $rewindable = &$row_sub(1);
		     if	($rewindable) {
			 while ((@row =	&$row_sub(0)), $#row >=	0) {
			     # examine lengths for optimal formatting
			 }
			 &$row_sub(1);	 # rewind
		     }
		     while ((@row = &$row_sub(0)), $#row >= 0) {
			 # format the data
		     }

		 The consequence of data that is not rewindable, a reasonably
		 nice table will still be formatted, but it may	contain	fairly
		 large amounts of whitespace for wide columns.

       "fmtsub"	=> \_fmt_sub
		 A reference to	a subroutine which formats a value, according
		 to its	type, width, precision,	and the	current	column width.
		 It is invoked either with a fixed list	of arguments, or with
		 a hash-array of parameter and value pairs.

		   $string = &fmt_sub {	I<parameter> =>	I<value>, ... };

		   $string = &fmt_sub($value, $type, $max_width, $width, $precision)

		 If \_fmt_sub is omitted, then a default subroutine,
		 ShowTableValue, will be used, which will use Perl's standard
		 string	formatting rules.

		 The arguments to \_fmt_sub, either as values passed in	a
		 fixed order, or as part of the	parameter value	pair, are
		 described in the section on "ShowTableValue below.

       "max_width" => number,
		 The maximum table width, including the	table formatting
		 characters.  If not given, defaults to	the global variable
		 $Max_Table_Width;

       "show_mode" => 'mode',
		 The display mode of the output.  One of five strings: 'Box',
		 'Table', 'Simple', 'List', and	'HTML'.

ShowDatabases
       Show a list of database names.

       A A ShowDatabases \@dbnames;

       A A ShowDatabases { 'data' => \@dbnames,	parameter => value, ...};

       ShowDatabases is	intended to be used to display a list of database
       names, under the	column heading of "Databases".	It is a	special	case
       usage of	ShowTable (and can thus	be passed any parameter	suitable for
       ShowTable.

       The argument, \@dbnames,	is a reference to an array of strings, used as
       the values of the single	column display.

ShowTables
       Show an array of	table names.

       A A ShowTables \@tblnames;

       A A ShowTables {	'data' => \@tblnames, parameter	=> value, ...};

       ShowTables is used to display a list of table names, under the column
       heading of "Tables".  It	is a special case usage	of ShowTable, and can
       be passed any "ShowTable" argument parameter.

ShowColumns
       Display a table of column names,	types, and attributes.

       A A ShowColumns { parameter => values, ... };

       A A ShowColumns \@columns, \@col_types, \@col_lengths, \@col_attrs;

       The ShowColumns subroutine displays a table of column names, types,
       lengths,	and other attributes in	a nicely formatted table.  It is a
       special case usage of ShowTable,	and can	be passed any argument
       suitable	for "ShowTable";

       The arguments are:

       "columns" = \@columns
		 An array of column names.  This provides the value for	the
		 first column of the output.

       "col_types" = \@col_types
		 An array of column types names.  This provides	the value for
		 the second column.

       "col_lengths" = \@col_lengths
		 An array of maximum lengths for corresponding columns.	 This
		 provides the value for	the third column of the	output.

       "col_attrs" = \@col_attrs
		 An array of column attributes array references	(ie: an	array
		 of arrays).  The attributes array for the first column	are at
		 "$col_attrs-\>[0]".  The first	attribute of the second	column
		 is "$col_attrs-\>[1][0]".

       The columns, types, lengths, and	attributes are displayed in a table
       with the	column headings: "Column", "Type", "Length", and "Attributes".
       This is a special case usage of ShowTable, and can be passed additional
       arguments suitable for "ShowTable".

ShowBoxTable
       Show tabular data in a box.

       A A ShowBoxTable	{ parameter = value, ... };

       A A ShowBoxTable	\@titles, \@types, \@widths, \_row_sub A A A A A A [,
       [ \_fmt_sub ] [,	$max_width ] ];

       The ShowBoxTable	displays tabular data in titled	columns	using a	"box"
       of ASCII	graphics, looking something like this:

	       +------------+----------+-----+----------+
	       | Column1    | Column2  | ... | ColumnN	|
	       +------------+----------+-----+----------+
	       | Value11    | Value12  | ... | Value 1M	|
	       | Value21    | Value22  | ... | Value 2M	|
	       | Value31    | Value32  | ... | Value 3M	|
	       |  ...	    |  ...     | ... |	...	|
	       | ValueN1    | ValueN2  | ... | Value NM	|
	       +------------+----------+-----+----------+

       The arguments are the same as with "ShowTable".	If the @titles array
       is empty, the header row	is omitted.

ShowSimpleTable
       Display a table of data using a simple table format.

       A A ShowSimpleTable \@titles, \@types, \@widths,	\_row_sub [,
       \_fmt_sub];

       A A ShowSimpleTable { parameter => values, ... };

       The ShowSimpleTable subroutine formats data into	a simple table of
       aligned columns,	in the following example:

	  Column1  Column2  Column3
	  -------  -------  -------
	  Value1   Value2   Value3
	  Value12  Value22  Value32

       Columns are auto-sized by the data's widths, plus two spaces between
       columns.	 Values	which are too long for the maximum colulmn width are
       wrapped within the column.

ShowHTMLTable
       Display a table of data nicely using HTML tables.

       A A ShowHTMLTable { parameter =>	value, ... };

       A A ShowHTMLTable \@titles, \@types, \@widths, \_row_sub	[, \_fmt_sub
       [, $max_width [,	\%URL_Keys [, $no_escape [, \@title_formats [,
       \@data_formats [, $table_attrs ]	] ] ] ]	] ];

       The ShowHTMLTable displays one or more rows of columns of data using
       the HTML	"\<TABLE\"> feature.  In addition to the usual parameter
       arguments of "ShowTable", the following parameter arguments are
       defined:

       "url_keys" => \%URL_Keys,
		 This is a hash	array of column	names (titles) and
		 corresponding base URLs.  The values of any column names or
		 indexes occuring as keys in the hash array will be generated
		 as hypertext anchors using the	associated printf-like string
		 as the	base URL. Either the column name or the	column index
		 (beginning with 1) may	be used	as the hash key.

		 In the	string value, these macros can be substituted:

		 "%K" is replaced with the column name.

		 "%V" is replaced with the column value;

		 "%I" is replaced with the column index.

		 For example, if we define the array:

		     $base_url = "http://www.$domain/cgi/lookup?col=%K?val=%V";
		     %url_cols = ('Author' => $base_url,
				  'Name'   => $base_url);

		 Then, the values in the "Author" column will be generated
		 with the following HTML text:

		     <A	HREF="http://www.$domain/cgi/lookup?col=Author?val=somevalue>somevalue</A>

		 and the values	in the "Name" column will be generated with
		 the URL:

		     <A	HREF="http://www.$domain/cgi/lookup?col=Name?val=othervalue>othervalue</A>

		 If this variable is not given,	it will	default	to the global
		 variable "\%URL_Keys".

       "no_escape" => boolean,
		 Unless	$no_escape is set, HTML-escaping is performed on the
		 data values in	order to properly display the special HTML
		 formatting characters : '\<', '\>', and '&'.  If you wish to
		 display data with embedded HTML text, you must	set
		 $no_escape.

		 Enabling embedded HTML, turns on certain heuristics which
		 enable	the user to more completely define appearance of the
		 table.	 For instance, any "\<TR\"> tokens found embedded
		 *anywhere* within a row of data will be placed	at the front
		 of the	row, within the	generated "\<TR\">.

		 Similarly, a row of data containing the "\<THEAD\"> or
		 "\<TFOOT\"> tokens, and their closing counterparts, will
		 begin and end,	respectively a table header or footer data.

       "title_formats" => \@title_formats,
       "tformats" => \@title_formats,
		 An array of HTML formatting elements for the column titles,
		 one for each column.  Each array element is a list of one or
		 more HTML elements, given as "\<ELEMENT\"> or plainly,
		 "ELEMENT", and	separated by a comma ',', semi-colon ';', or
		 vertical bar '|'.  Each given HTML element is prepended to
		 the corresponding column title, in the	order given.  The
		 corresponding HTML closing elements are appended in the
		 opposite order.

		 For example, if \@title_formats contains the two elements:

		     [ 'FONT SIZE=+2,BOLD', 'FONT COLOR=red,EM'	]

		 then the text output for the title of the first column	would
		 be:

		     <FONT SIZE=+2><BOLD>I<column_1_title></BOLD></FONT>

		 If "title_formats" is omitted,	the global variable
		 @Title_Formats	is used	by default.

       "data_formats" => \@data_formats,
       "dformats" => \@data_formats,
		 Similar to "title_formats", this array	provides HTML
		 formatting for	the columns of each row	of data.  If
		 "data_formats"	is omitted or null, then the global variable
		 \@Data_Formats	is used	by default.

       "table_attrs" =>	$table_attrs,
		 This variable defines a string	of attributes to be inserted
		 within	the "\<TABLE\">	token.	For example, if	the user
		 wishes	to have	no table border:

		     ShowHTMLTable {
			 ...
			 table_attrs =>	'BORDER=0',
			 ...
		     };

ShowListTable
       Display a table of data using a list format.

       A A ShowListTable { parameter =>	value, ... };

       A A ShowListTable \@titles, \@types, \@widths, \_row_sub	[, \_fmt_sub
       [, $max_width [,	$wrap_margin ] ] ];

       The arguments for ShowListTable are the same as for "ShowTable",	except
       for those described next.

       "max_width" = number,
       "wrap_margin" = number,
		 Lines are truncated, and wrapped when their length exceeds
		 $max_width.  Wrapping is done on a word-basis,	unless the
		 resulting right margin	exceeds	$wrap_margin, in which case
		 the line is simply truncated at the $max_width	limit.

		 The $max_width	variable defaults to $Max_List_Width.  The
		 $wrap_margin defaults to $List_Wrap_Margin.

       In List mode, columns (called "fields" in List mode) are	displayed wth
       a field name and	value pair per line, with records being	one or more
       fields .	 In other words, the output of a table would look something
       like this:

	   Field1_1: Value1_1
	   Field1_2: Value1_2
	   Field1_3: Value1_3
	   ...
	   Field1-N: Value1_M
	   <empty line>
	   Field2_1: Value2_1
	   Field2_2: Value2_2
	   Field2_3: Value2_3
	   ...
	   Field2_N: Value2_N
	   ...
	   FieldM_1: ValueM_1
	   FieldM_2: ValueM_2
	   ...
	   FieldM_N: ValueM_N
	   <empty line>
	   <empty line>

       Characteristics of List mode:

       o	 two empty lines indicate the end of data.

       o	 An empty field	(column) may be	omitted, or may	have a label,
		 but no	data.

       o	 A long	line can be continue by	a null field (column):

		     Field2: blah blah blah
			   : blah blah blah

       o	 On a continuation, the	null field is an arbitrary number of
		 leading white space, a	colon ':', a single blank or tab,
		 followed by the continued text.

       o	 Embedded newlines are indicated by the	escape mechanism "\n".
		 Similarly, embedded tabs are indicated	with "\t", returns
		 with "\r".

       o	 If the	@titles	array is empty,	the field names	""Field_"NN"
		 are used instead.

ShowRow
       Fetch rows successively from one	or more	columns	of data.

       A A ShowRow $rewindflag,	\$index, $col_array_1 [, $col_array_2, ...;]

       The ShowRow subroutine returns a	row of data from one or	more columns
       of data.	 It is designed	to be used as a	callback routine, within the
       ShowTable routine.   It can be used to select elements from one or more
       array reference arguments.

       If passed two or	more array references as arguments, elements of	the
       arrays selected by $index are returned as the "row" of data.

       If a single array argument is passed, and each element of the array is
       itself an array,	the subarray is	returned as the	"row" of data.

       If the $rewindflag flag is set, then the	$index pointer is reset	to
       zero, and "true"	is returned (a scalar 1).  This	indicates that the
       data is rewindable to the ShowTable routines.

       When the	$rewindflag is not set,	then the current row of	data, as
       determined by $index is returned, and $index will have been
       incremented.

       An actual invocation (from ShowColumns) is:

	 ShowTable \@titles, \@types, \@lengths,
	     sub { &ShowRow( $_[0], \$current_row, $col_names, $col_types,
			     $col_lengths, \@col_attrs); };

       In the example above, after each	invocation, the	$current_row argument
       will have been incremented.

ShowTableValue
       Prepare and return a formatted representation of	a value.  A value
       argument, using its corresponding type, effective width,	and precision
       is formatted into a field of a given maximum width.

       A A $fmt	= ShowTableValue $value, $type,	$max_width, $width,
       $precision, $showmode;

       "width" => $width
       $width	 The width of the current value.  If omittied, $max_width is
		 assumed.

       "precision" => $precision
       $precision
		 The number of decimal digits; zero is assumed if omittied.

       "value" => $value
       $value	 The value to be formatted.

       $type	 The type name of the value; eg: "char", "varchar", "int",
		 etc.

       "maxwidth" => $max_width
       $max_width
		 The maximum width of any value	in the current value's column.
		 If $width is zero or null, $max_width is used by default.
		 $max_width is also used as a minimum width, in	case $width is
		 a smaller value.

       $width	 The default width of the value, obtained from the width
		 specification of the column in	which this value occurs.

       $precision
		 The precision specification, if any, from the column width
		 specification.

       $showmode The mode of the output: one of	"table", "list", "box",	or
		 "html".  Currently, only the "html" mode is significant: it
		 is used to avoid using	HTML tokens as part of the formatted
		 text and length calculations.

PlainText
       A A $plaintext =	&PlainText($htmltext);

       A A &PlainText

       This function removes any HTML formatting sequences from	the input
       argument, or from $_ if no argument is given.  The resulting plain text
       is returned as the result.

VARIABLES
       The following variables may be set by the user to affect	the display
       (with the defaults enclosed in square brackets [..]):

       $Show_Mode [Box]
		 This is the default display mode when using ShowTable.	 The
		 environment variable, $ENV{'SHOW_MODE'}, is used when this
		 variable is null or the empty string.	The possible values
		 for this variable are:	"Box", "List", "Table",	and "HTML".
		 Case is insignificant.

       $List_Wrap_Margin [2]
		 This variable's value determines how large a margin to	keep
		 before	wrarpping a long value's display in a column.  This
		 value is only used in "List" mode.

       $Max_List_Width [80]
		 This variable,	used in	"List" mode, is	used to	determine how
		 long an output	line may be before wrapping it.	 The
		 environment variable, $ENV{'COLUMNS'},	is used	to define this
		 value when it is null.

       $Max_Table_Width	['']
		 This variable,	when set, causes all tables to have their
		 columns scaled	such that their	total combined width does not
		 exceed	this value.  When this variable	is not set, which is
		 the default case, there is no maximum table width, and	no
		 scaling will be done.

       $No_Escape ['']
		 If set, allows	embedded HTML text to be included in the data
		 displayed in an HTML-formatted	table.	By default, the	HTML
		 formatting characters ("<", ">", and "&") occuring in values
		 are escaped.

       %URL_Keys In HTML mode, this variable is	used to	recognize which
		 columns are to	be displayed with a corresponding hypertext
		 anchor.  See "ShowHTMLTable" for more details.

       @HTML_Elements
		 An array of HTML elements (as of HTML 3.0) used to recognize
		 and strip for width calculations.

       $HTML_Elements
		 A regular expression string formed from the elements of
		 @HTML_Elements.

INTERNAL SUBROUTINES
get_params
       A A my $args = &get_params \@argv, \%params, \@arglist;

       Given the @argv originally passed to the	calling	sub, and the hash of
       named parameters	as %params, and	the array of parameter names in	the
       order expected for a pass-by-value invocation, set the values of	each
       of the variables	named in @vars.

       If the only element of the @argv	is a hash array, then set the
       variables to the	values of their	corresponding parameters used as keys
       to the hash array.  If the parameter is not a key of the	%params	hash,
       and is not a key	in the global hash %ShowTableParams, then an error is
       noted.

       When @argv has multiple elements, or is not a hash array, set each
       variable, in the	order given within @arglist, to	the values from	the
       @argv, setting the variables named by each value	in %params.

       Variables may given either by name or by	reference.

       The result is a HASH array reference, either corresponding directly to
       the HASH	array passed as	the single argument, or	one created by
       associating the resulting variable values to the	parameter names
       associated with the variable names.

html_formats
       A A ($prefixes,$suffixes) = html_formats	\@html_formats;

       The html_format function	takes an array reference of HTML formatting
       elements	\@html_formats,	and builds two arrays of strings: the first:
       $prefixes, is an	array of prefixes containing the corresponding HTML
       formatting elements from	\@html_formats,	and the	second,	$suffixes,
       containing the appropriate HTML closing elements, in the	opposite
       order.

       The result is designed to be used as prefixes and suffixes for the
       corresponding titles and	column values.

       The array \@html_formats	contains lists of HTML formatting elements,
       one for each column (either title or data).  Each array element is a
       list of one or more HTML	elements, either given in HTML syntax, or as a
       "plain" name (ie: given as "\<ELEMENT\">	or plainly, "ELEMENT").
       Multiple	elements are separated by a comma ','.

       The resulting array of $prefixes	contains the corresponding opening
       elements, in the	order given, with the proper HTML element syntax.  The
       resulting array of $suffixes contains the closing elements, in the
       opposite	order given, with the proper HTML element syntax.

       For example, if \@html_formats contains the two elements:

	   [ 'FONT SIZE=+2,BOLD', 'FONT	COLOR=red,EM' ]

       then the	resulting two arrays will be returned as:

	   [ [ '<FONT SIZE=+2><BOLD>', '<FONT COLOR=red><EM>' ],
	     [ '</FONT></BOLD>',       '</FONT></EM>' ]	]

calc_widths
       A A ($num_cols, $widths,	$precision, $max_widths) = A A &calc_widths(
       $widthspec, $titles, $rewindable, A A A A A A $row_sub, $fmt_sub,
       $types, $showmode, A A A	A A A $max_width);

   DESCRIPTION
       calc_widths is a	generalized subroutine used by all the ShowTable
       variant subroutines to setup internal variables prior to	formatting for
       display.	 Calc_widths handles the column	width and precision analysis,
       including scanning the data (if rewindable) for appropriate default
       values.

       The number of columns in	the data is returned, as well as three arrays:
       the declared column widths, the column precision	values,	and the
       maximum column widths.

   RETURN VALUES
       $num_cols is the	number of columns in the data.	If the data is not
		 rewindable, this is computed as the maximum of	the number of
		 elements in the $widthspec array and the number of elements
		 in the	$titles	array.	When the data is rewindable, this is
		 the maximum of	the number of columns of each row of data.

       $widths	 is the	column widths array ref, without the precision specs
		 (if any).  Each column's width	value is determined by the
		 original $widthspec value and/or the maximum length of	the
		 formatted data	for the	column.

       $precision
		 is the	precision component (if	any) of	the original
		 $widthspec array ref.	If there was no	original precision
		 component from	the $widthspec,	and the	data is	rewindable,
		 then the data is examined to determine	the maximum default
		 precision.

       $max_widths
		 is the	ref to the array of maximum widths for the given
		 columns.

   ARGUMENTS
       $widthspec
		 A reference to	an array of column width (or length) values,
		 each given as an integer, real	number,	or a string value of
		 "width.precision".  If	a value	is zero	or null, the length of
		 the corresponding formatted data (if rewindable) and column
		 title length are used to determine a reasonable default.

		 If a column's width portion is	a positive, non-zero number,
		 then the column will be this wide, regardless of the values
		 lengths of the	data in	the column.

		 If the	column's width portion is given	as a negative number,
		 then the positive value is used as a minimum column width,
		 with no limit on the maximum column width.  In	other words,
		 the column will be at least width characters wide.

		 If the	data is	not rewindable,	and a column's width value is
		 null or zero, then the	length of the column title is used.
		 This may cause	severe wrapping	of data	in the column, if the
		 column	data lengths are much greater than the column title
		 widths.

       $titles	 The array ref to the column titles; used to determine the
		 minimum acceptable width, as well as the default number of
		 columns.  If the $titles array	is empty, then the $widthspec
		 array is used to determine the	default	number of columns.

       $rewindable
		 A flag	indicating whether or not the data being formatted is
		 rewindable.  If this is true, a pass over the data will be
		 done in order to calculate the	maximum	lengths	of the actual
		 formatted data, using $fmt_sub	(below), rather	than just rely
		 on the	declared column	lengths.  This allows for optimal
		 column	width adjustments (ie: the actual column widths	may be
		 less than the declared	column widths).

		 If it is not desired to have the column widths	dynamically
		 adjusted, then	set the	$rewindable argument to	0, even	if the
		 data is rewindable.

       $row_sub	 The code reference to the subroutine which returns the	data;
		 invoked only if $rewindable is	non-null.

       $fmt_sub	 The subroutine	used to	determine the length of	the data when
		 formatted; if this is omitted or null,	the length of the data
		 is used by default.  The $fmt_sub is used only	when the data
		 is rewindable.

       $types	 An array reference to the types of each of the	value columns;
		 used only when	$fmt_sub is invoked.

       $showmode A string indicating the mode of the eventual display; one of
		 four strings: ""box"",	""table"", ""list"", and ""html"".
		 Used to adjust	widths for formatting requirements.

       $max_width
		 The maximum width of the table	being formatted.  If set, and
		 the total sum of the individual columns exceeds this value,
		 the column widths are scaled down uniformly.  If not set
		 (null), no column width scaling is done.

putcell
       A A $wrapped = &putcell(	\@cells, $c, $cell_width, \@prefix, \@suffix,
       $wrap_flag );

       Output the contents of an array cell at $cell[$c], causing text longer
       than $cell_width	to be saved for	output on subsequent calls.  Prefixing
       the output of each cell's value is a string from	the two-element	array
       @prefix.	 Suffixing each	cell's value is	a string from the two-element
       array @suffix.  The first element of either array is selected when
       $wrap_flag is zero or null, or when there is no more text in the
       current to be output.  The second element is selected when $wrap_flag
       is non-zero, and	when there is more text	in the current cell to be
       output.

       In the case of text longer than $cell_width, a non-zero value is
       returned.

       Cells with undefined data are not output, nor are the prefix or suffix
       strings.

center
       Center a	string within a	given width.

       A A $field = center $string, $width;

max
       Compute the maximum value from a	list of	values.

       A A $max	= &max(	@values	);

min
       Compute the minum value from a list of values.

       A A $min	= &min(	@values	);

max_length
       Compute the maximum length of a set of strings in an array reference.

       A A $maxlength =	&max_length( \@array_ref );

htmltext
       Translate regular text for output into an HTML document.	 This means
       certain characters, such	as "&",	">", and "<" must be escaped.

       A A $output = &htmltext(	$input [, $allflag ] );

       If $allflag is non-zero,	then all characters are	escaped.  Normally,
       only the	four HTML syntactic break characters are escaped.

out
       Print text followed by a	newline.

       A A out $fmt [, @text ];

put
       Print text (without a trailing newline).

       A A out $fmt [, @text ];

AUTHOR
       Alan K. Stebbens	<aks@stebbens.org>

BUGS
       o	 Embedded HTML is how the user can insert formatting
		 overrides.  However, the HTML formatting techniques have not
		 been given much consideration -- feel free to provide
		 constructive feedback.

perl v5.24.1			  2014-01-03			  ShowTable(3)

NAME | USAGE | DESCRIPTION | EXPORTED NAMES | MODULES | ShowTable | ShowDatabases | ShowTables | ShowColumns | ShowBoxTable | ShowSimpleTable | ShowHTMLTable | ShowListTable | ShowRow | ShowTableValue | PlainText | VARIABLES | INTERNAL SUBROUTINES | get_params | html_formats | calc_widths | putcell | center | max | min | max_length | htmltext | out | put | AUTHOR | BUGS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Data::ShowTable&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help