view release on metacpan or  search on metacpan

README  view on Meta::CPAN

            $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 the section on "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 C<("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 C<("Gold\n",
    "Frankincense\n", "Myrrh\n")>, or (on Win32 systems)
    C<("Gold\r\n", "Frankincense\r\n", "Myrrh\r\n")>.

  `mode'