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

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

       Others Welcome!

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

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

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

   GettingInformationAboutFiles
          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' );

   GettingInformationAboutYourSystem'sIOCapabilities
          # 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.

   FileEncodingandUTF-8
       If you want to read/write in UTF-8, you can do that:

          $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)' withENCODING'slikeiso-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.

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

       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>

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

       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 purelyinPerl, and requires no compiler or make utility on your system in order to
       install and run it.  It loads a minimal amount of code when used, only pulling in support for lesser-used
       methods on demand.  It has no dependencies other than what comes installed with Perl itself.

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

       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:

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

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

       Cookbook
           The  File::Util::Cookbook  contains  examples  of  complete,  working programs that use File::Util to
           easily accomplish tasks which require file handling.

       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.

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

       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

       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.

       File::Util exposes the following public methods.

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

       atomize_path         (seeatomize_path)
       bitmask              (seebitmask)
       can_flock            (seecan_flock)
       can_utf8             (seecan_utf8)
       created              (seecreated)
       default_path         (seedefault_path)
       diagnostic           (seediagnostic)
       ebcdic               (seeebcdic)
       escape_filename      (seeescape_filename)
       existent             (seeexistent)
       file_type            (seefile_type)
       flock_rules          (seeflock_rules)
       is_bin               (seeis_bin)
       is_readable          (seeis_readable)
       is_writable          (seeis_writable)
       last_access          (seelast_access)
       last_changed         (seelast_changed)
       last_modified        (seelast_modified)
       line_count           (seeline_count)
       list_dir             (seelist_dir)
       load_dir             (seeload_dir)
       load_file            (seeload_file)
       make_dir             (seemake_dir)
       abort_depth          (seeabort_depth)
       needs_binmode        (seeneeds_binmode)
       new                  (seenew)
       onfail               (seeonfail)
       open_handle          (seeopen_handle)
       read_limit           (seeread_limit)
       return_path          (seereturn_path)
       size                 (seesize)
       split_path           (seesplit_path)
       strict_path          (seestrict_path)
       strip_path           (seestrip_path)
       touch                (seetouch)
       trunc                (seetrunc)
       unlock_open_handle   (seeunlock_open_handle)
       use_flock            (seeuse_flock)
       valid_filename       (seevalid_filename)
       write_file           (seewrite_file)

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

       File::Util consists of a set of smaller modules, but only loads the ones it needs when it needs them.  It
       offers  a  comparatively  fast  load-up  time,  so  using  File::Util  doesn't bloat your code's resource
       footprint.

       Additionally, File::Util has been optimized to run fast.  In many scenarios it does more and  still  out-
       performs  other  popular  IO  modules.   Benchmarking  tools  are  included  as  part  of  the File::Util
       installation package.

       (Seethebenchmarkingandprofilingscriptsthatareincludedaspartofthisdistribution.)

       None.  There are no external prerequisite modules.
           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.

       File::Util recommends Perl 5.8.1 or better ...
           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.

           Unicode::UTF8  is also recommended and helps speed things up in several places where you might choose
           to use unicode as described elsewhere in the File::Util::Manual.

       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

perl v5.36.0                                       2022-11-29                                    File::Util(3pm)

       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.

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

       version 4.201720