local-lib5/man/man3/Template::Plugin::Table.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "Template::Plugin::Table 3"
 132 .TH Template::Plugin::Table 3 "2009-05-20" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Template::Plugin::Table \- Plugin to present data in a table
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 1
 138 \&    [% USE table(list, rows=n, cols=n, overlap=n, pad=0) %]
 139 .Ve
 140 .PP
 141 .Vb 3
 142 \&    [% FOREACH item IN table.row(n) %]
 143 \&       [% item %]
 144 \&    [% END %]
 145 .Ve
 146 .PP
 147 .Vb 3
 148 \&    [% FOREACH item IN table.col(n) %]
 149 \&       [% item %]
 150 \&    [% END %]
 151 .Ve
 152 .PP
 153 .Vb 5
 154 \&    [% FOREACH row IN table.rows %]
 155 \&       [% FOREACH item IN row %]
 156 \&          [% item %]
 157 \&       [% END %]
 158 \&    [% END %]
 159 .Ve
 160 .PP
 161 .Vb 3
 162 \&    [% FOREACH col IN table.cols %]
 163 \&       [% col.first %] \- [% col.last %] ([% col.size %] entries)
 164 \&    [% END %]
 165 .Ve
 166 .SH "DESCRIPTION"
 167 .IX Header "DESCRIPTION"
 168 The \f(CW\*(C`Table\*(C'\fR plugin allows you to format a list of data items into a
 169 virtual table.  When you create a \f(CW\*(C`Table\*(C'\fR plugin via the \f(CW\*(C`USE\*(C'\fR directive,
 170 simply pass a list reference as the first parameter and then specify
 171 a fixed number of rows or columns.
 172 .PP
 173 .Vb 2
 174 \&    [% USE Table(list, rows=5) %]
 175 \&    [% USE table(list, cols=5) %]
 176 .Ve
 177 .PP
 178 The \f(CW\*(C`Table\*(C'\fR plugin name can also be specified in lower case as shown
 179 in the second example above.  You can also specify an alternative variable
 180 name for the plugin as per regular Template Toolkit syntax.
 181 .PP
 182 .Vb 1
 183 \&    [% USE mydata = table(list, rows=5) %]
 184 .Ve
 185 .PP
 186 The plugin then presents a table based view on the data set.  The data
 187 isn't actually reorganised in any way but is available via the \f(CW\*(C`row()\*(C'\fR,
 188 \&\f(CW\*(C`col()\*(C'\fR, \f(CW\*(C`rows()\*(C'\fR and \f(CW\*(C`cols()\*(C'\fR as if formatted into a simple two dimensional
 189 table of \f(CW\*(C`n\*(C'\fR rows x \f(CW\*(C`n\*(C'\fR columns.
 190 .PP
 191 So if we had a sample \f(CW\*(C`alphabet\*(C'\fR list contained the letters '\f(CW\*(C`a\*(C'\fR' to '\f(CW\*(C`z\*(C'\fR',
 192 the above \f(CW\*(C`USE\*(C'\fR directives would create plugins that represented the following
 193 views of the alphabet.
 194 .PP
 195 .Vb 1
 196 \&    [% USE table(alphabet, ... %]
 197 .Ve
 198 .PP
 199 .Vb 7
 200 \&    rows=5                  cols=5
 201 \&    a  f  k  p  u  z        a  g  m  s  y
 202 \&    b  g  l  q  v           b  h  n  t  z
 203 \&    c  h  m  r  w           c  i  o  u
 204 \&    d  i  n  s  x           d  j  p  v
 205 \&    e  j  o  t  y           e  k  q  w
 206 \&                            f  l  r  x
 207 .Ve
 208 .PP
 209 We can request a particular row or column using the \f(CW\*(C`row()\*(C'\fR and \f(CW\*(C`col()\*(C'\fR
 210 methods.
 211 .PP
 212 .Vb 4
 213 \&    [% USE table(alphabet, rows=5) %]
 214 \&    [% FOREACH item = table.row(0) %]
 215 \&       # [% item %] set to each of [ a f k p u z ] in turn
 216 \&    [% END %]
 217 .Ve
 218 .PP
 219 .Vb 3
 220 \&    [% FOREACH item = table.col(2) %]
 221 \&       # [% item %] set to each of [ m n o p q r ] in turn
 222 \&    [% END %]
 223 .Ve
 224 .PP
 225 Data in rows is returned from left to right, columns from top to
 226 bottom.  The first row/column is 0.  By default, rows or columns that
 227 contain empty values will be padded with the undefined value to fill
 228 it to the same size as all other rows or columns.
 229 .PP
 230 For example, the last row (row 4) in the first example would contain the
 231 values \f(CW\*(C`[ e j o t y undef ]\*(C'\fR. The Template Toolkit will safely accept these
 232 undefined values and print a empty string. You can also use the \s-1IF\s0 directive
 233 to test if the value is set.
 234 .PP
 235 .Vb 5
 236 \&   [% FOREACH item = table.row(4) %]
 237 \&      [% IF item %]
 238 \&         Item: [% item %]
 239 \&      [% END %]
 240 \&   [% END %]
 241 .Ve
 242 .PP
 243 You can explicitly disable the \f(CW\*(C`pad\*(C'\fR option when creating the plugin to
 244 returned shortened rows/columns where the data is empty.
 245 .PP
 246 .Vb 4
 247 \&   [% USE table(alphabet, cols=5, pad=0) %]
 248 \&   [% FOREACH item = table.col(4) %]
 249 \&      # [% item %] set to each of 'y z'
 250 \&   [% END %]
 251 .Ve
 252 .PP
 253 The \f(CW\*(C`rows()\*(C'\fR method returns all rows/columns in the table as a reference
 254 to a list of rows (themselves list references).  The \f(CW\*(C`row()\*(C'\fR methods
 255 when called without any arguments calls \f(CW\*(C`rows()\*(C'\fR to return all rows in
 256 the table.
 257 .PP
 258 Ditto for \f(CW\*(C`cols()\*(C'\fR and \f(CW\*(C`col()\*(C'\fR.
 259 .PP
 260 .Vb 6
 261 \&    [% USE table(alphabet, cols=5) %]
 262 \&    [% FOREACH row = table.rows %]
 263 \&       [% FOREACH item = row %]
 264 \&          [% item %]
 265 \&       [% END %]
 266 \&    [% END %]
 267 .Ve
 268 .PP
 269 The Template Toolkit provides the \f(CW\*(C`first\*(C'\fR, \f(CW\*(C`last\*(C'\fR and \f(CW\*(C`size\*(C'\fR virtual
 270 methods that can be called on list references to return the first/last entry
 271 or the number of entries in a list. The following example shows how we might
 272 use this to provide an alphabetical index split into 3 even parts.
 273 .PP
 274 .Vb 4
 275 \&    [% USE table(alphabet, cols=3, pad=0) %]
 276 \&    [% FOREACH group = table.col %]
 277 \&       [ [% group.first %] \- [% group.last %] ([% group.size %] letters) ]
 278 \&    [% END %]
 279 .Ve
 280 .PP
 281 This produces the following output:
 282 .PP
 283 .Vb 3
 284 \&    [ a \- i (9 letters) ]
 285 \&    [ j \- r (9 letters) ]
 286 \&    [ s \- z (8 letters) ]
 287 .Ve
 288 .PP
 289 We can also use the general purpose \f(CW\*(C`join\*(C'\fR virtual method which joins
 290 the items of the list using the connecting string specified.
 291 .PP
 292 .Vb 4
 293 \&    [% USE table(alphabet, cols=5) %]
 294 \&    [% FOREACH row = table.rows %]
 295 \&       [% row.join(' \- ') %]
 296 \&    [% END %]
 297 .Ve
 298 .PP
 299 Data in the table is ordered downwards rather than across but can easily
 300 be transformed on output.  For example, to format our data in 5 columns
 301 with data ordered across rather than down, we specify \f(CW\*(C`rows=5\*(C'\fR to order
 302 the data as such:
 303 .PP
 304 .Vb 5
 305 \&    a  f  .  .
 306 \&    b  g  .
 307 \&    c  h
 308 \&    d  i
 309 \&    e  j
 310 .Ve
 311 .PP
 312 and then iterate down through each column (a\-e, f\-j, etc.) printing
 313 the data across.
 314 .PP
 315 .Vb 4
 316 \&    a  b  c  d  e
 317 \&    f  g  h  i  j
 318 \&    .  .
 319 \&    .
 320 .Ve
 321 .PP
 322 Example code to do so would be much like the following:
 323 .PP
 324 .Vb 6
 325 \&    [% USE table(alphabet, rows=3) %]
 326 \&    [% FOREACH cols = table.cols %]
 327 \&      [% FOREACH item = cols %]
 328 \&        [% item %]
 329 \&      [% END %]
 330 \&    [% END %]
 331 .Ve
 332 .PP
 333 Output:
 334 .PP
 335 .Vb 5
 336 \&    a  b  c
 337 \&    d  e  f
 338 \&    g  h  i
 339 \&    j  .  .
 340 \&    .
 341 .Ve
 342 .PP
 343 In addition to a list reference, the \f(CW\*(C`Table\*(C'\fR plugin constructor may be passed
 344 a reference to a Template::Iterator object or subclass thereof. The
 345 Template::Iterator \fIget_all()\fR method is
 346 first called on the iterator to return all remaining items. These are then
 347 available via the usual Table interface.
 348 .PP
 349 .Vb 1
 350 \&    [% USE DBI(dsn,user,pass) \-%]
 351 .Ve
 352 .PP
 353 .Vb 2
 354 \&    # query() returns an iterator
 355 \&    [% results = DBI.query('SELECT * FROM alphabet ORDER BY letter') %]
 356 .Ve
 357 .PP
 358 .Vb 2
 359 \&    # pass into Table plugin
 360 \&    [% USE table(results, rows=8 overlap=1 pad=0) \-%]
 361 .Ve
 362 .PP
 363 .Vb 4
 364 \&    [% FOREACH row = table.cols \-%]
 365 \&       [% row.first.letter %] \- [% row.last.letter %]:
 366 \&          [% row.join(', ') %]
 367 \&    [% END %]
 368 .Ve
 369 .SH "AUTHOR"
 370 .IX Header "AUTHOR"
 371 Andy Wardley <abw@wardley.org> <http://wardley.org/>
 372 .SH "COPYRIGHT"
 373 .IX Header "COPYRIGHT"
 374 Copyright (C) 1996\-2007 Andy Wardley.  All Rights Reserved.
 375 .PP
 376 This module is free software; you can redistribute it and/or
 377 modify it under the same terms as Perl itself.
 378 .SH "SEE ALSO"
 379 .IX Header "SEE ALSO"
 380 Template::Plugin