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
29       leading '"/"' as per '"/foo/bar/baz.html"', or otherwise as one
30       relative to the current working directory.  The constructor performs a
31       stat() on the file and makes the 13 elements returned available as the
32       plugin items:
33
34           dev ino mode nlink uid gid rdev size
35           atime mtime ctime blksize blocks
36
37       e.g.
38
39           [% USE File('/foo/bar/baz.html') %]
40
41           [% File.mtime %]
42           [% File.mode %]
43           ...
44
45       In addition, the "user" and "group" items are set to contain the user
46       and group names as returned by calls to getpwuid() and getgrgid() for
47       the file "uid" and "gid" elements, respectively.  On Win32 platforms on
48       which getpwuid() and getgrid() are not available, these values are
49       undefined.
50
51           [% USE File('/tmp/foo.html') %]
52           [% File.uid %]      # e.g. 500
53           [% File.user %]     # e.g. abw
54
55       This user/group lookup can be disabled by setting the "noid" option.
56
57           [% USE File('/tmp/foo.html', noid=1) %]
58           [% File.uid %]      # e.g. 500
59           [% File.user %]     # nothing
60
61       The "isdir" flag will be set if the file is a directory.
62
63           [% USE File('/tmp') %]
64           [% File.isdir %]    # 1
65
66       If the stat() on the file fails (e.g. file doesn't exists, bad
67       permission, etc) then the constructor will throw a "File" exception.
68       This can be caught within a "TRY...CATCH" block.
69
70           [% TRY %]
71              [% USE File('/tmp/myfile') %]
72              File exists!
73           [% CATCH File %]
74              File error: [% error.info %]
75           [% END %]
76
77       Note the capitalisation of the exception type, '"File"', to indicate an
78       error thrown by the "File" plugin, to distinguish it from a regular
79       "file" exception thrown by the Template Toolkit.
80
81       Note that the "File" plugin can also be referenced by the lower case
82       name '"file"'.  However, exceptions are always thrown of the "File"
83       type, regardless of the capitalisation of the plugin named used.
84
85           [% USE file('foo.html') %]
86           [% file.mtime %]
87
88       As with any other Template Toolkit plugin, an alternate name can be
89       specified for the object created.
90
91           [% USE foo = file('foo.html') %]
92           [% foo.mtime %]
93
94       The "nostat" option can be specified to prevent the plugin constructor
95       from performing a stat() on the file specified.  In this case, the file
96       does not have to exist in the file system, no attempt will be made to
97       verify that it does, and no error will be thrown if it doesn't.  The
98       entries for the items usually returned by stat() will be set empty.
99
100           [% USE file('/some/where/over/the/rainbow.html', nostat=1)
101           [% file.mtime %]     # nothing
102

METHODS

104       All "File" plugins, regardless of the "nostat" option, have set a
105       number of items relating to the original path specified.
106
107   path
108       The full, original file path specified to the constructor.
109
110           [% USE file('/foo/bar.html') %]
111           [% file.path %]     # /foo/bar.html
112
113   name
114       The name of the file without any leading directories.
115
116           [% USE file('/foo/bar.html') %]
117           [% file.name %]     # bar.html
118
119   dir
120       The directory element of the path with the filename removed.
121
122           [% USE file('/foo/bar.html') %]
123           [% file.name %]     # /foo
124
125   ext
126       The file extension, if any, appearing at the end of the path following
127       a '"."' (not included in the extension).
128
129           [% USE file('/foo/bar.html') %]
130           [% file.ext %]      # html
131
132   home
133       This contains a string of the form '"../.."' to represent the upward
134       path from a file to its root directory.
135
136           [% USE file('bar.html') %]
137           [% file.home %]     # nothing
138
139           [% USE file('foo/bar.html') %]
140           [% file.home %]     # ..
141
142           [% USE file('foo/bar/baz.html') %]
143           [% file.home %]     # ../..
144
145   root
146       The "root" item can be specified as a constructor argument, indicating
147       a root directory in which the named file resides.  This is otherwise
148       set empty.
149
150           [% USE file('foo/bar.html', root='/tmp') %]
151           [% file.root %]     # /tmp
152
153   abs
154       This returns the absolute file path by constructing a path from the
155       "root" and "path" options.
156
157           [% USE file('foo/bar.html', root='/tmp') %]
158           [% file.path %]     # foo/bar.html
159           [% file.root %]     # /tmp
160           [% file.abs %]      # /tmp/foo/bar.html
161
162   rel(path)
163       This returns a relative path from the current file to another path
164       specified as an argument.  It is constructed by appending the path to
165       the '"home"' item.
166
167           [% USE file('foo/bar/baz.html') %]
168           [% file.rel('wiz/waz.html') %]      # ../../wiz/waz.html
169

EXAMPLES

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

AUTHORS

219       Michael Stevens wrote the original "Directory" plugin on which this is
220       based.  Andy Wardley split it into separate "File" and "Directory"
221       plugins, added some extra code and documentation for "VIEW" support,
222       and made a few other minor tweaks.
223

COPYRIGHT

225       Copyright 2000-2022 Michael Stevens, Andy Wardley.
226
227       This module is free software; you can redistribute it and/or modify it
228       under the same terms as Perl itself.
229