local-lib5/man/man3/Template::Plugin::File.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::File 3"
 132 .TH Template::Plugin::File 3 "2008-11-13" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Template::Plugin::File \- Plugin providing information about files
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 4
 138 \&    [% USE File(filepath) %]
 139 \&    [% File.path %]         # full path
 140 \&    [% File.name %]         # filename
 141 \&    [% File.dir %]          # directory
 142 .Ve
 143 .SH "DESCRIPTION"
 144 .IX Header "DESCRIPTION"
 145 This plugin provides an abstraction of a file.  It can be used to
 146 fetch details about files from the file system, or to represent abstract
 147 files (e.g. when creating an index page) that may or may not exist on
 148 a file system.
 149 .PP
 150 A file name or path should be specified as a constructor argument.  e.g.
 151 .PP
 152 .Vb 3
 153 \&    [% USE File('foo.html') %]
 154 \&    [% USE File('foo/bar/baz.html') %]
 155 \&    [% USE File('/foo/bar/baz.html') %]
 156 .Ve
 157 .PP
 158 The file should exist on the current file system (unless \f(CW\*(C`nostat\*(C'\fR
 159 option set, see below) as an absolute file when specified with as
 160 leading '\f(CW\*(C`/\*(C'\fR' as per '\f(CW\*(C`/foo/bar/baz.html\*(C'\fR', or otherwise as one relative
 161 to the current working directory.  The constructor performs a \f(CW\*(C`stat()\*(C'\fR
 162 on the file and makes the 13 elements returned available as the plugin
 163 items:
 164 .PP
 165 .Vb 2
 166 \&    dev ino mode nlink uid gid rdev size
 167 \&    atime mtime ctime blksize blocks
 168 .Ve
 169 .PP
 170 e.g.
 171 .PP
 172 .Vb 1
 173 \&    [% USE File('/foo/bar/baz.html') %]
 174 .Ve
 175 .PP
 176 .Vb 3
 177 \&    [% File.mtime %]
 178 \&    [% File.mode %]
 179 \&    ...
 180 .Ve
 181 .PP
 182 In addition, the \f(CW\*(C`user\*(C'\fR and \f(CW\*(C`group\*(C'\fR items are set to contain the user
 183 and group names as returned by calls to \f(CW\*(C`getpwuid()\*(C'\fR and \f(CW\*(C`getgrgid()\*(C'\fR for
 184 the file \f(CW\*(C`uid\*(C'\fR and \f(CW\*(C`gid\*(C'\fR elements, respectively.  On Win32 platforms
 185 on which \f(CW\*(C`getpwuid()\*(C'\fR and \f(CW\*(C`getgrid()\*(C'\fR are not available, these values are
 186 undefined.
 187 .PP
 188 .Vb 3
 189 \&    [% USE File('/tmp/foo.html') %]
 190 \&    [% File.uid %]      # e.g. 500
 191 \&    [% File.user %]     # e.g. abw
 192 .Ve
 193 .PP
 194 This user/group lookup can be disabled by setting the \f(CW\*(C`noid\*(C'\fR option.
 195 .PP
 196 .Vb 3
 197 \&    [% USE File('/tmp/foo.html', noid=1) %]
 198 \&    [% File.uid %]      # e.g. 500
 199 \&    [% File.user %]     # nothing
 200 .Ve
 201 .PP
 202 The \f(CW\*(C`isdir\*(C'\fR flag will be set if the file is a directory.
 203 .PP
 204 .Vb 2
 205 \&    [% USE File('/tmp') %]
 206 \&    [% File.isdir %]    # 1
 207 .Ve
 208 .PP
 209 If the \f(CW\*(C`stat()\*(C'\fR on the file fails (e.g. file doesn't exists, bad
 210 permission, etc) then the constructor will throw a \f(CW\*(C`File\*(C'\fR exception.
 211 This can be caught within a \f(CW\*(C`TRY...CATCH\*(C'\fR block.
 212 .PP
 213 .Vb 6
 214 \&    [% TRY %]
 215 \&       [% USE File('/tmp/myfile') %]
 216 \&       File exists!
 217 \&    [% CATCH File %]
 218 \&       File error: [% error.info %]
 219 \&    [% END %]
 220 .Ve
 221 .PP
 222 Note the capitalisation of the exception type, '\f(CW\*(C`File\*(C'\fR', to indicate an
 223 error thrown by the \f(CW\*(C`File\*(C'\fR plugin, to distinguish it from a regular
 224 \&\f(CW\*(C`file\*(C'\fR exception thrown by the Template Toolkit.
 225 .PP
 226 Note that the \f(CW\*(C`File\*(C'\fR plugin can also be referenced by the lower case
 227 name '\f(CW\*(C`file\*(C'\fR'.  However, exceptions are always thrown of the \f(CW\*(C`File\*(C'\fR
 228 type, regardless of the capitalisation of the plugin named used.
 229 .PP
 230 .Vb 2
 231 \&    [% USE file('foo.html') %]
 232 \&    [% file.mtime %]
 233 .Ve
 234 .PP
 235 As with any other Template Toolkit plugin, an alternate name can be
 236 specified for the object created.
 237 .PP
 238 .Vb 2
 239 \&    [% USE foo = file('foo.html') %]
 240 \&    [% foo.mtime %]
 241 .Ve
 242 .PP
 243 The \f(CW\*(C`nostat\*(C'\fR option can be specified to prevent the plugin constructor
 244 from performing a \f(CW\*(C`stat()\*(C'\fR on the file specified.  In this case, the
 245 file does not have to exist in the file system, no attempt will be made
 246 to verify that it does, and no error will be thrown if it doesn't.
 247 The entries for the items usually returned by \f(CW\*(C`stat()\*(C'\fR will be set
 248 empty.
 249 .PP
 250 .Vb 2
 251 \&    [% USE file('/some/where/over/the/rainbow.html', nostat=1)
 252 \&    [% file.mtime %]     # nothing
 253 .Ve
 254 .SH "METHODS"
 255 .IX Header "METHODS"
 256 All \f(CW\*(C`File\*(C'\fR plugins, regardless of the \f(CW\*(C`nostat\*(C'\fR option, have set a number
 257 of items relating to the original path specified.
 258 .Sh "path"
 259 .IX Subsection "path"
 260 The full, original file path specified to the constructor.
 261 .PP
 262 .Vb 2
 263 \&    [% USE file('/foo/bar.html') %]
 264 \&    [% file.path %]     # /foo/bar.html
 265 .Ve
 266 .Sh "name"
 267 .IX Subsection "name"
 268 The name of the file without any leading directories.
 269 .PP
 270 .Vb 2
 271 \&    [% USE file('/foo/bar.html') %]
 272 \&    [% file.name %]     # bar.html
 273 .Ve
 274 .Sh "dir"
 275 .IX Subsection "dir"
 276 The directory element of the path with the filename removed.
 277 .PP
 278 .Vb 2
 279 \&    [% USE file('/foo/bar.html') %]
 280 \&    [% file.name %]     # /foo
 281 .Ve
 282 .Sh "ext"
 283 .IX Subsection "ext"
 284 The file extension, if any, appearing at the end of the path following
 285 a '\f(CW\*(C`.\*(C'\fR' (not included in the extension).
 286 .PP
 287 .Vb 2
 288 \&    [% USE file('/foo/bar.html') %]
 289 \&    [% file.ext %]      # html
 290 .Ve
 291 .Sh "home"
 292 .IX Subsection "home"
 293 This contains a string of the form '\f(CW\*(C`../..\*(C'\fR' to represent the upward path
 294 from a file to its root directory.
 295 .PP
 296 .Vb 2
 297 \&    [% USE file('bar.html') %]
 298 \&    [% file.home %]     # nothing
 299 .Ve
 300 .PP
 301 .Vb 2
 302 \&    [% USE file('foo/bar.html') %]
 303 \&    [% file.home %]     # ..
 304 .Ve
 305 .PP
 306 .Vb 2
 307 \&    [% USE file('foo/bar/baz.html') %]
 308 \&    [% file.home %]     # ../..
 309 .Ve
 310 .Sh "root"
 311 .IX Subsection "root"
 312 The \f(CW\*(C`root\*(C'\fR item can be specified as a constructor argument, indicating
 313 a root directory in which the named file resides.  This is otherwise
 314 set empty.
 315 .PP
 316 .Vb 2
 317 \&    [% USE file('foo/bar.html', root='/tmp') %]
 318 \&    [% file.root %]     # /tmp
 319 .Ve
 320 .Sh "abs"
 321 .IX Subsection "abs"
 322 This returns the absolute file path by constructing a path from the
 323 \&\f(CW\*(C`root\*(C'\fR and \f(CW\*(C`path\*(C'\fR options.
 324 .PP
 325 .Vb 4
 326 \&    [% USE file('foo/bar.html', root='/tmp') %]
 327 \&    [% file.path %]     # foo/bar.html
 328 \&    [% file.root %]     # /tmp
 329 \&    [% file.abs %]      # /tmp/foo/bar.html
 330 .Ve
 331 .Sh "rel(path)"
 332 .IX Subsection "rel(path)"
 333 This returns a relative path from the current file to another path specified
 334 as an argument.  It is constructed by appending the path to the '\f(CW\*(C`home\*(C'\fR'
 335 item.
 336 .PP
 337 .Vb 2
 338 \&    [% USE file('foo/bar/baz.html') %]
 339 \&    [% file.rel('wiz/waz.html') %]      # ../../wiz/waz.html
 340 .Ve
 341 .SH "EXAMPLES"
 342 .IX Header "EXAMPLES"
 343 .Vb 1
 344 \&    [% USE file('/foo/bar/baz.html') %]
 345 .Ve
 346 .PP
 347 .Vb 11
 348 \&    [% file.path  %]      # /foo/bar/baz.html
 349 \&    [% file.dir   %]      # /foo/bar
 350 \&    [% file.name  %]      # baz.html
 351 \&    [% file.home  %]      # ../..
 352 \&    [% file.root  %]      # ''
 353 \&    [% file.abs   %]      # /foo/bar/baz.html
 354 \&    [% file.ext   %]      # html
 355 \&    [% file.mtime %]      # 987654321
 356 \&    [% file.atime %]      # 987654321
 357 \&    [% file.uid   %]      # 500
 358 \&    [% file.user  %]      # abw
 359 .Ve
 360 .PP
 361 .Vb 1
 362 \&    [% USE file('foo.html') %]
 363 .Ve
 364 .PP
 365 .Vb 6
 366 \&    [% file.path %]           # foo.html
 367 \&    [% file.dir  %]       # ''
 368 \&    [% file.name %]           # foo.html
 369 \&    [% file.root %]       # ''
 370 \&    [% file.home %]       # ''
 371 \&    [% file.abs  %]       # foo.html
 372 .Ve
 373 .PP
 374 .Vb 1
 375 \&    [% USE file('foo/bar/baz.html') %]
 376 .Ve
 377 .PP
 378 .Vb 6
 379 \&    [% file.path %]           # foo/bar/baz.html
 380 \&    [% file.dir  %]       # foo/bar
 381 \&    [% file.name %]           # baz.html
 382 \&    [% file.root %]       # ''
 383 \&    [% file.home %]       # ../..
 384 \&    [% file.abs  %]       # foo/bar/baz.html
 385 .Ve
 386 .PP
 387 .Vb 1
 388 \&    [% USE file('foo/bar/baz.html', root='/tmp') %]
 389 .Ve
 390 .PP
 391 .Vb 6
 392 \&    [% file.path %]           # foo/bar/baz.html
 393 \&    [% file.dir  %]       # foo/bar
 394 \&    [% file.name %]           # baz.html
 395 \&    [% file.root %]       # /tmp
 396 \&    [% file.home %]       # ../..
 397 \&    [% file.abs  %]       # /tmp/foo/bar/baz.html
 398 .Ve
 399 .PP
 400 .Vb 2
 401 \&    # calculate other file paths relative to this file and its root
 402 \&    [% USE file('foo/bar/baz.html', root => '/tmp/tt2') %]
 403 .Ve
 404 .PP
 405 .Vb 2
 406 \&    [% file.path('baz/qux.html') %]         # ../../baz/qux.html
 407 \&    [% file.dir('wiz/woz.html')  %]     # ../../wiz/woz.html
 408 .Ve
 409 .SH "AUTHORS"
 410 .IX Header "AUTHORS"
 411 Michael Stevens wrote the original \f(CW\*(C`Directory\*(C'\fR plugin on which this is based.
 412 Andy Wardley split it into separate \f(CW\*(C`File\*(C'\fR and \f(CW\*(C`Directory\*(C'\fR plugins, added
 413 some extra code and documentation for \f(CW\*(C`VIEW\*(C'\fR support, and made a few other
 414 minor tweaks.
 415 .SH "COPYRIGHT"
 416 .IX Header "COPYRIGHT"
 417 Copyright 2000\-2007 Michael Stevens, Andy Wardley.
 418 .PP
 419 This module is free software; you can redistribute it and/or
 420 modify it under the same terms as Perl itself.
 421 .SH "SEE ALSO"
 422 .IX Header "SEE ALSO"
 423 Template::Plugin, Template::Plugin::Directory, Template::View