libfile-util-perl 4.132140-2 / usr / share / perl5 / File / Util / Manual.pod

package File::Util::Manual;
use strict; use warnings; # for kwalitee tests

# ABSTRACT: File::Util Reference

=pod

=head1 NAME

File::Util::Manual - File::Util Reference

=head1 VERSION

version 4.132140

=head1 INTRODUCTION

This manual is is the complete reference to all available public methods for use
in L<File::Util>.  It also touches on a few other topics as set forth below.

For a "nutshell"-type reference full of actual small example code snippets, take
a look at the L<File::Util::Manual::Examples>

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

=head2 The layout of the Manual

Now we'll start out with some brief notes about what File::Util is (and isn't),
then we'll talk about the syntax used in File::Util.  After that we discuss
custom error handling and diagnostics in File::Util.  Finally, the rest of this
document will cover File::Util's object methods, one by one, with brief usage
examples.

=head2 What File::Util Is

File::Util is a "Pure Perl" library that provides you with several easy-to-use
tools to wrangle files and directories.  It has higher order methods
(that's fancy talk for saying that you can feed subroutine references to some
of File::Util's object methods and they will be treated like "callbacks").

File::Util is mainly Object-Oriented Perl, but strives to be gentle and
accommodating to those who do not know about or who do not like "OO" interfaces.
As such, many of the object methods available in File::Util can also be
imported into your namespace and I<used like regular subroutines> to make
short work of simple tasks.

For more advanced tasks and features, you will need to use File::Util's
object-oriented interface.  Don't worry, it's easy, and there are plenty of
examples here in the documentation to get you off to a great and productive
start.  If you run into trouble, L<help is available|File::Util/SUPPORT>.

File::Util tries its best to adhere to these guiding principles:

=over

=item B<Be easy>

Make hard things easier and safer to do while avoiding common mistakes
associated with file handling in Perl.  Code using File::Util will
automatically be abiding by best practices with regard to Perl IO.

File::Util makes the right decisions for you with regard to all the little
details involved in the vast majority of file-related tasks.  File locking
is automatically performed for you!  File handles are always lexically
scoped.  Safe reads and writes are performed with hard limits on the amount
of RAM you are allowed to consume in your process per file read.  (You can
adjust the limits.)

=item B<Be portable>

We make sure that File::Util is going to work on your computer or virtual
machine.  If you run Windows, Mac, Linux, BSD, some flavor of Unix, etc...
File::Util should work right out of the box.  There are currently no platforms
where Perl runs that we do not support.  If Perl can run on it, File::Util
can run on it.  If you want unicode support, however, you need to at least
be running Perl 5.8 or better.

=item B<Be compatible>

File::Util has been around for a long time, and so has Perl.  We'd like to
think that this is because they are good things!  This means there is a lot
of backward-compatibility to account for, even within File::Util itself.

In the last several years, there has never been a release of File::Util that
intentionally broke code running a previous version.  We are unaware of that
even happening.  File::Util is written to support both old and new features,
syntaxes, and interfaces with full backward-compatibility.

=item B<Be helpful>

If requested, File::Util outputs extremely detailed error messages when
something goes wrong in a File::Util operation.  The diagnostic error
messages not only provide information about what went wrong, but also hints
on how to fix the problem.

These error messages can easily be turned on and off.
See L<DIAGNOSTICS|/DIAGNOSTICS> for the details.

=item B<Be Pure>

File::Util uses no XS or C underpinnings that require you to have a compiler
or make utility on your system in order to use it.  Simply follow standard
installation procedures (L<INSTALLATION|File::Util/INSTALLATION>) and you're
done.  No compiling required.

=back

=head2 What File::Util Is NOT

File::Util offers significant performance increases over other modules for
most directory-walking and searching, whether doing so in a single
directory or in many directories recursively. I<(See also the benchmarking>
I<and profiling scripts included in the performance subdirectory as part of>
I<this distribution)*>

However File::Util is B<NOT> a single-purpose file-finding/searching utility
like File::Find::Rule which offers a handful of extra built-in search features
that File::Util does not give you out of the box, such as searching for files by
owner/group or size.  It is possible to accomplish the same things by
taking advantage of File::Util's callbacks if you want to, but this isn't
the "one thing" File::Util was built to do.

I<*Sometimes it doesn't matter how fast you can search through a directory 1000>
I<times.  Performance alone isn't the best criteria for choosing a module.>

=head1 SYNTAX

In the past, File::Util relied on an older method invocation syntax that
was not robust enough to support the newer features that have been added
since version 4.0.  In addition to making new features possible, the new
syntax is more in keeping with what the Perl community has come to expect
from its favorite modules, like Moose and DBIx::Class.

=head2 OLD Syntax Example

   # this legacy syntax looks clunky and kind of smells like shell script
   $f->list_dir( '/some/dir', '--recurse', '--as-ref', '--pattern=[^\d]' );

=head2 NEW Syntax Example (Does Much More)

   # This syntax is much more robust, and supports new features
   $f->list_dir(
      '/some/dir' => {
         files_match    => { or  => [ qr/bender$/, qr/^flexo/   ] },
         parent_matches => { and => [ qr/^Planet/, qr/Express$/ ] },
         callback       => \&deliver_interstellar_shipment,
         files_only     => 1,
         recurse        => 1,
         as_ref         => 1,
      }
   )

If you already have code that uses the old syntax, DON'T WORRY -- it's still
fully supported behind the scenes.  However, for new code that takes advantage
of new features like higher order functions (callbacks), or advanced matching
for directory listings, you'll need to use the syntax as set forth in this
document.  The old syntax isn't covered here, because you shouldn't use it
anymore.

=head3 I<An Explanation Of The "Options Hashref">

As shown in the code example above, the new syntax uses hash references to
specify options for calls to File::Util methods.  This documentation refers to
these as the "options hashref".  The code examples below illustrates what they
are and how they are used.  Advanced Perl programmers will recognize these
right away.

NOTE: I<"hashref" is short for "hash reference".>  Hash references use curly
brackets and look like this:

   my $hashref = { name => 'Larry', language => 'Perl', pet => 'Velociraptor' };

File::Util uses these hash references as argument modifiers that allow you to
enable or disable certain features or behaviors, so you get the output you
want, like this:

   my $result = $ftl->some_method_call( arg1, arg2, { options hashref } );
                                                    # ^^^^^^^^^^^^^^^ #

A couple of real examples would look like this:

   $ftl->write_file( '/some/file.txt', 'Hello World!', { mode => 'append' } );
                                                       # ^^^^^^^^^^^^^^^^ #

   $ftl->list_dir( '/home/dangerian' => { recurse => 1, files_only => 1 } );
                                        # ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ #


=head1 ERROR HANDLING

=head2 Feature Summary

Managing potential errors is a big part of Perl IO.  File::Util gives you
several options.  In fact, every single call to a File::Util method which
accepts an "options hashref" can also include an error handling directive.
File::Util has some pre-defined error handling behaviors that you can choose
from, or you can supply your own error handler routine.  This is accomplished
via the B<C<onfail>> option.

As an added convenience, when you use this option with the
L<File::Util constructor method|/new>, it sets the default error handling
policy for all failures; in other words, you can set up one error handler
for everything and never have to worry about it after that.

   # Set every error to cause a warning instead of dying by default
   my $ftl = File::Util->new( { onfail => 'warn' } );

   $ftl->write_file( 'C:\\' => 'woof!' ); # now this call will warn and not die

=head2 Details

The predefined B<C<onfail>> behaviors and their syntaxes are covered below.

=over

=item keyword: B<C<die>>

This is what File::Util already does: it calls C<CORE::die()> with an error
message when it encounters a fatal error, and your program terminates.

Example:

   my $ftl = File::Util->new( ... { onfail => 'die' } );

=item keyword: B<C<zero>>

When you use the predefined B<C<zero>> behavior as the C<onfail> handler,
File::Util will return a zero value (the integer C<0>) if it encounters a fatal
error, instead of dying.  File::Util won't warn about the error or abort
execution.  You will just get a zero back instead of what you would have
gotten otherwise, and execution will continue as if no error happened.

Example:

   my $content = File::Util->load_file( ... { onfail => 'zero' } );

=item keyword: B<C<undefined>>

When you use the predefined B<C<undefined>> behavior as the C<onfail> handler,
if File::Util runs into a fatal error it will return C<undef>.  Execution will
not be aborted, and no warnings will be issued.  A value of undef will just
get sent back to the caller instead of what you would have gotten otherwise.
Execution will then continue on as if no error happened.

Note: This option usually makes more practical sense than
C<< onfail => 'zero' >>

Example:

   my $handle = File::Util->open_handle( ... { onfail => 'undefined' } );

=item keyword: B<C<warn>>

When you use the predefined B<C<warn>> behavior as the C<onfail> handler,
File::Util will return C<undef>  if it encounters a fatal error, instead of
dying.  Then File::Util will emit a B<warning> with details about the error,
but will not abort execution.  You will just get a warning message sent to
STDERR and C<undef> gets sent back to the caller instead of what you would have
gotten otherwise.  Other than the warning, execution will continue as if no
error ever happened.

Example:

   my $write_ok = File::Util->write_file( ... { onfail => 'warn' } );

=item keyword: B<C<message>>

When you use the predefined B<C<message>> behavior as the C<onfail> handler,
if File::Util runs into a fatal error it will return an error message in the
form of a string containing details about the problem.  Execution will not
be aborted, and no warnings will be issued.  You will just get an error message
sent back to the caller instead of what you would have gotten otherwise.
Execution will then continue on as if no error happened.

Example:

   my @files = File::Util->list_dir( ... { onfail => 'message' } );

=item B<C<subroutine reference>>

If you supply a code reference to the C<onfail> option in a File::Util method
call, it will execute that code if it encounters a fatal error.  You must
supply a true code reference, as shown in the examples below, either to a
named or anonymous subroutine.

The subroutine you specify will receive two arguments as its input in "C<@_>".
The first will be the text of the error message, and the second will be a
stack trace in text format.  You can send them to a logger, to your
sysadmin in an email alert, or whatever you like-- because it is B<*your*>
error handler.

B<WARNING! >
B<If you do not call C<die> or C<exit> at the end of your error handler,>
B<File::Util will NOT exit, but continue to execute.>  When you opt to use
this feature, you are fully responsible for your process' error handling
and post-error execution.

Examples using the constructor:

   # step 1) define your custom error handler
   sub politician_error_handler {

      my ( $err, $stack ) = @_;

      # do stuff like ...

      $logger->debug( $stack );

      die 'We neither confirm nor deny that an IO error has happened.';
   }

   # step 2) apply your error handler
   my $ftl = File::Util->new( { onfail => \&politician_error_handler } );

      -OR-

   # Define and apply your error handler in one step:

   my $ftl = File::Util->new(
      {
         onfail => sub {
            my ( $err, $stack ) = @_;

            # do stuff ...
         }
      }
   );

Examples in individual method calls:

   $ftl->write_file( 'greedo' => 'try bargain' => { onfail => \&shoot_first } );

   my $file_handle = $ftl->open_handle(
      '/this/might/not/work' => {
         onfail => sub {
            warn "Couldn't open first choice, trying a backup plan...";
            return $ftl->open_handle( '/this/one/should/work' );
         }
      }
   );

=back


=head1 DIAGNOSTICS

When things go wrong, sometimes it's nice to get as much information as
possible about the error.  In C<File::Util>, you incur no performance penalties
by enabling more verbose error messages.  In fact, you're encouraged to do so.

You can globally enable diagnostic messages (for every C<File::Util> object you
create), or on a per-object basis, or even on a per-call basis when you just
want to diagnose a problem with a single method invocation.  Here's how:

=over 8

=item Enable Diagnostics Globally

   use File::Util qw( :diag );

=item Enable Diagnostics Per-Object

   my $ftl = File::Util->new( diag => 1 );

=item Enable Diagnostics Temporarily

   $ftl->diagnostic( 1 ); # turn diagnostic mode on

   # ... do some troubleshooting ...

   $ftl->diagnostic( 0 ); # turn diagnostic mode off

=item Enable Diagnostics per-call

   $ftl->load_file( 'abc.txt' => { diag => 1 } );

=back


=head1 METHODS

B<Note:> In the past, some of the methods listed would state that they were
autoloaded methods.  This mechanism has been changed in favor of more
modern practices, in step with the evolution of computing over the last decade
since File::Util was first released.

Methods listed in alphabetical order.

=head2 C<atomize_path>

=over

=item I<Syntax:> C<atomize_path( [/file/path or file_name] )>

This method is used internally by File::Util to handle absolute filenames on
different platforms in a portable manner, but it can be a useful tool for you
as well.

This method takes a single string as its argument.  The string is expected
to be a fully-qualified (absolute) or relative path to a file or directory.
It carefully splits the string into three parts: The root of the path, the
rest of the path, and the final file/directory named in the string.

Depending on the input, the root and/or path may be empty strings.  The
following table can serve as a guide in what to expect from C<atomize_path()>

   +-------------------------+----------+--------------------+----------------+
   |  INPUT                  |   ROOT   |   PATH-COMPONENT   |   FILE/DIR     |
   +-------------------------+----------+--------------------+----------------+
   |  C:\foo\bar\baz.txt     |   C:\    |   foo\bar          |   baz.txt      |
   |  /foo/bar/baz.txt       |   /      |   foo/bar          |   baz.txt      |
   |  ./a/b/c/d/e/f/g.txt    |          |   ./a/b/c/d/e/f    |   g.txt        |
   |  :a:b:c:d:e:f:g.txt     |   :      |   a:b:c:d:e:f      |   g.txt        |
   |  ../wibble/wombat.ini   |          |   ../wibble        |   wombat.ini   |
   |  ..\woot\noot.doc       |          |   ..\woot          |   noot.doc     |
   |  ../../zoot.conf        |          |   ../..            |   zoot.conf    |
   |  /root                  |   /      |                    |   root         |
   |  /etc/sudoers           |   /      |   etc              |   sudoers      |
   |  /                      |   /      |                    |                |
   |  D:\                    |   D:\    |                    |                |
   |  D:\autorun.inf         |   D:\    |                    |   autorun.inf  |
   +-------------------------+----------+--------------------+----------------+

=back

=head2 C<bitmask>

=over

=item I<Syntax:> C<bitmask( [file name] )>

Gets the bitmask of the named file, provided the file exists. If the file
exists and is accessible, the bitmask of the named file is returned in four
digit octal notation e.g.- C<0644>.  Otherwise, returns C<undef> if the file
does I<not> exist or could not be accessed.

=back

=head2 C<can_flock>

=over

=item I<Syntax:> C<can_flock>

Returns 1 if the current system claims to support C<flock()> I<and> if the
Perl process can successfully call it.  I<(see L<perlfunc/flock>.)>  Unless
both of these conditions are true, a zero value (0) is returned.  This is a
constant method.  It accepts no arguments and will always return the same
value for the system on which it is executed.

B<Note:> Perl tries to support or emulate flock whenever it can via
available system calls, namely C<flock>; C<lockf>; or with C<fcntl>.

=back

=head2 C<created>

=over

=item I<Syntax:> C<created( [file name] )>

Returns the time of creation for the named file in non-leap seconds since
whatever your system considers to be the epoch.  Suitable for feeding to
Perl's built-in functions "gmtime" and "localtime".  I<(see L<perlfunc/time>.)>

=back

=head2 C<diagnostic>

=over

=item I<Syntax:> C<diagnostic( [true / false value] )>

When called without any arguments, this method returns a true or false value
to reflect the current setting for the use of diagnostic (verbose) error
messages when a File::Util object encounters errors.

When called with a true or false value as its single argument, this tells
the File::Util object whether or not it should enable diagnostic
error messages in the event of a failure.  A true value indicates that the
File::Util object will enable diagnostic mode, and a false value indicates
that it will not.  The default setting for C<diagnostic()> is C<0>
(NOT enabled.)

I<see also L<DIAGNOSTICS|/DIAGNOSTICS>>

=back


=head2 C<ebcdic>

=over

=item I<Syntax:> C<ebcdic>

Returns 1 if the machine on which the code is running uses EBCDIC, or returns
0 if not.  I<(see L<perlebcdic>.)>  This is a constant method.  It accepts
no arguments and will always return the same value for the system on which it
is executed.

=back

=head2 C<escape_filename>

=over

=item I<Syntax:> C<escape_filename( [string], [escape char] )>

Returns it's argument in an escaped form that is suitable for use as a filename.
Illegal characters (i.e.- any type of newline character, tab, vtab, and the
following C<< / | * " ? < : > \ >>), are replaced with [escape char] or
"B<_>" if no [escape char] is specified.  Returns an empty string if no
arguments are provided.

=back

=head2 C<existent>

=over

=item I<Syntax:> C<existent( [file name] )>

Returns 1 if the named file (or directory) exists.  Otherwise a value of
undef is returned.

This works the same as Perl's built-in C<-e> file test operator,
I<(see L<perlfunc/-X>)>, it's just easier for some people to remember.

=back

=head2 C<file_type>

=over

=item I<Syntax:> C<file_type( [file name] )>

Returns a list of keywords corresponding to each of Perl's built in file tests
(those specific to file types) for which the named file returns true.
I<(see L<perlfunc/-X>.)>

The keywords and their definitions appear below; the order of keywords returned
is the same as the order in which the are listed here:

=over

=item C<PLAIN             File is a plain file.>

=item C<TEXT              File is a text file.>

=item C<BINARY            File is a binary file.>

=item C<DIRECTORY         File is a directory.>

=item C<SYMLINK           File is a symbolic link.>

=item C<PIPE              File is a named pipe (FIFO).>

=item C<SOCKET            File is a socket.>

=item C<BLOCK             File is a block special file.>

=item C<CHARACTER         File is a character special file.>

=back

=back

=head2 C<flock_rules>

=over

=item I<Syntax:> C<flock_rules( [keyword list] )>

Sets I/O race condition policy, or tells File::Util how it should handle race
conditions created when a file can't be locked because it is already locked
somewhere else (usually by another process).

An empty call to this method returns a list of keywords representing the rules
that are currently in effect for the object.

Otherwise, a call should include a list containing your chosen
directive keywords in order of precedence.  The rules will be applied in
cascading order when a File::Util object attempts to lock a file, so if the
actions specified by the first rule don't result in success, the second rule
is applied, and so on.

This setting can be dynamically changed at any point in your code by calling
this method as desired.

B<The default behavior of File::Util is to try and obtain an exclusive lock>
B<on all file opens (if supported by your operating system).  If a lock cannot>
B<be obtained, File::Util will throw an exception and exit.>

If you want to change that behavior, this method is the way to do it.  One
common situation is for someone to want their code to first try for a lock,
and failing that, to wait until one can be obtained.  If that's what you
want, see the examples after the keywords list below.

Recognized keywords:

=over

=item C<NOBLOCKEX>

tries to get an exclusive lock on the file without blocking (waiting)

=item C<NOBLOCKSH>

tries to get a shared lock on the file without blocking

=item C<BLOCKEX>

waits to get an exclusive lock

=item C<BLOCKSH>

waits to get a shared lock

=item C<FAIL>

dies with stack trace

=item C<WARN>

warn()s about the error and returns undef

=item C<IGNORE>

ignores the failure to get an exclusive lock

=item C<UNDEF>

returns undef

=item C<ZERO>

returns 0

=back

Examples:

=over

=item ex- C<flock_rules( qw( NOBLOCKEX FAIL ) );>

This is the default policy.  When in effect, the File::Util object will first
attempt to get a non-blocking exclusive lock on the file.  If that attempt
fails the File::Util object will call die() with an error.

=item ex- C<flock_rules( qw( NOBLOCKEX BLOCKEX FAIL ) );>

The File::Util object will first attempt to get a non-blocking exclusive lock
on the file.  If that attempt fails it falls back to the second policy rule
"BLOCKEX" and tries again to get an exclusive lock on the file, but this time
by blocking (waiting for its turn).  If that second attempt fails, the
File::Util object will fail with an error.

=item ex- C<flock_rules( qw( BLOCKEX IGNORE ) );>

The File::Util object will first attempt to get a file non-blocking lock on
the file.  If that attempt fails it will ignore the error, and go on to open
the file anyway and no failures or warnings will occur.

=back

=back

=head2 C<is_bin>

=over

=item I<Syntax:> C<is_bin( [file name] )>

Returns 1 if the named file (or directory) exists.  Otherwise a value of undef
is returned, indicating that the named file either does not exist or is of
another file type.

This works the same as Perl's built-in C<-B> file test operator,
I<(see L<perlfunc/-X>)>, it's just easier for some people to remember.

=back

=head2 C<is_readable>

=over

=item I<Syntax:> C<is_readable( [file name] )>

Returns 1 if the named file (or directory) is B<readable> by your program
according to the applied permissions of the file system on which the file
resides.  Otherwise a value of undef is returned.

This works the same as Perl's built-in C<-r> file test operator,
I<(see L<perlfunc/-X>)>, it's just easier for some people to remember.

=back

=head2 C<is_writable>

=over

=item I<Syntax:> C<is_writable( [file name] )>

Returns 1 if the named file (or directory) is B<writable> by your program
according to the applied permissions of the file system on which the file
resides.  Otherwise a value of undef is returned.

This works the same as Perl's built-in C<-w> file test operator,
I<(see L<perlfunc/-X>)>, it's just easier for some people to remember.

=back

=head2 C<last_access>

=over

=item I<Syntax:> C<last_access( [file name] )>

Returns the last accessed time for the named file in non-leap seconds since
whatever your system considers to be the epoch.  Suitable for feeding to
Perl's built-in functions "gmtime" and "localtime".  I<(see L<perlfunc/time>.)>

=back

=head2 C<last_changed>

=over

=item I<Syntax:> C<last_changed( [file name] )>

Returns the inode change time for the named file in non-leap seconds since
whatever your system considers to be the epoch.  Suitable for feeding to
Perl's built-in functions "gmtime" and "localtime".  I<(see L<perlfunc/time>.)>

=back

=head2 C<last_modified>

=over

=item I<Syntax:> C<last_modified( [file name] )>

Returns the last modified time for the named file in non-leap seconds since
whatever your system considers to be the epoch.  Suitable for feeding to
Perl's built-in functions "gmtime" and "localtime".  I<(see L<perlfunc/time>.)>

=back

=head2 C<line_count>

=over

=item I<Syntax:> C<line_count( [file name] )>

Returns the number of lines in the named file.  Fails with an error if the
named file does not exist.

=back

=head2 C<list_dir>

=over

=item I<Syntax:> C<< list_dir( [directory name] => { option => value, ... } ) >>

Returns all file names in the specified directory, sorted in alphabetical
order.  Fails with an error if no such directory is found, or if the
directory is inaccessible.

Note that this is one of File::Util's most robust methods, and can be very
useful.  It can be used as a higher order function (accepting callback
subrefs), and can be used for advanced pattern matching against files.
It can also return a hierarchical data structure of the file tree you ask it to
walk.

See the L<File::Util::Manual::Examples> for several useful ways to use
C<list_dir()>.

Syntax example to recursively return a list of subdirectories in
directory "dir_name":

   my @dirs = $f->list_dir( 'dir_name' => { dirs_only => 1, recurse => 1 } );

=over

=item B<Options accepted by C<list_dir()>>

=over

=item C<< callback => subroutine reference >>

C<list_dir()> can accept references to subroutines of your own.  If you
pass it a code reference using this option, File::Util will execute your
code every time list_dir() enters a directory.  This is particularly useful
when combined with the C<recurse> option which is explained below.

When you create a callback function, the File::Util will pass it four
arguments in this order: The name of the current directory, a reference to a
list of subdirectories in the current directory, a reference to a list of files
in the current directory, and the depth (positive integer) relative to the
directory you provided as your first argument to C<list_dir()>.
I<This means if you pass in a path such as> C</var/tmp>,
I<that "/var/tmp" is at a depth of 0, "/var/tmp/foo" is 1 deep, and so on>
I<down through the "/var/tmp" directory.>

Remember that the code in your callback gets executed in real time,
I<as list_dir() is walking the directory tree>.  Consider this example:

   # Define a subroutine to print the byte size and depth of all files in a
   # directory, designed to be used as a callback function to list_dir()

   sub filesize {
      my ( $selfdir, $subdirs, $files, $depth ) = @_;

      print( "$_ | " . ( -s $_ ) . " | $depth levels deep\n" for @$files;
   }

   # Now list directory recursively, invoking the callback on every recursion

   $f->list_dir( './droids' => { recurse => 1, callback => \&filesize } );

   # Output would look something like
   #
   #   ./droids/by-owner/luke/R2.spec | 1024 | 3 deep
   #   ./droids/by-owner/luke/C2P0.spec | 2048 | 3 deep
   #   ./droids/by-boss/dooku/Grievous.spec | 4096 | 3 deep
   #   ./droids/by-series/imperial/sentries/R5.spec | 1024 | 4 deep
   #
   # Depth breakdown
   #
   #    level 0 => ./droids/
   #    level 1 => ./droids/by-owner/
   #    level 1 => ./droids/by-boss/
   #    level 1 => ./droids/by-series/
   #    level 2 => ./droids/by-owner/luke/
   #    level 2 => ./droids/by-boss/dooku/
   #    level 2 => ./droids/by-series/imperial/
   #    level 3 => ./droids/by-series/imperial/sentries/

Another way to use callbacks is in combination with closures, to "close around"
a variable or variables defined in the same scope as the callback.  A demonstration
of this technique is shown below:

   {
      my $size_total;
      my $dir = 'C:\Users\superman\projects\scripts_and_binaries';

      # how many total bytes are in all of the executable files in $dir

      $f->list_dir(
         $dir => {
            callback => sub {
               my ( $selfdir, $subdirs, $files, $depth ) = @_;

               $size_total += -s $_ for grep { -B $_ } @$files;
            }
         }
      );

      print "There's $size_total bytes of binary files in my projects dir.";
   }

=item C<< d_callback => subroutine reference >>

A C<d_callback> is just like a C<callback>, except it is only executed
on directories encountered in the file tree, not files, and its input
is slightly different.  C<@_> is comprised of (in order) the name of the
current directory, a reference to a list of all subdirectories in that
directory, and the depth (positive integer) relative to the B<top level>
directory in the path you provided as your first argument to C<list_dir>.

=item C<< f_callback => subroutine reference >>

Similarly an C<f_callback> is just like a C<callback>, except it is only
concerned with files encountered in the file tree, not directories.  It's input
is also slightly different.  C<@_> is comprised of (in order) the name of the
current directory, a reference to a list of all files present in that
directory, and the depth (positive integer) relative to the B<top level>
directory in the path you provided as your first argument to C<list_dir>.

=item C<< dirs_only => boolean >>

return only directory contents which are also directories

=item C<< files_only => boolean >>

return only directory contents which are files

=item C<< max_depth => positive integer >>

Works just like the C<-maxdepth> flag in the GNU find command.  This option
tells C<list_dir()> to limit results to directories at no more than the maximum
depth you specify.  This only works in tandem with the C<recurse> option
(or the C<recurse_fast> option which is similar).

For compatibility reasons, you can use "C<maxdepth>" without the underscore
instead, and get the same functionality.

=item C<< no_fsdots => boolean >>

do not include "." and ".." in the list of directory contents returned

=item C<< abort_depth => positive integer >>

Override the global limit on L<abort_depth|/abort_depth> recursions for
directory listings, on a per-listing basis with this option.  Just like the
main C<abort_depth()> object method, this option takes a positive integer.  The
default is 1000.  Sometimes it is useful to increase this number by quite a lot
when walking directories with callbacks.

=item C<< with_paths => boolean >>

Return results with the preceding file paths intact, relative
to the directory named in the call.

=item C<< recurse => boolean >>

Recurse into subdirectories.  In other words, open up subdirectories and
continue to descend into the directory tree either as far as it goes, or until
the C<abort_depth> limit is reached. I<See L<abort_depth()|/abort_depth>>

=item C<< recurse_fast => boolean >>

Recurse into subdirectories, without checking for filesystem loops.  This
works exactly like the C<recurse> option, except it turns off internal
checking for duplicate inodes while descending through a file tree.

You get a performance boost at the sacrifice of a little "safety checking".

The bigger your file tree, the more performance gains you see.

This option has no effect on Windows. I<(see perldoc -f stat)>

=item C<< dirs_as_ref => boolean >>

When returning directory listing, include first a reference to the list
of subdirectories found, followed by anything else returned by the call.

=item C<< files_as_ref => boolean >>

When returning directory listing, include last a reference to the list
of files found, preceded by a list of subdirectories found (or preceded
by a list reference to subdirectories found if C<dirs_as_ref> was also used).

=item C<< as_ref => boolean >>

Return a pair list references: the first is a reference to any subdirectories
found by the call, the second is a reference to any files found by the call.

=item C<< sl_after_dirs => boolean >>

Append a directory separator ("/, "\", or ":" depending on your system)
to all directories found by the call.  Useful in visual displays for quick
differentiation between subdirectories and files.

=item C<< ignore_case => boolean >>

Return items in a case-insensitive alphabetic sort order, as opposed to the
default.

**By default, items returned by the call to this method are alphabetically
sorted in a case-insensitive manner, such that "Zoo.txt" comes before
"alligator.txt".  This is also the way files are listed at the system
level on most operating systems.

However, if you'd like the directory contents returned by this method to be
sorted without regard to case, use this option.  That way, "alligator.txt"
will come before "Zoo.txt".

=item C<< count_only => boolean >>

Returns a single value: an integer reflecting the number of items found in
the directory after applying any filter criteria that may also have been
specified by other options (i.e.- "dirs_only", "recurse", etc.)

=item C<< as_tree => boolean >>

Returns a hierarchical data structure (hashref) of the file tree in the directory
you specify as the first argument to C<list_dir()>.  Use in combination with
other options to get the exact results you want in the data structure.

*Note: When using this option, the C<"files_only"> and C<"dirs_only"> options
are ignored, but you can still specify things like a C<"max_depth"> argument,
however.  Note also that you need to specifically call this with the
C<"recurse"> or C<"recurse_fast"> option or you will only get a single-level
tree structure.

One quick example:

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

   # output would look something like this if you Data::Dumper'd it
   {
     '/' => {
              '_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',
                                         }
                       }
            }
   }


When using this option, the hashref you get back will have certain metadata
entries at each level of the hierarchy, namely there will be two special
keys: "_DIR_SELF", and "_DIR_PARENT_".  Their values will be the name of
the directory itself, and the name of its parent, respectively.

That metadata can be extremely helpful when iterating over and parsing the
hashref later on, but if you don't want the metadata, include the
C<dirmeta> option and set it to a zero (false) value as shown below:

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

**Remember: the C<as_tree> doesn't recurse into subdirectories unless you tell
it to with C<< recurse => 1 >>

=back

=item B<Filtering and Matching with C<list_dir()>>

C<list_dir()> can use Perl L<Regular Expressions|perlre> to match against
and thereby filter the results it returns.  It can match based on file name,
directory name, the path preceding results, and the parent directory of
results.  The matching arguments you use must be real regular expression
references as shown (i.e.- NOT strings).

Regular expressions can be provided as a single argument value, or a
specifically crafted hashref designating a list of patterns to match against
in either an "or" manner, or an "and"ed cumulative manner.

Some short examples of proper syntax will be provided after the list of
matching options below.

I<**If you experience a big slowdown in directory listings while>
I<using regular expressions, check to make sure your regular expressions are>
I<properly written and optimized.  In general, directory listings should>
I<not be slow or resource-intensive.  Badly-written regular expressions will>
I<result in considerable slowdowns and bottlenecks in any application.>

=over

=item C<< files_match => qr/regexp/ >>

=item I<OR:> C<< files_match => { and/or => [ qr/listref of/, qr/regexps/ ] } >>

Return only file names matching the regex(es).  Preceding directories are
included in the results; for technical reasons they are not excluded (if they
were excluded, C<list_dir()> would not be able to "cascade" or recurse into
subdirectories in search of matching files.

Use the C<files_only> option in combination with this matching parameter to
exclude the preceding directory names.

=item C<< dirs_match => qr/regexp/ >>

=item I<OR:> C<< dirs_match => { and/or => [ qr/listref of/, qr/regexps/ ] } >>

Return only files and subdirectory names in directories that match the
regex(es) you specify.  B<BE CAREFUL> with this one!!  It doesn't "cascade"
the way you might expect; for technical reasons, it won't descend into
directories that don't match the regex(es) you provide.  For example, if you
want to match a directory name that is three levels deep against a given
pattern, but don't know (or don't care about) the names of the intermediate
directories-- THIS IS NOT THE OPTION YOU ARE LOOKING FOR.  Use the
C<path_matches> option instead.

B<*NOTE:> Bear in mind that just because you tell C<list_dir()> to match each
directory against the regex(es) you specify here, that doesn't mean you are
telling it to only show directories in its results.  You will get file names
in matching directories included in the results as well, unless you combine
this with the C<dirs_only> option.

=item C<< path_matches => qr/regexp/ >>

=item I<OR:> C<< path_matches => { and/or => [ qr/listref of/, qr/regexps/ ] } >>

Return only files and subdirectory names with preceding paths that match the
regex(es) you specify.

=item C<< parent_matches => qr/regexp reference/ >>

=item I<OR:> C<< parent_matches => { and/or => [ qr/listref of/, qr/regexps/ ] } >>

Return only files and subdirectory names whose parent directory matches the
regex(es) you specify.

=back

=item Examples of matching and filtering results in C<listdir()>

Single-argument matching examples

   my @files = $f->list_dir(
      '../notes' => { files_match => qr/\.txt$/i, files_only => 1 }
   );

   my @dirs = $f->list_dir(
      '/var' => {
         dirs_match => qr/log|spool/i,
         recurse => 1,
         dirs_only => 1,
      }
   );

   my @dirs = $f->list_dir(
      '/home' => {
         path_matches => qr/Desktop/,
         recurse => 1,
         dirs_only => 1,
      }
   );

   my @files = $f->list_dir(
      '/home/tommy/projects' => {
         parent_matches => qr/^\.git$/,
         recurse => 1,
      }
   );

A multiple-argument matching examples with B<OR>

   my @files = $f->list_dir(
      'C:\Users\Billy G' => {
         parent_matches => { or => [ qr/Desktop/, qr/Pictures/ ] }
         recurse => 1,
      }
   );

   # ... same concepts apply to "files_match", "dirs_match",
   #     and "parent_matches" filtering

Multiple-argument matching examples with B<AND>

   my @files = $f->list_dir(
      '/home/leia' => {
         parent_matches => { and => [ qr/Anakin/, qr/Amidala/ ] }
         recurse => 1,
      }
   );

   my @files = $f->list_dir(
      '/home/mace' => {
         path_matches => { and => [ qr/^(?!.*dark.side)/i, qr/[Ff]orce/ ] }
         recurse => 1,
      }
   );

   # ... same concepts apply to "files_match" and "dirs_match" filtering

B<**When you specify regexes for more than one filter type parameter>, the
patterns are I<AND'ed> together, as you'd expect, and all matching criteria must
be satisfied for a successful overall match.

   my @files = $f->list_dir(
      '/var' => {
         dirs_match     => { or => [ qr/^log$/,   qr/^lib$/    ] },
         files_match    => { or => [ qr/^syslog/, qr/\.isam$/i ] },
         parent_matches => qr/[[:alpha:]]+/
         path_matches   => qr/^(?!.*home)/,
         recurse     => 1,
         files_only  => 1,
      }

B<Negative matches> (when you want to NOT match something) - use Perl!

As shown in the L<File::Util::Manual::Examples>, Perl already provides
support for negated matching in the form of "zero-width negative assertions".
(See L<perlre> for details on how they work).  Use syntax like the regular
expressions below to match anything that is NOT part of the subpattern.

   # match all files with names that do NOT contain "apple" (case sensitive)
   my @no_apples = $f->list_dir(
      'Pictures/fruit' => { files_match => qr/^(?!.*apple)/ }
   );

   # match all files that that do NOT end in *.mp3 (case INsensitive)
   # also, don't match files that end in *.wav either
   my @no_music = $f->list_dir(
      '/opt/music' => {
         files_match => { and => [ qr/^(?!.*mp3$)/i, qr/^(?!.*wav$)/i ]
      }
   );

=back

=back

=head2 C<load_dir>

=over

=item I<Syntax:> C<< load_dir( [directory name] => { options } ) >>

Returns a data structure containing the contents of each file present in the
named directory.

The type of data structure returned is determined by the optional data-type
option parameter.  Only one option at a time may be used for a given call
to this method.  Recognized options are listed below.

   my $files_hash_ref = $f->load_dir( $dirname ); # default (hashref)

      -OR-

   my $files_list_ref = $f->load_dir( $dirname => { as_listref => 1 } );

      -OR-

   my @files = $f->load_dir( $dirname => { as_list => 1 } );

=over

=item B<Options accepted by C<load_dir()>>

=over

=item C<< as_hashref => boolean >> *(default)

Implicit.  If no option is passed in, the default behavior is to return a
reference to an anonymous hash whose keys are the names of each file in the
specified directory; the hash values for contain the contents of the file
represented by its corresponding key.

=item C<< as_list => boolean >>

Causes the method to return a list comprised of the contents loaded from
each file (in case-sensitive order) located in the named directory.

This is useful in situations where you don't care what the filenames were
and you just want a list of file contents.

=item C<< as_listref => boolean >>

Same as above, except an array reference to the list of items is returned
rather than the list itself.  This is more efficient than the above,
particularly when dealing with large lists.

=back

C<load_dir()> does not recurse or accept matching parameters, etc.  It's an
effective tool for loading up things like a directory of template files on
a web server, or to store binary data streams in memory.  Use it however you
like.

However, if you do want to load files into a hashref/listref or array while
using the advanced features of C<list_dir()>, just use list_dir to return the
files and map the contents into your variable:

   my $hash_ref = {};

   %$hash_ref = map { $_ => $ftl->load_file( $_ ) }
                $ftl->list_dir( $dir_name => { advanced options... } );

=back

B<Note:> This method does not distinguish between plain files and other file
types such as binaries, FIFOs, sockets, etc.

Restrictions imposed by the current "read limit"
I<(see the L<read_limit()|/read_limit>) entry below> will be applied to the
individual files opened by this method as well.  Adjust the read limit as
necessary.

Example usage:

   my $templates = $f->load_dir( 'templates/stock-ticker' );

The above code creates an anonymous hash reference that is stored in the
variable named "C<$files>".  The keys and values of the hash referenced by
"C<$files>" would resemble those of the following code snippet (given that
the files in the named directory were the files 'a.txt', 'b.html', 'c.dat',
and 'd.conf')

   my $files =
      {
         'a.txt'  => 'the contents of file a.txt',
         'b.html' => 'the contents of file b.html',
         'c.dat'  => 'the contents of file c.dat',
         'd.conf' => 'the contents of file d.conf',
      };

=back

=head2 C<load_file>

=over

=item I<Syntax:> C<< load_file( [file name] => { options } ) >>

=item I<OR:> C<< load_file( file_handle => [file handle reference] => { options } ) >>

If [file name] is passed, returns the contents of [file name] in a string.
If a [file handle reference] is passed instead, the filehandle will be
C<CORE::read()> and the data obtained by the read will be returned in a string.

If you desire the contents of the file (or file handle data) in a list of
lines instead of a single string, this can be accomplished through the use
of the C<as_lines> option (see below).

=over

=item B<Options accepted by C<load_file()>>

=over

=item C<< as_lines => boolean >>

If this option is enabled then your call to C<load_file> will return a list of
strings, each one of which is a line as it was read from the file [file name].
The lines are returned in the order they are read, from the beginning of the
file to the end.

This is not the default behavior.  The default behavior is for C<load_file> to
return a single string containing the entire contents of the file.

=item C<< no_lock => boolean >>

By default this method will attempt to get a lock on the file while it is
being read, following whatever rules are in place for the flock policy
established either by default (implicitly) or changed by you in a call to
File::Util::flock_rules()
I<(see the L<flock_rules()|/flock_rules>) entry below>.

This method will not try to get a lock on the file if the File::Util object was
created with the option C<no_lock> or if the method was called with the
option C<no_lock>.

This method will automatically call binmode() on binary files for you.  If you
pass in a filehandle instead of a file name you do not get this automatic
check performed for you.  In such a case, you'll have to call binmode() on
the filehandle yourself.  Once you pass a filehandle to this method it has no
way of telling if the file opened to that filehandle is binary or not.

=item C<< binmode => [ boolean or 'utf8' ] >>

Tell File::Util to read the file in binmode (if set to a true boolean: B<C<1>>),
or to read the file as UTF-8 encoded data, specify a value of B<C<utf8>> to this
option.  I<(see L<perlfunc/binmode>)>.

You need Perl 5.8 or better to use C<'utf8'> or your program will fail with
an error message.

Example Usage:

   my $encoded_data = $ftl->load_file( 'encoded.txt' => { binmode => 'utf8' } );

=item C<< read_limit => positive integer >>

Override the global read limit setting for the File::Util object you are working
with, on a one time basis.  By specifying a this option with a positive integer
value (representing the maximum number of bytes to allow for your C<load_file()>
call), you are telling C<load_file()> to ignore the global/default setting for
I<just that call>, and to apply your one-time limit of [ positive integer ]
bytes on the file while it is read into memory.

B<Notes:> This method does not distinguish between plain files and other file
types such as binaries, FIFOs, sockets, etc.

Restrictions imposed by the current "read limit"
I<(see the L<read_limit()|/read_limit>) entry below> will be applied to the
files opened by this method.  Adjust the read limit as necessary either
by overriding (using the C<'read_limit'> option above), or by adjusting the
global value for your File::Util object with the provided
L<read_limit() object method|/read_limit>.

=back

=back

=back

=head2 C<make_dir>

=over

=item I<Syntax:> C<< make_dir( [new directory name], [bitmask] => { options } ) >>

Attempts to create (recursively) a directory as [new directory name] with
the [bitmask] provided.  The bitmask is an optional argument and defaults to
oct 777, B<combined with the current user's umask>.  If specified, the bitmask
must be supplied in the form required by the native perl umask function (as
an octal number).  I<see L<perlfunc/"umask">> for more information about the
format of the bitmask argument.

As mentioned above, the recursive creation of directories is transparently
handled for you.  This means that if the name of the directory you pass in
contains a parent directory that does not exist, the parent directory(ies) will
be created for you automatically and silently in order to create the final
directory in the [new directory name].

Simply put, if [new directory] is "/path/to/directory" and the directory
"/path/to" does not exist, the directory "/path/to" will be created and the
"/path/to/directory" directory will be created thereafter.  All directories
created will be created with the [bitmask] you specify, or with the default
of oct 777, B<combined with the current user's umask>.

Upon successful creation of the [new directory name], the [new directory name]
is returned to the caller.

=over

=item B<Options accepted by C<make_dir()>>

=over

=item C<< if_not_exists => boolean >>

Example:

   $f->make_dir( '/home/jspice' => oct 755 => { if_not_exists => 1 } );

If this option is enabled then make_dir will not attempt to create the directory
if it already exists.  Rather it will return the name of the directory as it
normally would if the directory did not exist previous to calling this method.

If a call to this method is made without the C<if_not_exists> option and the
directory specified as [new directory name] does in fact exist, an error will
result as it is impossible to create a directory that already exists.

=back

=back

=back

=head2 C<abort_depth>

=over

=item I<Syntax:> C<abort_depth( [positive integer] )>

When called without any arguments, this method returns an integer reflecting
the current number of times the File::Util object will dive into the
subdirectories it discovers when recursively listing directory contents from
a call to C<File::Util::list_dir()>.  The default is 1000.  If the number is
exceeded, the File::Util object will fail with an error.

When called with an argument, it sets the maximum number of times a File::Util
object will recurse into subdirectories before failing with an error message.

This method can only be called with a numeric integer value.  Passing a bad
argument to this method will cause it to fail with an error.

I<(see also: L<list_dir|/list_dir>)>

=back

=head2 C<needs_binmode>

=over

=item I<Syntax:> C<needs_binmode>

Returns 1 if the machine on which the code is running requires that C<binmode()>
I<(a built-in function)> be called on open file handles, or returns 0 if not.
I<(see L<perlfunc/binmode>.)>  This is a constant method.  It accepts no
arguments and will always return the same value for the system on which it
is executed.

=back

=head2 C<new>

=over

=item I<Syntax:> C<< new( { options } ) >>

This is the File::Util constructor method.  It returns a new File::Util
object reference when you call it.  It recognizes various options that govern
the behavior of the new File::Util object.

=over

=item B<Parameters accepted by C<new()>>

=over

=item C<< use_flock => boolean >>

Optionally specify this option to the C<File::Util::new> method to instruct the
new object that it should never attempt to use C<flock()> in it's I/O
operations.  The default is to use C<flock()> if available on your system.
Specify this option with a true or false value ( 1 or 0 ), true to use
C<flock()>, false to not use it.

=item C<< read_limit => positive integer >>

Optionally specify this option to the File::Util::new method to instruct the
new object that it should never attempt to open and read in a file greater
than the number of bytes you specify.  This argument can only be
a numeric integer value, otherwise it will be I<silently ignored.>  The default
read limit for File::Util objects is 52428800 bytes (50 megabytes).

=item C<< abort_depth => positive integer >>

Optionally specify this option to the File::Util::new method to instruct the
new object to set the maximum number of times it will recurse into
subdirectories while performing directory listing operations before failing
with an error message.  This argument can only be a numeric integer value,
otherwise it will be I<silently ignored.>

I<(see also: L<abort_depth()|/abort_depth>)>

=item B<C<< onfail => designated handler >>>

Set the I<default> policy for how the new File::Util object handles fatal
errors.  This option takes any one of a list of predefined keywords, or a
reference to a named or anonymous error handling subroutine of your own.

You can supply an C<onfail> handler to nearly any function in File::Util, but
when you do so for the C<new()> constructor, you are setting the I<default>.

Acceptable values are all covered in the B<L<ERROR HANDLING|/ERROR HANDLING>>
section (above), along with proper syntax and example usage.

=back

=back

=back

=head2 C<onfail>

=over

=item I<Syntax:> C<onfail( [keyword or code reference] )>

Dynamically set/change the default error handling policy for an object.

This works exactly the same as it does when you specify an "onfail"
handler to the constructor method (I<see also C<L<new|/new>>>).

The syntax and keywords available to use for this method are already discussed
above in the L<ERROR HANDLING|/ERROR HANDLING> section, so refer to that for
in-depth details.

Here are some examples:

   $ftl->onfail( 'die' );

   $ftl->onfail( 'zero' );

   $ftl->onfail( 'undefined' );

   $ftl->onfail( 'message' );

   $ftl->onfail( \&subroutine_reference );

   $ftl->onfail( sub { my ( $error, $stack_trace ) = @_; ... } );

=back

=head2 C<open_handle>

=over

=item I<Syntax:> C<< open_handle( [file name] => [mode] => { options } ) >>

=item I<OR:> C<< open_handle( file => [file name] => mode => [mode] => { options } ) >>

Attempts to get a lexically scoped open file handle on [file name] in [mode]
mode.  Returns the file handle if successful or generates a fatal error with a
diagnostic message if the operation fails.

You will need to remember to call C<close()> on the filehandle yourself, at
your own discretion.  Leaving filehandles open is not a good practice, and
is not recommended.  I<see L<perlfunc/close>>).

Once you have the file handle you would use it as you would use any file handle.
Remember that unless you specifically turn file locking off when the
C<File::Util> object is created I<(see L<new|/new>)> or by using the
C<no_lock> option when calling C<open_handle>, that file locking is going to
automagically be handled for you behind the scenes, so long as your OS supports
file locking of any kind at all.  Great!  It's very convenient for you to not
have to worry about portability in taking care of file locking between one
application and the next; by using C<File::Util> in all of them, you know
that you're covered.

A slight inconvenience for the price of a larger set of features (compare
L<write_file|/write_file> to this method)
I<B<you will have to release the file lock on the open handle yourself.>>
C<File::Util> can't manage it for you anymore once it turns the handle over
to you.  At that point, it's all yours.  In order to release the file lock
on your file handle, call L<unlock_open_handle()|/unlock_open_handle> on it.
Otherwise the lock will remain for the life of your process.  If you don't
want to use the free portable file locking, remember the C<no_lock> option,
which will turn off file locking for your open handle.  Seldom, however, should
you ever opt to not use file locking unless you really know what you are doing.
The only obvious exception would be if you are working with files on a
network-mounted filesystem like NFS or SMB (CIFS), in which case locking can
be buggy.

If the file does not yet exist it will be created, and it will be created
with a bitmask of [bitmask] if you specify a file creation bitmask using
the C<'bitmask'> option, otherwise the file will be created with the default
bitmask of oct 777.  The bitmask is combined with the current user's umask,
whether you specify a value or not.  This is a function of Perl,
not File::Util.

If specified, the bitmask must be supplied in the form of an octal number as
required by the native perl umask function.  I<See L<perlfunc/"umask">> for
more information about the format of the bitmask argument.  If the file
[file name] already exists then the bitmask argument has no effect and is
silently ignored.

Any non-existent directories in the path preceding the actual file name will
be automatically (and silently - no warnings) created for you and any new
directories will be created with a bitmask of [dbitmask], provided you specify
a directory creation bitmask with the C<'dbitmask'> option.

If specified, the directory creation bitmask [dbitmask] must be supplied in
the form required by the native perl umask function.

If there is an error while trying to create any preceding directories, the
failure results in a fatal error with an error.  If all
directories preceding the name of the file already exist, the dbitmask
argument has no effect and is silently ignored.

=back

=over

=item B<Native Perl open modes>

The default behavior of C<open_handle()> is to open file handles using Perl's
native C<open()> I<(see L<perlfunc/open>)>.  Unless you use the
C<use_sysopen> option, only then are the following modes valid:

=over

=item C<< mode => 'read' >> (this is the default mode)

[file name] is opened in read-only mode.  If the file does not yet exist then
a fatal error will occur.

=item C<< mode => 'write' >>

[file name] is created if it does not yet exist.  If [file name] already exists
then its contents are overwritten with the new content provided.

=item C<< mode => 'append' >>

[file name] is created if it does not yet exist.  If [file name] already exists
its contents will be preserved and the new content you provide will be appended
to the end of the file.

=back

=back

=over

=item B<System level open modes ("open a la C")>

Optionally you can ask C<File::Util> to open your handle using C<CORE::sysopen>
instead of using the native Perl C<CORE::open()>.  This is accomplished by
enabling the C<use_sysopen> option.  Using this feature opens up more
possibilities as far as the open modes you can choose from, but also carries
with it a few caveats so you have to be careful, just as you'd have to be a
little more careful when using C<sysopen()> anyway.

Specifically you need to remember that when using this feature you must NOT
mix different types of I/O when working with the file handle.  You can't go
opening file handles with C<sysopen()> and print to them as you normally
would print to a file handle.  You have to use C<syswrite()> instead.  The
same applies here.  If you get a C<sysopen()>'d filehandle from C<open_handle()>
it is imperative that you use C<syswrite()> on it.  You'll also need to use
C<sysseek()> and other type of C<sys>* commands on the filehandle instead of
their native Perl equivalents.

(see L<perlfunc/sysopen>, L<perlfunc/syswrite>, L<perlfunc/sysseek>,
L<perlfunc/sysread>)

That said, here are the different modes you can choose from to get a file handle
when using the C<use_sysopen> option.  Remember that these won't work unless
you use that option, and will generate an error if you try using them without it.
The standard C<'read'>, C<'write'>, and C<'append'> modes are already available
to you by default.  These are the extended modes:

=over

=item C<< mode => 'rwcreate' >>

[file name] is opened in read-write mode, and will be created for you if it
does not already exist.

=item C<< mode => 'rwupdate' >>

[file name] is opened for you in read-write mode, but must already exist.  If
it does not exist, a fatal error will result.

=item C<< mode => 'rwclobber' >>

[file name] is opened for you in read-write mode.  If the file already exists
it's contents will be "clobbered" or wiped out.  The file will then be empty
and you will be working with the then-truncated file.  This can not be undone.
Once you call C<open_handle()> using this option, your file WILL be wiped out.
If the file does not exist yet, it will be created for you.

=item C<< mode => 'rwappend' >>

[file name] will be opened for you in read-write mode ready for appending.  The
file's contents will not be wiped out; they will be preserved and you will be
working in append fashion.  If the file does not exist, it will be created
for you.

=back

Remember to use C<sysread()> and not plain C<read()> when reading those
C<sysopen()>'d filehandles!

=back

=over

=item B<Options accepted by C<open_handle()>>

=over

=item C<< binmode => [ boolean or 'utf8' ] >>

Tell File::Util to open the file in binmode (if set to a true boolean: B<C<1>>),
or to open the file with UTF-8 encoding, specify a value of B<C<utf8>> to this
option.  I<(see L<perlfunc/binmode>)>.

You need Perl 5.8 or better to use C<"utf8"> or your program will fail with
an error message.

Example Usage:

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

=item C<< no_lock => boolean >>

By default this method will attempt to get a lock on the file while it is
being read, following whatever rules are in place for the flock policy
established either by default (implicitly) or changed by you in a call to
File::Util::flock_rules()
I<(see L<flock_rules()|/flock_rules>)>.

This method will not try to get a lock on the file if the File::Util object was
created with the option C<no_lock> or if this method is called with the
option C<no_lock>.

=item C<< use_sysopen => boolean >>

Instead of opening the file using Perl's native C<open()> command, C<File::Util>
will open the file with the C<sysopen()> command.  You will have to remember
that your filehandle is a C<sysopen()>'d one, and that you will not be able to
use native Perl I/O functions on it.  You will have to use the C<sys>*
equivalents.  See L<perlopentut> for a more in-depth explanation of why you
can't mix native Perl I/O with system I/O.

=back

=back

=head2 C<read_limit>

=over

=item I<Syntax:> C<read_limit( [positive integer] )>

By default, the largest size file that File::Util will read into memory and
return via the L<load_file|/load_file> is 52428800 bytes (50 megabytes).

This value can be modified by calling this method with an integer value
reflecting the new limit you want to impose, in bytes.  For example, if you want
to set the limit to 10 megabytes, call the method with an argument of 10485760.

If this method is called without an argument, the read limit currently in force
for the File::Util object will be returned.

=back

=head2 C<return_path>

=over

=item I<Syntax:> C<return_path( [string] )>

Takes the file path from the file name provided and returns it such that
C</who/you/callin/scruffy.txt> is returned as C</who/you/callin>.

=back

=head2 C<size>

=over

=item I<Syntax:> C<size( [file name] )>

Returns the file size of [file name] in bytes.  Returns C<0> if the file is
empty. Returns C<undef> if the file does not exist.

=back

=head2 C<split_path>

=over

=item I<Syntax:> C<split_path( [string] )>

Takes a path/filename, fully-qualified or relative (it doesn't matter), and it
returns a list comprising the root of the path (if any), each directory in
the path, and the final part of the path (be it a file, a directory, or
otherwise)

This method doesn't divine or detect any information about the path, it simply
manipulates the string value.  It doesn't map it to any real filesystem object.
It doesn't matter whether or not the file/path named in the input string
exists or not.

=back

=head2 C<strip_path>

=over

=item I<Syntax:> C<strip_path( [string] )>

Strips the file path from the file name provided and returns the file name only.

Given C</kessel/run/12/parsecs>, it returns C<parsecs>

Given C<C:\you\scoundrel>, it returns C<scoundrel>

=back

=head2 C<touch>

=over

=item I<Syntax:> C<touch( [file name] )>

Behaves like the *nix C<touch> command; Updates the access and modification
times of the specified file to the current time.  If the file does not exist,
C<File::Util> tries to create it empty.  This method will fail with a fatal
error if system permissions deny alterations to or creation of the file.

Returns C<1> if successful.  If unsuccessful, fails with an error.

=back

=head2 C<trunc>

=over

=item I<Syntax:> C<trunc( [file name] )>

Truncates [file name] (i.e.- wipes out, or "clobbers" the contents of the
specified file.)  Returns C<1> if successful.  If unsuccessful, fails with a
descriptive error message about what went wrong.

=back

=head2 C<unlock_open_handle>

=over

=item I<Syntax:> C<unlock_open_handle([file handle])>

Release the flock on a file handle you opened with L<open_handle|/open_handle>.

Returns true on success, false on failure.  Will not raise a fatal error if
the unlock operation fails.  You can capture the return value from your call
to this method and C<die()> if you so desire.  Failure is not ever very likely,
or C<File::Util> wouldn't have been able to get a portable lock on the file
in the first place.

If C<File::Util> wasn't able to ever lock the file due to limitations of your
operating system, a call to this method will return a true value.

If file locking has been disabled on the file handle via the C<no_lock> option
at the time L<open_handle|/open_handle> was called, or if file locking was
disabled using the L<use_flock|/use_flock> method, or if file locking was
disabled on the entire C<File::Util> object at the time of its creation
I<(see L<new()|/new>)>, calling this method will have no effect and a true value
will be returned.

=back

=head2 C<use_flock>

=over

=item I<Syntax:> C<use_flock( [true / false value] )>

When called without any arguments, this method returns a true or false value
to reflect the current use of C<flock()> within the File::Util object.

When called with a true or false value as its single argument, this method
will tell the File::Util object whether or not it should attempt to use
C<flock()> in its I/O operations.  A true value indicates that the File::Util
object will use C<flock()> if available, a false value indicates that it will
not.  The default is to use C<flock()> when available on your system.

=over

=item I<B<DON'T USE FLOCK ON NETWORK FILESYSTEMS>>

If you are working with files on an NFS mount, or a Windows file share, it
is quite likely that using flock will be buggy and cause unexpected failures
in your program.  You should not use flock in such situations.

=item I<B<A WORD OF CAUTION FOR SOLARIS USERS>>

File locking has known issues on B<SOLARIS>.  Solaris claims to offer
a native C<flock()> implementation, but after obtaining a lock on a file,
Solaris will very often just silently refuse to unlock it again until
your process has completely exited.  This is not an issue with File::Util or
even with Perl itself.  Other programming languages encounter the same
problems; it is a system-level issue.  So please be aware of this if you are
a Solaris user and want to use file locking on your OS.

You may have to explicitly disable file locking completely.

=back

=back

=head2 C<write_file>

=over

=item I<Syntax:> C<< write_file( [file name] => [string] => { other_options } ) >>

=item I<OR:> C<< write_file( { file => [file name], content => [string], mode => [mode], other_options } ) >>

Syntax Examples:

   # get some content (a string returned from a function call, perhaps)
   my $answer = ask_commissioner( 'Can he be trusted?' );

   $ftl->write_file( 'Harvey_Dent.txt' => $answer );

      -OR-

   # get some binary content, maybe a picture...
   my $binary_data = get_mugshot( alias => 'twoface' );

   $ftl->write_file( 'suspect.png' => $binary_data => { binmode => 1 } );

      -OR-

   # write a file with UTF-8 encoding (unicode character support)
   $ftl->write_file( 'encoded.txt' => $encoded_data => { binmode => 'utf8' } );

      -OR-

   $ftl->write_file(
      {
         file    => '/gotham/city/ballots/Bruce_Wayne.txt',
         content => 'Vote for Harvey!',
         bitmask => oct 600, # <- secret ballot file permissions
      }
   );

Attempts to write [string] to [file name] in mode [mode].  If the file does
not yet exist it will be created, and it will be created with a bitmask of
[bitmask] if you specify a file creation bitmask using the C<'bitmask'> option,
otherwise the file will be created with the default bitmask of oct 777.
The bitmask is combined with the current user's umask, whether you specify a
value or not.  This is a function of Perl, not File::Util.

[string] should be a string or a scalar variable containing a string.  The
string can be any type of data, such as a binary stream, or ascii text with
line breaks, etc.  Be sure to enable the C<< binmode => 1 >> option for binary
streams, and be sure to specify a value of C<< binmode => 'utf8' >> for UTF-8
encoded data.

NOTE: that you will need Perl version 5.8 or better to use the C<'utf8'>
feature, or your program will fail with an error.

If specified, the bitmask must be supplied in the form of an octal number,
as required by the native perl umask function.  I<see L<perlfunc/"umask">>
for more information about the format of the bitmask argument.  If the file
[file name] already exists then the bitmask argument has no effect and is
silently ignored.

Returns 1 if successful or fails with an error if not successful.

Any non-existent directories in the path preceding the actual file name will
be automatically (and silently - no warnings) created for you and new
directories will be created with a bitmask of [dbitmask], provided you specify
a directory creation bitmask with the C<'dbitmask'> option.

If specified, the directory creation bitmask [dbitmask] must be supplied in
the form required by the native perl umask function.

If there is a problem while trying to create any preceding directories, the
failure results in a fatal error.  If all directories preceding the name of
the file already exist, the dbitmask argument has no effect and is silently
ignored.

=over

=item C<< mode => 'write' >> (this is the default mode)

[file name] is created if it does not yet exist.  If [file name] already exists
then its contents are overwritten with the new content provided.

=item C<< mode => 'append' >>

[file name] is created if it does not yet exist.  If [file name] already exists
its contents will be preserved and the new content you provide will be appended
to the end of the file.

=back

=over

=item B<Options accepted by C<write_file()>>

=over

=item C<< binmode => [ boolean or 'utf8' ] >>

Tell File::Util to write the file in binmode (if set to a true boolean: B<C<1>>),
or to write the file with UTF-8 encoding, specify a value of B<C<utf8>> to this
option.  I<(see L<perlfunc/binmode>)>.

You need Perl 5.8 or better to use C<"utf8"> or your program will fail with
an error message.

Example Usage:

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

=item C<< empty_writes_OK => boolean >>

Allows you to call this method without providing a content argument (it lets
you create an empty file without warning you or failing.  Be advised that
if you enable this option, it will have the same effect as truncating a file
that already has content in it (i.e.- it will "clobber" non-empty files)

=item C<< no_lock => boolean >>

By default this method will attempt to get a lock on the file while it is
being read, following whatever rules are in place for the flock policy
established either by default (implicitly) or changed by you in a call to
File::Util::flock_rules()
I<(see L<flock_rules()|/flock_rules>)>.

This method will not try to get a lock on the file if the File::Util object was
created with the option C<no_lock> or if this method is called with the
option C<no_lock> enabled.

=back

=back

=back

=head2 C<valid_filename>

=over

=item I<Syntax:> C<valid_filename( [string] )>

For the given string, returns 1 if the string is a legal file name for the
system on which the program is running, or returns undef if it is not.  This
method does not test for the validity of file paths!  It tests for the validity
of file names only.  (It is used internally to check beforehand if a file name
is usable when creating new files, but is also a public method available for
external use.)

=back

=head1 CONSTANTS

=head2 C<NL>

=over

=item I<Syntax:> C<NL>

Short for "B<N>ew B<L>ine".  Returns the correct new line character (or character
sequence) for the system on which your program runs.

=back

=head2 C<SL>

=over

=item I<Syntax:> C<SL>

Short for "B<Sl>ash". Returns the correct directory path separator for the system on
which your program runs.

=back

=head2 C<OS>

=over

=item I<Syntax:> C<OS>

Returns the File::Util keyword for the operating system B<FAMILY> it detected.
The keyword for the detected operating system will be one of the following,
derived from the contents of C<$^O>, or if C<$^O> can not be found, from the
contents of C<$Config::Config{osname}> (see native L<Config> library), or if
that doesn't contain a recognizable value, finally falls back to C<UNIX>.

Generally speaking, Linux operating systems are going to be detected as C<UNIX>.
This isn't a bug.  The OS FAMILY to which it belongs uses C<UNIX> style
filesystem conventions and line endings, which are the relevant things to
file handling operations.

=over

=item UNIX

Specifics: OS name =~ /^(?:darwin|bsdos)/i

=item CYGWIN

Specifics: OS name =~ /^cygwin/i

=item WINDOWS

Specifics: OS name =~ /^MSWin/i

=item VMS

Specifics: OS name =~ /^vms/i

=item DOS

Specifics: OS name =~ /^dos/i

=item MACINTOSH

Specifics: OS name =~ /^MacOS/i

=item EPOC

Specifics: OS name =~ /^epoc/i

=item OS2

Specifics: OS name =~ /^os2/i

=back

=back



=head1 AUTHORS

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

=head1 COPYRIGHT

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

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

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

=head1 SEE ALSO

L<File::Util::Cookbook>, L<File::Util::Manual::Examples>, L<File::Util>

=cut

__END__