1Padre::File(3)        User Contributed Perl Documentation       Padre::File(3)
2
3
4

NAME

6       Padre::File - Common API for file functions
7

DESCRIPTION

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

METHODS

14   "RegisterProtocol"
15         Padre::File->RegisterProtocol($RegExp, $Module);
16
17       Class method, may not be called on an object.
18
19       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
23       Example:
24
25         Padre::File->RegisterProtocol('^nfs\:\/\/','Padre::Plugin::NFS');
26
27       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
31       Returns true on success or false on error.
32
33       Registered protocols may override the internal protocols.
34
35   "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
43         Padre::File->RegisterProtocol(qr/^sftp:\/\//, 'Padre::File::MySFTP');
44
45       then you need to drop it with
46
47         Padre::File->DropProtocol(qr/^sftp:\/\//, 'Padre::File::MySFTP');
48
49       Returns true if a handler was removed and the empty list if no handler
50       was found for the given regular expression.
51
52   "new"
53         my $file = Padre::File->new($File_or_URL);
54
55       The "new" constructor lets you create a new "Padre::File" object.
56
57       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
61       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
66       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
71       Returns a new "Padre::File" or dies on error.
72
73   "atime"
74         $file->atime;
75
76       Returns the last-access time of the file.
77
78       This is usually not possible for non-local files, in these cases, the
79       empty list is returned.
80
81   "basename"
82         $file->basename;
83
84       Returns the plain file name without path if a path/file name structure
85       exists for this module.
86
87   "blksize"
88         $file->blksize;
89
90       Returns the block size of the file system where the file resides.
91
92       This is usually not possible for non-local files, in these cases, the
93       empty list is returned.
94
95   "blocks"
96         $file->blocks;
97
98       Returns the number of blocks used by the file.
99
100       This is usually not possible for non-local files, in these cases, the
101       empty list is returned.
102
103   "browse_mtime"
104         $file->browse_mtime($path_and_filename);
105
106       Returns the modification time of the given file on the remote server.
107
108       Leave out the protocol and server name for remote protocols, for
109       example
110
111         my $file = Padre::File->new('http://perlide.org/current/foo.html');
112         $file->browse_mtime('/archive/bar.html');
113
114       This returns the modification time of
115       "http://perlide.org/archive/bar.html"
116
117       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
121   "browse_url_join"
122         $file->browse_url_join($server, $path, $basename);
123
124       Merges a server name, path name and a file name to a complete URL.
125
126       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
129       You may think of
130
131         /tmp + padre.$$                       => /tmp/padre.$$
132         C:\\temp + padre.$$                   => C:\\temp\\padre.$$
133
134       ...but also remember
135
136         http://perlide.org + about.html       => http://perlide.org/about.html
137
138       Datapoint created a file syntax...
139
140         common + program/text                 => program/text:common
141
142       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
146       The most common seems to be a "/" as the directory separator character,
147       so we'll use this as the default.
148
149       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
152   "can_clone"
153         $file->can_clone;
154
155       Returns true if the protocol allows re-using of connections for new
156       files (usually from the same project).
157
158       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
163   "can_delete"
164         $file->can_delete;
165
166       Returns true if the protocol allows deletion of files or false if it
167       doesn't.
168
169   "can_run"
170         $file->can_run;
171
172       Returns true if the protocol allows execution of files or the empty
173       list if it doesn't.
174
175       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
179   "clone"
180         my $clone = $file->clone($File_or_URL);
181
182       The "clone" constructor lets you create a new "Padre::File" object
183       reusing an existing connection.
184
185       Takes the same arguments as the "new" method.
186
187       If the protocol doesn't know about (server) connections/sessions,
188       returns a brand new Padre::File object.
189
190       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
197       Returns a new "Padre::File" or dies on error.
198
199   "clone_file"
200         my $clone = $file->clone_file($filename_with_path);
201         my $clone = $file->clone_file($path,$filename);
202
203       The "clone" constructor lets you create a new "Padre::File" object
204       reusing an existing connection.
205
206       Takes one or two arguments:
207
208       either the complete path + file name of an URL
209       or the path and file name as separate arguments
210
211       If the protocol doesn't know about (server) connections/sessions,
212       returns a brand new "Padre::File" object.
213
214       Returns a new "Padre::File" or dies on error.
215
216   "ctime"
217         $file->ctime;
218
219       Returns the last-change time of the inode (not the file!).
220
221       This is usually not possible for non-local files, in these cases, the
222       empty list is returned.
223
224   "delete"
225         $file->delete;
226
227       Removes the current object's file from disk (or whereever it's stored).
228
229       Should clear any caches.
230
231   "dev"
232         $file->dev;
233
234       Returns the device number of the file system where the file resides.
235
236       This is usually not possible for non-local files, in these cases, the
237       empty list is returned.
238
239   "dirname"
240         $file->dirname;
241
242       Returns the plain path without file name if a path/file name structure
243       exists for this module.
244
245       Returns the empty list on failure or undefined behaviour for the given
246       protocol.
247
248   "error"
249         $file->error;
250
251       Returns the last error message (like $! for system calls).
252
253   "exists"
254         $file->exists;
255
256       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
260   "filename"
261         $file->filename;
262
263       Returns the the file name including path handled by this object.
264
265       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
270   "gid"
271         $file->gid;
272
273       Returns the real group ID of the file group.
274
275       This is usually not possible for non-local files, in these cases, the
276       empty list is returned.
277
278   "inode"
279         $file->inode;
280
281       Returns the inode number of the file.
282
283       This is usually not possible for non-local files, in these cases, the
284       empty list is returned.
285
286   "mime"
287         $file->mime;
288         $file->mime('text/plain');
289
290       Returns or sets the MIME type of the file.
291
292   "mode"
293         $file->mode;
294
295       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
299         use Fcntl ':mode';
300         my $perms_octal = S_IMODE($file->mode);
301
302       This is usually not possible for non-local files, in these cases, the
303       empty list is returned.
304
305   "mtime"
306         $file->mtime;
307
308       Returns the last-modification (change) time of the file.
309
310   "nlink"
311         $file->nlink;
312
313       Returns the number of hard links to the file.
314
315       This is usually not possible for non-local files, in these cases, the
316       empty list is returned.
317
318   "rdev"
319         $file->rdev;
320
321       Returns the device identifier.
322
323       This is usually not possible for non-local files, in these cases, the
324       empty list is returned.
325
326   "read"
327         $file->read;
328
329       Reads the file contents and returns them.
330
331       Returns the empty list on error. The error message can be retrieved
332       using the "error" method.
333
334   "servername"
335         $file->servername;
336
337       Returns the server name for this module - if the protocol knows about a
338       server, local files don't.
339
340       WARNING: The Padre "path" includes the server name in a protocol
341       dependent
342                syntax!
343
344   "size"
345         $file->size;
346
347       Returns the file size in bytes or the empty list if the method was not
348       implemented by the "Padre::File" subclass.
349
350   "stat"
351         $file->stat;
352
353       This emulates a stat call and returns the same values:
354
355         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
369       A module should fill as many items as possible, but if you're thinking
370       about using this method, always remember
371
372       1.  Usually, you need only one or two of the items, request them
373           directly.
374
375       2.  Besides from local files, most of the values will not be accessible
376           (resulting in empty lists/false returned).
377
378       3.  On most protocols these values must be requested one-by-one, which
379           is very expensive.
380
381       Please always consider using the function for the value you really need
382       instead of using "stat"!
383
384   "uid"
385         $file->uid;
386
387       Returns the real user ID of the file owner.
388
389       This is usually not possible for non-local files, in these cases, the
390       empty list is returned.
391
392   "write"
393         $file->write($Content);
394         $file->write($Content,$Coding);
395
396       Writes the given $Content to the file, if a encoding is given and the
397       protocol allows encoding, it is respected.
398
399       Returns 1 on success.  Returns 0 on failure.  Returns the empty list if
400       the function is not available on the protocol.
401

INTERNAL METHODS

403   "_info"
404         $file->_info($message);
405
406       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
410       Doesn't return anything.
411
412
413
414perl v5.32.0                      2020-07-28                    Padre::File(3)
Impressum