Provided by: libfile-util-perl_4.201720-2_all bug

NAME

       File::Util::Manual::Examples - File::Util Examples

VERSION

       version 4.201720

INTRODUCTION

       This manual subsection is fully comprised of simple examples of File::Util in greater
       depth than what you see in the main documentation, however to keep things simple, these
       examples are short, quick, and to the point.

       For examples of full Programs using File::Util, take a look at the Cookbook at the
       File::Util::Cookbook.

EXAMPLES

       Many of these are demonstrated in the standalone scripts that come in the "examples"
       directory as part of this distribution.

       Unless indicated otherwise, all of these short examples assume that you have started out
       with:

          use File::Util;
          my $f = File::Util->new();

       The variable $f is used for simplicity here in the examples.  In your actual programming
       you should refrain from using single-letter variables and use something more obvious
       instead, such as $ftl or $futil

   Get the contents of a file in a string
          my $contents = $f->load_file( 'filename' );


             -OR-
          my $contents = $f->load_file( '/path/to/filename' );


             -OR-
          my $contents = $f->load_file( 'C:\path\to\filename' );

   Get the contents of a UTF-8 encoded file in a UTF-8 encoded string
          my $encoded_data = $f->load_file( 'encoded.txt' => { binmode => 'utf8' } );

   Get the contents of a file in an array of lines in the file
          my @contents = $f->load_file( 'filename' => { as_lines => 1 } );

   Get an open file handle for reading
          my $fh = $f->open_handle(
             file => '/some/existing/file',
             mode => 'read'
          );


             -OR-
          # ... you can also use the shorter syntax:
          my $fh = $f->open_handle( '/some/existing/file' => 'read' );

          # ... you can open a file handle to a UTF-8 encoded file too
          my $fh = $f->open_handle( 'encoded.txt' => 'read' => { binmode => 'utf8' } );

          # then use the filehandle like you would use any other file handle:
          while ( my $line = <$fh> ) {

             # ... do stuff with $line
          }

          close $fh or die $!;

   Get an open file handle for writing
       Opening a file for writing (write mode) will create the file if it doesn't already exist.
       The file handle is automatically locked for you with flock() if your system supports it.

          my $fh = $f->open_handle(
             file => '/some/file',
             mode => 'write'
          );


             -OR-
          # ... you can also use the shorter syntax:
          my $fh = $f->open_handle( '/some/file' => 'write' );

          # ... you can open a file handle with UTF-8 encoding support
          my $fh = $f->open_handle( '/some/file' => 'write' => { binmode => 'utf8' } );

          print $fh 'Hello world!';

          close $fh or die $!;

   Write to a new or existing file
          my $content = 'Pathelogically Eclectic Rubbish Lister';

          $f->write_file( file => 'a new file.txt', content => $content );


             -OR-
          # you can use the shorter syntax:
          $f->write_file( 'a new file.txt' => $content );


             -OR-
          # write UTF-8 encoded data also.  the file will have UTF-8 encoding:
          $f->write_file( 'encoded.txt' => $encoded_data => { binmode => 'utf8' } );

       You can optionally specify a bitmask for a file if it doesn't exist yet.  The bitmask is
       combined with the user's current umask for the creation mode of the file.  (You should
       usually omit this.)

          $f->write_file(
             file    => 'C:\some\new\file.txt',
             content => $content
             bitmask => oct 777,
          );


             -OR-
          $f->write_file( 'file.txt' => $content => { bitmask => oct 777 } );

   Warn if the file couldn't be written, instead of dying by default
          $f->write_file(
             'file.txt' => $content,
             {
                onfail  => 'warn',
                bitmask => oct 777
             }
          );

   Conceal the error if the file couldn't be written (secure), but log it too
          # define a custom (secure) error handler

          $f->write_file(
             'file.txt' => $content =>
             {
                bitmask => oct 777
                onfail  => sub {
                   my ( $err, $stack ) = @_;

                   # send the error message and stack trace to a logger of some kind...
                   $logger->log( $err . $stack );

                   # or send an email alert?
                   send_email_alert_to_admin( $err ); #<< you'll have to write that sub

                   # return undef to indicate a problem (or you could die/exit too)
                   return;
                }
             }
          );

   Why not first check if the file is writeable/can be created
          if ( $f->is_writable( '/root/some/file.txt' ) ) {

             # ... now create/write to the file
          }

   Append to a new or existing file
          my $content = 'The fastest hunk of junk in the galaxy';

          $f->write_file(
             file    => 'mfalcon.spec',
             mode    => 'append',
             content => $content
          );


             -OR-
          $f->write_file( 'mfalcon.spec' => $content => { mode => 'append' } );

   Get the names of all files and subdirectories in a directory
          # option no_fsdots excludes "." and ".." from the list
          my @dirs_and_files = $f->list_dir( '/foo' => { no_fsdots => 1 } );

   Get the names of all files and subdirectories in a directory, recursively
          my @dirs_and_files = $f->list_dir( '/foo' => { recurse => 1 } );

   Do the same as above, but only to a certain maximum depth
          my @dirs_and_files =
             $f->list_dir( '/foo' => { recurse => 1, max_depth => 3 } );

   Do the same, but ignore potential filesystem loops for a speed boost
          my @dirs_and_files =
             $f->list_dir( '/foo' => { recurse_fast => 1, max_depth => 3 } );

   Get the names of all files (no subdirectories) in a directory
          my @dirs_and_files = $f->list_dir( '/foo' => { files_only => } );

   Get the names of all subdirectories (no files) in a directory
          my @dirs_and_files = $f->list_dir( '/foo' => { dirs_only => 1 } );

   Get the number of files and subdirectories in a directory
          my @dirs_and_files = $f->list_dir(
             '/foo' => { no_fsdots => 1, count_only => 1 }
          );

   Get the names of files and subdirs in a directory as separate array refs
          my( $dirs, $files ) = $f->list_dir( '/foo' => { as_ref => 1 } );


             -OR-
          my( $dirs, $files ) = $f->list_dir(
             '/foo' => { dirs_as_ref => 1, files_as_ref => 1 }
          );

   Load all the files in a directory into a hashref
          my $templates = $f->load_dir( '/var/www/mysite/templates' );

          # $templates now contains something like:
          # {
          #    'header.html' => '...file contents...',
          #    'body.html'   => '...file contents...',
          #    'footer.html' => '...file contents...',
          # }

          print $templates->{'header.html'};

   Recursively Get the names of all files that end in '.pl'
          my @perl_files = $f->list_dir(
             '/home/scripts' => { files_match => qr/\.pl$/, recurse => 1 }
          }

   Recursively get the names of all files that do NOT end in '.pl'
       File::Util's "list_dir()" method doesn't have a "not_matches" counterpart to the
       "files_match" parameter.  This is because it doesn't need one.  Perl already provides
       native support for negation in regular expressions.  The example below shows you how to
       make sure a file does NOT match the pattern you provide as a subexpression in a "negative
       zero width assertion".

       It might sound complicated for a beginner, but it's really not that hard.

       See the perlre documentation for more about negation in regular expressions.

          # find all files that don't end in ".pl"
          my @other_files = $f->list_dir(
             '/home/scripts' => { files_match => qr/^(?!.*\.pl$)/, recurse => 1 }
          }

   Combine several options for list_dir() and be awesome
       Find all files (not directories) that matches *any* number of given patterns (OR), whose
       parent directory matches *every* pattern in a list of given patterns (AND).  Also make
       sure that the path to the files matches a list of patterns (AND).

          # find the droids I'm looking for...
          my @files = $f->list_dir(
             '/home/anakin' => {
                files_match    => { or  => [ qr/droid/, qr/3p(o|O)$/i, qr/^R2/ },
                parent_matches => { and => [ qr/vader/i, qr/darth/i ] },
                path_matches   => { and => [ qr/obi-wan/i, qr/^(?!.*Qui-Gon)/ ] },
                recursive      => 1,
                files_only     => 1,
                max_depth      => 8,
             }
          );

       The above example would find and return files like:

          /home/anakin/mentors/obi-wan/villains/darth-vader/R2.png
          /home/anakin/mentors/obi-wan/villains/darth-vader/C3P0.dict
          /home/anakin/mentors/obi-wan/villains/darth-vader/my_droids.list

       But would not return files like:

          /home/anakin/mentors/Qui-Gon Jinn/villains/darth-vader/my_droids.list

   Use a callback to descend through (walk) a directory tree
       This is a really powerful feature. Because File::Util::list_dir() is a higher order
       function, it can take other functions as arguments.  We often refer to these as
       "callbacks".

       Any time you specify a callback, File::Util will make sure it's first argument is the name
       if the directory it's in (recursion), and then the second and third arguments are
       listrefs.  The first is a list reference containing the names of all subdirectories, and
       the second list ref contains the names of all the files.

       Below is a very simple example that doesn't really do much other than demonstrate the
       syntax.  You can see more full-blown examples of callbacks in the File::Util::Cookbook

          # print all subdirectories under /home/larry/
          $f->list_dir(
             '/home/larry' => {
                callback => sub { print shift @_, "\n" },
                recurse  => 1,
             }
          }

   Get a directory tree in a hierarchical hashref
          my $tree = $f->list_dir( '/tmp' => { as_tree => 1, recurse => 1 } );

          Gives you a datastructure like:
          {
            '/' => {
                     '_DIR_PARENT_' => undef,
                     '_DIR_SELF_' => '/',
                     'tmp' => {
                                '_DIR_PARENT_' => '/',
                                '_DIR_SELF_' => '/tmp',
                                'hJMOsoGuEb' => {
                                                  '_DIR_PARENT_' => '/tmp',
                                                  '_DIR_SELF_' => '/tmp/hJMOsoGuEb',
                                                  'a.txt' => '/tmp/hJMOsoGuEb/a.txt',
                                                  'b.log' => '/tmp/hJMOsoGuEb/b.log',
                                                  'c.ini' => '/tmp/hJMOsoGuEb/c.ini',
                                                  'd.bat' => '/tmp/hJMOsoGuEb/d.bat',
                                                  'e.sh' => '/tmp/hJMOsoGuEb/e.sh',
                                                  'f.conf' => '/tmp/hJMOsoGuEb/f.conf',
                                                  'g.bin' => '/tmp/hJMOsoGuEb/g.bin',
                                                  'h.rc' => '/tmp/hJMOsoGuEb/h.rc',
                                                }
                              }
                   }
          }

       *You can add the "dirmeta" option, set to 0 (false), to remove the special entries
       "_DIR_PARENT_" and "_DIR_SELF_" from each subdirectory branch.

       Example:

          my $tree = $f->list_dir(
             '/tmp' => { as_tree => 1, dirmeta => 0, recurse => 1 }
          );

       *You can still combine the "as_tree" option with other options, such as the regex pattern
       matching options covered above, or options like "recurse", or "files_only".

       *You should be careful using this feature with very large directory trees, due to the
       memory it might consume.  Memory usage is generally low, but will grow when you use this
       feature for larger and larger directory trees.  Bear in mind that the $ABORT_DEPTH limit
       applies here too (see File::Util documentation), which you can override manually by
       setting the "abort_depth" option:

          # set max recursion limit to an integer value as shown below
          $f->list_dir( '/tmp' => { as_tree => 1, recurse => 1, abort_depth => 123 } );

   Determine if something is a valid file name
       NOTE: This method is for determining if a file name  is valid.  It does not determine if a
       full path is valid.

          print $f->valid_filename( 'foo?+/bar~@/#baz.txt' ) ? 'ok' : 'bad';


             -OR-
          print File::Util->valid_filename( 'foo?+/bar~@/#baz.txt' ) ? 'ok' : 'bad';

       Like many other methods in File::Util, you can import this into your own namespace so you
       can call it like any other function, avoid the object-oriented syntax when you don't want
       or need it:  (This manual doesn't duplicate the main documentation by telling you every
       method you can import -- see the @EXPORT_OK section of the File::Util documentation)

          use File::Util qw( valid_filename );

          if ( valid_filename( 'foo?+/bar~@/#baz.txt' ) )
          {
             print 'file name is valid';
          }
          else
          {
             print 'That file name contains illegal characters';
          }

   Get the number of lines in a file
          my $linecount = $f->line_count( 'foo.txt' );

   Split a file path into its parts
       This method works differently than atomize_path().  With this method, you get not just the
       components of the path, but each element in the form of a list.  The path will be split
       into the following pieces: (path root, if it exists, each subdirectory in the path, and
       the final file/directory )

          use File::Util qw( split_path );

          print "$_\n" for split_path( q{C:\foo\bar\baz\flarp.pl} )


             -OR-
          print "$_\n" for $f->split_path( q{C:\foo\bar\baz\flarp.pl} )


             -OR-
          print "$_\n" for File::Util->split_path( q{C:\foo\bar\baz\flarp.pl} )

          The output of all of the above commands is:
             C:\
             foo
             bar
             baz
             flarp.pl

       Above you see examples working on Windows-type paths.  Below are some examples using
       *nix-style paths:

          print "$_\n" for split_path( '/I/am/your/father/NOOOO' )

          The output of all of the above commands is:
             /
             I
             am
             your
             father
             NOOOO

   Strip the path from a file name
          # On Windows
          #  (prints "hosts")
          my $path = $f->strip_path( 'C:\WINDOWS\system32\drivers\etc\hosts' );

          # On Linux/Unix
          #  (prints "perl")
          print $f->strip_path( '/usr/bin/perl' );

          # On a Mac
          #  (prints "baz")
          print $f->strip_path( 'foo:bar:baz' );


             -OR-
          use File::Util qw( strip_path );

          print strip_path( '/some/file/name' ); # prints "name"

   Get the path preceding a file name
          # On Windows
          #  (prints "C:\WINDOWS\system32\drivers\etc")
          my $path = $f->return_path( 'C:\WINDOWS\system32\drivers\etc\hosts' );

          # On Linux/Unix
          #  (prints "/usr/bin")
          print $f->return_path( '/usr/bin/perl' );

          # On a (very, very old) Mac
          #  (prints "foo:bar")
          print $f->return_path( 'foo:bar:baz' );

   Find out if the host system can use flock
          use File::Util qw( can_flock );
          print can_flock;


             -OR-
          print File::Util->can_flock;


             -OR-
          print $f->can_flock;

   Find out if the host system needs to call binmode on binary files
          use File::Util qw( needs_binmode );
          print needs_binmode;


             -OR-
          print File::Util->needs_binmode;


             -OR-
          print $f->needs_binmode;

   Find out if a file can be opened for read (based on file permissions)
          my $is_readable = $f->is_readable( 'foo.txt' );

   Find out if a file can be opened for write (based on file permissions)
          my $is_writable = $f->is_writable( 'foo.txt' );

   Escape illegal characters in a potential file name (and its path)
          # prints "C__WINDOWS_system32_drivers_etc_hosts"
          print $f->escape_filename( 'C:\WINDOWS\system32\drivers\etc\hosts' );

          # prints "baz)__@^"
          # (strips the file path from the file name, then escapes it
          print $f->escape_filename( '/foo/bar/baz)?*@^' => { strip_path => 1 } );

          # prints "_foo_!_@so~me#illegal$_file&(name"
          # (yes, technically that is a legal filename)
          print $f->escape_filename( q{\foo*!_@so~me#illegal$*file&(name} );

   Find out if the host system uses EBCDIC
          use File::Util qw( ebcdic );
          print ebcdic;


             -OR-
          print File::Util->ebcdic;


             -OR-
          print $f->ebcdic;

   Get the type(s) of an existent file
          use File::Util qw( file_type );
          print file_type( 'foo.exe' );


             -OR-
          print File::Util->file_type( 'bar.txt' );


             -OR-
          print $f->file_type( '/dev/null' );

   Get the bitmask of an existent file
          use File::Util qw( bitmask );
          print bitmask( '/usr/sbin/sendmail' );


             -OR-
          print File::Util->bitmask( 'C:\COMMAND.COM' );


             -OR-
          print $f->bitmask( '/dev/null' );

   Get time of creation for a file
          use File::Util qw( created );
          print scalar localtime created( '/usr/bin/exim' );


             -OR-
          print scalar localtime File::Util->created( 'C:\COMMAND.COM' );


             -OR-
          print scalar localtime $f->created( '/bin/less' );

   Get the last access time for a file
          use File::Util qw( last_access );
          print scalar localtime last_access( '/usr/bin/exim' );


             -OR-
          print scalar localtime File::Util->last_access( 'C:\COMMAND.COM' );


             -OR-
          print scalar localtime $f->last_access( '/bin/less' );

   Get the inode change time for a file
          use File::Util qw( last_changed );
          print scalar localtime last_changed( '/usr/bin/vim' );


             -OR-
          print scalar localtime File::Util->last_changed( 'C:\COMMAND.COM' );


             -OR-
          print scalar localtime $f->last_changed( '/bin/cpio' );

   Get the last modified time for a file
          use File::Util qw( last_modified );
          print scalar localtime last_modified( '/usr/bin/exim' );


             -OR-
          print scalar localtime File::Util->last_modified( 'C:\COMMAND.COM' );


             -OR-
          print scalar localtime $f->last_modified( '/bin/less' );

   Make a new directory, recursively if necessary
          $f->make_dir( '/var/tmp/tempfiles/foo/bar/' );

          # you can optionally specify a bitmask for the new directory.
          # the bitmask is combined with the user's current umask for the creation
          # mode of the directory.  (You should usually omit this.)

          $f->make_dir( '/var/tmp/tempfiles/foo/bar/', 0755 );

   Touch a file
          use File::Util qw( touch );
          touch( 'somefile.txt' );


             -OR-
          $f->touch( '/foo/bar/baz.tmp' );

   Truncate a file
          $f->trunc( '/wibble/wombat/noot.tmp' );

   Get the correct path separator for the host system
          use File::Util qw( SL );
          print SL;


             -OR-
          print File::Util->SL;


             -OR-
          print $f->SL;

   Get the correct newline character for the host system
          use File::Util qw( NL );

          print NL;


             -OR-
          print File::Util->NL;


             -OR-
          print $f->NL;

   Choose what to do if there's a problem (die, warn, zero, undefined, subref)
          # When doing things with IO that might fail, set up good error handlers

          # "Fail, these examples will..."

          # If this call fails, die with an error message (*default*)
          $f->write_file( 'bobafett.txt' => $content => { onfail => 'die' } );

          # If this call fails, issue a warning to STDERR, but don't die/exit
          $f->list_dir( '/home/greivous' => { onfail => 'warn' } );

          # If this call fails, return a zero value (0), and don't die/exit
          $f->open_handle( '/home/ventress/.emacs' => { onfail => 'zero' } );

          # If this call fails, return undef, and don't die/exit
          $f->load_file( '/home/vader/darkside.manual' => { onfail => 'undefined' } );

          # If this call fails, execute the subroutine code and do whatever it says
          # This code tries to load one directory, and failing that, loads another
          $f->load_dir( '/home/palpatine/lofty_plans/' => {
                onfail => sub { return $f->load_dir( '/home/sidious/evil_plots/' ) }
             }
          );

AUTHORS

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

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

       File::Util::Manual, File::Util::Cookbook