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;

    Get a (read-only) file handle which (if necessary) has had the existing
    record separator (line endings) replaced with the current local
    platform's (OS's).

        my $fh = $rw->read(file => 'file.txt');

    Get an array of the contents of the file after having record separators
    checked/stored, modify the contents, then re-write the file with the
    original record separator found.

        my @contents = $rw->read(file => 'file.txt');
    
        s/this/that/g for @contents;
    
        $rw->write(contents => \@contents);

    When writing, override the original record separator with a custom one.

        $rw->write(recsep => "\r\n", contents => \@contents);

    Get the original record separator found in the file in hex format.

        my $hex_record_separator = $rw->recsep('file');

    Get the local platforms record separator. This will be in string
    representation.

        my $platform_recsep = $rw->platform_recsep;

    There's also a non-OO interface...

        use File::Edit::Portable qw(read write);
    
        my $fh = read('file.txt');
    
        # and/or
    
        my @contents = read('file.txt');
    
        # then
    
        write('file.txt', \@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. It can return either a file
    handle (in scalar context) that has had its line endings replaced with
    that of the local OS platform, or an array of the file's contents (in
    list context) with line endings stripped off. You can then modify this
    array and send it back in for writing to the same file or a new file,
    where the original file's line endings will be re-appended (or a custom
    ending if you so choose).

    Uses are for dynamically reading/writing files while on one Operating
    System, but you don't know whether the record separators are
    platform-standard. Shared storage between multpile platforms are a good
    use case. This module affords you the ability to not have to check each
    file, and is very useful in looping over a directory where various
    files may have been written by different platforms.

EXPORT

    None by default. See EXPORT_OK

EXPORT_OK

    If you desire using the non-OO functionality, the following functions
    are exported on demand.

    read() and write(). If there are namespace collisions with those two
    functions, pread() and pwrite() are available as well.

METHODS

 new

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

 read

    Parameters: file => 'filename'

    In scalar context, will return a read-only file handle to a copy of the
    file that has had its line endings replaced with those of the local OS
    platform's record separator.

    In list context, will return an array, where each element is a line
    from the file, with all line endings stripped off.

    In both cases, we save the line endings that were found in the original
    file (which is used when write() is used, by default).

 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 (new)
    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).

 platform_recsep

    Returns the string representation of the current platform's (OS) record
    separator. Takes no parameters.

FUNCTIONS

 read('file.txt')

    pread() can alternately be imported in the event of namespace
    collisions.

    In scalar context, will return a read-only file handle. In list
    context, returns an array with each element being a line in the file,
    with the endings stripped off.

 write('file.txt', \@contents, 'copy.txt', "\r\n")

    pwrite() can alternately be imported in the event of namespace
    collisions.

    Writes back out the file (or alternately a new file (copy.txt), using
    the original file's line endings, or optionally a custom record
    separator as specified by the last parameter. Note the record separator
    MUST be sent in within double-quotes.

    If you want to send in a custom record separator but not use a copy
    file, just set the third parameter (copy.txt) to undef within the call.

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.

REPOSITORY

    https://github.com/stevieb9/file-edit-portable

BUILD RESULTS

    Travis-CI: https://travis-ci.org/stevieb9/file-edit-portable

    CPAN Testers: http://matrix.cpantesters.org/?dist=File-Edit-Portable

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.

