Getting Started

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

File Operations

   # load file content into a scalar variable as raw text
   my $content = $f->load_file( 'somefile.txt' );

   # read a binary file the same way
   my $binary_content = $f->load_file( 'barking-cat.mp4' );

   # write a raw text file
   $f->write_file( 'somefile.txt' => $content );

   # ...and write a binary 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' );

File Handles

   # 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 with open_handle():
   # read, write, append, rwcreate, rwclobber, rwappend, rwupdate, and trunc

PLEASE NOTE that as of Perl 5.23, it is deprecated to mix system IO (sysopen/syswrite/sysread/sysseek) with utf8 binmode (see perldoc perlport). As such, File::Util will no longer allow you to do this after version 4.132140. Please see notes on UTF-8 and encoding further below.

   # ...THIS WILL NOW FAIL!
   $f->open_handle(
      'somefile.txt' => 'write' => { use_sysopen => 1, binmode => 'utf8' }
   );

Directories

   # 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 } );

Getting 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->is_bin( 'my.file' );

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

Getting Information About Your System's IO Capabilities

   # 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 Encoding and UTF-8

   $ftl->load_file( 'file.txt' => $content => { binmode => 'utf8' } );

   $ftl->write_file( 'file.txt' => $content => { binmode => 'utf8' } );

   $ftl->open_handle( 'file.txt' => 'read' => { binmode => 'utf8' } );

   # ...and so on

Only use "binmode => 'utf8'" for text.

Encoding and IO layers (sometimes called disciplines) can become complex. It's not something you usually need to worry about unless you wish to really fine tune File::Util's behavior beyond what are very suitable, portable defaults, or accomplish very specific tasks like encoding conversions.

You're free to specify any binmode you like, or allow File::Util to use the system's default IO layering. It will automatically use the ":raw" pseudo layer when reading files that are binary, unless specifically told to use something different.

You can control things as shown in the examples below:

   $ftl->load_file( 'file.txt' => $content => { binmode => SPEC } );

   $ftl->write_file( 'file.txt' => $content => { binmode => SPEC } );

   $ftl->open_handle( 'file.txt' => 'read' => { binmode => SPEC } );

...where "SPEC" is one or more of any supported IO layers on your system. Examples might include:

• ':raw'
• ':unix'
• ':crlf'
• ':stdio'
• ':encoding(ENCODING)' with ENCODING's like iso-8859-1, shiftjis, etc
• ...and much more

You can learn about the IO layers available to you and what they do in the PerlIO perldoc. Available options have increased over the years, and are likely subject to continued evolution. Consult the PerlIO and Encode documentation as your authoritative source of info on what layers to use.

EXPORT_OK

   -  atomize_path      -  can_flock         -  can_utf8
   -  created           -  default_path      -  diagnostic
   -  ebcdic            -  escape_filename   -  existent
   -  file_type         -  is_bin            -  is_readable
   -  is_writable       -  last_access       -  last_changed
   -  last_modified     -  needs_binmode     -  strict_path
   -  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 );

EXPORT_TAGS

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