NAME

File::Util - Easy, versatile, portable file handling

IMPORTANT!

This is a developer's release, and is not intended for use in the public sector. This code is made available for developers who wish to aid in the furthering of the code, though it _is_ stable.

This is not a registered module in the CPAN module list. It is not part of the CPAN yet.

SYNOPSIS

-- This part of the documentation is not yet complete! --

   Nothing here at present.

DESCRIPTION

File::Util provides a comprehensive toolbox of utilities to automate all kinds of common tasks on file / directories. Its purpose is to do so in the most portable manner possible so that users of this module won't have to worry about whether their programs will work on other OSes and machines.

INSTALLATION

To install this module type the following at the command prompt:

   perl Makefile.PL
   make
   make test
   make install

On windows machines use nmake rather than make; those running cygwin don't have to worry about this. If you don't know what cygwin is, use nmake and check out http://cygwin.com/ after you're done installing this module if you want to find out.

File::Util ISA

Exporter
Class::OOorNO

METHODS

Note: Some of the methods listed will state that they are autoloaded methods. Autloaded methods are not compiled at runtime as part of your process and only get created if called somewhere in your program. (see AutoLoader.)

`bitmask`

Syntax: bitmask( [file name] ): Gets the bitmask of the named file, provided the file exists. If the file exists, the bitmask of the named file is returned in four digit octal notation eg- 0644. Otherwise, returns undef if the file does not exist. This is an autoloaded method.

`can_flock`

Syntax: can_flock

Returns 1 if the current system claims to support flock() and if the Perl process can successfully call it. (see "flock" in perlfunc.) Unless both of these conditions are true a zero value (0) is returned. This is an autoloaded method. This is a constant subroutine. It accepts no arguments and will always return the same value for the system on which it is executed.

Note: Perl will try to support or emulate flock whenever it can via available system calls, namely flock; lockf; or with fcntl.

`can_read`

Syntax: can_read( [file name] )

Returns 1 if the named file (or directory) is readable by your program according to the applied permissions of the file system on which the file resides. Otherwise a value of undef is returned.

This works the same as Perl's built-in -r file test operator, (see "-X" in perlfunc), it's just easier for some people to remember. This is an autoloaded method.

`can_write`

Syntax: can_write( [file name] )

Returns 1 if the named file (or directory) is writable by your program according to the applied permissions of the file system on which the file resides. Otherwise a value of undef is returned.

This works the same as Perl's built-in -w file test operator, (see "-X" in perlfunc), it's just easier for some people to remember. This is an autoloaded method.

`created`

Syntax: created( [file name] ): Returns the time of creation for the named file in non-leap seconds since whatever your system considers to be the epoch. Suitable for feeding to Perl's built-in functions "gmtime" and "localtime". (see "time" in perlfunc.) This is an autoloaded method.

`ebcdic`

Syntax: ebcdic: Returns 1 if the machine on which the code is running uses EBCDIC, or returns 0 if not. (see perlebcdic.) This is an autoloaded method. This is a constant subroutine. It accepts no arguments and will always return the same value for the system on which it is executed.

`escape_filename`

Syntax: escape_filename( [string] ): -- Documentation for this method is not yet complete! -- This is an autoloaded method.

`existent`

Syntax: existent( [file name] )

Returns 1 if the named file (or directory) exists. Otherwise a value of undef is returned.

This works the same as Perl's built-in -e file test operator, (see "-X" in perlfunc), it's just easier for some people to remember. This is an autoloaded method.

`file_type`

Syntax: file_type( [file name] )

Returns a list of keywords corresponding to each of Perl's built in file tests (those specific to file types) for which the named file returns true. (see "-X" in perlfunc.) This is an autoloaded method.

The keywords and their definitions appear below; the order of keywords returned is the same as the order in which the are listed here:

PLAIN: File is a plain file.
TEXT: File is a text file.
BINARY: File is a binary file.
DIRECTORY: File is a directory.
SYMLINK: File is a symbolic link.
PIPE: File is a named pipe (FIFO).
SOCKET: File is a socket.
BLOCK: File is a block special file.
CHARACTER: File is a character special file.

`flock_rules`

Syntax: flock_rules( [Keywords] ): -- Documentation for this method is not yet complete! -- This is an autoloaded method.

`isbin`

Syntax: isbin( [file name] )

Returns 1 if the named file (or directory) exists. Otherwise a value of undef is returned, indicating that the named file either does not exist or is of another file type.

This works the same as Perl's built-in -B file test operator, (see "-X" in perlfunc), it's just easier for some people to remember. This is an autoloaded method.

`last_access`

Syntax: last_access( [file name] ): Returns the last accessed time for the named file in non-leap seconds since whatever your system considers to be the epoch. Suitable for feeding to Perl's built-in functions "gmtime" and "localtime". (see "time" in perlfunc.) This is an autoloaded method.

`last_mod`

Syntax: last_mod( [file name] ): Returns the last modified time for the named file in non-leap seconds since whatever your system considers to be the epoch. Suitable for feeding to Perl's built-in functions "gmtime" and "localtime". (see "time" in perlfunc.) This is an autoloaded method.

`line_count`

Syntax: line_count( [file name] ): Returns the number of lines in the named file. Fails with an error if the named file does not exist.

`list_dir`

Syntax: list_dir( [directory name] , [--opts] ): -- Documentation for this method is not yet complete! --

`load_dir`

Syntax: load_dir( [directory name] , [--ds-type] )

Returns a data structure containing the contents of each file present in the named directory. This is an autoloaded method.

The type of data structure returned is determined by the optional data-type switch. Only one option may be used for a given call to this method. Recognized options are listed below.

--as-list: Causes the method to return a list comprised of the contents loaded from each file (in case-sensitive order) located in the named directory.
--as-listref: Same as above, except an array reference to the list of items is returned rather than the list itself.
--as-hashref *(default): Implicit. If no option is passed in, the default behavior is to return a reference to an anonymous hash whose keys are the names of each file in the specified directory; the hash values for contain the contents of the file represented by its corresponding key.

Note: This method does not distinguish between plain files and other file types such as binaries, FIFOs, sockets, etc.

Restrictions imposed by the current "read limit" (see the readlimit()) entry below will be applied to the files opened by this method as well. Adjust the readlimit as necessary.

   my($files) = $fu->load_dir('directory/to/load/');

The above code creates an anonymous hash reference that is stored in the variable named "$files". The keys and values of the hash referenced by "$files" would resemble those of the following code snippet (given that the files in the named directory were the files 'a.txt', 'b.html', 'c.dat', and 'd.conf')

   my($files) =
      {
         'a.txt'  => "the contents of file a.txt",
         'b.html' => "the contents of file b.html",
         'c.dat'  => "the contents of file c.dat",
         'd.conf' => "the contents of file d.conf",
      };

`load_file`

Syntax: load_file( [file name] , [--opts] ): -- Documentation for this method is not yet complete! --

`make_dir`

Syntax: make_dir( [new directory name] , [--opts] ): -- Documentation for this method is not yet complete! -- This is an autoloaded method.

`max_dives`

Syntax: max_dives( [integer] ): -- Documentation for this method is not yet complete! -- This is an autoloaded method.

`needs_binmode`

Syntax: needs_binmode: Returns 1 if the machine on which the code is running requires that binmode() (a built-in function) be called on open file handles, or returns 0 if not. (see "binmode" in perlfunc.) This is an autoloaded method. This is a constant subroutine. It accepts no arguments and will always return the same value for the system on which it is executed.

`new`

Syntax: new( [--opts] ): -- Documentation for this method is not yet complete! --

`open_handle`

Syntax: open_handle( [file name] , [--opts] ): -- Documentation for this method is not yet complete! -- This is an autoloaded method.

`readlimit`

Syntax: readlimit( [integer] ): -- Documentation for this method is not yet complete! -- This is an autoloaded method.

`size`

Syntax: size( [file name] ): -- Documentation for this method is not yet complete! -- This is an autoloaded method.

`strip_path`

Syntax: strip_path( [string] ): -- Documentation for this method is not yet complete! --

`trunc`

Syntax: trunc( [file name] ): -- Documentation for this method is not yet complete! -- This is an autoloaded method.

`use_flock`

Syntax: use_flock( [true / false value] ): -- Documentation for this method is not yet complete! -- This is an autoloaded method.

`write_file`

Syntax: write_file('file' = [file name], 'content' => [data], [--opts])>: -- Documentation for this method is not yet complete! --

`valid_filename`

Syntax: valid_filename( [string] ): -- Documentation for this method is not yet complete! --

CONSTANTS

`NL`

Syntax: NL: -- Documentation for this method is not yet complete! --

SL

Syntax: SL: -- Documentation for this method is not yet complete! --

EXPORT

None by default.

EXPORT_OK

bitmask
can_flock
can_read
can_write
ebcdic
escape_filename
existent
file_type
isbin
NL
needs_binmode
size
SL
strip_path
valid_filename
Symbols in @Class::OOorNO::EXPORT_OK are also available for import.

EXPORT_TAGS

   :all (exports all of @File::Util::EXPORT_OK)

PREREQUISITES

Perl 5.006 or better
Class::OOorNO v0.01_1 or better
Exception::Handler v1.00_0 or better

EXAMPLES

None at present.

BUGS

This documentation isn't done yet, as you can see. This is being rectified as quickly as possible. Please exercise caution if you choose to use this code before it can be further documented for you. Please excuse the inconvenience.

AUTHOR

Tommy Butler <cpan@atrixnet.com>

COPYRIGHT

LICENSE

This library is free software, you may redistribute and/or modify it under the same terms as Perl itself.

	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

IMPORTANT!

SYNOPSIS

DESCRIPTION

INSTALLATION

File::Util ISA

METHODS

bitmask

can_flock

can_read

can_write

created

ebcdic

escape_filename

existent

file_type

flock_rules

isbin

last_access

last_mod

line_count

list_dir

load_dir

load_file

make_dir

max_dives

needs_binmode

new

open_handle

readlimit

size

strip_path

trunc

use_flock

write_file

valid_filename