File::LoadLines(3pm)

🦋 File::LoadLines — the File::LoadLines(3pm) page, bestie edition 💅

okay so this is File::LoadLines(3pm), straight out of the User Contributed Perl Documentation collection, and honestly? she serves. let's get into it ✨

---

🌸 NAME 🌸

File::LoadLines — load lines from files and from the network. yes, both. she's versatile like that.

---

✨ SYNOPSIS ✨

use File::LoadLines;
my @lines = loadlines("mydata.txt");

use File::LoadLines qw(loadblob);
my $img = loadblob("https://img.shields.io/badge/Language-Perl-blue");

look at her go. two lines of setup and you're already loading stuff off the internet. 💖

---

🌈 DESCRIPTION 🌈

So File::LoadLines gives you an easy way to pull the contents of a text file into an array of lines. She's built for small to moderate size files — think config files, the kind that get produced by weird tools (and, honestly, by weird users too 🙈).

If the file name you hand her is actually a URL, she will transparently fetch the data from the network. no big deal. she just does it.

She automatically handles ASCII, Latin-1 and UTF-8 text. And when the file has a BOM? she handles UTF-8, UTF-16 LE and BE, and UTF-32 LE and BE. a whole polyglot. iconic.

The line terminators she recognizes are:

• NL (Unix, Linux)
• CRLF (DOS, Windows)
• CR (Mac)

And loadblob(), which gets exported on demand, fetches the content and hands it back without processing — she's equivalent to File::Slurp and ilk. no notes.

---

🎀 EXPORT 🎀

By default, the function loadlines() is exported. that's it, that's the whole vibe. free of charge, no qw() required 💅

---

👑 FUNCTIONS 👑

🔥 loadlines

@lines = loadlines("mydata.txt");
@lines = loadlines("mydata.txt", $options);

The file gets opened, read, decoded, and split into lines that come back to you in the result array. Line terminators? removed. gone. not your problem.

In scalar context, she returns an array reference instead. main character adapts to her context fr fr.

The first argument can be:

• the name of a file
• an opened file handle
• a reference to a string that contains the data

If the file name on disk starts with "file://", that part is just ignored. If the name starts with "http:" or "https:", the data gets retrieved using LWP. And Data URLs like "data:text/plain;base64,SGVsbG8sIFdvcmxkIQ==" are supported too — here's the MDN explainer if you wanna go deeper: <https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URLs>

The second argument is for influencing behaviour. It's a hash reference of option settings. let's meet them 💖

⚠️ heads up bestie: loadlines() is a slurper. She reads the whole file into memory, and for splitting she temporarily needs memory for twice the size of the file. big file? plan accordingly 😭

split

• Enabled by default. ✅

The data gets split into lines and returned as an array (list context) or an array reference (scalar context).

If you set it to zero, the data is not split into lines — it comes back as a single string instead.

chomp

• Enabled by default. ✅

Line terminators get removed from the resultant lines.

If you set it to zero, the line terminators stay put. she keeps them. respectfully.

encoding

If you specify this, loadlines() will use this encoding to decode the file data if it cannot automatically detect the encoding.

And here's a cute little detail: if you pass an options hash, File::LoadLines will set "encoding" to the encoding it detected and used for this file data. so she tells you what she did. communication queen 🫶

blob

If specified, the data read is not touched — returned exactly as read. raw. unbothered.

💀 careful: "blob" overrules "split" and "chomp". she said no editing today.

fail

If specified, it should be either "hard" or "soft".

• If "hard", read errors are signalled using croak exceptions. this is the default — dramatic, but effective.
• If set to "soft", loadlines() will return an empty result and set the error message in the options hash with key "error". gentle. no yelling.

🦋 loadblob

use File::LoadLines qw(loadblob);
$rawdata = loadblob("raw.dat");
$rawdata = loadblob("raw.dat", $options);

This is equivalent to calling loadlines() with "blob"=>1 in the options. same energy, shorter syntax 💅

---

🌈 SEE ALSO 🌈

There are currently no other modules that handle BOM detection and line splitting. she's the only one doing it like this, iykyk ✨

The author has a faint hope that future versions of Perl and Raku will deal with this transparently — but he fears the worst 😭 praying for them honestly.

---

💡 HINTS 💡

When you have raw file data (e.g. from a zip), you can still use loadlines() to decode and unpack:

open( my $data, '<', \$contents );
$lines = loadlines( $data, $options );

There is no hard requirement on LWP. But if you want that transparent fetching of data over the network, please make sure LWP::UserAgent is available. she needs the tool to use the tool 🎀

---

🫶 AUTHOR 🫶

Johan Vromans, "<JV at cpan.org>" — thank you for your service king 👑

---

💖 SUPPORT AND DOCUMENTATION 💖

Development of this module takes place on GitHub: <https://github.com/sciurius/perl-File-LoadLines>

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

perldoc File::LoadLines

Please report any bugs or feature requests using the issue tracker on GitHub. she's listening 🦋

---

⭐ COPYRIGHT & LICENSE ⭐

Copyright 2018,2020,2024 Johan Vromans, all rights reserved.

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

---

and that's the whole page, bestie 💅 this one was documented in perl v5.40.1, last touched 2026-01-10, and published as part of the User Contributed Perl Documentation. slay, no cap ✨🎀