1Padre::File(3) User Contributed Perl Documentation Padre::File(3)
2
6 Padre::File - Common API for file functions
7
9 "Padre::File" provides a common API for file access within Padre. It
10 covers all the differences with non-local files by mapping every
11 function call to the currently used transport stream.
12
14 "RegisterProtocol"
15 Padre::File->RegisterProtocol($RegExp, $Module);
16 Class method, may not be called on an object.
18 A plug-in could call "Padre::File->RegisterProtocol" to register a new
20 protocol to "Padre::File" and enable Padre to use URLs handled by this
21 module.
22 Example:
24 Padre::File->RegisterProtocol('^nfs\:\/\/','Padre::Plugin::NFS');
26 Every file/URL opened through "Padre::File" which starts with "nfs://"
28 is now handled through "Padre::Plugin::NFS". "Padre::File->new()" will
29 respect this and call "Padre::Plugin::NFS->new()" to handle such URLs.
30 Returns true on success or false on error.
32 Registered protocols may override the internal protocols.
34 "DropProtocol"
36 Drops a previously registered protocol handler. First argument must be
37 the same regular expression (matching a protocol from an URI) that was
38 used to register the protocol handler in the first place using
39 "RegisterProtocol". Similarly, the second argument must be the name of
40 the class (module) that the handler was registered for. That means if
41 you registered your protocol with
42 Padre::File->RegisterProtocol(qr/^sftp:\/\//, 'Padre::File::MySFTP');
44 then you need to drop it with
46 Padre::File->DropProtocol(qr/^sftp:\/\//, 'Padre::File::MySFTP');
48 Returns true if a handler was removed and the empty list if no handler
50 was found for the given regular expression.
51 "new"
53 my $file = Padre::File->new($File_or_URL);
54 The "new" constructor lets you create a new "Padre::File" object.
56 Only one parameter is accepted at the moment: The name of the file
58 which should be used. As soon as there are HTTP, FTP, SSH and other
59 modules, also URLs should be accepted.
60 If you know the protocol (which should be true every time you build the
62 URL by source), it's better to call "Padre::File::Protocol->new($URL)"
63 directly (replacing Protocol by the protocol which should be used, of
64 course).
65 The module for the selected protocol should fill "->{filename}"
67 property. This should be used for all further references to the file as
68 it will contain the file name in universal correct format (for example
69 correct the "C:\ eq C:/" problem on Windows).
70 Returns a new "Padre::File" or dies on error.
72 "atime"
74 $file->atime;
75 Returns the last-access time of the file.
77 This is usually not possible for non-local files, in these cases, the
79 empty list is returned.
80 "basename"
82 $file->basename;
83 Returns the plain file name without path if a path/file name structure
85 exists for this module.
86 "blksize"
88 $file->blksize;
89 Returns the block size of the file system where the file resides.
91 This is usually not possible for non-local files, in these cases, the
93 empty list is returned.
94 "blocks"
96 $file->blocks;
97 Returns the number of blocks used by the file.
99 This is usually not possible for non-local files, in these cases, the
101 empty list is returned.
102 "browse_mtime"
104 $file->browse_mtime($path_and_filename);
105 Returns the modification time of the given file on the remote server.
107 Leave out the protocol and server name for remote protocols, for
109 example
110 my $file = Padre::File->new('http://perlide.org/current/foo.html');
112 $file->browse_mtime('/archive/bar.html');
113 This returns the modification time of
115 "http://perlide.org/archive/bar.html"
116 The default uses one "Padre::File" clone per request which is a
118 reasonable fallback but very inefficient! Please add "browse_X" methods
119 to the subclass module whenever possible.
120 "browse_url_join"
122 $file->browse_url_join($server, $path, $basename);
123 Merges a server name, path name and a file name to a complete URL.
125 A "path" in this function is meant to be the local path on the server,
127 not the Padre path (which includes the server name).
128 You may think of
130 /tmp + padre.$$ => /tmp/padre.$$
132 C:\\temp + padre.$$ => C:\\temp\\padre.$$
133 ...but also remember
135 http://perlide.org + about.html => http://perlide.org/about.html
137 Datapoint created a file syntax...
139 common + program/text => program/text:common
141 This could happen once someone adds a "Padre::File::DBCFS" for using a
143 "DB/C FS" file server. "program" is the file name, "text" the extension
144 and "common" is what we call a directory.
145 The most common seems to be a "/" as the directory separator character,
147 so we'll use this as the default.
148 This method should care about merging double "/" to one if this should
150 be done on this file system (even if the default doesn't care).
151 "can_clone"
153 $file->can_clone;
154 Returns true if the protocol allows re-using of connections for new
156 files (usually from the same project).
157 Local files don't use connections at all, HTTP uses one-request-
159 connections, cloning has no benefit for them. FTP and SSH use
160 connections to a remote server and we should work to get no more than
161 one connection per server.
162 "can_run"
164 $file->can_run;
165 Returns true if the protocol allows execution of files or the empty
167 list if it doesn't.
168 This is usually not possible for non-local files (which return true),
170 because there is no way to reproduce a save environment for running a
171 HTTP or FTP based file (they return false).
172 "clone"
174 my $clone = $file->clone($File_or_URL);
175 The "clone" constructor lets you create a new "Padre::File" object
177 reusing an existing connection.
178 Takes the same arguments as the "new" method.
180 If the protocol doesn't know about (server) connections/sessions,
182 returns a brand new Padre::File object.
183 NOTICE: If you request a clone which is located on another server,
185 you'll
186 get a Padre::File object using the original connection to the
187 original server and the original authentication data but the
188 new
189 path and file name!
190 Returns a new "Padre::File" or dies on error.
192 "clone_file"
194 my $clone = $file->clone_file($filename_with_path);
195 my $clone = $file->clone_file($path,$filename);
196 The "clone" constructor lets you create a new "Padre::File" object
198 reusing an existing connection.
199 Takes one or two arguments:
201 either the complete path + file name of an URL
203 or the path and file name as separate arguments
204 If the protocol doesn't know about (server) connections/sessions,
206 returns a brand new "Padre::File" object.
207 Returns a new "Padre::File" or dies on error.
209 "ctime"
211 $file->ctime;
212 Returns the last-change time of the inode (not the file!).
214 This is usually not possible for non-local files, in these cases, the
216 empty list is returned.
217 "dev"
219 $file->dev;
220 Returns the device number of the file system where the file resides.
222 This is usually not possible for non-local files, in these cases, the
224 empty list is returned.
225 "dirname"
227 $file->dirname;
228 Returns the plain path without file name if a path/file name structure
230 exists for this module.
231 Returns the empty list on failure or undefined behaviour for the given
233 protocol.
234 "error"
236 $file->error;
237 Returns the last error message (like $! for system calls).
239 "exists"
241 $file->exists;
242 Returns true if the file exists. Returns false if the file doesn't
244 exist. Returns the empty list if unsure (network problem, not
245 implemented).
246 "filename"
248 $file->filename;
249 Returns the the file name including path handled by this object.
251 Please remember that "Padre::File" is able to open many URL types. This
253 file name may also be a URL. Please use the "basename" and "dirname"
254 methods to split it (assuming that a path exists in the current
255 protocol).
256 "gid"
258 $file->gid;
259 Returns the real group ID of the file group.
261 This is usually not possible for non-local files, in these cases, the
263 empty list is returned.
264 "inode"
266 $file->inode;
267 Returns the inode number of the file.
269 This is usually not possible for non-local files, in these cases, the
271 empty list is returned.
272 "mime"
274 $file->mime;
275 $file->mime('text/plain');
276 Returns or sets the MIME type of the file.
278 "mode"
280 $file->mode;
281 Returns the file mode (type and rights). See also: "stat" in perlfunc.
283 To get the POSIX file permissions as the usual octal number (as opposed
284 to a string) use:
285 use Fcntl ':mode';
287 my $perms_octal = S_IMODE($file->mode);
288 This is usually not possible for non-local files, in these cases, the
290 empty list is returned.
291 "mtime"
293 $file->mtime;
294 Returns the last-modification (change) time of the file.
296 "nlink"
298 $file->nlink;
299 Returns the number of hard links to the file.
301 This is usually not possible for non-local files, in these cases, the
303 empty list is returned.
304 "rdev"
306 $file->rdev;
307 Returns the device identifier.
309 This is usually not possible for non-local files, in these cases, the
311 empty list is returned.
312 "read"
314 $file->read;
315 Reads the file contents and returns them.
317 Returns the empty list on error. The error message can be retrieved
319 using the "error" method.
320 "servername"
322 $file->servername;
323 Returns the server name for this module - if the protocol knows about a
325 server, local files don't.
326 WARNING: The Padre "path" includes the server name in a protocol
328 dependent
329 syntax!
330 "size"
332 $file->size;
333 Returns the file size in bytes or the empty list if the method was not
335 implemented by the "Padre::File" subclass.
336 "stat"
338 $file->stat;
339 This emulates a stat call and returns the same values:
341 0 dev device number of file system
343 1 ino inode number
344 2 mode file mode (type and permissions)
345 3 nlink number of (hard) links to the file
346 4 uid numeric user ID of file's owner
347 5 gid numeric group ID of file's owner
348 6 rdev the device identifier (special files only)
349 7 size total size of file, in bytes
350 8 atime last access time in seconds since the epoch
351 9 mtime last modify time in seconds since the epoch
352 10 ctime inode change time in seconds since the epoch (*)
353 11 blksize preferred block size for file system I/O
354 12 blocks actual number of blocks allocated
355 A module should fill as many items as possible, but if you're thinking
357 about using this method, always remember
358 1. Usually, you need only one or two of the items, request them
360 directly.
361 2. Besides from local files, most of the values will not be accessible
363 (resulting in empty lists/false returned).
364 3. On most protocols these values must be requested one-by-one, which
366 is very expensive.
367 Please always consider using the function for the value you really need
369 instead of using "stat"!
370 "uid"
372 $file->uid;
373 Returns the real user ID of the file owner.
375 This is usually not possible for non-local files, in these cases, the
377 empty list is returned.
378 "write"
380 $file->write($Content);
381 $file->write($Content,$Coding);
382 Writes the given $Content to the file, if a encoding is given and the
384 protocol allows encoding, it is respected.
385 Returns 1 on success. Returns 0 on failure. Returns the empty list if
387 the function is not available on the protocol.
388
390 "_info"
391 $file->_info($message);
392 Shows $message to the user as an information. The output is guaranteed
394 to be non-blocking and messages shown this way must be safe to be
395 ignored by the user.
396 Doesn't return anything.
398perl v5.12.1 2010-06-11 Padre::File(3)