/ 
hub-standard-03.01.048
/ Hub::Data::File

NAME

Hub::Data::File -

Part of the Hub Library

SYNOPSIS

DESCRIPTION

METHODS

chperm fileopen find mkdiras rmdirrec
cpdir filescan find_files mvfile rmfile
cpfile filetest getcrown parsefile safefn
fileclose filetime listfiles readfile writefile
chperm

Usage: chperm PATH OPTIONS

Change permissions of a file or directory

OPTIONS

{
    # see find and cpdir

    'recperms'   => 1,       # will recurse if PATH is a directory


}
cpdir

Usage: cpdir SOURCE_DIR, TARGET_DIR, [OPTIONS]

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

SOURCE_DIR    SCALAR, Source directory


TARGET_DIR    SCALAR, Destination *parent* directory


OPTIONS       HASHREF, Options:


             {
                 include => [ ".*" ],
                 ignore  => [ "CVS", "\.cvsignore", "README" ],
                 force   => 1,


                 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


             }
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

See also: chperm

fileclose

Usage: fileclose HANDLE, [FILENAME]

Unlock and close the file.

Always remove the lockfile for a specified filename.

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

filescan

Usage: filescan PATH, [PATH] ...

Clear the list of recognized files, then find all nodes in the specified path(s) and mark them as existing.

filetest

Usage: filetest PATH
Usage: filetest PATH TEST

Returns 1 if PATH is an element which we recognize as existing on disk. The idea behind this logic is that it is faster to build a list of existing files once then check the list as the program progresses, than it is to make the -e, -f and -d perl calls. The frequency with which the list of known files is updated is left to user configuration. (see filescan)

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


DIRECTORY     SCALAR, Can be an absolute or relative path.



OPTIONS       HASH {
                 ignore_path  => [ "CVS", ],
                 ignore       => [ ".cvsignore$" ],
                 include      => [ "pl$", "pm$" ],
                 filesonly    => 0,
             }


RETURNS       ARRAY


NOTES         . and .. are always ignored.
find_files

Hub::find_files( $directory )

$directory can be absolute or relative. Trim the trailing slash before calling this method.

Example:

Hub::find_files( '/var' );

Returns and array of:

/var/log/lastlog
/var/log/setup.log
/var/log/setup.log.full
/var/log/sshd.log
/var/log/wtmp
/var/run/sshd.pid
/var/run/utmp
getcrown

Usage: getcrown

Return the first line of a file

listfiles

Usage: listfiles

List files in a directory.

mkdiras

Usage: mkdiras

Make a directy with specified permissions

mvfile

Usage: mvfile

Move (rename) a file

parsefile

Usage: parsefile FILENAME, [DATA], [OPTIONS]


FILENAME:     File to parse as a template.



[DATA]:       Hashref of name/value pairs.

[OPTIONS]:

-sdref      Return a scalar copy (not a reference)
-alone      Do not include configuration and instance values
-inline     Update the template on disk!

Populate a file with runtime data.

readfile

Usage: readfile PATH

Read and return the contents of a file.

rmdirrec

Usage: rmdirrec TARGET_DIR

Recursively remove a directory.

rmfile

Usage: rmfile

We rely on server security and file permissions to prevent tamperring.

safefn

Usage: safefn EXPR

Create a name which is safe for using as a filename.

Example: This example:

safefn( 'alsk/lsdkfj' );

matches:

alsk_2f_lsdkfj
writefile

Usage: writefile FILEPATH, CONTENTS, [FLAGS]

Write CONTENTS to FILEPATH which is openned with FLAGS. Default FLAGS is '>'.

Sets the correct file permissions.

INTERNAL

_chperm _chperm_normal _chperm_win32
_chperm

_chperm_normal

_chperm_win32

AUTHOR

Ryan Gies

COPYRIGHT

Copyright (c) 2006 Livesite Networks, LLC. All rights reserved.

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

UPDATED

This file created by on at