NAME

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

SYNOPSIS

use Hub qw(:standard);

DESCRIPTION

Intention

PUBLIC METHODS

fileopen

```
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).

fileclose

```
Usage: fileclose HANDLE, [FILENAME]
```
Unlock and close the file.

Always remove the lockfile for a specified filename.

filetime

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

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");

cpdir

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

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

cpfile

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

rmfile

Remove file

mvfile

Move (rename) a file

rmdirrec

```
Usage: rmdirrec TARGET_DIR
```
Recursively remove a directory.

chperm

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.

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

mkdiras

Make a directy with specified permissions

Usage: mkdiras $path, [permissions]

permissions: See chperm

getcrown

Return the first line of a file

Usage: getcrown $file_path

Returns empty-string when $file_path does not exist

readdir

Read a directory in proper order

Usage: readdir $dir

sort_dir_list

Sort the provided directory listing

Usage: sort_dir_list $dir, \@listing

readfile

```
Usage: readfile PATH
```
Read and return the contents of a file.

writefile

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.

parsefile

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!

pushwp

Push path onto working directory stack

popwp

Pop path from working directory stack

srcpath

Search the working path for $file

Usage: srcpath $file

fixpath

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

getaddr

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

getpath

Exract the parent from the given filepath

Example: (matches)

getpath( "/etc/passwd" )


/etc

Example: (matches)

getpath( "/usr/local/bin" )


/usr/local

getspec

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

Usage: getspec $path

getname

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

getext

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

realpath

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

abspath

Return the absolute path

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

relpath

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

mkabsdir

Create the directory specified, including parent directories.

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

INTERNAL METHODS

_find

_chperm

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

_chperm_normal

Use chmod and chown to change permissions

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

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

_chperm_win32

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

_find_abspath

Get the absolute path (may or may not exist)

Usage: _find_abspath $node

AUTHOR

Ryan Gies (ryangies@livesite.net)

COPYRIGHT

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.

UPDATED

06/09/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.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

Intention

PUBLIC METHODS

fileopen

fileclose

filetime

find

cpdir

cpfile

rmfile

mvfile

rmdirrec

chperm

mkdiras

getcrown

readdir

sort_dir_list

readfile

writefile

parsefile

pushwp

popwp

srcpath

fixpath

getaddr

getpath

getspec

getname

getext

realpath

abspath

relpath

mkabsdir

INTERNAL METHODS

_find

_chperm

_chperm_normal

_chperm_win32

_find_abspath

AUTHOR

COPYRIGHT

UPDATED

Module Install Instructions