Bric::Util::Trans::FS(3p)

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

VERSION
$LastChangedRevision$

DATE
$LastChangedDate: 2006-03-18 01:26:34 +0100 (Sat, 18 Mar 2006) $

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:

    *   Incorrect number of args to Bric::_set().

    *   Bric::set() - Problems setting fields.

    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:

    *   Bric::_get() - Problems retrieving fields.

    *   Incorrect number of args to Bric::_set().

    *   Bric::set() - Problems setting fields.

    *   Unable to connect to database.

    *   Unable to prepare SQL statement.

    *   Unable to select column into arrayref.

    *   Unable to execute SQL statement.

    *   Unable to bind to columns to statement handle.

    *   Unable to fetch row from statement handle.

    *   Bad AUTOLOAD method format.

    *   Cannot AUTOLOAD private methods.

    *   Access denied: READ access for field 'uri' required.

    *   No AUTOLOAD method.

    *   Error copying $src to $dst.

    *   Error creating path.

    *   Error deleting path.

    *   Error opening directory.

    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:

    *   Bric::_get() - Problems retrieving fields.

    *   Incorrect number of args to Bric::_set().

    *   Bric::set() - Problems setting fields.

    *   Unable to connect to database.

    *   Unable to prepare SQL statement.

    *   Unable to select column into arrayref.

    *   Unable to execute SQL statement.

    *   Unable to bind to columns to statement handle.

    *   Unable to fetch row from statement handle.

    *   Bad AUTOLOAD method format.

    *   Cannot AUTOLOAD private methods.

    *   No AUTOLOAD method.

    *   Error deleting path.

    *   Error opening directory.

    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:

    *   Error copying $src to $dst.

    *   Error creating path.

    *   Error deleting path.

    *   Error opening directory.

    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:

    *   Error creating path.

    *   Error deleting path.

    *   Error moving $src to $dst.

    Side Effects: NONE.

    Notes: NONE.

my $bool = $fs->mk_path($path)
    Creates a directory path.

    Throws:

    *   Error creating path.

    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:

    *   Error deleting path.

    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 URI and returns its directory parts.

    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 name, chops off the last URI specification, 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:

    *   Error copying $src to $dst.

    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:

    *   Error moving $src to $dst.

    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:

    *   Error opening directory.

    *   Error copying $src to $dst.

    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:

    *   Error opening directory.

    *   Error copying $src to $dst.

    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