view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

        $array[13] = 'blah';     # line 13 of the file is now 'blah'
        print $array[42];        # display line 42 of the file

        $n_recs = @array;        # how many records are in the file?
        $#array -= 2;            # chop two records off the end


        for (@array) {
          s/PERL/Perl/g;         # Replace PERL with Perl everywhere in the file
        }

        # These are just like regular push, pop, unshift, shift, and splice
        # Except that they modify the file in the way you would expect

        push @array, new recs...;
        my $r1 = pop @array;
        unshift @array, new recs...;
        my $r2 = shift @array;
        @old_recs = splice @array, 3, 7, new recs...;

        untie @array;            # all finished

# DESCRIPTION

`Tie::File` represents a regular text file as a Perl array.  Each
element in the array corresponds to a record in the file.  The first
line of the file is element 0 of the array; the second line is element
1, and so on.

The file is _not_ loaded into memory, so this will work even for
gigantic files.

Changes to the array are reflected in the file immediately.

Lazy people and beginners may now stop reading the manual.

## `recsep`

What is a 'record'?  By default, the meaning is the same as for the
`<...>` operator: It's a string terminated by `$/`, which is
probably `"\n"`.  (Minor exception: on DOS and Win32 systems, a
'record' is a string terminated by `"\r\n"`.)  You may change the
definition of "record" by supplying the `recsep` option in the `tie`
call:

        tie @array, 'Tie::File', $file, recsep => 'es';

This says that records are delimited by the string `es`.  If the file
contained the following data:

        Curse these pesky flies!\n

then the `@array` would appear to have four elements:

        "Curse th"
        "e p"
        "ky fli"
        "!\n"

An undefined value is not permitted as a record separator.  Perl's
special "paragraph mode" semantics (à la `$/ = ""`) are not
emulated.

Records read from the tied array do not have the record separator
string on the end; this is to allow

        $array[17] .= "extra";

to work as expected.

(See ["autochomp"](#autochomp), below.)  Records stored into the array will have
the record separator string appended before they are written to the
file, if they don't have one already.  For example, if the record
separator string is `"\n"`, then the following two lines do exactly
the same thing:

        $array[17] = "Cherry pie";
        $array[17] = "Cherry pie\n";

The result is that the contents of line 17 of the file will be
replaced with "Cherry pie"; a newline character will separate line 17
from line 18.  This means that this code will do nothing:

        chomp $array[17];

Because the `chomp`ed value will have the separator reattached when
it is written back to the file.  There is no way to create a file
whose trailing record separator string is missing.

Inserting records that _contain_ the record separator string is not
supported by this module.  It will probably produce a reasonable
result, but what this result will be may change in a future version.
Use 'splice' to insert records or to replace one record with several.

## `autochomp`

Normally, array elements have the record separator removed, so that if
the file contains the text

        Gold
        Frankincense
        Myrrh

the tied array will appear to contain `("Gold", "Frankincense",
"Myrrh")`.  If you set `autochomp` to a false value, the record
separator will not be removed.  If the file above was tied with

        tie @gifts, "Tie::File", $gifts, autochomp => 0;

then the array `@gifts` would appear to contain `("Gold\n",
"Frankincense\n", "Myrrh\n")`, or (on Win32 systems) `("Gold\r\n",
"Frankincense\r\n", "Myrrh\r\n")`.

## `mode`

Normally, the specified file will be opened for read and write access,
and will be created if it does not exist.  (That is, the flags
`O_RDWR | O_CREAT` are supplied in the `open` call.)  If you want to
change this, you may supply alternative flags in the `mode` option.
See [Fcntl](https://metacpan.org/pod/Fcntl) for a listing of available flags.
For example: