---
name: "File::File::Data"
section: "3pm"
platform: "linux"
package: "libfile-data-perl"
version: "1.16-3"
release: "Debian 9 (Stretch)"
platforms: ["linux"]
url: "https://new.carta.tech/File::File::Data"
---

# File::File::Data(3pm)

interface to file data

## 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 succesful.  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;
```

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

  Hopefully future versions of perl may return a reference if you request one, but as this is not supported generically yet, nor do we, so we require the variable to be set.  There may be an argument to make this a reference 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
  ```

## PRIVATE

Private methods not expected to be called by anybody, and completely unsupported.

Expected to metamorphose regularly - do **not** call these - you have been warned!

\_var

Variable get/set method

```
    my $get = $o_dat->_var($key);        # get
    my $set = $o_dat->_var($key, $val);    # set
```

\_debug

Print given args on STDOUT

```
    $o_dat->_debug($msg) if $File::Data::DEBUG;
```

\_vars

Return dumped env and object **key** and **values**

```
    print $o_dat->_vars;
```

\_err

Get/set error handling methods/objects

```
    my $c_sub = $o_dat->_err('insert'); # or default
```

\_error

By default prints error to STDERR, will **croak** if **File::Data::FATAL** set, returning ().

See EXAMPLES for info on how to pass your own error handlers in.

\_mapfile

Maps file

```
    my $file = $o_dat->_mapfile($filename);
```

\_mapperms

Maps given permissions to appropriate form for **FileHandle**

```
    my $perms = $o_dat->_mapperms('+<');
```

\_maperrs

Map error handlers, if given

```
    my $h_errs = $o_dat->_maperrs(\%error_handlers);
```

\_enter

Mark the entering of a special section, or state

```
    my $entered = $o_dat->enter('search');
```

\_leave

Mark the leaving of a special section, or state

```
    my $left = $o_dat->_leave('search');
```

\_fh

Get and set **FileHandle**.

Returns undef otherwise.

```
    my $FH = $o_dat->_fh($FH);
```

## UTILITY

Private methods not expected to be called by anybody, and completely unsupported.

Expected to metamorphose regularly - do **not** call these - you have been warned!

The following utility methods return integer values

```
    1 = success
    0 = failure
```

\_init

Setup object, open a file, with permissions.

```
    my $i_ok = $o_date->_init($file, $perm, $h_errs);
```

\_check\_access

Checks the args for existence and appropriate permissions etc.

```
    my $i_isok = $o_dat->_check_access($filename, $permissions);
```

\_open

Open the file

```
    my $i_ok = $o_dat->_open;
```

\_lock

Lock the file

```
    my $i_ok = $o_dat->_lock;
```

\_unlock

Unlock the file

```
    my $i_ok = $o_dat->_unlock;
```

\_close

Close the filehandle

```
    my $i_ok = $o_dat->_close;
```

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

## LICENSE AND COPYRIGHT

Copyright 2012 by Richard Foley \<file.data@rfi.net\>

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

See http://www.perl.com/perl/misc/Artistic.html

## POD ERRORS

Hey! **The above document had some coding errors, which are explained below:**

- Around line 63:

  You forgot a '=back' before '=head1'

- Around line 872:

  You can't have =items (as at line 878) unless the first thing after the =over is an =item

- Around line 1181:

  You can't have =items (as at line 1189) unless the first thing after the =over is an =item