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_…" 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_delete"
164 $file->can_delete;
165 Returns true if the protocol allows deletion of files or false if it
167 doesn't.
168 "can_run"
170 $file->can_run;
171 Returns true if the protocol allows execution of files or the empty
173 list if it doesn't.
174 This is usually not possible for non-local files (which return true),
176 because there is no way to reproduce a save environment for running a
177 HTTP or FTP based file (they return false).
178 "clone"
180 my $clone = $file->clone($File_or_URL);
181 The "clone" constructor lets you create a new "Padre::File" object
183 reusing an existing connection.
184 Takes the same arguments as the "new" method.
186 If the protocol doesn't know about (server) connections/sessions,
188 returns a brand new Padre::File object.
189 NOTICE: If you request a clone which is located on another server,
191 you'll
192 get a Padre::File object using the original connection to the
193 original server and the original authentication data but the
194 new
195 path and file name!
196 Returns a new "Padre::File" or dies on error.
198 "clone_file"
200 my $clone = $file->clone_file($filename_with_path);
201 my $clone = $file->clone_file($path,$filename);
202 The "clone" constructor lets you create a new "Padre::File" object
204 reusing an existing connection.
205 Takes one or two arguments:
207 either the complete path + file name of an URL
209 or the path and file name as separate arguments
210 If the protocol doesn't know about (server) connections/sessions,
212 returns a brand new "Padre::File" object.
213 Returns a new "Padre::File" or dies on error.
215 "ctime"
217 $file->ctime;
218 Returns the last-change time of the inode (not the file!).
220 This is usually not possible for non-local files, in these cases, the
222 empty list is returned.
223 "delete"
225 $file->delete;
226 Removes the current object's file from disk (or whereever it's stored).
228 Should clear any caches.
230 "dev"
232 $file->dev;
233 Returns the device number of the file system where the file resides.
235 This is usually not possible for non-local files, in these cases, the
237 empty list is returned.
238 "dirname"
240 $file->dirname;
241 Returns the plain path without file name if a path/file name structure
243 exists for this module.
244 Returns the empty list on failure or undefined behaviour for the given
246 protocol.
247 "error"
249 $file->error;
250 Returns the last error message (like $! for system calls).
252 "exists"
254 $file->exists;
255 Returns true if the file exists. Returns false if the file doesn't
257 exist. Returns the empty list if unsure (network problem, not
258 implemented).
259 "filename"
261 $file->filename;
262 Returns the the file name including path handled by this object.
264 Please remember that "Padre::File" is able to open many URL types. This
266 file name may also be a URL. Please use the "basename" and "dirname"
267 methods to split it (assuming that a path exists in the current
268 protocol).
269 "gid"
271 $file->gid;
272 Returns the real group ID of the file group.
274 This is usually not possible for non-local files, in these cases, the
276 empty list is returned.
277 "inode"
279 $file->inode;
280 Returns the inode number of the file.
282 This is usually not possible for non-local files, in these cases, the
284 empty list is returned.
285 "mime"
287 $file->mime;
288 $file->mime('text/plain');
289 Returns or sets the MIME type of the file.
291 "mode"
293 $file->mode;
294 Returns the file mode (type and rights). See also: "stat" in perlfunc.
296 To get the POSIX file permissions as the usual octal number (as opposed
297 to a string) use:
298 use Fcntl ':mode';
300 my $perms_octal = S_IMODE($file->mode);
301 This is usually not possible for non-local files, in these cases, the
303 empty list is returned.
304 "mtime"
306 $file->mtime;
307 Returns the last-modification (change) time of the file.
309 "nlink"
311 $file->nlink;
312 Returns the number of hard links to the file.
314 This is usually not possible for non-local files, in these cases, the
316 empty list is returned.
317 "rdev"
319 $file->rdev;
320 Returns the device identifier.
322 This is usually not possible for non-local files, in these cases, the
324 empty list is returned.
325 "read"
327 $file->read;
328 Reads the file contents and returns them.
330 Returns the empty list on error. The error message can be retrieved
332 using the "error" method.
333 "servername"
335 $file->servername;
336 Returns the server name for this module - if the protocol knows about a
338 server, local files don't.
339 WARNING: The Padre "path" includes the server name in a protocol
341 dependent
342 syntax!
343 "size"
345 $file->size;
346 Returns the file size in bytes or the empty list if the method was not
348 implemented by the "Padre::File" subclass.
349 "stat"
351 $file->stat;
352 This emulates a stat call and returns the same values:
354 0 dev device number of file system
356 1 ino inode number
357 2 mode file mode (type and permissions)
358 3 nlink number of (hard) links to the file
359 4 uid numeric user ID of file's owner
360 5 gid numeric group ID of file's owner
361 6 rdev the device identifier (special files only)
362 7 size total size of file, in bytes
363 8 atime last access time in seconds since the epoch
364 9 mtime last modify time in seconds since the epoch
365 10 ctime inode change time in seconds since the epoch (*)
366 11 blksize preferred block size for file system I/O
367 12 blocks actual number of blocks allocated
368 A module should fill as many items as possible, but if you're thinking
370 about using this method, always remember
371 1. Usually, you need only one or two of the items, request them
373 directly.
374 2. Besides from local files, most of the values will not be accessible
376 (resulting in empty lists/false returned).
377 3. On most protocols these values must be requested one-by-one, which
379 is very expensive.
380 Please always consider using the function for the value you really need
382 instead of using "stat"!
383 "uid"
385 $file->uid;
386 Returns the real user ID of the file owner.
388 This is usually not possible for non-local files, in these cases, the
390 empty list is returned.
391 "write"
393 $file->write($Content);
394 $file->write($Content,$Coding);
395 Writes the given $Content to the file, if a encoding is given and the
397 protocol allows encoding, it is respected.
398 Returns 1 on success. Returns 0 on failure. Returns the empty list if
400 the function is not available on the protocol.
401
403 "_info"
404 $file->_info($message);
405 Shows $message to the user as an information. The output is guaranteed
407 to be non-blocking and messages shown this way must be safe to be
408 ignored by the user.
409 Doesn't return anything.
411perl v5.32.0 2020-07-28 Padre::File(3)