NAME
Padre::File - Common API for file functions
DESCRIPTION
Padre::File provies a common API for file access within Padre. It covers all the differences with non-local files by mapping every function call to the currently used transport stream.
FUNCTIONS
REGISTER
Padre::File::REGISTER($RegExp,$Module);This function is NOT a OO-method, it may not be called on a Padre::File object!
A plugin could call Padre::File::REGISTER to register a new protocol to Padre::File and enable Padre to use URLs handled by this module.
Example: Padre::File::REGISTER('^nfs\:\/\/','Padre::Plugin::NFS');
Every file/URL opened through Padre::File which starts with nfs:// is now handled through Padre::Plugin::NFS. Padre::File->new() will respect this and call Padre::Plugin::NFS->new() to handle such URLs.
Returns true on success or false on error.
REGISTERed protocols may override the internal protocols.
METHODS
new
my $file = Padre::File->new($File_or_URL);The new constructor lets you create a new Padre::File object.
Only one parameter is accepted at the moment: The name of the file which should be used. As soon as there are HTTP, FTP, SSH and other modules, also URLs should be accepted.
If you know the protocol (which should be true every time you build the URL by source), it's better to call Padre::File::Protocol->new($URL) directly (replacing Protocol by the protocol which should be used, of course).
The module for the selected protocol should fill ->{filename} property. This should be used for all further references to the file as it will contain the filename in universal correct format (for example correct the C:\ eq C:/ problem on windows).
Returns a new Padre::File or dies on error.
atime
$file->atime;Returns the last-access time of the file.
This is usually not possible for non-local files, in these cases, undef is returned.
basename
$file->basename;Returns the plain filename without path if a path/filename structure exists for this module.
blksize
$file->blocks;Returns the block size of the filesystem where the file resides
This is usually not possible for non-local files, in these cases, undef is returned.
blocks
$file->blocks;Returns the number of blockes used by the file.
This is usually not possible for non-local files, in these cases, undef is returned.
can_run
$file->can_run;Returns 1 if the protocol allows execution of files or 0 if it doesn't.
This is usually not possible for non-local files (which return 1), because there is no way to reproduce a save environment for running a HTTP or FTP based file (they return 0).
ctime
$file->ctime;Returns the last-change time of the inode (not the file!).
This is usually not possible for non-local files, in these cases, undef is returned.
dev
$file->dev;Returns the device number of the filesystem where the file resides.
This is usually not possible for non-local files, in these cases, undef is returned.
dirname
$file->dirname;Returns the plain path without filename if a path/filename structure exists for this module.
exists
$file->exists;Returns true if the file exists. Returns false if the file doesn't exist. Returns undef if unsure (network problem, not implemented).
filename
$file->filename;Returns the the filename including path handled by this object
Please remember that Padre::File is able to open many URL types. This "filename" may also be a URL. Please use the ->basename and ->dirname methods to split it (assuming that a path exists in the current protocol).
gid
$file->gid;Returns the GID of the file group.
This is usually not possible for non-local files, in these cases, undef is returned.
inode
$file->inode;Returns the inode number of the file.
This is usually not possible for non-local files, in these cases, undef is returned.
mime
$file->mime;
$file->mime('text/plain');Returns or sets the mime type of the file.
mode
$file->mode;Returns the file mode (type and rights).
TODO: Add a description what exactly is returned.
This is usually not possible for non-local files, in these cases, undef is returned.
mtime
$file->mtime;Returns the last-modification (change) time of the file.
nlink
$file->nlink;Returns the number of hard links to the file
This is usually not possible for non-local files, in these cases, undef is returned.
rdev
$file->rdev;Returns the device identifier.
This is usually not possible for non-local files, in these cases, undef is returned.
read
$file->read;Reads the file contents and returns them.
Returns undef on error. The error message could be retrieved using the ->error method.
size
$file->size;Returns the file size in bytes.
stat
$file->stat;This emulates a stat call and returns the same values:
0 dev device number of filesystem
1 ino inode number
2 mode file mode (type and permissions)
3 nlink number of (hard) links to the file
4 uid numeric user ID of file's owner
5 gid numeric group ID of file's owner
6 rdev the device identifier (special files only)
7 size total size of file, in bytes
8 atime last access time in seconds since the epoch
9 mtime last modify time in seconds since the epoch
10 ctime inode change time in seconds since the epoch (*)
11 blksize preferred block size for file system I/O
12 blocks actual number of blocks allocatedA module should fill as many items as possible, but if you're thinking about using this method, always remember 1. Usually, you need only one or two of the items, request them directly. 2. Besides from local files, most of the values will not be accessable (resulting in undef values) 3. On most protocols these values must be requested one-by-one which is very very expensive
Please always consider using the function for the value you really need instead of using ->stat!
uid
$file->uid;Returns the UID of the file owner.
This is usually not possible for non-local files, in these cases, undef is returned.
write
$file->write($Content);
$file->write($Content,$Coding);Writes the given $Content to the file, if a encoding is given and the protocol allows the usage of encodings, it is respected.
Returns 1 on success. Returns 0 on failure. Returns undef if the function is not avaible on the protocol.