local-lib5/man/man3/Template::Plugin::Directory.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::Directory 3"
 132 .TH Template::Plugin::Directory 3 "2008-11-13" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Template::Plugin::Directory \- Plugin for generating directory listings
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 1
 138 \&    [% USE dir = Directory(dirpath) %]
 139 .Ve
 140 .PP
 141 .Vb 4
 142 \&    # files returns list of regular files
 143 \&    [% FOREACH file = dir.files %]
 144 \&       [% file.name %] [% file.path %] ...
 145 \&    [% END %]
 146 .Ve
 147 .PP
 148 .Vb 4
 149 \&    # dirs returns list of sub\-directories
 150 \&    [% FOREACH subdir = dir.dirs %]
 151 \&       [% subdir.name %] [% subdir.path %] ...
 152 \&    [% END %]
 153 .Ve
 154 .PP
 155 .Vb 8
 156 \&    # list returns both interleaved in order
 157 \&    [% FOREACH item = dir.list %]
 158 \&       [% IF item.isdir %]
 159 \&          Directory: [% item.name %]
 160 \&       [% ELSE %]
 161 \&          File: [% item.name %]
 162 \&       [% END %]
 163 \&    [% END %]
 164 .Ve
 165 .PP
 166 .Vb 5
 167 \&    # define a VIEW to display dirs/files
 168 \&    [% VIEW myview %]
 169 \&       [% BLOCK file %]
 170 \&       File: [% item.name %]
 171 \&       [% END %]
 172 .Ve
 173 .PP
 174 .Vb 5
 175 \&       [% BLOCK directory %]
 176 \&       Directory: [% item.name %]
 177 \&       [% item.content(myview) | indent \-%]
 178 \&       [% END %]
 179 \&    [% END %]
 180 .Ve
 181 .PP
 182 .Vb 2
 183 \&    # display directory content using view
 184 \&    [% myview.print(dir) %]
 185 .Ve
 186 .SH "DESCRIPTION"
 187 .IX Header "DESCRIPTION"
 188 This Template Toolkit plugin provides a simple interface to directory
 189 listings.  It is derived from the Template::Plugin::File module and
 190 uses Template::Plugin::File object instances to represent files within
 191 a directory.  Sub-directories within a directory are represented by
 192 further \f(CW\*(C`Template::Plugin::Directory\*(C'\fR instances.
 193 .PP
 194 The constructor expects a directory name as an argument.
 195 .PP
 196 .Vb 1
 197 \&    [% USE dir = Directory('/tmp') %]
 198 .Ve
 199 .PP
 200 It then provides access to the files and sub-directories contained within
 201 the directory.
 202 .PP
 203 .Vb 4
 204 \&    # regular files (not directories)
 205 \&    [% FOREACH file IN dir.files %]
 206 \&       [% file.name %]
 207 \&    [% END %]
 208 .Ve
 209 .PP
 210 .Vb 4
 211 \&    # directories only
 212 \&    [% FOREACH file IN dir.dirs %]
 213 \&       [% file.name %]
 214 \&    [% END %]
 215 .Ve
 216 .PP
 217 .Vb 4
 218 \&    # files and/or directories
 219 \&    [% FOREACH file IN dir.list %]
 220 \&       [% file.name %] ([% file.isdir ? 'directory' : 'file' %])
 221 \&    [% END %]
 222 .Ve
 223 .PP
 224 The plugin constructor will throw a \f(CW\*(C`Directory\*(C'\fR error if the specified
 225 path does not exist, is not a directory or fails to \f(CW\*(C`stat()\*(C'\fR (see
 226 Template::Plugin::File).  Otherwise, it will scan the directory and
 227 create lists named '\f(CW\*(C`files\*(C'\fR' containing files, '\f(CW\*(C`dirs\*(C'\fR' containing
 228 directories and '\f(CW\*(C`list\*(C'\fR' containing both files and directories combined.
 229 The \f(CW\*(C`nostat\*(C'\fR option can be set to disable all file/directory checks
 230 and directory scanning.
 231 .PP
 232 Each file in the directory will be represented by a
 233 Template::Plugin::File object instance, and each directory by another
 234 \&\f(CW\*(C`Template::Plugin::Directory\*(C'\fR.  If the \f(CW\*(C`recurse\*(C'\fR flag is set, then those
 235 directories will contain further nested entries, and so on.  With the
 236 \&\f(CW\*(C`recurse\*(C'\fR flag unset, as it is by default, then each is just a place
 237 marker for the directory and does not contain any further content
 238 unless its \f(CW\*(C`scan()\*(C'\fR method is explicitly called.  The \f(CW\*(C`isdir\*(C'\fR flag can
 239 be tested against files and/or directories, returning true if the item
 240 is a directory or false if it is a regular file.
 241 .PP
 242 .Vb 7
 243 \&    [% FOREACH file = dir.list %]
 244 \&       [% IF file.isdir %]
 245 \&          * Directory: [% file.name %]
 246 \&       [% ELSE %]
 247 \&          * File: [% file.name %]
 248 \&       [% END %]
 249 \&    [% END %]
 250 .Ve
 251 .PP
 252 This example shows how you might walk down a directory tree, displaying
 253 content as you go.  With the recurse flag disabled, as is the default,
 254 we need to explicitly call the \f(CW\*(C`scan()\*(C'\fR method on each directory, to force
 255 it to lookup files and further sub-directories contained within.
 256 .PP
 257 .Vb 3
 258 \&    [% USE dir = Directory(dirpath) %]
 259 \&    * [% dir.path %]
 260 \&    [% INCLUDE showdir %]
 261 .Ve
 262 .PP
 263 .Vb 11
 264 \&    [% BLOCK showdir \-%]
 265 \&      [% FOREACH file = dir.list \-%]
 266 \&        [% IF file.isdir \-%]
 267 \&        * [% file.name %]
 268 \&          [% file.scan \-%]
 269 \&          [% INCLUDE showdir dir=file FILTER indent(4) \-%]
 270 \&        [% ELSE \-%]
 271 \&        \- [% f.name %]
 272 \&        [% END \-%]
 273 \&      [% END \-%]
 274 \&     [% END %]
 275 .Ve
 276 .PP
 277 This example is adapted (with some re-formatting for clarity) from
 278 a test in \fIt/directry.t\fR which produces the following output:
 279 .PP
 280 .Vb 10
 281 \&    * test/dir
 282 \&        \- file1
 283 \&        \- file2
 284 \&        * sub_one
 285 \&            \- bar
 286 \&            \- foo
 287 \&        * sub_two
 288 \&            \- waz.html
 289 \&            \- wiz.html
 290 \&        \- xyzfile
 291 .Ve
 292 .PP
 293 The \f(CW\*(C`recurse\*(C'\fR flag can be set (disabled by default) to cause the
 294 constructor to automatically recurse down into all sub\-directories,
 295 creating a new \f(CW\*(C`Template::Plugin::Directory\*(C'\fR object for each one and
 296 filling it with any further content.  In this case there is no need
 297 to explicitly call the \f(CW\*(C`scan()\*(C'\fR method.
 298 .PP
 299 .Vb 2
 300 \&    [% USE dir = Directory(dirpath, recurse=1) %]
 301 \&       ...
 302 .Ve
 303 .PP
 304 .Vb 5
 305 \&        [% IF file.isdir \-%]
 306 \&        * [% file.name %]
 307 \&          [% INCLUDE showdir dir=file FILTER indent(4) \-%]
 308 \&        [% ELSE \-%]
 309 \&           ...
 310 .Ve
 311 .PP
 312 The directory plugin also provides support for views. A view can be defined as
 313 a \f(CW\*(C`VIEW ... END\*(C'\fR block and should contain \f(CW\*(C`BLOCK\*(C'\fR definitions for files
 314 ('\f(CW\*(C`file\*(C'\fR') and directories ('\f(CW\*(C`directory\*(C'\fR').
 315 .PP
 316 .Vb 4
 317 \&    [% VIEW myview %]
 318 \&    [% BLOCK file %]
 319 \&       \- [% item.name %]
 320 \&    [% END %]
 321 .Ve
 322 .PP
 323 .Vb 5
 324 \&    [% BLOCK directory %]
 325 \&       * [% item.name %]
 326 \&         [% item.content(myview) FILTER indent %]
 327 \&    [% END %]
 328 \&    [% END %]
 329 .Ve
 330 .PP
 331 The view \f(CW\*(C`print()\*(C'\fR method can then be called, passing the
 332 \&\f(CW\*(C`Directory\*(C'\fR object as an argument.
 333 .PP
 334 .Vb 2
 335 \&    [% USE dir = Directory(dirpath, recurse=1) %]
 336 \&    [% myview.print(dir) %]
 337 .Ve
 338 .PP
 339 When a directory is presented to a view, either as \f(CW\*(C`[% myview.print(dir) %]\*(C'\fR
 340 or \f(CW\*(C`[% dir.present(view) %]\*(C'\fR, then the \f(CW\*(C`directory\*(C'\fR \f(CW\*(C`BLOCK\*(C'\fR within the
 341 \&\f(CW\*(C`myview\*(C'\fR \f(CW\*(C`VIEW\*(C'\fR is processed. The \f(CW\*(C`item\*(C'\fR variable will be set to alias the
 342 \&\f(CW\*(C`Directory\*(C'\fR object.
 343 .PP
 344 .Vb 4
 345 \&    [% BLOCK directory %]
 346 \&       * [% item.name %]
 347 \&         [% item.content(myview) FILTER indent %]
 348 \&    [% END %]
 349 .Ve
 350 .PP
 351 In this example, the directory name is first printed and the content(view)
 352 method is then called to present each item within the directory to the view.
 353 Further directories will be mapped to the \f(CW\*(C`directory\*(C'\fR block, and files will be
 354 mapped to the \f(CW\*(C`file\*(C'\fR block.
 355 .PP
 356 With the recurse option disabled, as it is by default, the \f(CW\*(C`directory\*(C'\fR
 357 block should explicitly call a \f(CW\*(C`scan()\*(C'\fR on each directory.
 358 .PP
 359 .Vb 4
 360 \&    [% VIEW myview %]
 361 \&    [% BLOCK file %]
 362 \&       \- [% item.name %]
 363 \&    [% END %]
 364 .Ve
 365 .PP
 366 .Vb 6
 367 \&    [% BLOCK directory %]
 368 \&       * [% item.name %]
 369 \&         [% item.scan %]
 370 \&         [% item.content(myview) FILTER indent %]
 371 \&    [% END %]
 372 \&    [% END %]
 373 .Ve
 374 .PP
 375 .Vb 2
 376 \&    [% USE dir = Directory(dirpath) %]
 377 \&    [% myview.print(dir) %]
 378 .Ve
 379 .SH "AUTHORS"
 380 .IX Header "AUTHORS"
 381 Michael Stevens wrote the original Directory plugin on which this is based.
 382 Andy Wardley split it into separate File and
 383 Directory plugins, added some extra code and
 384 documentation for \f(CW\*(C`VIEW\*(C'\fR support, and made a few other minor tweaks.
 385 .SH "COPYRIGHT"
 386 .IX Header "COPYRIGHT"
 387 Copyright (C) 2000\-2007 Michael Stevens, Andy Wardley.
 388 .PP
 389 This module is free software; you can redistribute it and/or
 390 modify it under the same terms as Perl itself.
 391 .SH "SEE ALSO"
 392 .IX Header "SEE ALSO"
 393 Template::Plugin, Template::Plugin::File, Template::View