Bric::Util::Trans::FS(User Contributed Perl DocumentaBric::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:

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

           o   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:

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

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

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

           o   Unable to connect to database.

           o   Unable to prepare SQL statement.

           o   Unable to select column into arrayref.

           o   Unable to execute SQL statement.

           o   Unable to bind to columns to statement handle.

           o   Unable to fetch row from statement handle.

           o   Bad AUTOLOAD method format.

           o   Cannot AUTOLOAD private methods.

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

           o   No AUTOLOAD method.

           o   Error copying $src to $dst.

           o   Error creating path.

           o   Error deleting path.

           o   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:

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

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

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

           o   Unable to connect to database.

           o   Unable to prepare SQL statement.

           o   Unable to select column into arrayref.

           o   Unable to execute SQL statement.

           o   Unable to bind to columns to statement handle.

           o   Unable to fetch row from statement handle.

           o   Bad AUTOLOAD method format.

           o   Cannot AUTOLOAD private methods.

           o   No AUTOLOAD method.

           o   Error deleting path.

           o   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:

           o   Error copying $src to $dst.

           o   Error creating path.

           o   Error deleting path.

           o   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:

           o   Error creating path.

           o   Error deleting path.

           o   Error moving $src to $dst.

           Side Effects: NONE.

           Notes: NONE.

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

           Throws:

           o   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:

           o   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:

           o   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:

           o   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:

           o   Error opening directory.

           o   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:

           o   Error opening directory.

           o   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



perl v5.12.2                      2006-03-17         Bric::Util::Trans::FS(3p)
