Name

Bric::Util::Trans::FS - Utility class for handling files, paths and filenames.

Synopsis

use Bric::Util::Trans::FS;

# Constructors.
my $fs = Bric::Util::Trans::FS->new;

# Class methods.
Bric::Util::Trans->put_res($res, @sts);
Bric::Util::Trans->del_res($res, @sts);

# Instance methods.
$fs->copy($src, $loc);
$fs->move($src, $loc);
$fs->mk_path($path);
$fs->del(@files);
my $dir  = $fs->cat_dir(@dir_parts);
my $file = $fs->cat_file(@file_parts);
my $dir  = $fs->trunc_dir($dir);
my $uri  = $fs->cat_uri(@uri_parts);
my $uri  = $fs->trunc_uri($dir);
my $uri  = $fs->dir_to_uri($dir);
my $dir  = $fs->uri_to_dir($uri);

Description

This class provides a thin abstraction around a number of File::* modules (Copy, Spec, Basename, Find, etc.). Use it for all your portable file-system access needs.

Interface

Constructors

my $mail = Bric::Util::Trans::FS->new

Instantiates a Bric::Util::Trans::FS object.

Throws:

Side Effects: NONE.

Notes: NONE.

Destructors

$org->DESTROY

Dummy method to prevent wasting time trying to AUTOLOAD DESTROY.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

Public Class Methods

my $bool = Bric::Util::Trans::FS->put_res($resources, $st)

Copies the resources in the $resources anonymous array to each of the file system document roots specified by the servers associated with the $st server type.

Throws:

Side Effects: NONE.

Notes: NONE.

my $bool = Bric::Util::Trans::FS->del_res($resources, $st)

Deletes the resources in the $resources anonymous array from each of the file system document roots specified by the servers associated with the $st server type.

Throws:

Side Effects: NONE.

Notes: NONE.

Public Instance Methods

$fs = $fs->copy($src, $dst, $recurse)

Copies $src to $dest. If the directory hierarchy for $dst does not exist, it will be created. If $src is a file and $dst doesn't exist, $dst will be created as a copy of $src. If $srcs is a file and $dst exists as a directory, then $src will be copied into $dst. If $src is a file and $dst is a file, then $dst will be replaced with a copy of $src. If $src is a directory, then only the immediate contents of $src will be copied unless $recurse is true. If $src is a directory and $dst doesn't exist, then $dst will be created as a copy of $src. If $src is a directory and $dst is a directory, then $src will be copied into $dst. If $src is a directory and $dst is a file, then $dst will be wiped out and replaced with a copy of $src.

Throws:

Side Effects: NONE.

Notes: NONE.

$fs = $fs->move($src, $dest)

Moves $src to $dest. If the directory hierarchy for $dst does not exist, it will be created. If $src is a file and $dest is a file or doesn't exist, $src will be moved to (become) $dst. If $src is a file and $dst is a directory, $src will be moved into $dst. If $src is a directory and $dst doesn't exist, then $src will be moved to (become) $dst, including all of its contents. If $src is a directory and $dsts is a directory, then $src will be moved, with all of its contents, into $dst. If $src is a directory and $dst is a file, $dst will be blown away and then $src will be moved to (become) $dst.

Throws:

Side Effects: NONE.

Notes: NONE.

my $bool = $fs->mk_path($path)

Creates a directory path.

Throws:

Side Effects: NONE.

Notes: Uses File::Path::mkpath() internally.

my $bool = $fs->del(@paths)

Deletes a an entire directory tree from the file system. If any path in @paths is a simple file, it will be deleted.

Throws:

Side Effects: NONE.

Notes: Uses File::Path::rmtree() internally.

my $dir = $fs->cat_dir(@dir_parts)

Takes a list of directory parts and concatenates them for the local file system.

Throws: NONE.

Side Effects: NONE.

Notes: Uses File::Spec::Functions::catdir() internally.

my $file = $fs->cat_file(@file_parts)

Takes a list of directory parts and a filename and concatenates them for the local file system.

Throws: NONE.

Side Effects: NONE.

Notes: Uses File::Spec::Functions::catfile() internally.

my $uri = $fs->cat_uri(@uri_parts)

Takes a list of directory parts and concatenates them into a URI.

Throws: NONE.

Side Effects: NONE.

Notes: Uses File::Spec::Unix->catdir() internally.

my @dir_parts = $fs->split_dir($dir)

Takes a local filesystem directory name and and returns its directory parts.

Throws: NONE.

Side Effects: NONE.

Notes: Uses File::Spec::Functions::splitdir() internally.

my @uri_parts = $fs->split_uri($uri)

Takes a URI and and returns its directory parts.

Throws: NONE.

Side Effects: NONE.

Notes: Uses File::Spec::Unix->splitdir() internally.

my $dir = $fs->trunc_dir($dir)
my $dir = '/here/there/every/where';
$dir = $fs->trunc_dir($dir);
print $dir; # Prints "/here/there/every" on Unix.

Takes a directory name, chops off the last directory specification, and returns the truncated directory. Returns undef when the directory passed in is the root directory (e.g., '/').

Throws: NONE.

Side Effects: NONE.

Notes: Uses File::Spec::Functions::catdir() and File::Spec::Functions::splitdir() internally.

my $uri = $fs->trunc_uri($uri)

Takes a URI, chops off the last directoey, and returns the truncated URI. Returns undef when the URI passed in is the root URI (e.g., '/').

Throws: NONE.

Side Effects: NONE.

Notes: Uses File::Spec::Unix->catdir() and File::Spec::Unix->splitdir() internally.

my $uri = $fs->dir_to_uri($dir)

Takes a platform-specific directory name and changes it to a URI.

Throws: NONE.

Side Effects: NONE.

Notes: Uses File::Spec::Unix->catdir() and File::Spec::Unix->splitdir() internally.

my $uri = $fs->uri_to_dir($uri)

Takes a URI and changes it to a directory name for the local platform.

Throws: NONE.

Side Effects: NONE.

Notes: Uses File::Spec::Unix->catdir() and File::Spec::Unix->splitdir() internally.

my $base_name = $fs->base_name($file_name)
my $base_name = $fs->base_name($file_name, $OS)

Takes a complete file path name and extracts just the file name. The $OS argument may be any one of the following:

Unix
SomeNix
Windows NT
Windows 95
Windows 98
Windows XP
Windows ME
MacOS
Mac
VMS
DOS
MSDOS
Amiga
AmigaOS

If it's not included, the $OS argument is assumed to be 'Unix'.

Throws: NONE.

Side Effects: NONE.

Notes: Uses File::Basename::basename() and File::Basename::fileparse_set_fstype() internally.

my $uri_base_name = $fs->uri_base_name($uri)

Takes a URI as an argument and returns just the base name of the file at the end of the URI.

Throws: NONE.

Side Effects: NONE.

Notes: Uses File::Basename::basename() and File::Basename::fileparse_set_fstype() internally.

my $dir_name = $fs->dir_name($file_name)
my $dir_name = $fs->dir_name($file_name, $OS)

Takes a complete file path name and extracts just the file name. The $OS argument may be any one of the options listed in base_name() above.

Throws: NONE.

Side Effects: NONE.

Notes: Uses File::Basename::dirname() and File::Basename::fileparse_set_fstype() internally.

my $uri_dir_name = $fs->uri_dir_name($uri)

Takes a URI as an argument and returns just the directory name, minus the filename at the end of the URI.

Throws: NONE.

Side Effects: NONE.

Notes: Uses File::Basename::basename() and File::Basename::fileparse_set_fstype() internally.

Private

Private Class Methods

NONE.

Private Instance Methods

NONE.

Private Functions

my $bool = &$cp($src, $dst)

Copies a source file to a destination file.

Throws:

Side Effects: NONE.

Notes: Uses File::Copy::copy() internally.

my $bool = &$mv($src, $dst)

Moves a source file or directory to a destination file or directory.

Throws:

Side Effects: NONE.

Notes: Uses File::Copy::move() internally.

my $bool = &$cpdir($src, $dst, $recurse)

Copies the contents of $src into $dst. If $recurse is true, it will copy all the subdirectories of $src, too. Otherwise, it'll just copy the immediate contents of $src.

Throws:

Side Effects: NONE.

Notes: Uses &$glob() and &$glob_rec() internally.

my $bool = &$glob($src_dir, $dst_dir)

Copies the immediate contents of $src_dir into $dst_dir. Does not recursively copy the subdirectories of $src.

Throws:

Side Effects: NONE.

Notes: Uses &$cp() internally.

my $bool = &$glob_rec($src_dir, $dest_dir)

Recursively copies the contents of $src to $dst.

Throws: NONE.

Side Effects: NONE.

Notes: Uses File::Find::find() internally. Not yet implemented.

Notes

NONE.

Author

David Wheeler <david@justatheory.com>

See Also

Bric, File::Copy, File::Path, File::Basename, File::Find, File::Spec