NAME
Badger::Filesystem::File - file object
SYNOPSIS
# using Badger::Filesytem constructor subroutine
use Badger::Filesystem 'File';
# use native OS-specific paths:
$file = File('/path/to/file');
# or generic OS-independent paths
$file = File('path', 'to', 'file');
# manual object construction
use Badger::Filesystem::File;
# positional arguments
$file = Badger::Filesystem::File->new('/path/to/file');
$file = Badger::Filesystem::File->new(['path', 'to', 'file']);
# named parameters
$file = Badger::Filesystem::File->new(
path => '/path/to/file' # native
);
$file = Badger::Filesystem::File->new(
path => ['path', 'to', 'file'] # portable
);
# path inspection methods
$file->path; # full path
$file->name; # file name
$file->directory; # parent directory
$file->dir; # alias to directory()
$file->base; # same thing as directory()
$file->volume; # path volume (e.g. C:)
$file->is_absolute; # path is absolute
$file->is_relative; # path is relative
$file->exists; # returns true/false
$file->must_exist; # throws error if not
@stats = $file->stat; # returns list
$stats = $file->stat; # returns list ref
# path translation methods
$file->relative; # relative to cwd
$file->relative($base); # relative to $base
$file->absolute; # relative to filesystem root
$file->definitive; # physical file location
$file->collapse; # resolve '.' and '..' in $file path
# path comparison methods
$file->above($another_path); # $file is ancestor of $another_path
$file->below($another_path); # $file is descendant of $another_path
# file manipulation methods
$file->create; # create file
$file->touch; # create file or update timestamp
$file->delete; # delete file
$fh = $file->open($mode); # open file (for read by default)
$fh = $file->write; # open for write
$fh = $file->append; # open for append;
# all-in-one read/write methods
@data = $file->read; # return list of lines
$data = $file->read; # slurp whole content
$text = $file->text; # same as read();
$file->write(@content); # write @content to file
$file->append(@content); # append @content to fileDESCRIPTION
The Badger::Filesystem::File module is a subclass of Badger::Filesystem::Path for representing files in a file system.
You can create a file object File constructor function in Badger::Filesystem.
use Badger::Filesystem 'File';File paths can be specified as a single string using your native filesystem format or as a list or reference to a list of items in the path for platform-independent paths.
my $file = File('/path/to/file');If you're concerned about portability to other operating systems and/or file systems, then you can specify the file path as a list or reference to a list of component names.
my $file = File('path', 'to', 'file');
my $file = File(['path', 'to', 'file']);METHODS
In addition to the methods inherited from Badger::Filesystem::Path, the following methods are defined or re-defined.
init(\%config)
Customised initialisation method specific to files.
volume() / vol()
Returns any volume defined as part of the path. This is most commonly used on MS Windows platforms to indicate drive letters, e.g. C:.
directory() / dir() / base()
Returns the directory portion of the file path. This can also be used with an argument to locate another directory relative to this file.
my $file = File('/path/to/file');
print $file->dir; # /path/to
print $file->dir('subdir'); # /path/to/subdirname()
Returns the file name portion of the path.
file()
When called without arguments, this method simply returns the file object itself. It can also be called with an argument to locate another file relative to the directory in which the current file is located.
my $file = File('/path/to/file1');
print $file->file; # /path/to/file1
print $file->file('file2'); # /path/to/file2exists
Returns true if the file exists in the filesystem. Returns false if the file does not exists or if it is not a file (e.g. a directory).
is_file()
This method returns true for all Badger::Filesystem::File instances.
create()
This method can be used to create the file if it doesn't already exist.
touch()
This method can be used to create the file if it doesn't already exist or update the timestamp if it does.
open($mode,$perms)
This method opens the file and returns an IO::File handle to it. The default is to open the file for read-only access. The optional arguments can be used to specify a different mode and default permissions for the file (these arguments are forwarded to IO::File).
my $fh = $file->open; # read
my $fh = $file->open('w'); # writeread()
This method read the content of the file. It is returned as a single string in scalar context and a list of each line in list context.
my $text = $file->read;
my @lines = $file->read;write(@content)
When called without arguments this method opens the file for writing and returns an IO::File handle.
my $fh = $file->write;
$fh->print("Hello World!\n");
$fh->close;When called with arguments, the method opens the file, writes the argument to it, and then closes the file again.
$file->write("Hello World!\n");print(@content)
This method concatentates all arguments into a single string which it then forwards to the write() method. This effectively forces the write() method to always write something to the file, even if it's an empty string.
$file->print("hello");
$file->print(@stuff); # works OK if @stuff is empty append(@content)
This method is similar to write(), but opens the file for appending (when called with no arguments), or appends any arguments to the end of the file.
# manual open, append, close
my $fh = $file->append;
$fh->print("Hello World!\n");
$fh->close;
# all-in-one
$file->append("Hello World\n");delete()
This method deletes the file permanently. Use it wisely.
text()
This method is a wrapper around the read() method which forces scalar context. The content of the file is always returned as a single string. NOTE: future versions will probably return this as a text object.
accept($visitor)
This method is called to dispatch a visitor to the correct method for a filesystem object. In the Badger::Filesystem::File class, it calls the visitor visit_file() method, passing the $self object reference as an argument.
AUTHOR
Andy Wardley <abw@wardley.org>
COPYRIGHT
Copyright (C) 2005-2008 Andy Wardley. All rights reserved.
ACKNOWLEDGEMENTS
The Badger::Filesystem modules are built around a number of existing Perl modules, including File::Spec, File::Path, Cwd, IO::File, IO::Dir and draw heavily on ideas in Path::Class.
Please see the ACKNOWLEDGEMENTS in Badger::Filesystem for further information.
SEE ALSO
Badger::Filesystem, Badger::Filesystem::Path, Badger::Filesystem::Directory, Badger::Filesystem::Visitor.