view release on metacpan or  search on metacpan

lib/File/Util/Manual.pod  view on Meta::CPAN

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