Provided by: libfile-data-perl_1.20-4_all bug

NAME

       File::Data - interface to file data

DESCRIPTION

       Wraps all the accessing of a file into a convenient set of calls for reading and writing
       data, including a simple regex interface.

       Note that the file needs to exist prior to using this module!

       See new()

SYNOPSIS

           use strict;

           use File::Data;

           my $o_dat = File::Data->new('./t/example');

           $o_dat->write("complete file contents\n");

           $o_dat->prepend("first line\n"); # line 0

           $o_dat->append("original second (last) line\n");

           $o_dat->insert(2, "new second line\n"); # inc. zero!

           $o_dat->replace('line', 'LINE');

           print $o_dat->READ;

           Or, perhaps more seriously :-}

               my $o_sgm = File::Data->new('./sgmlfile');

               print "new SGML data: ".$o_sgm->REPLACE(
                   '\<\s*((?i)tag)\s*\>\s*((?s).*)\s*\<\s*((?i)\s*\/\s*tag)\s*\>',
                   qq|<tag>key="val"</tag>|,
               ) if $o_sgm;

           See METHODS and EXAMPLES.

IMPORTANT

       lowercase method calls return the object itself, so you can chain calls.

           my $o_obj = $o_dat->read; # ! <= object !

       UPPERCASE method calls return the data relevant to the operation.

           my @data  = $o_dat->READ; # ! <= data   !

       While this may occasionally be frustrating, using the principle of least surprise, it is
       at least consistent.

       See do

EXPLANATION

           The idea is to standardise accessing of files for repetitive and straight forward
           tasks, and remove the repeated and therefore error prone file access I have seen in
           many sites, where varying, (with equivalently varying success), methods are used to
           achieve essentially the same result - a simple search and replace and/or a regex
           match.

           Approaches to opening and working with files vary so much, where one person may wish
           to know if a file exists, another wishes to know whether the target is a file, or if
           it is readable, or writable and so on.  Sometimes, in production code even (horror),
           file's are opened without any checks of whether the open was successful.  Then there's
           a loop through each line to find the first or many patterns to read and/or replace.
           With a failure, normally the only message is 'permission denied', is that read or
           write access, does the file even exist? etc.

           This module attempts to provide a plain/generic interface to accessing a file's data.
           This will not suit every situation, but I have included some examples which will
           hopefully demonstrate that it may be used in situations where people would normally go
           through varying and inconsistent, (and therefore error-prone),  procedures - to get at
           the same data.

           Theoretically you can mix and match your read and writes so long as you don't open
           read-only.

               my $o_dat  = File::Data->new($file);

               my $i_snrd = $o_dat->append($append)->REPLACE($search, $replace);

               print $o_dat->READ;

           If you want to apply the same regex, or insert/prepend/replacement/whatever mechanism,
           to many different files, then the neatest solution may be to do something like the
           following:

               foreach my $file ( @list_of_file_names ) {
                   my $o_dat  = File::Data->new($file);

                   my $i_snrd = $o_dat->append($append)->REPLACE($search, $replace);

                   print $o_dat->READ;
               }

           One last thing - I'm sure this could be made more efficient, and I'd be receptive to
           any suggestions to that effect. Note though that the intention has been to create a
           simple and consistent interface, rather than a complicated one.

METHODS

       new Create a new File::Data object (default read-write).

               my $o_rw = File::Data->new($filename); # read-write

               my $o_ro = File::Data->new($filename, 'ro'); # read-only

           Each file should have it's own discrete object.

           Note that if you open a file read-only and then attempt to write to it, that will be
           regarded as an error, even if you change the permissions in the meantime.

           Further: The file must exist before successful use of this method is possible.  This
           is not a replacement for modules which create and delete files, this is purely
           designed as an interface to the data of existing files.  A create function is a future
           possibility.

           Look in EXAMPLES for a more complete explanation of possible arguments to the new()
           method

       read
           Read all data from file

               $o_dat = $o_dat->read; # !

               my @data = $o_dat->READ;

       _internal
           read

               does this...

       write
           Write data to file

               my $o_dat = $o_dat->WRITE; # !

               my @written = $o_dat->write;

       prepend
           Prepend to file

               my $o_dat = $o_dat->prepen(\@lines); # !

               my @prepended = $o_dat->prepend(\@lines);

       insert
           Insert data at line number, starting from '0'

               my $o_dat = $o_dat->insert($i_lineno, \@lines); # !

               my @inserted = $o_dat->INSERT($i_lineno, \@lines);

       append
           Append to file

               my $o_dat = $o_dat->append(\@lines); # !

               my @appended = $o_dat->APPEND(\@lines);

       search
           Retrieve data out of a file, simple list of all matches found are returned.

           Note - you must use capturing parentheses for this to work!

               my $o_dat = $o_dat->search('^(.*\@.*)$'); # !

               my @addrs = $o_dat->SEARCH('^(.*\@.*)$');

               my @names = $o_dat->SEARCH('^(?:[^:]:){4}([^:]+):');

       replace
           Replace data in a 'search and replace' manner, returns the final data.

               my $o_dat = $o_dat->replace($search, $replace); # !

               my @data = $o_dat->REPLACE($search, $replace);

               my @data = $o_dat->REPLACE(
                   q|\<a href=(['"])([^$1]+)?$1| => q|'my.sales.com'|,
               );

           This is simple, in that you can do almost anything in the search side, but the replace
           side is a bit more restricted, as we can't effect the replacement modifiers on the
           fly.

           If you really need this, perhaps (?{}) can help?

       xreturn
           Returns the product of the given (or last) do(), undef on failure.

               my $o_dat = $o_dat->prepend($A)->append($b)->return('prepend'); # !

               my @prepended = $o_dat->prepend($A)->append($b)->RETURN('prepend');

               my @appended  = $o_dat->prepend($A)->append($b)->RETURN; # like read()

       create
           placeholder - unsupported

       delete
           placeholder - unsupported

       close
           Close the file

               my $i_closed = $o_dat->close; # 1|0

       info
           placeholder - unsupported

VARIABLES

       Various variables may be set affecting the behaviour of the module.

       $File::Data::DEBUG
           Set to 0 (default) or 1 for debugging information to be printed on STDOUT.

               $File::Data::DEBUG = 1;

           Alternatively  set to a regex of any of the prime methods to debug them individually.

               $File::Data::DEBUG = '(ap|pre)pend';

       $File::Data::FATAL
           Will die if there is any failure in accessing the file, or reading the data.

           Default = 0 (don't die - just warn);

               $File::Data::FATAL = 1;    # die

       $File::Data::REFERENCE
           Will return a reference, not a list, useful with large files.

           Default is 0, ie; methods normally returns a list.  There may be an argument to make
           returns work with references by default, feedback will decide.

               $File::Data::REFERENCE = 1;

               my $a_ref = $o_dat->search('.*');

               print "The log: \n".@{ $a_ref };

       $File::Data::SILENT
           Set to something other than zero if you don't want error messages ?-\

               $File::Data::SILENT = 0; # per line

       $File::Data::STRING
           Where regex's are used, default behaviour is to treate the entire file as a single
           scalar string, so that, for example, (?ms:...) matches are effective.

           Unset if you don't want this behaviour.

               $File::Data::STRING = 0; # per line

       $File::Data::PERMISSIONS
           File will be opened read-write (insert() compatible) unless this variable is set
           explicitly or given via new().  In either case, unless it is one of our valid
           permission keys declared below, it will be passed on to FileHandle and otherwise not
           modified.  We don't support fancy permission sets, just read or write.

           Read-only permissions may be explicitly set using one of these keys:

               $File::Data::PERMISSIONS = 'ro'; # or readonly or <

           Or, equivalently, for read-write (default):

               $File::Data::PERMISSIONS = 'rw'; # or readwrite or +<

           Note that it makes no sense to have an 'append only' command (>>), we'd have to
           disable all of write, search and replace, and insert, etc. in that case - just use the
           append() method only.

           This is a KISS-compatible module remember?

       # ================================================================

SPECIAL

       ...

       AUTOLOAD
           Any unrecognised function will be passed to the FileHandle object for final
           consideration, behaviour is then effectively 'o_dat ISA FileHandle'.

               $o_dat->truncate;

EXAMPLES

       Typical construction examples:

           my $o_rw = File::Data->new($filename, 'rw');

           my $o_ro = File::Data->new($filename, 'ro');

       complete
               my $o_dat = File::Data->new('./jabber');

               $o_dat->write("  Bewxre the Jabberwock my son,\n");

               $o_dat->prepend("The Jxbberwock by Lewis Cxrroll:\n");

               $o_dat->append("  the claws thxt snxtch,\n  ...\n");

               $o_dat->insert(2, "  the jaws which bite.\n");

               $o_dat->replace('x', 'a');

               print $o_dat->SEARCH('The.+\n')->REPLACE("The.+\n", '')->return('search');

               print $o_dat->READ;

       error
           Failure is indicated by an error routine being called, this will print out any error
           to STDERR, unless warnings are declared fatal, in which case we croak.  You can
           register your own error handlers for any method mentioned in the METHOD section of
           this document, in addition is a special init call for initial file opening and general
           setting up.

           Create a read-write object with a callback for all errors:

               my $o_rw = File::Data->new($filename, 'ro', {
                   'error'        => \&myerror,
               });

           Create a read-only object with a separate object handler for each error type:

               my $o_rw = File::Data->new($filename, 'rw', {
                   'error'        => $o_generic->error_handler,
                   'insert'    => $o_handler->insert_error,
                   'open'        => $o_open_handler,
                   'read'        => \&carp,
                   'write'        => \&write_error,
               });

       commandline
           From the command line:

               C<perl -MFile::Data -e "File::Data->new('./test.txt')->write('some stuff')">

           And (very non-obfuscated)

             C<
             perl -MFile::Data -e "@x=sort qw(perl another hacker just);
               print map {split(\"\n\", ucfirst(\$_).\" \")}\
               File::Data->new(\"./t/japh\")->\
                 write(shift(@x).\"\n\")->    \
                 append(shift(@x).\"\n\")->   \
                 prepend(shift(@x).\"\n\")->  \
                 insert(2, shift(@x).\"\n\")->\
               READ;"
             >

           If you still have problems, mail me the output of

               make test TEST_VERBOSE=1

       do  Simple wrapper for method calls, returning the content.

               my @inserted = $o_dat->do('insert', @this);

               my @appended = $o_dat->do('append', @this);

           An addendum to this method, and to make life generally easier, is that you can also
           call any of the above methods in uppercase, to call via do() eg;

               my @data = $o_dat->WRITE($this)->APPEND->($that)->read;

           First argument is the method to call, followed by the arguments that method expects.

               perl -MFile::Data -e "print File::Data->new($file)->INSERT(3,
               \"third line\n\")->READ";

           If you want to get at the output of a particular called method see return()

AUTHOR

       Richard Foley <File.Data@rfi.net>

COPYRIGHT AND LICENSE

       Copyright (C) 2016 by Richard Foley

       This is free software; you can redistribute it and/or modify it under the same terms as
       the Perl 5 programming language system itself.