{ "content": [ { "type": "text", "text": "# Data::ShowTable (perldoc)\n\n## NAME\n\nShowTable - routines to display tabular data in several formats.\n\n## DESCRIPTION\n\nThe ShowTable module provides subroutines to display tabular data, typially from a database, in\nnicely formatted columns, in several formats. Its arguments can either be given in a fixed\norder, or, as a single, anonymous hash-array.\n\n## Sections\n\n- **NAME**\n- **USAGE**\n- **DESCRIPTION**\n- **EXPORTED NAMES**\n- **MODULES**\n- **ShowTable**\n- **ShowDatabases**\n- **ShowTables**\n- **ShowColumns**\n- **ShowBoxTable**\n- **ShowSimpleTable**\n- **ShowHTMLTable**\n- **ShowListTable**\n- **ShowRow**\n- **ShowTableValue**\n- **PlainText**\n- **VARIABLES**\n- **INTERNAL SUBROUTINES**\n- **AUTHOR**\n- **BUGS**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "Data::ShowTable", "section": "", "mode": "perldoc", "summary": "ShowTable - routines to display tabular data in several formats.", "synopsis": null, "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "USAGE", "lines": 56, "subsections": [] }, { "name": "DESCRIPTION", "lines": 22, "subsections": [] }, { "name": "EXPORTED NAMES", "lines": 16, "subsections": [] }, { "name": "MODULES", "lines": 1, "subsections": [] }, { "name": "ShowTable", "lines": 96, "subsections": [] }, { "name": "ShowDatabases", "lines": 13, "subsections": [] }, { "name": "ShowTables", "lines": 9, "subsections": [] }, { "name": "ShowColumns", "lines": 31, "subsections": [] }, { "name": "ShowBoxTable", "lines": 23, "subsections": [] }, { "name": "ShowSimpleTable", "lines": 17, "subsections": [] }, { "name": "ShowHTMLTable", "lines": 90, "subsections": [] }, { "name": "ShowListTable", "lines": 61, "subsections": [] }, { "name": "ShowRow", "lines": 29, "subsections": [] }, { "name": "ShowTableValue", "lines": 35, "subsections": [] }, { "name": "PlainText", "lines": 7, "subsections": [] }, { "name": "VARIABLES", "lines": 39, "subsections": [] }, { "name": "INTERNAL SUBROUTINES", "lines": 190, "subsections": [] }, { "name": "AUTHOR", "lines": 2, "subsections": [] }, { "name": "BUGS", "lines": 4, "subsections": [] } ], "sections": { "NAME": { "content": "ShowTable - routines to display tabular data in several formats.\n", "subsections": [] }, "USAGE": { "content": "\"use Data::ShowTable;\"\n\nShowTable { *parameter* => *value*, ... };\n\nShowTable *\\@titles*, *\\@types*, *\\@widths*, *\\&rowsub* [, *\\&fmtsub* ];\n\nShowDatabases *\\@dbnames*;\n\nShowDatabases { *parameter* => *value*, ... };\n\nShowTables *\\@tblnames*;\n\nShowTables { *parameter* => *value*, ... };\n\nShowColumns *\\@columns*, *\\@coltypes*, *\\@collengths*, *\\@colattrs*;\n\nShowColumns { *parameter* => *value*, ... };\n\nShowBoxTable *\\@titles*, *\\@types*, *\\@widths*, *\\&rowsub* [, *\\&fmtsub* ];\n\nShowBoxTable { *parameter* => *value*, ... };\n\nShowSimpleTable *\\@titles*, *\\@types*, *\\@widths*, *\\&rowsub* [, *\\&fmtsub*];\n\nShowSimpleTable { *parameter* => *value*, ... };\n\nShowHTMLTable *\\@titles*, *\\@types*, *\\@widths*, *\\&rowsub* [, *\\&fmtsub*];\n\nShowHTMLTable { *parameter* => *value*, ... };\n\nShowListTable *\\@titles*, *\\@types*, *\\@widths*, *\\&rowsub* [, *\\&fmtsub*];\n\nShowListTable { *parameter* => *value*, ... };\n\n\"package Data::ShowTable\";\n\n$ShowMode = '*mode*';\n\n$MaxTableWidth = *number*;\n\n$MaxListWidth = *number*;\n\n$NoEscape = *flag*;\n\n%URLKeys = { \"*$colname*\" => \"*$colURL*\", ... };\n\n@TitleFormats = ( *fmt1html*, , ... );\n\n@DataFormats = ( *fmt1html*, , ... );\n\nShowRow *$rewindflag*, *\\$index*, *$colarray1* [, *$colarray2*, ...;]\n\n*$fmt* = ShowTableValue *$value*, *$type*, *$maxwidth*, *$width*, *$precision*, *$showmode*;\n\n[*$plaintext* = ] PlainText [*$htmltext*];\n", "subsections": [] }, "DESCRIPTION": { "content": "The ShowTable module provides subroutines to display tabular data, typially from a database, in\nnicely formatted columns, in several formats. Its arguments can either be given in a fixed\norder, or, as a single, anonymous hash-array.\n\nThe output format for any one invocation can be one of four possible styles:\n\nBox A tabular format, with the column titles and the entire table surrounded by a \"box\" of\n\"\"+\"\", \"\"-\"\", and \"\"|\"\" characters. See \"ShowBoxTable\" for details.\n\nTable A simple tabular format, with columns automatically aligned, with column titles. See\n\"ShowSimpleTable\".\n\nList A *list* style, where columns of data are listed as a *name*:*value* pair, one pair\nper line, with rows being one or more column values, separated by an empty line. See\n\"ShowListTable\".\n\nHTML The data is output as an HTML *TABLE*, suitable for display through a *Web*-client.\nSee \"ShowHTMLTable\". Input can either be plain ASCII text, or text with embedded HTML\nelements, depending upon an argument or global parameter.\n\nThe subroutines which perform these displays are listed below.\n", "subsections": [] }, "EXPORTED NAMES": { "content": "This module exports the following subroutines:\n\nShowDatabases - show list of databases\nShowTables - show list of tables\nShowColumns - show table of column info\nShowTable - show a table of data\nShowRow - show a row from one or more columns\nShowTableValue - show a single column's value\nShowBoxTable - show a table of data in a box\nShowListTable - show a table of data in a list\nShowSimpleTable - show a table of data in a simple table\nShowHTMLTable - show a table of data using HTML\nPlainText - convert HTML text into plain text\n\nAll of these subroutines, and others, are described in detail in the following sections.\n", "subsections": [] }, "MODULES": { "content": "", "subsections": [] }, "ShowTable": { "content": "Format and display the contents of one or more rows of data.\n\nShowTable { *parameter* => *value*, ... };\n\nShowTable *\\@titles*, *\\@types*, *\\@widths*, *\\&rowsub* [, *\\&fmtsub* [, *$maxwidth* ] [,\n*$showmode* ] ];\n\nThe ShowTable subroutine displays tabular data aligned in columns, with headers. ShowTable\nsupports four *modes* of display: Box, Table, List, and HTML. Each mode is described separately\nbelow.\n\nThe arguments to ShowTable may be given in one of two ways: as a hashed-array, or by a\ncombination of fixed order arguments, and some package-global variable settings. The hash-array\nparameters correspond to the fixed arguments and the global-parameter settings.\n\nIn the list below, both the hash-array parameter name and the fixed-order argument name is given\nas the value. In the case where there is no fixed-order argument for a given parameter-value\npair, then the corresponding global variable name is given.\n\n\"titles\" => *\\@titles*\nA reference to an array of column names, or titles. If a particular column name is\nnull, then the string \"Field*num*\" is used by default. To have a column have no\ntitle, use the empty string.\n\n\"types\" => *\\@types*\nA reference to an array of types, one for each column. These types are passed to the\n*fmtsub* for appropriate formatting. Also, if a column type matches the regexp\n\"\"/text|char|string/i\"\", then the column alignment will be left-justified, otherwise\nit will be right-justified.\n\n\"widths\" => *\\@widths*\nA reference to an array of column widths, which may be given as an integer, or as a\nstring of the form: \"*width*.*precision*\".\n\n\"rowsub\" => *\\&rowsub*\nA reference to a subroutine which successively returns rows of values in an array. It\nis called for two purposes, each described separately:\n\n* To fetch successive rows of data:\n\n@row = &$rowsub(0);\n\nWhen given a null, zero, or empty argument, the next row is returned.\n\n* To initialize or rewind the data traversal.\n\n$rewindable = &$rowsub(1);\n\nWhen invoked with a non-null argument, the subroutine should rewind its row pointer to\nstart at the first row of data. If the data which *rowsub* is traversing is not\nrewindable, it must return zero or null. If the data is rewindable, a non-null,\nnon-zero value should be returned.\n\nThe *rowsub* must expect to be invoked once with a non-null argument, in order to\ndiscover whether or not the data is rewindable. If the data cannot be rewound,\n*rowsub* will thereafter only be called with a zero argument.\n\nSpecifically, *rowsub* subroutine is used in this manner:\n\n$rewindable = &$rowsub(1);\nif ($rewindable) {\nwhile ((@row = &$rowsub(0)), $#row >= 0) {\n# examine lengths for optimal formatting\n}\n&$rowsub(1); # rewind\n}\nwhile ((@row = &$rowsub(0)), $#row >= 0) {\n# format the data\n}\n\nThe consequence of data that is not rewindable, a reasonably nice table will still be\nformatted, but it may contain fairly large amounts of whitespace for wide columns.\n\n\"fmtsub\" => *\\&fmtsub*\nA reference to a subroutine which formats a value, according to its type, width,\nprecision, and the current column width. It is invoked either with a fixed list of\narguments, or with a hash-array of parameter and value pairs.\n\n$string = &fmtsub { I => I, ... };\n\n$string = &fmtsub($value, $type, $maxwidth, $width, $precision)\n\nIf *\\&fmtsub* is omitted, then a default subroutine, ShowTableValue, will be used,\nwhich will use Perl's standard string formatting rules.\n\nThe arguments to *\\&fmtsub*, either as values passed in a fixed order, or as part of\nthe parameter value pair, are described in the section on \"ShowTableValue below.\n\n\"maxwidth\" => *number*,\nThe maximum table width, including the table formatting characters. If not given,\ndefaults to the global variable $MaxTableWidth;\n\n\"showmode\" => '*mode*',\nThe display mode of the output. One of five strings: 'Box', 'Table', 'Simple', 'List',\nand 'HTML'.\n", "subsections": [] }, "ShowDatabases": { "content": "Show a list of database names.\n\nShowDatabases *\\@dbnames*;\n\nShowDatabases { 'data' => *\\@dbnames*, *parameter* => *value*, ...};\n\nShowDatabases is intended to be used to display a list of database names, under the column\nheading of \"Databases\". It is a special case usage of ShowTable (and can thus be passed any\nparameter suitable for ShowTable.\n\nThe argument, *\\@dbnames*, is a reference to an array of strings, used as the values of the\nsingle column display.\n", "subsections": [] }, "ShowTables": { "content": "Show an array of table names.\n\nShowTables *\\@tblnames*;\n\nShowTables { 'data' => *\\@tblnames*, *parameter* => *value*, ...};\n\nShowTables is used to display a list of table names, under the column heading of \"Tables\". It is\na special case usage of ShowTable, and can be passed any \"ShowTable\" argument parameter.\n", "subsections": [] }, "ShowColumns": { "content": "Display a table of column names, types, and attributes.\n\nShowColumns { *parameter* => *values*, ... };\n\nShowColumns *\\@columns*, *\\@coltypes*, *\\@collengths*, *\\@colattrs*;\n\nThe ShowColumns subroutine displays a table of column names, types, lengths, and other\nattributes in a nicely formatted table. It is a special case usage of ShowTable, and can be\npassed any argument suitable for \"ShowTable\";\n\nThe arguments are:\n\n\"columns\" = *\\@columns*\nAn array of column names. This provides the value for the first column of the output.\n\n\"coltypes\" = *\\@coltypes*\nAn array of column types names. This provides the value for the second column.\n\n\"collengths\" = *\\@collengths*\nAn array of maximum lengths for corresponding columns. This provides the value for the\nthird column of the output.\n\n\"colattrs\" = *\\@colattrs*\nAn array of column attributes array references (ie: an array of arrays). The\nattributes array for the first column are at \"*$colattrs*-\\>[0]\". The first attribute\nof the second column is \"*$colattrs*-\\>[1][0]\".\n\nThe columns, types, lengths, and attributes are displayed in a table with the column headings:\n\"Column\", \"Type\", \"Length\", and \"Attributes\". This is a special case usage of ShowTable, and can\nbe passed additional arguments suitable for \"ShowTable\".\n", "subsections": [] }, "ShowBoxTable": { "content": "Show tabular data in a box.\n\nShowBoxTable { *parameter* = *value*, ... };\n\nShowBoxTable *\\@titles*, *\\@types*, *\\@widths*, *\\&rowsub* [, [ *\\&fmtsub* ] [,\n*$maxwidth* ] ];\n\nThe ShowBoxTable displays tabular data in titled columns using a \"box\" of ASCII graphics,\nlooking something like this:\n\n+------------+----------+-----+----------+\n| Column1 | Column2 | ... | ColumnN |\n+------------+----------+-----+----------+\n| Value11 | Value12 | ... | Value 1M |\n| Value21 | Value22 | ... | Value 2M |\n| Value31 | Value32 | ... | Value 3M |\n| ... | ... | ... | ... |\n| ValueN1 | ValueN2 | ... | Value NM |\n+------------+----------+-----+----------+\n\nThe arguments are the same as with \"ShowTable\". If the *@titles* array is empty, the header row\nis omitted.\n", "subsections": [] }, "ShowSimpleTable": { "content": "Display a table of data using a simple table format.\n\nShowSimpleTable *\\@titles*, *\\@types*, *\\@widths*, *\\&rowsub* [, *\\&fmtsub*];\n\nShowSimpleTable { *parameter* => *values*, ... };\n\nThe ShowSimpleTable subroutine formats data into a simple table of aligned columns, in the\nfollowing example:\n\nColumn1 Column2 Column3\n------- ------- -------\nValue1 Value2 Value3\nValue12 Value22 Value32\n\nColumns are auto-sized by the data's widths, plus two spaces between columns. Values which are\ntoo long for the maximum colulmn width are wrapped within the column.\n", "subsections": [] }, "ShowHTMLTable": { "content": "Display a table of data nicely using HTML tables.\n\nShowHTMLTable { *parameter* => *value*, ... };\n\nShowHTMLTable *\\@titles*, *\\@types*, *\\@widths*, *\\&rowsub* [, *\\&fmtsub* [, *$maxwidth* [,\n*\\%URLKeys* [, *$noescape* [, *\\@titleformats* [, *\\@dataformats* [, *$tableattrs* ] ] ] ]\n] ] ];\n\nThe ShowHTMLTable displays one or more rows of columns of data using the HTML \"\\\nfeature. In addition to the usual parameter arguments of \"ShowTable\", the following parameter\narguments are defined:\n\n\"urlkeys\" => *\\%URLKeys*,\nThis is a hash array of column names (titles) and corresponding base URLs. The values\nof any column names or indexes occuring as keys in the hash array will be generated as\nhypertext anchors using the associated *printf*-like string as the base URL. Either\nthe column name or the column index (beginning with 1) may be used as the hash key.\n\nIn the string value, these macros can be substituted:\n\n\"%K\" is replaced with the column name.\n\n\"%V\" is replaced with the column value;\n\n\"%I\" is replaced with the column index.\n\nFor example, if we define the array:\n\n$baseurl = \"http://www.$domain/cgi/lookup?col=%K?val=%V\";\n%urlcols = ('Author' => $baseurl,\n'Name' => $baseurl);\n\nThen, the values in the \"Author\" column will be generated with the following HTML\ntext:\n\nsomevalue\n\nand the values in the \"Name\" column will be generated with the URL:\n\nothervalue\n\nIf this variable is not given, it will default to the global variable \"\\%URLKeys\".\n\n\"noescape\" => *boolean*,\nUnless $noescape is set, HTML-escaping is performed on the data values in order to\nproperly display the special HTML formatting characters : '\\<', '\\>', and '&'. If you\nwish to display data with embedded HTML text, you must set $noescape.\n\nEnabling embedded HTML, turns on certain heuristics which enable the user to more\ncompletely define appearance of the table. For instance, any \"\\ tokens found\nembedded *anywhere* within a row of data will be placed at the front of the row,\nwithin the generated \"\\.\n\nSimilarly, a row of data containing the \"\\ or \"\\ tokens, and their\nclosing counterparts, will begin and end, respectively a table header or footer data.\n\n\"titleformats\" => *\\@titleformats*,\n\"tformats\" => *\\@titleformats*,\nAn array of HTML formatting elements for the column titles, one for each column. Each\narray element is a list of one or more HTML elements, given as \"\\ or\nplainly, \"ELEMENT\", and separated by a comma ',', semi-colon ';', or vertical bar '|'.\nEach given HTML element is prepended to the corresponding column title, in the order\ngiven. The corresponding HTML closing elements are appended in the opposite order.\n\nFor example, if *\\@titleformats* contains the two elements:\n\n[ 'FONT SIZE=+2,BOLD', 'FONT COLOR=red,EM' ]\n\nthen the text output for the title of the first column would be:\n\nI\n\nIf \"titleformats\" is omitted, the global variable @TitleFormats is used by default.\n\n\"dataformats\" => *\\@dataformats*,\n\"dformats\" => *\\@dataformats*,\nSimilar to \"titleformats\", this array provides HTML formatting for the columns of\neach row of data. If \"dataformats\" is omitted or null, then the global variable\n\\@DataFormats is used by default.\n\n\"tableattrs\" => *$tableattrs*,\nThis variable defines a string of attributes to be inserted within the \"\\\ntoken. For example, if the user wishes to have no table border:\n\nShowHTMLTable {\n...\ntableattrs => 'BORDER=0',\n...\n};\n", "subsections": [] }, "ShowListTable": { "content": "Display a table of data using a list format.\n\nShowListTable { *parameter* => *value*, ... };\n\nShowListTable *\\@titles*, *\\@types*, *\\@widths*, *\\&rowsub* [, *\\&fmtsub* [, *$maxwidth* [,\n*$wrapmargin* ] ] ];\n\nThe arguments for ShowListTable are the same as for \"ShowTable\", except for those described\nnext.\n\n\"maxwidth\" = *number*,\n\"wrapmargin\" = *number*,\nLines are truncated, and wrapped when their length exceeds *$maxwidth*. Wrapping is\ndone on a word-basis, unless the resulting right margin exceeds *$wrapmargin*, in\nwhich case the line is simply truncated at the *$maxwidth* limit.\n\nThe *$maxwidth* variable defaults to $MaxListWidth. The *$wrapmargin* defaults to\n$ListWrapMargin.\n\nIn *List* mode, columns (called \"fields\" in List mode) are displayed wth a field name and value\npair per line, with records being one or more fields . In other words, the output of a table\nwould look something like this:\n\nField11: Value11\nField12: Value12\nField13: Value13\n...\nField1-N: Value1M\n\nField21: Value21\nField22: Value22\nField23: Value23\n...\nField2N: Value2N\n...\nFieldM1: ValueM1\nFieldM2: ValueM2\n...\nFieldMN: ValueMN\n\n\n\nCharacteristics of *List* mode:\n\n* two empty lines indicate the end of data.\n\n* An empty field (column) may be omitted, or may have a label, but no data.\n\n* A long line can be continue by a null field (column):\n\nField2: blah blah blah\n: blah blah blah\n\n* On a continuation, the null field is an arbitrary number of leading white space, a\ncolon ':', a single blank or tab, followed by the continued text.\n\n* Embedded newlines are indicated by the escape mechanism \"\\n\". Similarly, embedded tabs\nare indicated with \"\\t\", returns with \"\\r\".\n\n* If the *@titles* array is empty, the field names \"\"Field\"*NN*\" are used instead.\n", "subsections": [] }, "ShowRow": { "content": "Fetch rows successively from one or more columns of data.\n\nShowRow *$rewindflag*, *\\$index*, *$colarray1* [, *$colarray2*, ...;]\n\nThe ShowRow subroutine returns a row of data from one or more columns of data. It is designed to\nbe used as a *callback* routine, within the ShowTable routine. It can be used to select elements\nfrom one or more array reference arguments.\n\nIf passed two or more array references as arguments, elements of the arrays selected by *$index*\nare returned as the \"row\" of data.\n\nIf a single array argument is passed, and each element of the array is itself an array, the\nsubarray is returned as the \"row\" of data.\n\nIf the *$rewindflag* flag is set, then the *$index* pointer is reset to zero, and \"true\" is\nreturned (a scalar 1). This indicates that the data is rewindable to the ShowTable routines.\n\nWhen the *$rewindflag* is not set, then the current row of data, as determined by *$index* is\nreturned, and *$index* will have been incremented.\n\nAn actual invocation (from ShowColumns) is:\n\nShowTable \\@titles, \\@types, \\@lengths,\nsub { &ShowRow( $[0], \\$currentrow, $colnames, $coltypes,\n$collengths, \\@colattrs); };\n\nIn the example above, after each invocation, the *$currentrow* argument will have been\nincremented.\n", "subsections": [] }, "ShowTableValue": { "content": "Prepare and return a formatted representation of a value. A value argument, using its\ncorresponding type, effective width, and precision is formatted into a field of a given maximum\nwidth.\n\n*$fmt* = ShowTableValue *$value*, *$type*, *$maxwidth*, *$width*, *$precision*, *$showmode*;\n\n\"width\" => *$width*\n*$width* The width of the current value. If omittied, *$maxwidth* is assumed.\n\n\"precision\" => *$precision*\n*$precision*\nThe number of decimal digits; zero is assumed if omittied.\n\n\"value\" => *$value*\n*$value* The value to be formatted.\n\n*$type* The type name of the value; eg: \"char\", \"varchar\", \"int\", etc.\n\n\"maxwidth\" => *$maxwidth*\n*$maxwidth*\nThe maximum width of any value in the current value's column. If *$width* is zero or\nnull, *$maxwidth* is used by default. *$maxwidth* is also used as a *minimum* width,\nin case *$width* is a smaller value.\n\n*$width* The default width of the value, obtained from the width specification of the column in\nwhich this value occurs.\n\n*$precision*\nThe precision specification, if any, from the column width specification.\n\n*$showmode*\nThe mode of the output: one of \"table\", \"list\", \"box\", or \"html\". Currently, only the\n\"html\" mode is significant: it is used to avoid using HTML tokens as part of the\nformatted text and length calculations.\n", "subsections": [] }, "PlainText": { "content": "*$plaintext* = &PlainText(*$htmltext*);\n\n&PlainText\n\nThis function removes any HTML formatting sequences from the input argument, or from $ if no\nargument is given. The resulting plain text is returned as the result.\n", "subsections": [] }, "VARIABLES": { "content": "The following variables may be set by the user to affect the display (with the defaults enclosed\nin square brackets [..]):\n\n$ShowMode [Box]\nThis is the default display mode when using ShowTable. The environment variable,\n$ENV{'SHOWMODE'}, is used when this variable is null or the empty string. The\npossible values for this variable are: \"Box\", \"List\", \"Table\", and \"HTML\". Case is\ninsignificant.\n\n$ListWrapMargin [2]\nThis variable's value determines how large a margin to keep before wrarpping a long\nvalue's display in a column. This value is only used in \"List\" mode.\n\n$MaxListWidth [80]\nThis variable, used in \"List\" mode, is used to determine how long an output line may\nbe before wrapping it. The environment variable, $ENV{'COLUMNS'}, is used to define\nthis value when it is null.\n\n$MaxTableWidth ['']\nThis variable, when set, causes all tables to have their columns scaled such that\ntheir total combined width does not exceed this value. When this variable is not set,\nwhich is the default case, there is no maximum table width, and no scaling will be\ndone.\n\n$NoEscape ['']\nIf set, allows embedded HTML text to be included in the data displayed in an\nHTML-formatted table. By default, the HTML formatting characters (\"<\", \">\", and \"&\")\noccuring in values are escaped.\n\n%URLKeys In HTML mode, this variable is used to recognize which columns are to be displayed\nwith a corresponding hypertext anchor. See \"ShowHTMLTable\" for more details.\n\n@HTMLElements\nAn array of HTML elements (as of HTML 3.0) used to recognize and strip for width\ncalculations.\n\n$HTMLElements\nA regular expression string formed from the elements of @HTMLElements.\n", "subsections": [] }, "INTERNAL SUBROUTINES": { "content": "getparams\nmy *$args* = &getparams *\\@argv*, *\\%params*, *\\@arglist*;\n\nGiven the *@argv* originally passed to the calling sub, and the hash of named parameters as\n*%params*, and the array of parameter names in the order expected for a pass-by-value\ninvocation, set the values of each of the variables named in *@vars*.\n\nIf the only element of the *@argv* is a hash array, then set the variables to the values of\ntheir corresponding parameters used as keys to the hash array. If the parameter is not a key of\nthe *%params* hash, and is not a key in the global hash %ShowTableParams, then an error is\nnoted.\n\nWhen *@argv* has multiple elements, or is not a hash array, set each variable, in the order\ngiven within *@arglist*, to the values from the *@argv*, setting the variables named by each\nvalue in *%params*.\n\nVariables may given either by name or by reference.\n\nThe result is a HASH array reference, either corresponding directly to the HASH array passed as\nthe single argument, or one created by associating the resulting variable values to the\nparameter names associated with the variable names.\n\nhtmlformats\n(*$prefixes*,*$suffixes*) = htmlformats *\\@htmlformats*;\n\nThe htmlformat function takes an array reference of HTML formatting elements *\\@htmlformats*,\nand builds two arrays of strings: the first: *$prefixes*, is an array of prefixes containing the\ncorresponding HTML formatting elements from *\\@htmlformats*, and the second, *$suffixes*,\ncontaining the appropriate HTML closing elements, in the opposite order.\n\nThe result is designed to be used as prefixes and suffixes for the corresponding titles and\ncolumn values.\n\nThe array *\\@htmlformats* contains lists of HTML formatting elements, one for each column\n(either title or data). Each array element is a list of one or more HTML elements, either given\nin HTML syntax, or as a \"plain\" name (ie: given as \"\\ or plainly, \"ELEMENT\").\nMultiple elements are separated by a comma ','.\n\nThe resulting array of *$prefixes* contains the corresponding opening elements, in the order\ngiven, with the proper HTML element syntax. The resulting array of *$suffixes* contains the\nclosing elements, in the opposite order given, with the proper HTML element syntax.\n\nFor example, if *\\@htmlformats* contains the two elements:\n\n[ 'FONT SIZE=+2,BOLD', 'FONT COLOR=red,EM' ]\n\nthen the resulting two arrays will be returned as:\n\n[ [ '', '' ],\n[ '', '' ] ]\n\ncalcwidths\n(*$numcols*, *$widths*, *$precision*, *$maxwidths*) = &calcwidths( *$widthspec*,\n*$titles*, *$rewindable*, *$rowsub*, *$fmtsub*, *$types*, *$showmode*,\n*$maxwidth*);\n\nDESCRIPTION\ncalcwidths is a generalized subroutine used by all the ShowTable variant subroutines to setup\ninternal variables prior to formatting for display. Calcwidths handles the column width and\nprecision analysis, including scanning the data (if rewindable) for appropriate default values.\n\nThe number of columns in the data is returned, as well as three arrays: the declared column\nwidths, the column precision values, and the maximum column widths.\n\nRETURN VALUES\n*$numcols*\nis the number of columns in the data. If the data is not rewindable, this is computed\nas the maximum of the number of elements in the *$widthspec* array and the number of\nelements in the *$titles* array. When the data is rewindable, this is the maximum of\nthe number of columns of each row of data.\n\n*$widths* is the column widths array ref, without the precision specs (if any). Each column's\nwidth value is determined by the original *$widthspec* value and/or the maximum length\nof the formatted data for the column.\n\n*$precision*\nis the precision component (if any) of the original *$widthspec* array ref. If there\nwas no original precision component from the *$widthspec*, and the data is rewindable,\nthen the data is examined to determine the maximum default precision.\n\n*$maxwidths*\nis the ref to the array of maximum widths for the given columns.\n\nARGUMENTS\n*$widthspec*\nA reference to an array of column width (or length) values, each given as an integer,\nreal number, or a string value of \"*width*.*precision*\". If a value is zero or null,\nthe length of the corresponding formatted data (if rewindable) and column title length\nare used to determine a reasonable default.\n\nIf a column's *width* portion is a positive, non-zero number, then the column will be\nthis wide, regardless of the values lengths of the data in the column.\n\nIf the column's *width* portion is given as a negative number, then the positive value\nis used as a minimum column width, with no limit on the maximum column width. In other\nwords, the column will be at least *width* characters wide.\n\nIf the data is not rewindable, and a column's width value is null or zero, then the\nlength of the column title is used. This may cause severe wrapping of data in the\ncolumn, if the column data lengths are much greater than the column title widths.\n\n*$titles* The array ref to the column titles; used to determine the minimum acceptable width, as\nwell as the default number of columns. If the $titles array is empty, then the\n$widthspec array is used to determine the default number of columns.\n\n*$rewindable*\nA flag indicating whether or not the data being formatted is rewindable. If this is\ntrue, a pass over the data will be done in order to calculate the maximum lengths of\nthe actual formatted data, using *$fmtsub* (below), rather than just rely on the\ndeclared column lengths. This allows for optimal column width adjustments (ie: the\nactual column widths may be less than the declared column widths).\n\nIf it is not desired to have the column widths dynamically adjusted, then set the\n*$rewindable* argument to 0, even if the data is rewindable.\n\n*$rowsub*\nThe code reference to the subroutine which returns the data; invoked only if\n*$rewindable* is non-null.\n\n*$fmtsub*\nThe subroutine used to determine the length of the data when formatted; if this is\nomitted or null, the length of the data is used by default. The *$fmtsub* is used\nonly when the data is rewindable.\n\n*$types* An array reference to the types of each of the value columns; used only when\n*$fmtsub* is invoked.\n\n*$showmode*\nA string indicating the mode of the eventual display; one of four strings: \"\"box\"\",\n\"\"table\"\", \"\"list\"\", and \"\"html\"\". Used to adjust widths for formatting requirements.\n\n*$maxwidth*\nThe maximum width of the table being formatted. If set, and the total sum of the\nindividual columns exceeds this value, the column widths are scaled down uniformly. If\nnot set (null), no column width scaling is done.\n\nputcell\n*$wrapped* = &putcell( *\\@cells*, *$c*, *$cellwidth*, *\\@prefix*, *\\@suffix*, *$wrapflag* );\n\nOutput the contents of an array cell at *$cell*[*$c*], causing text longer than *$cellwidth* to\nbe saved for output on subsequent calls. Prefixing the output of each cell's value is a string\nfrom the two-element array *@prefix*. Suffixing each cell's value is a string from the\ntwo-element array *@suffix*. The first element of either array is selected when *$wrapflag* is\nzero or null, or when there is no more text in the current to be output. The second element is\nselected when *$wrapflag* is non-zero, and when there is more text in the current cell to be\noutput.\n\nIn the case of text longer than *$cellwidth*, a non-zero value is returned.\n\nCells with undefined data are not output, nor are the prefix or suffix strings.\n\ncenter\nCenter a string within a given width.\n\n*$field* = center *$string*, *$width*;\n\nmax\nCompute the maximum value from a list of values.\n\n*$max* = &max( *@values* );\n\nmin\nCompute the minum value from a list of values.\n\n*$min* = &min( *@values* );\n\nmaxlength\nCompute the maximum length of a set of strings in an array reference.\n\n*$maxlength* = &maxlength( *\\@arrayref* );\n\nhtmltext\nTranslate regular text for output into an HTML document. This means certain characters, such as\n\"&\", \">\", and \"<\" must be escaped.\n\n*$output* = &htmltext( *$input* [, *$allflag* ] );\n\nIf *$allflag* is non-zero, then all characters are escaped. Normally, only the four HTML\nsyntactic break characters are escaped.\n\nout\nPrint text followed by a newline.\n\nout *$fmt* [, *@text* ];\n\nput\nPrint text (without a trailing newline).\n\nout *$fmt* [, *@text* ];\n", "subsections": [] }, "AUTHOR": { "content": "Alan K. Stebbens \n", "subsections": [] }, "BUGS": { "content": "* Embedded HTML is how the user can insert formatting overrides. However, the HTML\nformatting techniques have not been given much consideration -- feel free to provide\nconstructive feedback.\n", "subsections": [] } } } }