Hub::Base::FileSystem - Utility methods for working with the file system

  use Hub qw(:standard);

 Usage: fileopen FILENAME [PARAMS]

For platforms which don't flock, create a lockfile for a specified filename. Waits for #winlock_timeout seconds if a lockfile exists (unless READONLY is specified).

 Usage: fileclose HANDLE, [FILENAME]

Unlock and close the file.

Always remove the lockfile for a specified filename.

Return file's timestamp

 Usage: filetime LIST, [OPTIONS]

Where:

  LIST                A list of valid path names or file handles
  OPTIONS -mtime      Return last-modified time (default)
          -atime       last-accessed time
          -ctime       creation time
  OPTIONS -max        Return greatest value (default)
          -min         least value

Find files on disk

 Usage: find $directory, [options]

The directory entries '.' and '..' are always suppressed.

No sorting is done here, entries appear in directory order with the directory listing coming before its sub-directory's listings.

Options:

  -name         => \@list|$list   Filename patterns to include
  -include      => \@list|$list   Path patterns to include
  -exclude      => \@list|$list   Path patterns to ignore.

  -ignore       => \@list|$list   Path patterns to ignore
  -filesonly    => 0|1            Omit directory entries from the result
  -dirsonly     => 0|1            Omit file entries from the result

Examples:

  # Return the whole mess
  find('/var/www/html');




  # Wild-card search
  my @list = find('/var/www/html/*.css');




  # Find by filename
  my @list = find('/var/www/html', -name => '\.htaccess;\.htpasswd');




  # Ignore these paths
  my @list = find('/var/www/html', -ignore => ".bak;.swp");




  # Ignore these paths AND do not recurse into them
  my @list = find('/var/www/html', -exclude => "CVS;.svn");




  # Just find these paths
  # This would also match a directories named ".gif"!
  my @list = find('/var/www/html', -include => ".gif;.jp?g;.png");




  # Omit directory entries from the result
  my @list = find('/var/www/html', -filesonly => 1);




  # Omit file entries from the result
  my @list = find('/var/www/html', -dirsonly => 1);

The options:

  -name
  -include
  -exclude
  -ignore

Can be provided as array references, meaning:

  my @patterns = qw(1024x768.gif 800x600.jpe?g)
  my @list = find('/var/www/html', -include => \@patterns);

is equivelent to:

  my @list = find('/var/www/html', -include => "1024x768.gif;800x600.jpe?g");

Copy a directory

 Usage: cpdir $source_dir, $target_dir, [filters], [permissions], [options]

WARNING this function does *not* behave like your shell's cp -r command! It differs in that when the target directory exists, the *contents* of the source directory are copied. This is done so that the default operation is:

  # don't create /home/$username/newuser!
  cpdir('templates/newuser', "/home/$username");

To get the same behavior as cp -r, use the '-as_subdir' flag.

Files are only copied when the source file's modified time is newer (unless the 'force' option is set).

filters: See find

permissions: See chperm (chperm)

options:

  -force => 1               # Always perform the copy
  -as_subdir => 1           # Copy as a sub-directory of $target
  -peers => 1               # The $source and $target are peers (may be
                              different names)




  -peers and -as_subdir are mutually exclusive

Copy a file and apply permissions and mode

 Usage: cpfile $SOURCE, $TARGET, [\%PERMISSIONS], [OPTIONS]

Where:

  $SOURCE         File to be copied
  $TARGET         Target path (file or directory)
  \%PERMISSIONS   Permission hash (see Hub::chperm)
  OPTIONS         -newer      Only copy when the source is newer (mtime) than
                              the target

See also: chperm (chperm)

Remove file

Move (rename) a file

 Usage: rmdirrec TARGET_DIR

Recursively remove a directory.

Change permissions of a file or directory

 Usage: chperm $path, [filters], [permissions], [options]

options:

  recperms=1        # will recurse if  is a directory

filters: Used when recperms is set. See find (find).

permissions:

  uid     => Hub::getuid( "username" ),    # user id
  gid     => Hub::getgid( "username" ),    # group id
  dmode   => 0775,
  fmode   => {            # fmode can ref a hash of extensions
      '*'     => 0644,    # '*' is used for unmatched
      'cgi'   => 0755,    # specific cgi file extension
      'dll'   => 'SKIP',  # do not update dll files
  }
  fmode   => 0655,        # or, fmode can be used for all files

Make a directy with specified permissions

 Usage: mkdiras $path, [permissions]

permissions: See chperm

Return the first line of a file

 Usage: getcrown $file_path

Returns empty-string when $file_path does not exist

Read a directory in proper order

 Usage: readdir $dir

Sort the provided directory listing

 Usage: sort_dir_list $dir, \@listing

 Usage: readfile PATH

Read and return the contents of a file.

Write $contents to $path

 Usage: writefile $path, \$contents, [options]
 Usage: writefile $path, $contents, [options]

options:

  -mode   => 0644     Set/update file's mode
  -flags  => >|>>     Flags used to open the file

Returns 1 if the file could be openned and written to, otherwise 0.

Populate a file with runtime data.

 Usage: parsefile $filename, [options]
 Usage: parsefile $filename, \%data, [\%more_data..], [options]

parameters:

  $filename   File to parse as a template.

  \%data      Hashref of name/value pairs.

options:

  -as_ref=1   Return a scalar reference
  -alone      Do not include configuration and instance values
  -inline     Update the file on disk!

Push path onto working directory stack

Pop path from working directory stack

Search the working path for $file

 Usage: srcpath $file

Authorize a path for the runtime access

 Usage: secpath $path

Intention is to be able to pass anything to this method and it will only return a path when it is valid. Being valid means that it resolves to a file or directory which is at or below the WORKING_DIR.

Clean up malformed paths (usually due to concatenation logic).

 Usage: fixpath $path

Example: (matches)

    fixpath( "../../../users/newuser/web/bin/../src/screens" );




    ../../../users/newuser/web/src/screens

Example: (matches)

    fixpath( "users/newuser/web/" );




    users/newuser/web

Example: (matches)

    fixpath( "users/../web/bin/../src" );




    web/src

Example: (matches)

    fixpath( "users//newuser" );




    users/newuser

Example: (matches)

    fixpath( "users//newuser/./files" );




    users/newuser/files

Example: (matches)

    fixpath( "http://site/users//newuser" );




    http://site/users/newuser

Example: (matches)

    fixpath( '/home/hub/build/../../../out/doc/pod' );




    /out/doc/pod

Get the Hub address for a file

 Usage: getaddr $filename

$filename may be relative to the running module (see Hub::modexec)

For the inverse, see Hub::realpath

Exract the parent from the given filepath

Example: (matches)

    getpath( "/etc/passwd" )




    /etc

Example: (matches)

    getpath( "/usr/local/bin" )




    /usr/local

Given a path to a file, return (directory, filename, extension)

 Usage: getspec $path

 Usage: getname Return the file name (last element) of given path
 Usage: getname $path
Note, if the given path is a full directory path, the last directory is
still considerred a filename.

Example: (matches)

    getname("../../../users/newuser/web/data/p001/batman-small.jpg");




    batman-small.jpg

Example: (matches)

    getname("../../../users/newuser/web/data/p001");




    p001

Example: (matches)

    getname("/var/log/*.log");




    *.log

Return the file extension at the given path

 Usage: getext $path

Example: (matches)

    getext( "/foo/bar/filename.ext" )




    ext

Example: (matches)

    getext( "filename.cgi" )




    cgi

Resolve the address to it's real file on disk.

 Usage: realpath $address

Used to translate our Hub system addresses into real filesystem paths.

When /foo/bar.txt is really cwd().'/foo/bar.txt', we strip the beginning /.

When using mounts, return the file's real path.

For the inverse, see Hub::getaddr

Return the absolute path

 Usage: abspath $node, [options]
options:
  -must_exist=0   Allow paths which don't exist

Relative path

 Usage: relpath $path, $from_dir

Example: (matches)

    relpath("/home/docs", "/home/docs/install");




    ..

Example: (matches)

    relpath("/home/src", "/home/docs/install");




    ../../src

Example: (matches)

    relpath("/home/docs/README.txt", "/home/docs");




    README.txt

Example: (matches)

    relpath("README.txt", "/DEBUG");




    README.txt

Create the directory specified, including parent directories.

 Usage: mkabsdir $dir, [permissions]
See L<hubperms>

Change permission proxy (splits between Win32 and normal routines)

 Usage: _chperm $user, $group, $mode, @targets

$user may be either the numeric uid, or the user name

$group may be either the numeric gid, or the group name

$mode may be either the octal value (such as 0755) or the string value (such as '755')

On win32, default permissions are taken from the configuration file (by default, '.conf' in the current directory):

  group = /conf/win32/group_name
  owner = /conf/win32/owner_name
  other = /conf/win32/other_name

When not specified in the configuration, these values will be

  group = Win32::LoginName
  owner = the same as 'other'
  other = Everyone

Use chmod and chown to change permissions

 Usage: _chperm_normal $user, $group, $mode, $target

See _chperm for $user, $group, and $mode settings

Change permissions on Win32

On Win32, we still don't "really" change the owner (Anybody know how?)

Get the absolute path (may or may not exist)

 Usage: _find_abspath $node
 Usage: _find_abspath $node $working_dir

Ryan Gies (ryangies@livesite.net)

Copyright (C) 2006-2007 by Livesite Networks, LLC. All rights reserved.

Copyright (C) 2000-2005 by Ryan Gies. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

* The origin of this software must not be misrepresented; you must not claim that you wrote the original software. If you use this software in a product, an acknowledgment in the product documentation would be appreciated but is not required.

* Altered source versions must be plainly marked as such, and must not be misrepresented as being the original software.

* The name of the author may not be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE AUTHOR "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

To the best of our knowledge, no patented algorithms have been used. However, we do not have the resources to carry out a patent search, and therefore cannot give any guarantee of the above statement.

08/02/2007