Template::Plugin::File(3pm)

1Template::Plugin::File(U3s)er Contributed Perl DocumentatTieomnplate::Plugin::File(3)
2
3
4

NAME

6       Template::Plugin::File - Plugin providing information about files
7

SYNOPSIS

9           [% USE File(filepath) %]
10           [% File.path %]         # full path
11           [% File.name %]         # filename
12           [% File.dir %]          # directory
13

DESCRIPTION

15       This plugin provides an abstraction of a file.  It can be used to fetch
16       details about files from the file system, or to represent abstract
17       files (e.g. when creating an index page) that may or may not exist on a
18       file system.
19
20       A file name or path should be specified as a constructor argument.
21       e.g.
22
23           [% USE File('foo.html') %]
24           [% USE File('foo/bar/baz.html') %]
25           [% USE File('/foo/bar/baz.html') %]
26
27       The file should exist on the current file system (unless 'nostat'
28       option set, see below) as an absolute file when specified with as lead‐
29       ing '/' as per '/foo/bar/baz.html', or otherwise as one relative to the
30       current working directory.  The constructor performs a stat() on the
31       file and makes the 13 elements returned available as the plugin items:
32
33           dev ino mode nlink uid gid rdev size
34           atime mtime ctime blksize blocks
35
36       e.g.
37
38           [% USE File('/foo/bar/baz.html') %]
39
40           [% File.mtime %]
41           [% File.mode %]
42           ...
43
44       In addition, the 'user' and 'group' items are set to contain the user
45       and group names as returned by calls to getpwuid() and getgrgid() for
46       the file 'uid' and 'gid' elements, respectively.  On Win32 platforms on
47       which getpwuid() and getgrid() are not available, these values are
48       undefined.
49
50           [% USE File('/tmp/foo.html') %]
51           [% File.uid %]      # e.g. 500
52           [% File.user %]     # e.g. abw
53
54       This user/group lookup can be disabled by setting the 'noid' option.
55
56           [% USE File('/tmp/foo.html', noid=1) %]
57           [% File.uid %]      # e.g. 500
58           [% File.user %]     # nothing
59
60       The 'isdir' flag will be set if the file is a directory.
61
62           [% USE File('/tmp') %]
63           [% File.isdir %]    # 1
64
65       If the stat() on the file fails (e.g. file doesn't exists, bad permis‐
66       sion, etc) then the constructor will throw a 'File' exception.  This
67       can be caught within a TRY...CATCH block.
68
69           [% TRY %]
70              [% USE File('/tmp/myfile') %]
71              File exists!
72           [% CATCH File %]
73              File error: [% error.info %]
74           [% END %]
75
76       Note the capitalisation of the exception type, 'File' to indicate an
77       error thrown by the 'File' plugin, to distinguish it from a regular
78       'file' exception thrown by the Template Toolkit.
79
80       Note that the 'File' plugin can also be referenced by the lower case
81       name 'file'.  However, exceptions are always thrown of the 'File' type,
82       regardless of the capitalisation of the plugin named used.
83
84           [% USE file('foo.html') %]
85           [% file.mtime %]
86
87       As with any other Template Toolkit plugin, an alternate name can be
88       specified for the object created.
89
90           [% USE foo = file('foo.html') %]
91           [% foo.mtime %]
92
93       The 'nostat' option can be specified to prevent the plugin constructor
94       from performing a stat() on the file specified.  In this case, the file
95       does not have to exist in the file system, no attempt will be made to
96       verify that it does, and no error will be thrown if it doesn't.  The
97       entries for the items usually returned by stat() will be set empty.
98
99           [% USE file('/some/where/over/the/rainbow.html', nostat=1)
100           [% file.mtime %]     # nothing
101
102       All File plugins, regardless of the nostat option, have set a number of
103       items relating to the original path specified.
104
105       path
106           The full, original file path specified to the constructor.
107
108               [% USE file('/foo/bar.html') %]
109               [% file.path %]     # /foo/bar.html
110
111       name
112           The name of the file without any leading directories.
113
114               [% USE file('/foo/bar.html') %]
115               [% file.name %]     # bar.html
116
117       dir The directory element of the path with the filename removed.
118
119               [% USE file('/foo/bar.html') %]
120               [% file.name %]     # /foo
121
122       ext The file extension, if any, appearing at the end of the path fol‐
123           lowing a '.' (not included in the extension).
124
125               [% USE file('/foo/bar.html') %]
126               [% file.ext %]      # html
127
128       home
129           This contains a string of the form '../..' to represent the upward
130           path from a file to its root directory.
131
132               [% USE file('bar.html') %]
133               [% file.home %]     # nothing
134
135               [% USE file('foo/bar.html') %]
136               [% file.home %]     # ..
137
138               [% USE file('foo/bar/baz.html') %]
139               [% file.home %]     # ../..
140
141       root
142           The 'root' item can be specified as a constructor argument, indi‐
143           cating a root directory in which the named file resides.  This is
144           otherwise set empty.
145
146               [% USE file('foo/bar.html', root='/tmp') %]
147               [% file.root %]     # /tmp
148
149       abs This returns the absolute file path by constructing a path from the
150           'root' and 'path' options.
151
152               [% USE file('foo/bar.html', root='/tmp') %]
153               [% file.path %]     # foo/bar.html
154               [% file.root %]     # /tmp
155               [% file.abs %]      # /tmp/foo/bar.html
156
157       In addition, the following method is provided:
158
159       rel(path)
160           This returns a relative path from the current file to another path
161           specified as an argument.  It is constructed by appending the path
162           to the 'home' item.
163
164               [% USE file('foo/bar/baz.html') %]
165               [% file.rel('wiz/waz.html') %]      # ../../wiz/waz.html
166

EXAMPLES

168           [% USE file('/foo/bar/baz.html') %]
169
170           [% file.path  %]      # /foo/bar/baz.html
171           [% file.dir   %]      # /foo/bar
172           [% file.name  %]      # baz.html
173           [% file.home  %]      # ../..
174           [% file.root  %]      # ''
175           [% file.abs   %]      # /foo/bar/baz.html
176           [% file.ext   %]      # html
177           [% file.mtime %]      # 987654321
178           [% file.atime %]      # 987654321
179           [% file.uid   %]      # 500
180           [% file.user  %]      # abw
181
182           [% USE file('foo.html') %]
183
184           [% file.path %]           # foo.html
185           [% file.dir  %]       # ''
186           [% file.name %]           # foo.html
187           [% file.root %]       # ''
188           [% file.home %]       # ''
189           [% file.abs  %]       # foo.html
190
191           [% USE file('foo/bar/baz.html') %]
192
193           [% file.path %]           # foo/bar/baz.html
194           [% file.dir  %]       # foo/bar
195           [% file.name %]           # baz.html
196           [% file.root %]       # ''
197           [% file.home %]       # ../..
198           [% file.abs  %]       # foo/bar/baz.html
199
200           [% USE file('foo/bar/baz.html', root='/tmp') %]
201
202           [% file.path %]           # foo/bar/baz.html
203           [% file.dir  %]       # foo/bar
204           [% file.name %]           # baz.html
205           [% file.root %]       # /tmp
206           [% file.home %]       # ../..
207           [% file.abs  %]       # /tmp/foo/bar/baz.html
208
209           # calculate other file paths relative to this file and its root
210           [% USE file('foo/bar/baz.html', root => '/tmp/tt2') %]
211
212           [% file.path('baz/qux.html') %]         # ../../baz/qux.html
213           [% file.dir('wiz/woz.html')  %]     # ../../wiz/woz.html
214

AUTHORS

216       Michael Stevens <michael@etla.org> wrote the original Directory plugin
217       on which this is based.  Andy Wardley <abw@wardley.org> split it into
218       separate File and Directory plugins, added some extra code and documen‐
219       tation for VIEW support, and made a few other minor tweaks.
220

VERSION

222       2.71, distributed as part of the Template Toolkit version 2.18,
223       released on 09 February 2007.
224

COPYRIGHT

226       This module is free software; you can redistribute it and/or modify it
227       under the same terms as Perl itself.
228