NAME

File::Alter

SYNOPSIS

    use File::Alter;
    
    $fh = File::Alter->new( "filename.txt" );
    
    $fh->insert( 3 => "new text\n" );   # insert text on line 3

    $fh->remove( 7 );                   # remove line 7
    $fh->remove( '$LINE =~ /foo/' );    # remove the line if 
                                        # it matches 'foo'

    $fh->alter( qr/2/, 'TWO' );         # replace all occurrences of 
                                        # 2 by TWO
    $fh->alter( a => 'b', '$e == 4');   # replace all a by b if 
                                        # $e equals 4

    $str = $fh->as_string;              # returns the buffer as string

    ### global variables you can use in conditions
    $File::Alter::LINE                  # contents of the current line
    $File::Alter::LINENUMBER            # line number of the current line

DESCRIPTION

File::Alter allows in memory manipulation of a file's contents. The modified buffer will NOT be written back to the file at any point! This is useful if you want to massage read-only files, or files you do not wish to alter, before they are read or used by an application.

File::Alter inherits directly from IO::String adding it's own methods. This means that any method that is supported by IO::String is supported by File::Alter.

METHODS

$fh = File::Alter->new( FILENAME );

Creates a new File::Alter filehandle object. The arguments get passed straight to IO::String::new, so even more complicated strings are accepted. Please note though that opening a file for writing makes no sense, as you're only able to modify the files contents in memory, without writing it to disk.

$string = $fh->as_string;

Returns the stringified version of the internal buffer

$bool = $fh->insert( $line => $text );

Inserts the given text at linenumber $line. This text can be multiline if desired, as it's a plain insert. That means that if you want this text to be on it's own line, you should add a newline to it.

$bool = $fh->alter( $find => $replace, [$condition] );

Looks on a per-line basis for the string specified by $find and tries to replace that with $replace. Note that $find can be a qr// object if you so desire.

If you specify a condition, the substitute will only be attempted if the condition evaluates to true. You can use some of File::Alter's global variables to make conditions based on line numbers and contents; see the GLOBAL VARIABLES section for details.

$bool = $fh->remove( $line | $condition );

Removes a line based on either line number or condition.

If you specify a condition, the remove will only be done if the condition evaluates to true. You can use some of File::Alter's global variables to make conditions based on line numbers and contents; see the GLOBAL VARIABLES section for details.

GLOBAL VARIABLES

$File::Alter::LINE

Contains the contents of the current line being read. You can use this in a condition if you wish to only have it apply relative to a certain line number. For example:

    $fh->remove( '$LINE =~ /foo/ or $LINE =~ /bar/' );
    
    To remove all lines that contain C<foo> or C<bar>.

$File::Alter::LINENUMBER

Containts the current line number of the file being read. You can use this in a condition if you wish to only have it apply relative to a certain line number. For example:

    $fh->remove( '$LINENUMBER > 20 and $LINENUMBER < 30' );
    
    To remove all lines between 20 and 30.

CAVEATS

Filehandle position always reset to 0 after modification

As we're modifying the filehandle on every alter, insert and replace, we can not be certain that the position the last read was from is still correct (especially since the position is in bytes), nor can we be sure it's desirable.

So, after every alteration of the in memory string using above mentioned methods, the file's position is set to 0, so any read will start again at the beginning of the file

use $File::Alter::LINENUMBER rather than $.

$. isn't actually the current line number of the last active filehandle but the amount of times a line has been read from the last active filehandle.

This is a subtle but important difference, seeing when you loop over a file as a whole, and then read the first line again, $. would hold lines in the file + 1 rather than 1.

$File::Alter::LINENUMBER does what you expect here and would hold 1.

AUTHOR

This module by Jos Boumans <kane@cpan.org>.

COPYRIGHT

This module is copyright (c) 2005 Jos Boumans <kane@cpan.org>. All rights reserved.

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