1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
|
<HTML>
<HEAD>
<TITLE>Data::ShowTable Man Page</TITLE>
</HEAD>
<BODY>
<H1>Data::ShowTable Man Page</H1>
<HR>
<PRE>
<STRONG>ShowTable</STRONG> - routines to display tabular data in several
formats.
</PRE>
<H2>USAGE</H2><PRE>
<STRONG>use</STRONG> <STRONG>Data::ShowTable;</STRONG>
<STRONG>ShowTable</STRONG> \@<EM>titles</EM>, \@<EM>types</EM>, \@<EM>widths</EM>, \&<EM>row</EM><STRONG>_</STRONG><EM>sub</EM> [,
\&<EM>fmt</EM><STRONG>_</STRONG><EM>sub</EM> ];
$Data::ShowTable::<STRONG>Show_Mode</STRONG> = '<EM>mode</EM>';
$Data::ShowTable::<STRONG>Term_Columns</STRONG> = <EM>NNN</EM>;
$Data::ShowTable::<STRONG>Max_Table_Width</STRONG> = <EM>NNN</EM>;
<STRONG>ShowRow</STRONG> $<EM>rewindflag</EM>, \$<EM>index</EM>, $<EM>col</EM><STRONG>_</STRONG><EM>array</EM><STRONG>_</STRONG><EM>1</EM> [,
$<EM>col</EM><STRONG>_</STRONG><EM>array</EM><STRONG>_</STRONG><EM>2</EM>, ...;]
<STRONG>ShowDatabases</STRONG> \@<EM>dbnames</EM>;
<STRONG>ShowTables</STRONG> \@<EM>tblnames</EM>;
<STRONG>ShowColumns</STRONG> \@<EM>columns</EM>, \@<EM>col</EM><STRONG>_</STRONG><EM>types</EM>, \@<EM>col</EM><STRONG>_</STRONG><EM>lengths</EM>,
\@<EM>col</EM><STRONG>_</STRONG><EM>attrs</EM>;
<STRONG>ShowBoxTable</STRONG> \@<EM>titles</EM>, \@<EM>types</EM>, \@<EM>widths</EM>, \&<EM>row</EM><STRONG>_</STRONG><EM>sub</EM> [,
\&<EM>fmt</EM><STRONG>_</STRONG><EM>sub</EM> ];
<STRONG>ShowSimpleTable</STRONG> \@<EM>titles</EM>, \@<EM>types</EM>, \@<EM>widths</EM>, \&<EM>row</EM><STRONG>_</STRONG><EM>sub</EM> [,
\&<EM>fmt</EM><STRONG>_</STRONG><EM>sub</EM>];
<STRONG>ShowHTMLTable</STRONG> \@<EM>titles</EM>, \@<EM>types</EM>, \@<EM>widths</EM>, \&<EM>row</EM><STRONG>_</STRONG><EM>sub</EM> [,
\&<EM>fmt</EM><STRONG>_</STRONG><EM>sub</EM>];
<STRONG>ShowListTable</STRONG> \@<EM>titles</EM>, \@<EM>types</EM>, \@<EM>widths</EM>, \&<EM>row</EM><STRONG>_</STRONG><EM>sub</EM> [,
\&<EM>fmt</EM><STRONG>_</STRONG><EM>sub</EM>];
$<EM>fmt</EM> = <STRONG>ShowTableValue</STRONG> $<EM>value</EM>, $<EM>type</EM>, $<EM>max</EM><STRONG>_</STRONG><EM>width</EM>, $<EM>width</EM>,
$<EM>precision</EM>;
</PRE>
<H2>DESCRIPTION</H2><PRE>
The <STRONG>ShowTable</STRONG> module provides subroutines to display
tabular data, typially from a database, in nicely
formatted columns, in several formats. 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 "<STRONG>+</STRONG>", "<STRONG>-</STRONG>",
and "<STRONG>|</STRONG>" characters. See the section on
<EM>ShowBoxTable</EM> for details.
Table A simple tabular format, with columns
List A <EM>list</EM> style, where columns of data are listed
as a <EM>name</EM>:<EM>value</EM> pair, one pair per line, with
rows being one or more column values, separated
by an empty line. See the section on
<EM>ShowListTable</EM>.
HTML The data is output as an HTML <EM>TABLE</EM>, suitable
for display through a <EM>Web</EM>-client. See the
section on <EM>ShowHTMLTable</EM>.
The subroutines which perform these displays are listed
below.
</PRE>
<H2>EXPORTED NAMES</H2><PRE>
This module exports the following subroutines:
<STRONG>ShowDatabases</STRONG> <STRONG>-</STRONG> <STRONG>show</STRONG> <STRONG>list</STRONG> <STRONG>of</STRONG> <STRONG>databases</STRONG>
<STRONG>ShowTables</STRONG> <STRONG>-</STRONG> <STRONG>show</STRONG> <STRONG>list</STRONG> <STRONG>of</STRONG> <STRONG>tables</STRONG>
<STRONG>ShowColumns</STRONG> <STRONG>-</STRONG> <STRONG>show</STRONG> <STRONG>table</STRONG> <STRONG>of</STRONG> <STRONG>column</STRONG> <STRONG>info</STRONG>
<STRONG>ShowTable</STRONG> <STRONG>-</STRONG> <STRONG>show</STRONG> <STRONG>a</STRONG> <STRONG>table</STRONG> <STRONG>of</STRONG> <STRONG>data</STRONG>
<STRONG>ShowRow</STRONG> <STRONG>-</STRONG> <STRONG>show</STRONG> <STRONG>a</STRONG> <STRONG>row</STRONG> <STRONG>from</STRONG> <STRONG>one</STRONG> <STRONG>or</STRONG> <STRONG>more</STRONG> <STRONG>columns</STRONG>
<STRONG>ShowTableValue</STRONG> <STRONG>-</STRONG> <STRONG>show</STRONG> <STRONG>a</STRONG> <STRONG>single</STRONG> <STRONG>column's</STRONG> <STRONG>value</STRONG>
<STRONG>ShowBoxTable</STRONG> <STRONG>-</STRONG> <STRONG>show</STRONG> <STRONG>a</STRONG> <STRONG>table</STRONG> <STRONG>of</STRONG> <STRONG>data</STRONG> <STRONG>in</STRONG> <STRONG>a</STRONG> <STRONG>box</STRONG>
<STRONG>ShowListTable</STRONG> <STRONG>-</STRONG> <STRONG>show</STRONG> <STRONG>a</STRONG> <STRONG>table</STRONG> <STRONG>of</STRONG> <STRONG>data</STRONG> <STRONG>in</STRONG> <STRONG>a</STRONG> <STRONG>list</STRONG>
<STRONG>ShowSimpleTable</STRONG> <STRONG>-</STRONG> <STRONG>show</STRONG> <STRONG>a</STRONG> <STRONG>table</STRONG> <STRONG>of</STRONG> <STRONG>data</STRONG> <STRONG>in</STRONG> <STRONG>a</STRONG> <STRONG>simple</STRONG> <STRONG>table</STRONG>
<STRONG>ShowHTMLTable</STRONG> <STRONG>-</STRONG> <STRONG>show</STRONG> <STRONG>a</STRONG> <STRONG>table</STRONG> <STRONG>of</STRONG> <STRONG>data</STRONG> <STRONG>using</STRONG> <STRONG>HTML</STRONG>
All of these subroutines, and others, are described in
detail in the following sections.
</PRE>
<H2>MODULES</H2><PRE>
</PRE>
<H2>ShowTable</H2><PRE>
Format and display the contents of one or more rows of
data.
<STRONG>ShowTable</STRONG> \@<EM>titles</EM>, \@<EM>types</EM>, \@<EM>widths</EM>, \&<EM>row</EM><STRONG>_</STRONG><EM>sub</EM> [,
\&<EM>fmt</EM><STRONG>_</STRONG><EM>sub</EM> ];
$Data::ShowTable::<STRONG>Show_Mode</STRONG> = '<EM>mode</EM>';
$Data::ShowTable::<STRONG>Term_Columns</STRONG> = <EM>NNN</EM>;
$Data::ShowTable::<STRONG>Max_Table_Width</STRONG> = <EM>NNN</EM>;
The <STRONG>ShowTable</STRONG> subroutine displays tabular data aligned in
columns, with headers. <STRONG>ShowTable</STRONG> supports four <EM>modes</EM> of
display: <STRONG>Box</STRONG>, <STRONG>Table</STRONG>, <STRONG>List</STRONG>, and <STRONG>HTML</STRONG>. Each mode is
described separately below.
The arguments to <STRONG>ShowTable</STRONG> are:
titles. If a particular column name is null,
then the string <STRONG>Column</STRONG> <EM>num</EM> is used by default.
To have a column have no title, use the empty
string.
\@<EM>types</EM> A reference to an array of types, one for each
column. These types are passed to the <EM>fmt</EM><STRONG>_</STRONG><EM>sub</EM>
for appropriate formatting. Also, if a column
type matches the regexp "<STRONG>/text|char|string/i</STRONG>",
then the column alignment will be left-
justified, otherwise it will be right-justified.
\@<EM>widths</EM> A reference to an array of column widths, which
may be given as an integer, or as a string of
the form: <STRONG>"</STRONG><EM>width</EM>.<EM>precision</EM>".
\&<EM>row</EM><STRONG>_</STRONG><EM>sub</EM> 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:
<STRONG>@row</STRONG> <STRONG>=</STRONG> <STRONG>&$row_sub(0);</STRONG>
When given a null, zero, or empty argument, the
next row is returned.
* To initialize or rewind the data traversal.
<STRONG>$rewindable</STRONG> <STRONG>=</STRONG> <STRONG>&$row_sub(1);</STRONG>
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 <EM>row</EM><STRONG>_</STRONG><EM>sub</EM> 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 <EM>row</EM><STRONG>_</STRONG><EM>sub</EM> 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, <EM>row</EM><STRONG>_</STRONG><EM>sub</EM> will thereafter
only be called with a zero argument.
Specifically, <EM>row</EM><STRONG>_</STRONG><EM>sub</EM> subroutine is used in this
manner:
<STRONG>if</STRONG> <STRONG>($rewindable)</STRONG> <STRONG>{</STRONG>
<STRONG>while</STRONG> <STRONG>((@row</STRONG> <STRONG>=</STRONG> <STRONG>&$row_sub(0)),</STRONG> <STRONG>$#row</STRONG> <STRONG>>=</STRONG> <STRONG>0)</STRONG> <STRONG>{</STRONG>
<STRONG>#</STRONG> <STRONG>examine</STRONG> <STRONG>lengths</STRONG> <STRONG>for</STRONG> <STRONG>optimal</STRONG> <STRONG>formatting</STRONG>
<STRONG>}</STRONG>
<STRONG>&$row_sub(1);</STRONG> <STRONG>#</STRONG> <STRONG>rewind</STRONG>
<STRONG>}</STRONG>
<STRONG>while</STRONG> <STRONG>((@row</STRONG> <STRONG>=</STRONG> <STRONG>&$row_sub(0)),</STRONG> <STRONG>$#row</STRONG> <STRONG>>=</STRONG> <STRONG>0)</STRONG> <STRONG>{</STRONG>
<STRONG>#</STRONG> <STRONG>format</STRONG> <STRONG>the</STRONG> <STRONG>data</STRONG>
<STRONG>}</STRONG>
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.
\&<EM>fmt</EM><STRONG>_</STRONG><EM>sub</EM> A reference to a subroutine which formats a
value, according to its type, width, precision,
and the current column width. It is invoked
this way:
<STRONG>$string</STRONG> <STRONG>=</STRONG> <STRONG>&fmt_sub($value,</STRONG> <STRONG>$type,</STRONG> <STRONG>$max_width,</STRONG> <STRONG>$width,</STRONG> <STRONG>$precision)</STRONG>
The $<EM>max</EM><STRONG>_</STRONG><EM>width</EM> is the maximum width for the
column currently being formatted.
If $<EM>width</EM> is omitted, $<EM>max</EM><STRONG>_</STRONG><EM>width</EM> is assumed.
If $<EM>precision</EM> is omitted, zero is assumed.
If \&<EM>fmt</EM><STRONG>_</STRONG><EM>sub</EM> is omitted, then a default
subroutine, <STRONG>ShowTableValue</STRONG>, will be used, which
will use Perl's standard string formatting
rules.
</PRE>
<H2>ShowRow</H2><PRE>
Fetch rows successively from one or more columns of data.
<STRONG>ShowRow</STRONG> $<EM>rewindflag</EM>, \$<EM>index</EM>, $<EM>col</EM><STRONG>_</STRONG><EM>array</EM><STRONG>_</STRONG><EM>1</EM> [,
$<EM>col</EM><STRONG>_</STRONG><EM>array</EM><STRONG>_</STRONG><EM>2</EM>, ...;]
The <STRONG>ShowRow</STRONG> subroutine returns a row of data from one or
more columns of data. It is designed to be used as a
<EM>callback</EM> routine, within the <STRONG>ShowTable</STRONG> 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 $<EM>index</EM> 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
reset to zero, and "true" is returned (a scalar 1). This
indicates that the data is rewindable to the <STRONG>ShowTable</STRONG>
routines.
When the $<EM>rewindflag</EM> is not set, then the current row of
data, as determined by $<EM>index</EM> is returned, and $<EM>index</EM> will
have been incremented.
An actual invocation (from <STRONG>ShowColumns</STRONG>) is:
<STRONG>ShowTable</STRONG> <STRONG>\@titles,</STRONG> <STRONG>\@types,</STRONG> <STRONG>\@lengths,</STRONG>
<STRONG>sub</STRONG> <STRONG>{</STRONG> <STRONG>&ShowRow(</STRONG> <STRONG>$_[0],</STRONG> <STRONG>\$current_row,</STRONG> <STRONG>$col_names,</STRONG> <STRONG>$col_types,</STRONG>
<STRONG>$col_lengths,</STRONG> <STRONG>\@col_attrs);</STRONG> <STRONG>};</STRONG>
In the example above, after each invocation, the
$<EM>current</EM><STRONG>_</STRONG><EM>row</EM> argument will have been incremented.
</PRE>
<H2>ShowDatabases</H2><PRE>
Show a list of database names.
<STRONG>ShowDatabases</STRONG> \@<EM>dbnames</EM>;
<STRONG>ShowDatabases</STRONG> 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 <STRONG>ShowTable</STRONG>.
The argument, \@<EM>dbnames</EM>, is a reference to an array of
strings.
</PRE>
<H2>ShowTables</H2><PRE>
Show an array of table names.
<STRONG>ShowTables</STRONG> \@<EM>tblnames</EM>;
<STRONG>ShowTables</STRONG> is used to display a list of table names, under
the column heading of "Tables". It is a special case
usage of <STRONG>ShowTable</STRONG>.
</PRE>
<H2>ShowColumns</H2><PRE>
Display a table of column names, types, and attributes.
<STRONG>ShowColumns</STRONG> \@<EM>columns</EM>, \@<EM>col</EM><STRONG>_</STRONG><EM>types</EM>, \@<EM>col</EM><STRONG>_</STRONG><EM>lengths</EM>,
\@<EM>col</EM><STRONG>_</STRONG><EM>attrs</EM>;
The <STRONG>ShowColumns</STRONG> subroutine displays a table of column
names, types, lengths, and other attributes in a nicely
formatted table. It is a special case usage of <STRONG>ShowTable</STRONG>.
The arguments are:
\@<EM>columns</EM> An array of column names.
An array of column types names.
\@<EM>col</EM><STRONG>_</STRONG><EM>lengths</EM>
An array of maximum lengths for corresponding
columns.
\@<EM>col</EM><STRONG>_</STRONG><EM>attrs</EM>
An array of column attributes array references
(ie: an array of arrays). The attributes array
for the first column are at "$<EM>col</EM><STRONG>_</STRONG><EM>attrs</EM>-\>[0]".
The first attribute of the second column is
"$<EM>col</EM><STRONG>_</STRONG><EM>attrs</EM>-\>[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 <STRONG>ShowTable</STRONG>.
</PRE>
<H2>ShowBoxTable</H2><PRE>
Show tabular data in a box.
<STRONG>ShowBoxTable</STRONG> \@<EM>titles</EM>, \@<EM>types</EM>, \@<EM>widths</EM>, \&<EM>row</EM><STRONG>_</STRONG><EM>sub</EM> [,
\&<EM>fmt</EM><STRONG>_</STRONG><EM>sub</EM> ];
The <STRONG>ShowBoxTable</STRONG> 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 <STRONG>ShowTable</STRONG>. If the
@<EM>titles</EM> array is empty, the header row is omitted.
</PRE>
<H2>ShowSimpleTable</H2><PRE>
Display a table of data using a simple table format.
<STRONG>ShowSimpleTable</STRONG> \@<EM>titles</EM>, \@<EM>types</EM>, \@<EM>widths</EM>, \&<EM>row</EM><STRONG>_</STRONG><EM>sub</EM>
[, \&<EM>fmt</EM><STRONG>_</STRONG><EM>sub</EM>];
The <STRONG>ShowSimpleTable</STRONG> subroutine formats data into a simple
table of aligned columns, in the following example:
<STRONG>-------</STRONG> <STRONG>-------</STRONG> <STRONG>-------</STRONG>
<STRONG>Value1</STRONG> <STRONG>Value2</STRONG> <STRONG>Value3</STRONG>
<STRONG>Value12</STRONG> <STRONG>Value22</STRONG> <STRONG>Value32</STRONG>
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.
</PRE>
<H2>ShowHTMLTable</H2><PRE>
Display a table of data nicely using HTML tables.
<STRONG>ShowHTMLTable</STRONG> \@<EM>titles</EM>, \@<EM>types</EM>, \@<EM>widths</EM>, \&<EM>row</EM><STRONG>_</STRONG><EM>sub</EM> [,
\&<EM>fmt</EM><STRONG>_</STRONG><EM>sub</EM>];
The <STRONG>ShowHTMLTable</STRONG> displays one or more rows of columns of
data using the HTML C<\<TABLE\>> feature. The arguments
are described in the section on <EM>ShowTable</EM>.
If the @<EM>titles</EM> array is empty, no header row is generated.
There is a variable which controls if and how hypertext
links are generated within the table:
<STRONG>%URL_Keys</STRONG> This is a hash array of column names (titles)
and corresponding base URLs. The values of any
columns occuring as keys in the hash array will
be generated as hypertext anchors using the
associated base URL and the column value as a
querystring for the "<EM>val</EM>" parameter.
For example, if we define the array:
<STRONG>$base_url</STRONG> <STRONG>=</STRONG> <STRONG>"http://www.$domain/cgi/lookup";</STRONG>
<STRONG>%url_cols</STRONG> <STRONG>=</STRONG> <STRONG>('Author'</STRONG> <STRONG>=></STRONG> <STRONG>$base_url,</STRONG>
<STRONG>'Name'</STRONG> <STRONG>=></STRONG> <STRONG>$base_url);</STRONG>
Then, the values in the <STRONG>Author</STRONG> column will be generated
with the following HTML text:
<STRONG><A</STRONG> <STRONG>HREF="http://www.$domain/cgi/lookup?col=Author?val=somevalue>somevalue</A></STRONG>
and the values in the <STRONG>Name</STRONG> column will be generated with
the URL:
<STRONG><A</STRONG> <STRONG>HREF="http://www.$domain/cgi/lookup?col=Name?val=othervalue>othervalue</A></STRONG>
</PRE>
<H2>ShowListTable</H2><PRE>
Display a table of data using a list format.
<STRONG>ShowListTable</STRONG> \@<EM>titles</EM>, \@<EM>types</EM>, \@<EM>widths</EM>, \&<EM>row</EM><STRONG>_</STRONG><EM>sub</EM> [,
\&<EM>fmt</EM><STRONG>_</STRONG><EM>sub</EM>];
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:
<STRONG>Field1-1:</STRONG> <STRONG>Value1-1</STRONG>
<STRONG>Field1-2:</STRONG> <STRONG>Value1-2</STRONG>
<STRONG>Field1-3:</STRONG> <STRONG>Value1-3</STRONG>
<STRONG>...</STRONG>
<STRONG>Field1-N:</STRONG> <STRONG>Value1-M</STRONG>
<STRONG><empty</STRONG> <STRONG>line></STRONG>
<STRONG>Field2-1:</STRONG> <STRONG>Value2-1</STRONG>
<STRONG>Field2-2:</STRONG> <STRONG>Value2-2</STRONG>
<STRONG>Field2-3:</STRONG> <STRONG>Value2-3</STRONG>
<STRONG>...</STRONG>
<STRONG>Field2-N:</STRONG> <STRONG>Value2-N</STRONG>
<STRONG>...</STRONG>
<STRONG>FieldM-1:</STRONG> <STRONG>ValueM-1</STRONG>
<STRONG>FieldM-2:</STRONG> <STRONG>ValueM-2</STRONG>
<STRONG>...</STRONG>
<STRONG>FieldM-N:</STRONG> <STRONG>ValueM-N</STRONG>
<STRONG><empty</STRONG> <STRONG>line></STRONG>
<STRONG><empty</STRONG> <STRONG>line></STRONG>
Characteristics of <EM>List</EM> mode:
<STRONG>o</STRONG> two empty lines indicate the end of data.
<STRONG>o</STRONG> An empty field (column) may be omitted, or may
have a label, but no data.
<STRONG>o</STRONG> A long line can be continue by a null field
(column):
<STRONG>Field2:</STRONG> <STRONG>blah</STRONG> <STRONG>blah</STRONG> <STRONG>blah</STRONG>
<STRONG>:</STRONG> <STRONG>blah</STRONG> <STRONG>blah</STRONG> <STRONG>blah</STRONG>
<STRONG>o</STRONG> On a continuation, the null field is an
arbitrary number of leading white space, a colon
':', and exactly one blank, followed by the
continued text.
<STRONG>o</STRONG> Embedded newlines are indicated by the escape
mechanism "\n". Similarly, embedded tabs are
indicated with "\t", returns with "\r".
<STRONG>o</STRONG> If the @<EM>Titles</EM> array is empty, the field names
"<STRONG>Field</STRONG> <EM>NN</EM>" are used instead.
</PRE>
<H2>ShowTableValue</H2><PRE>
Prepare and return a formatted representation of a value.
A value argument, using its corresponding type, effective
$<EM>fmt</EM> = <STRONG>ShowTableValue</STRONG> $<EM>value</EM>, $<EM>type</EM>, $<EM>max</EM><STRONG>_</STRONG><EM>width</EM>, $<EM>width</EM>,
$<EM>precision</EM>;
$<EM>value</EM> The value to be formatted.
$<EM>type</EM> The type name of the value; eg: <STRONG>char</STRONG>, <STRONG>varchar</STRONG>,
<STRONG>int</STRONG>, etc.
$<EM>max</EM><STRONG>_</STRONG><EM>width</EM>
The maximum width of any value in the current
value's column. If $<EM>width</EM> is zero or null,
$<EM>max</EM><STRONG>_</STRONG><EM>width</EM> is used by default. $<EM>max</EM><STRONG>_</STRONG><EM>width</EM> is
also used as a <EM>minimum</EM> width, in case $<EM>width</EM> is
a smaller value.
$<EM>width</EM> The default width of the value, obtained from
the width specification of the column in which
this value occurs.
$<EM>precision</EM>
The precision specification, if any, from the
column width specification.
</PRE>
<H2>VARIABLES</H2><PRE>
The following variables may be set by the user to affect
the display (with the defaults enclosed in square brackets
[..]):
$<STRONG>Show_Mode</STRONG> [Box]
This is the default display mode when using
<STRONG>ShowTable</STRONG>. The environment variable,
<STRONG>$ENV{'SHOWMODE'}</STRONG>, is used when this variable is
null or the empty string. The possible values
for this variable are: <STRONG>"Box"</STRONG>, <STRONG>"List"</STRONG>, <STRONG>"Table"</STRONG>,
and <STRONG>"HTML"</STRONG>. Case is insignificant.
$<STRONG>List_Wrap_Margin</STRONG> [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.
$<STRONG>Term_Columns</STRONG> [80]
This variable, used in "List" mode, is used to
determine how long an output line may be before
wrapping it. The environment variable,
<STRONG>$ENV{'COLUMNS'}</STRONG>, is used to define this value
when it is null.
$<STRONG>Max_Table_Width</STRONG> ['']
This variable, when set, causes all tables to
this variable is not set, which is the default
case, there is no maximum table width, and no
scaling will be done.
%<STRONG>URL_Keys</STRONG> In HTML mode, this variable is used to recognize
which columns are to be displayed with a
corresponding hypertext anchor. See the section
on <EM>ShowHTMLTable</EM> for more details.
</PRE>
<H2>INTERNAL SUBROUTINES</H2><PRE>
</PRE>
<H2>calc_widths</H2><PRE>
<STRONG>($</STRONG><EM>num</EM><STRONG>_</STRONG><EM>cols</EM>, $<EM>widths</EM>, $<EM>precision</EM>, $<EM>max</EM><STRONG>_</STRONG><EM>widths</EM>) =
<STRONG>&calc_widths</STRONG>( $<EM>widthspec</EM>, $<EM>titles</EM>, $<EM>rewindable</EM>,
<STRONG>$</STRONG><EM>row</EM><STRONG>_</STRONG><EM>sub</EM>, $<EM>fmt</EM><STRONG>_</STRONG><EM>sub</EM>, $<EM>types</EM>, $<EM>showmode</EM>);
<STRONG>DESCRIPTION</STRONG>
<STRONG>calc_widths</STRONG> is a generalized subroutine used by all the
<STRONG>ShowTable</STRONG> variant subroutines to setup internal variables
prior to formatting for display. <STRONG>Calc_widths</STRONG> 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.
<STRONG>RETURN</STRONG> <STRONG>VALUES</STRONG>
<EM>$num</EM><STRONG>_</STRONG><EM>cols</EM> 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
<EM>$widthspec</EM> array and the number of elements in
the <EM>$titles</EM> array. When the data is rewindable,
this is the maximum of the number of columns of
each row of data.
<EM>$widths</EM> is the column widths array ref, without the
precision specs (if any). Each column's width
value is determined by the original <EM>$widthspec</EM>
value and/or the maximum length of the formatted
data for the column.
<EM>$precision</EM>
is the precision component (if any) of the
original <EM>$widthspec</EM> array ref. If there was no
original precision component from the
<EM>$widthspec</EM>, and the data is rewindable, then the
data is examined to determine the maximum
default precision.
is the ref to the array of maximum widths for
the given columns.
<STRONG>ARGUMENTS</STRONG>
<EM>$widthspec</EM>
A reference to an array of column width (or
length) values, each given as an integer, real
number, or a string value of "<EM>width</EM>.<EM>precision</EM>".
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 <EM>width</EM> 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 <EM>width</EM> 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 <EM>width</EM> 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.
<EM>$titles</EM> The array ref to the column titles; used to
determine the minimum acceptable width, as well
as the default number of columns. If the
<STRONG>$titles</STRONG> array is empty, then the <STRONG>$widthspec</STRONG>
array is used to determine the default number of
columns.
<EM>$rewindable</EM>
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 <EM>$fmt</EM><STRONG>_</STRONG><EM>sub</EM> (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
<EM>$row</EM><STRONG>_</STRONG><EM>sub</EM> The code reference to the subroutine which
returns the data; invoked only if <EM>$rewindable</EM> is
non-null.
<EM>$fmt</EM><STRONG>_</STRONG><EM>sub</EM> 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 <EM>$fmt</EM><STRONG>_</STRONG><EM>sub</EM> is used only when the data is
rewindable.
<EM>$types</EM> An array reference to the types of each of the
value columns; used only when <EM>$fmt</EM><STRONG>_</STRONG><EM>sub</EM> is
invoked.
<EM>$showmode</EM> A string indicating the mode of the eventual
display; one of four strings: "<STRONG>box</STRONG>", "<STRONG>table</STRONG>",
"<STRONG>list</STRONG>", and "<STRONG>html</STRONG>". Used to adjust widths for
formatting requirements.
</PRE>
<H2>putcell</H2><PRE>
$<EM>wrapped</EM> = &<STRONG>putcell</STRONG>( \@<EM>cells</EM>, $<EM>c</EM>, $<EM>cell</EM><STRONG>_</STRONG><EM>width</EM>, \@<EM>prefix</EM>,
\@<EM>suffix</EM>, $<EM>wrap</EM><STRONG>_</STRONG><EM>flag</EM> );
Output the contents of an array cell at $<EM>cell</EM>[$<EM>c</EM>], causing
text longer than $<EM>cell</EM><STRONG>_</STRONG><EM>width</EM> to be saved for output on
subsequent calls. Prefixing the output of each cell's
value is a string from the two-element array @<EM>prefix</EM>.
Suffixing each cell's value is a string from the two-
element array @<EM>suffix</EM>. The first element of either array
is selected when $<EM>wrap</EM><STRONG>_</STRONG><EM>flag</EM> is zero or null, or when there
is no more text in the current to be output. The second
element is selected when $<EM>wrap</EM><STRONG>_</STRONG><EM>flag</EM> is non-zero, and when
there is more text in the current cell to be output.
In the case of text longer than $<EM>cell</EM><STRONG>_</STRONG><EM>width</EM>, a non-zero
value is returned.
Cells with undefined data are not output, nor are the
prefix or suffix strings.
</PRE>
<H2>center</H2><PRE>
Center a string within a given width.
$<EM>field</EM> = <STRONG>center</STRONG> $<EM>string</EM>, $<EM>width</EM>;
</PRE>
<H2>max</H2><PRE>
Compute the maximum value from a list of values.
$<EM>max</EM> = &<STRONG>max</STRONG>( @<EM>values</EM> );
</PRE>
<H2>min</H2><PRE>
</PRE>
<H2>max_length</H2><PRE>
Compute the maximum length of a set of strings in an array
reference.
$<EM>maxlength</EM> = &<STRONG>max_length</STRONG>( \@<EM>array</EM><STRONG>_</STRONG><EM>ref</EM> );
</PRE>
<H2>htmltext</H2><PRE>
Translate regular text for output into an HTML document.
This means certain characters, such as "&", ">", and "<"
must be escaped.
$<EM>output</EM> = &<STRONG>htmltext</STRONG>( $<EM>input</EM> );
</PRE>
<H2>AUTHOR</H2><PRE>
Alan K. Stebbens <aks@sgi.com>
</PRE>
</BODY>
</HTML>
|
