NAME

    File::Edit::Portable - Read and write files while keeping the original
    line-endings intact, no matter the platform.

SYNOPSIS

        use File::Edit::Portable;
    
        my $rw = File::Edit::Portable->new;
    
        my @contents = $rw->read(file => 'file.txt');
    
        push @contents, 'new line 1', 'new line 2';
    
        $rw->write(contents => \@contents);
    
        # get the record separator for a file
    
        my $hex_record_separator = $rw->recsep('file');
    
        # override the found line ending with a custom one 
    
        $rw->write(recsep => "\r\n", contents => \@contents);

DESCRIPTION

    The default behaviour of perl is to read and write files using the
    Operating System's (OS) default record separator (line ending). If you
    open a file on an OS where the record separators are that of another
    OS, things can and do break.

    This module will read in a file, keep track of the file's current
    record separators regardless of the OS, and write the file back out
    using those same original line endings, or optionally a user supplied
    custom record separator.

    Uses are for dynamically reading/writing files while on one Operating
    System, but you don't know whether the record separators are
    platform-standard. This module affords you the ability to not have to
    check.

    You're returned an array with all of the lines of the file on read. You
    can then manipulate it, and then pass it back for re-writing the file
    (or a copy).

METHODS

 new

    Returns a new File::Edit::Portable object.

 read

    Opens a file and extracts its contents, returning an array of the
    file's contents where each line of the file is a separate element in
    the array (line endings have been stripped off).

    Parameters: file => 'filename'

 write

    Writes the data back to the original file, or alternately a copy of the
    file. Returns 1 on success. If you inadvertantly append newlines to the
    new elements of the contents array, we'll strip them off before
    appending the real newlines.

    Parameters:

    file => 'file': Not needed if you've used read() to open the file.

    copy => 'file2': Set this if you want to write to an alternate file,
    rather than the original.

    contents => \@contents: Mandatory, should contain a reference to the
    array that was returned by read().

    recsep => "\r\n": Optional, a double-quoted string of any characters
    you want to write as the line ending (record separator). This value
    will override what was found in the read() call. Common ones are "\r\n"
    for Windows, "\n" for Unix and "\r" for Mac.

 recsep('file')

    Returns a string of the hex representation of the line endings (record
    separators) in 'file'. For example, "\0d\0a" will be returned for
    Windows line endings (CRLF).

AUTHOR

    Steve Bertrand, <steveb at cpan.org>

BUGS

    Please report any bugs or feature requests to bug-file-edit-portable at
    rt.cpan.org, or through the web interface at
    http://rt.cpan.org/NoAuth/ReportBug.html?Queue=File-Edit-Portable. I
    will be notified, and then you'll automatically be notified of progress
    on your bug as I make changes.

SUPPORT

    You can find documentation for this module with the perldoc command.

        perldoc File::Edit::Portable

    You can also look for information at:

      * RT: CPAN's request tracker (report bugs here)

      http://rt.cpan.org/NoAuth/Bugs.html?Dist=File-Edit-Portable

      * Search CPAN

      http://search.cpan.org/dist/File-Edit-Portable/

LICENSE AND COPYRIGHT

    Copyright 2015 Steve Bertrand.

    This program is free software; you can redistribute it and/or modify it
    under the terms of either: the GNU General Public License as published
    by the Free Software Foundation; or the Artistic License.

    See http://dev.perl.org/licenses/ for more information.