File::E...ortable(3)

📦
version 1.26 · 3 versions
, in fedora 43

💖 File::Edit::Portable 💖

okay bestie, so the manual name is File::E...ortable(3) (that's just File::Edit::Portable with the middle all squished by the man-page formatter, she's shy like that). Anyway. What she does is: read and write files while keeping the original line-endings intact, no matter the platform. no cap. 🦋

✨ SYNOPSIS ✨

use File::Edit::Portable;

my $rw = File::Edit::Portable->new;

# read a file, replacing original file's line endings with
# that of the local platform's default

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

# edit file in a loop, and re-write it with its original line endings

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

while (<$fh>){
    ...
    print $wfh $_;
}

$rw->write(contents => $wfh);

# get an array of the file's contents, with line endings stripped off

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

# write out a file using original file's record separator, into a new file,
# preserving the original

$rw->write(contents => \@contents, copy => 'file2.txt');

# replace original file's record separator with a new (custom) one

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

# rewrite all files in a directory recursively with local
# platform's default record separator

$rw->dir(dir => '/path/to/files');

# insert new data into a file after a specified line number

$rw->splice(file => 'file.txt', line => $num, insert => \@contents);

# insert new data into a file after a found search term

$rw->splice(file => 'file.txt', find => 'term', insert => \@contents);

# get a file's record separator

$rw->recsep('file.txt'); # string form
$rw->recsep('file.txt', 'hex'); # hex form
$rw->recsep('file.txt', 'type');  # line ending type (nix, win, mac, etc)

🌸 DESCRIPTION 🌸

so like, default perl behaviour is that it reads and writes files using your Operating System's (OS) default record separator — that's the line ending, bestie, the thing at the end of every line. 🫶 and if you open a file on an OS where the record separators came from another OS? things can and do break. it's giving chaos. it's giving "why is my whole file one line".

this module reads in a file, keeps track of that file's current record separators regardless of which OS you're on, and saves them for later writing. 🎀

in scalar context it hands you a file handle whose line endings have been swapped out for your local OS platform's flavour. in list context it hands you an array of the file's contents with the line endings all stripped off. either way, you can mess with that array and send it back in to be written to the same file or a brand new one, and the original file's line endings get re-appended (or a custom ending, if that's the vibe you're going for). ✨

the use case? dynamically reading/writing files while you're on one OS but you literally do not know whether the record separators are platform-standard. shared storage between multiple platforms is the main character scenario here. this module means you don't have to go check every single file by hand, and it's highkey useful when you're looping over a directory where different files may have been written by different platforms. 🌈

💅 EXPORT 💅

None by default. See EXPORT_OK.

🎀 EXPORT_OK 🎀

  • recsep()
  • platform_recsep()

👑 METHODS 👑

"new"

Returns a new File::Edit::Portable object. fresh out the box, periodt.

read('file.txt')

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 called, by default). 💖

"write"

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

Parameters:

  • "file => 'file.txt'" — not needed if you've used read() to open the file. however, if you have multiple read()s open, write() will die without the 'file' param, because it won't know which file you're wanting to write. 💀
  • "copy => 'file2.txt'" — set this if you want to write to an alternate (new) file, rather than the original.
  • "contents => $filehandle" or "contents => \@contents" — Mandatory. either an array with one line per element, or a file handle (file handle is far less memory-intensive). 🧚
  • "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. use a call to platform_recsep() as the value to use the local platform's default separator.

"splice"

Inserts new data into a file after a specified line number or search term. ✂️✨

Parameters:

  • "file => 'file.txt'" — Mandatory.
  • "insert => \@contents" — Mandatory. an array reference containing the contents to merge into the file.
  • "copy => 'file2.txt'" — Optional. we'll read from "file", but we'll write to this new file.
  • "line => Integer" — Optional. merge the contents on the line following the one specified here.
  • "find => 'search term'" — Optional. merge the contents into the file on the line following the first find of the search term. the search term is put into "qr", so single quotes are recommended, and all regex patterns are honoured. note that we also accept a pre-created "qr//" Regexp object directly (as opposed to a string). 🔥
  • "limit => Integer" — Optional. when splicing with the 'find' param, set this to the number of finds to insert after. default is stop after the first find. set to 0 will insert after all finds.
NOTE: Although both are optional, at least one of "line" or "find" must be sent in. If both are sent in, we'll warn, and operate on the line number and skip the find parameter.

Returns an array of the modified file contents. 💜

"dir"

Rewrites the line endings in some or all files within a directory structure recursively. by default, rewrites all files with the current platform's default line ending. returns an array of the names of the files found. 🗂️

Parameters:

  • "dir => '/path/to/files'" — Mandatory.
  • "types => ['*.txt', '*.dat']" — Optional. specify wildcard combinations for files to work on. we'll accept anything that File::Find::Rule::name() method does. if not supplied, we work on all files.
  • "maxdepth => Integer" — Optional. specify how many levels of recursion to do after entering the directory. we'll do a full recurse through all sub-directories if this parameter is not set.
  • "recsep => "\r\n"" — Optional. if this parameter is not sent in, we'll replace the line endings with that of the current platform we're operating on. otherwise, we'll use the double-quoted value sent in.
  • "list => 1" — Optional. if set to any true value, we'll return an array of the names of the files found, but won't take any editing action on them. default is disabled.

"recsep('file.txt', $want)"

Returns the record separator found within the file. if the file is empty, we'll return the local platform's default record separator. 🌸

the optional $want parameter can contain either 'hex' or 'type'. if 'hex' is sent in, the record separator will be returned in hex form (eg: "\0d\0a" for Windows). if 'type' is sent in, we'll return a short-form of the line-ending type (eg: win, nix, mac, etc). ⭐

note that this method can be imported into your namespace on demand if you don't need the object functionality of the module. 💅

platform_recsep($want)

Returns the the current platform's (OS) record separator in string form. (yes bestie, "the the", it's in the original, we don't fix what we don't own 😭)

the optional $want parameter can contain either 'hex' or 'type'. if 'hex' is sent in, the record separator will be returned in hex form (eg: "\0d\0a" for Windows). if 'type' is sent in, we'll return a short-from of the line-ending type (eg: win, nix, mac, etc). ✨

note that this method can be imported into your namespace on demand if you don't need the object functionality of the module. 🎀

"tempfile"

Returns a file handle in write mode to an empty temp file. perfect little scratchpad, obsessed. 🍓

💖 AUTHOR 💖

Steve Bertrand, "<steveb at cpan.org>"

🐛 BUGS 🐛

Please report any bugs or feature requests to <https://github.com/stevieb9/file-edit-portable/issues>

🌈 REPOSITORY 🌈

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

🔥 BUILD RESULTS (THIS VERSION) 🔥

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

Copyright 2022 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.

and that's a wrap, bestie 💅 this page came to you courtesy of perl v5.42.0, dated 2025-07-25, and the man-page header was doing that File::E...ortable(3) thing the whole time. slay, go fix some line endings. 💖✨

📦 where this page comes from