File::Util - Easy, versatile, portable file handling
version 4.132140
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.
After browsing this document, please have a look at the other documentation. (See DOCUMENTATION section below.)
# use File::Util in your program use File::Util; # create a new File::Util object my $f = File::Util->new(); # read file into a variable my $content = $f->load_file( 'some_file.txt' ); # write content to a file $f->write_file( 'some_other_file.txt' => 'Hello world!' ); # get the contents of a directory, 3 levels deep my @songs = $f->list_dir( '~/Music' => { recurse => 1, max_depth => 3 } );
You can do much more with File::Util than the examples above. For an explanation of all the features available to you, take a look at these other reference materials:
The File::Util::Manual::Examples document has a long list of small, reusable code snippets and techniques to use in your own programs. This is the "cheat sheet", and is a great place to get started quickly. Almost everything you need is here.
The File::Util::Manual is the complete reference document explaining every available feature and object method. Use this to look up the full information on any given feature when the examples aren't enough.
The File::Util::Cookbook contains examples of complete, working programs that use File::Util to easily accomplish tasks which require file handling.
# use File::Util in your program use File::Util; # ...you can optionally enable File::Util's diagnostic error messages: # (see File::Util::Manual section regarding diagnostics) use File::Util qw( :diag ); # create a new File::Util object my $f = File::Util->new(); # ...you can enable diagnostics for individual objects: $f = File::Util->new( diag => 1 );
# load content into a variable, be it text, or binary, either works my $content = $f->load_file( 'data.txt' ); # wrangle some text $content =~ s/this/that/g; # write a file with your changes $f->write_file( 'new_data.txt' => $content ); # try binary this time my $binary_content = $f->load_file( 'barking-cat.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( 'llama.jpg' => $picture_data => { binmode => 1, bitmask => oct 644 } ); # ...or write a file with UTF-8 encoding (unicode support) $f->write_file( 'encoded.txt' => qq(\x{c0}) => { binmode => 'utf8' } ); # load a file into an array, line by line my @lines = $f->load_file( 'file.txt' => { as_lines => 1 } ); # see if you have permission to write to a file, then append to it if ( $f->is_writable( 'captains.log' ) ) { my $fh = $f->open_handle( 'captains.log' => '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' );
# get an open file handle for reading my $fh = $f->open_handle( 'Ian likes cats.txt' => 'read' ); while ( my $line = <$fh> ) { # read the file, line by line # ... do stuff } # get an open file handle for writing the same way $fh = $f->open_handle( 'John prefers dachshunds.txt' => 'write' ); # You add the option to turn on UTF-8 strict encoding for your reads/writes $fh = $f->open_handle( 'John prefers dachshunds.txt' => 'write' => { binmode => 'utf8' } ); print $fh "Bob is happy! \N{U+263A}"; # << unicode smiley face! # you can use sysopen to get low-level with your file handles if needed $fh = $f->open_handle( 'alderaan.txt' => 'rwclobber' => { use_sysopen => 1 } ); syswrite $fh, "that's no moon"; # ...you can use any of these syswrite modes, also with { binmode => 'utf8' } # read, write, append, rwcreate, rwclobber, rwappend, rwupdate, and trunc
# 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 $f->list_dir( '/home/larry' => { recurse => 1, callback => sub { my ( $selfdir, $subdirs, $files ) = @_; # do stuff ... }, } ); # get an entire directory tree as a hierarchal datastructure reference my $tree = $f->list_dir( '/my/podcasts' => { as_tree => 1 } );
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->is_bin( 'my.file' ); print 'My file was last modified on ' . scalar localtime $f->last_modified( 'my.file' );
# Does your running Perl support unicode? print 'I support unicode' if $f->can_utf8; # Can your system use file locking? print 'I can use flock' if $f->can_flock; # The correct directory separator for your system print 'The correct directory separator for this system is ' . $f->SL; # Does your platform require binmode for all IO? print 'I always need binmode' if $f->needs_binmode; # Is your system an EBCDIC platform? (see perldoc perlebcdic) print 'This is an EBCDIC platform, so be careful!' if $f->EBCDIC;
...See the File::Util::Manual for more details and features like advanced pattern matching in directories, callbacks, directory walking, user-definable error handlers, and more.
File::Util consists of several modules, but only loads the ones it needs when it needs them and also offers a comparatively fast load-up time, so using File::Util doesn't bloat your code footprint.
Additionally, File::Util has been optimized to run fast. In many scenarios it does more and still out-performs other popular IO modules from anywhere from 100%-400%, although Path::Tiny is also extremely fast at what it is designed to do.
(See the benchmarking and profiling scripts that are included as part of this distribution.)
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 for HTML POD readers. For those viewing this document in a text terminal, open perldoc to the File::Util::Manual.
File::Util::Manual
Exports nothing by default. File::Util fully respects your namespace. You can, however, ask it for certain things (below).
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.
@File::Util::EXPORT_OK
- atomize_path - can_flock - can_utf8 - created - diagnostic - ebcdic - escape_filename - existent - file_type - is_bin - is_readable - is_writable - last_access - last_changed - last_modified - needs_binmode - return_path - size - split_path - strip_path - valid_filename - NL and S L
To get any of these functions/symbols into your namespace without having to use them as object methods, use this kind of syntax:
use File::Util qw( strip_path return_path existent size ); my $file = $ARGV[0]; my $fname = strip_path( $file ); my $path = return_path( $file ); my $size = size( $file ); print qq(File "$fname" exists in "$path", and is $size bytes in size) if existent( $file );
:all (imports all of @File::Util::EXPORT_OK to your namespace) :diag (imports nothing to your namespace, it just enables diagnostics)
You can use these tags alone, or in combination with other symbols as shown above.
File::Util only depends on modules that are part of the Core Perl distribution, and you don't need a compiler on your system to install it.
You can technically run File::Util on older versions of Perl 5, but it isn't recommended, especially if you want unicode support and wish to take advantage of File::Util's ability to read and write files using UTF-8 encoding.
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
Send bug reports and patches to the CPAN Bug Tracker for File::Util at rt.cpan.org
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.
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.
The following people have contributed to File::Util in the form of feedback, encouragement, recommendations, testing, or assistance with problems either on or offline in one form or another. Listed in no particular order:
John Fields <jfields.cpan.org@spammenot.com>
BrowserUk <browseruk@cpan.org>
Ricardo SIGNES <rjbs@cpan.org>
Matt S Trout <perl-stuff@trout.me.uk>
Nicholas Perez <nperez@cpan.org>
David Golden <dagolden@cpan.org>
Tommy Butler http://www.atrixnet.com/contact
Others Welcome!
Copyright(C) 2001-2013, Tommy Butler. All rights reserved.
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.
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.
This disclaimer applies to every part of the File::Util distribution.
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, File::Find::Rule, Path::Class, Path::Tiny
To install File::Util, copy and paste the appropriate command in to your terminal.
cpanm
cpanm File::Util
CPAN shell
perl -MCPAN -e shell install File::Util
For more information on module installation, please visit the detailed CPAN module installation guide.