/ 
File-Util-4.130420-TRIAL
River stage two • 12 direct dependents • 13 total dependents
/ File::Util

NAME

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

VERSION

version 4.130420

DESCRIPTION

File::Util provides a comprehensive toolbox of utilities to automate all kinds of common tasks on files and 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 operating systems and/or architectures. It works on Linux, Windows, Mac, BSD, Unix and others.

File::Util is written purely in Perl, and requires no compiler or make utility on your system in order to install and run it.

File::Util also aims to be as backward compatible as possible, running without problems on Perl installations as old as 5.006. You are encouraged to run File::Util on Perl version 5.8 and above.

SYNOPSIS

# use File::Util in your program
use File::Util;

# ...you can optionally enable File::Util's diagnostic error messages:
use File::Util qw( :diag );

# create a new File::Util object
my $f = File::Util->new();

# ...or if you want to enable diagnostics on a per-object basis instead:
$f = File::Util->new( diag => 1 );

# load content into a variable, be it text, or binary, either works
my $content = $f->load_file( 'Meeting Notes.txt' );

# ...or if you only want diagnostic error messages on a per-call basis:
$content = $f->load_file( 'Meeting Notes.txt' => { diag => 1 } );

# wrangle text
$content =~ s/this/that/g;

# re-write the file with your changes
$f->write_file(
   file => 'Meeting Notes.txt',
   content => $content,
);

# try binary this time
my $binary_content = $f->load_file( 'cat-movie.avi' );

# get some image data from somewhere...
my $picture_data = get_image_upload();

# ...and write a binary image file, using some other options as well
$f->write_file(
   file => 'llama.jpg',
   content => $picture_data,
   { binmode => 1, bitmask => oct 644 }
);

# load a file into an array, line by line
my @lines = $f->load_file( 'file.txt' => { as_lines => 1 } );

# get an open file handle for reading
my $fh = $f->open_handle( file => 'Ian likes cats.txt', mode => 'read' );

while ( my $line = <$fh> ) { # read the file, line by line

   # ... do stuff
}

close $fh or die $!; # don't forget to close ;-)

# get an open file handle for writing
$fh = $f->open_handle(
   file => 'John prefers dachshunds.txt',
   mode => 'write'
);

print $fh 'Shout out to Bob!';

close $fh or die $!; # _never_ forget to close ;-)

# get a listing of files, recursively, skipping directories
my @files = $f->list_dir( '/var/tmp' => { files_only => 1, recurse => 1 } );

# get a listing of text files, recursively
my @textfiles = $f->list_dir(
   '/var/tmp' => {
      files_match => qr/\.txt$/,
      files_only  => 1,
      recurse     => 1,
   }
);

# walk a directory, using an anonymous function or function ref as a
# callback (higher order Perl)
$f->list_dir( '/home/larry' => {
   recurse  => 1,
   callback => sub {
      my ( $selfdir, $subdirs, $files ) = @_;

      print "In $selfdir there are...\n";

      print scalar @$subdirs . " subdirectories, and ";
      print scalar @$files   . " files\n";

      for my $file ( @$files ) {

         # ... do something with $file
      }
   },
} );

# get an entire directory tree as a hierarchal datastructure reference
my $tree = $f->list_dir( '/my/podcasts' => { as_tree => 1 } );

# see if you have permission to write to a file, then append to it
# using an auto-flock'd filehandle (for operating systems that support flock)
# ...you can also use the write_file() method in append mode as well...

if ( $f->can_write( 'captains.log' ) ) {

   my $fh = $f->open_handle(
      file => 'captains.log',
      mode => 'append'
   );

   print $fh "Captain's log, stardate 41153.7.  Our destination is...";

   close $fh or die $!;
}
else { # ...or warn the crew

   warn "Trouble on the bridge, the Captain can't access his log!";
}

# get the number of lines in a file
my $log_line_count = $f->line_count( '/var/log/messages' );

# the next several examples show how to get different information about files

print "My file has a bitmask of " . $f->bitmask( 'my.file' );

print "My file is a " . join(', ', $f->file_type( 'my.file' )) . " file.";

warn 'This file is binary!' if $f->isbin( 'my.file' );

print 'My file was last modified on ' .
   scalar localtime $f->last_modified( 'my.file' );

...and _lots_ more, See the File::Util::Manual for more details and more features

INSTALLATION

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

perl Build.PL
perl Build
perl Build test
sudo perl Build install

On Windows systems, the "sudo" part of the command may be omitted, but you will need to run the rest of the install command with Administrative privileges

DOCUMENTATION

There's more than just this document! Take a look at the File::Util::Manual, the File::Util::Manual::Examples, and the File::Util::Cookbook.

METHODS

File::Util exposes the following public methods.

Each of which are covered in the File::Util::Manual, which has more room for the detailed explanation that is provided there.

This is just an itemized table of contents.

atomize_path (see atomize_path)
bitmask (see bitmask)
can_flock (see can_flock)
can_read (see can_read)
can_write (see can_write)
created (see created)
diagnostic (see diagnostic)
ebcdic (see ebcdic)
escape_filename (see escape_filename)
existent (see existent)
file_type (see file_type)
flock_rules (see flock_rules)
isbin (see isbin)
last_access (see last_access)
last_changed (see last_changed)
last_modified (see last_modified)
line_count (see line_count)
list_dir (see list_dir)
load_dir (see load_dir)
load_file (see load_file)
make_dir (see make_dir)
max_dives (see max_dives)
needs_binmode (see needs_binmode)
new (see new)
open_handle (see open_handle)
readlimit (see readlimit)
return_path (see return_path)
size (see size)
split_path (see split_path)
strip_path (see strip_path)
touch (see touch)
trunc (see trunc)
unlock_open_handle (see unlock_open_handle)
use_flock (see use_flock)
valid_filename (see valid_filename)
write_file (see write_file)

EXPORTED SYMBOLS

Exports nothing by default. File::Util fully respects your namespace. You can, however, ask it for certain things (below).

@EXPORT_OK

The following symbols comprise @File::Util::EXPORT_OK), and as such are available for import to your namespace only upon request. They can be used either as object methods or like regular subroutines in your program.

To get any of these functions/symbols into your namespace without having to use them as an object method, use this kind of syntax:

use File::Util qw( strip_path NL );

atomize_path

can_flock

can_read

can_write

created

diagnostic

ebcdic

escape_filename

existent

file_type

isbin

last_access

last_changed

last_modified

NL

needs_binmode

return_path

size

SL

split_path

strip_path

valid_filename

EXPORT_TAGS

:all (imports all of @File::Util::EXPORT_OK to your namespace)

use File::Util qw( :all ); # seldom if ever necessary, but it's an option

PREREQUISITES

Exception::Handler

For graceful and helpful error handling

Scalar::Util

For tools that support the better call interface in File::Util versions 4.x and higher

Perl 5.006 or better ...

This requirement will increase soon with the advent of unicode support

EXAMPLES

See File::Util::Manual

EXAMPLES (Full Programs)

See File::Util::Cookbook

BUGS

Send bug reports and patches to the CPAN Bug Tracker for File::Util at https://rt.cpan.org/Dist/Display.html?Name=File%3A%3AUtil

SUPPORT

If you want to get help, contact the authors (links below in AUTHORS section)

I fully endorse http://www.perlmonks.org as an excellent source of help with Perl in general.

CONTRIBUTING

The project website for File::Util is at https://github.com/tommybutler/file-util/wiki

The git repository for File::Util is on Github at https://github.com/tommybutler/file-util

Clone it at git://github.com/tommybutler/file-util.git

This project was a private endeavor for too long so don't hesitate to pitch in. I want to say I very much appreciate the emails, bug reports, patches, and all those who contribute their time and talents as CPAN testers.

AUTHORS

Tommy Butler http://www.atrixnet.com/contact

Others Welcome!

COPYRIGHT

Copyright(C) 2001-2013, Tommy Butler. All rights reserved.

LICENSE

This library is free software, you may redistribute it and/or modify it under the same terms as Perl itself. For more details, see the full text of the LICENSE file that is included in this distribution.

LIMITATION OF WARRANTY

This software is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.

SEE ALSO

The rest of the documentation: File::Util::Manual, File::Util::Manual::Examples, File::Util::Cookbook,

Other Useful Modules that do similar things: File::Slurp, File::Spec, Path::Class