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.
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
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");
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:
cp -r
# 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
filters
permissions: See chperm
permissions
options:
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
Usage: cpfile $SOURCE, $TARGET, [\%PERMISSIONS], [OPTIONS]
$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
Usage: rmdirrec TARGET_DIR
Recursively remove a directory.
Usage: chperm $path, [filters], [permissions], [options]
recperms=1 # will recurse if is a directory
filters: Used when recperms is set. See 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
Usage: mkdiras $path, [permissions]
Usage: getcrown $file_path
Returns empty-string when $file_path does not exist
Usage: readdir $dir
Usage: sort_dir_list $dir, \@listing
Usage: readfile PATH
Read and return the contents of a file.
Usage: writefile $path, \$contents, [options] Usage: writefile $path, $contents, [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.
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.
-as_ref=1 Return a scalar reference -alone Do not include configuration and instance values -inline Update the file on disk!
Usage: srcpath $file
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.
Usage: fixpath $path
Example: (matches)
fixpath( "../../../users/newuser/web/bin/../src/screens" ); ../../../users/newuser/web/src/screens
fixpath( "users/newuser/web/" ); users/newuser/web
fixpath( "users/../web/bin/../src" ); web/src
fixpath( "users//newuser" ); users/newuser
fixpath( "users//newuser/./files" ); users/newuser/files
fixpath( "http://site/users//newuser" ); http://site/users/newuser
fixpath( '/home/hub/build/../../../out/doc/pod' ); /out/doc/pod
Usage: getaddr $filename
$filename may be relative to the running module (see Hub::modexec)
$filename
For the inverse, see Hub::realpath
getpath( "/etc/passwd" ) /etc
getpath( "/usr/local/bin" ) /usr/local
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.
getname("../../../users/newuser/web/data/p001/batman-small.jpg"); batman-small.jpg
getname("../../../users/newuser/web/data/p001"); p001
getname("/var/log/*.log"); *.log
Usage: getext $path
getext( "/foo/bar/filename.ext" ) ext
getext( "filename.cgi" ) cgi
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
Usage: abspath $node, [options] options: -must_exist=0 Allow paths which don't exist
Usage: relpath $path, $from_dir
relpath("/home/docs", "/home/docs/install"); ..
relpath("/home/src", "/home/docs/install"); ../../src
relpath("/home/docs/README.txt", "/home/docs"); README.txt
relpath("README.txt", "/DEBUG"); README.txt
Usage: mkabsdir $dir, [permissions] See L<hubperms>
Usage: _chperm $user, $group, $mode, @targets
$user may be either the numeric uid, or the user name
$user
$group may be either the numeric gid, or the group name
$group
$mode may be either the octal value (such as 0755) or the string value (such as '755')
$mode
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
Usage: _chperm_normal $user, $group, $mode, $target
See _chperm for $user, $group, and $mode settings
On Win32, we still don't "really" change the owner (Anybody know how?)
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
To install Hub, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Hub
CPAN shell
perl -MCPAN -e shell install Hub
For more information on module installation, please visit the detailed CPAN module installation guide.