File::Read(3pm)

📦
version 0.0801 · 4 versions
, in debian bookworm, debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking

💖 File::Read 💖

okay bestie, so this is File::Read, a lil Perl module from the User Contributed Perl Documentation collection, and it's literally the ✨unique interface✨ for reading one or more files. no cap.

🌸 VERSION 🌸

Version 0.0801 — yeah she's an elder but she's still slaying 💅

✨ SYNOPSIS ✨

ok so here's the whole vibe in code form, look:

use File::Read;

# read a file
$file = read_file($path);

# read several files
@files = read_files(@paths);

# aggregate several files
$file = read_files(@paths);

# read a file as root, skip comments and blank lines
$file = read_file({ as_root => 1, skip_comments => 1, skip_blanks => 1 }, $path);

like… it's giving efficient. 🦋

🌈 DESCRIPTION 🌈

so basically this module's whole personality is: functions for reading one or more files, and it has options. plural. many. we love options. scroll down for the deets and the examples, bestie 🫶

🎀 Rationale 🎀

ok story time. this module was born out of a very specific need: reading a whole bunch of files, some as a normal user and some as root, and then doing a lil extra processing on top — and doing ALL of that while staying compatible with Perl 5.004. (yes. 5.004. ancient. iconic. 💀)

File::Slurp handles the first part of that, but not the rest, which is literally why File::Read exists. and if you don't need the whole read-as-root thing or the post-processing features? then honestly it's faster to just use File::Slurp directly. periodt. ✨

💫 EXPORT 💫

by default this module exports all the functions documented afterhand. no holding back. she gives everything.

it also recognizes import options, like:

use File::Read 'err_mode=quiet';

which sets read_file()'s err_mode option default value to quiet. so now you don't have to type it every time, you're welcome 😌

👑 FUNCTIONS 👑

🍓 read_file()

read the files given in argument and return their content — as a list, one element per file, when called in list context, or as one big chunk of text when called in scalar context. and you can set options by passing a hashref as the first parameter. cute, right?

🌸 Options 🌸

  • aggregate — controls how the function returns the content of the files that were successfully read. by default, when set to true (default), the function returns the content as a scalar; when set to false, the content comes back as a list.
  • as_root — tells the function to read the given file(s) as root, using the command indicated by the cmd option. yes, root. main character energy, lowkey scary. 👑
  • cmd — sets the shell command used for reading files as root. default is sudo cat. so like, you need sudo(8) and cat(1) on your system, AND sudoers(5) must be set up so the user can execute cat(1). that's not optional bestie, that's the whole mechanism. 💅
  • err_mode — controls how the function behaves when an error occurs. available values are croak, carp and quiet. default value is croak.
  • skip_comments — tells the functions to remove all comment lines from the read files. bye bye # lines 🧚
  • skip_blanks — tells the functions to remove all blank lines from the read files. no more empty vibes ✨
  • to_ascii — tells the functions to convert the text to US-ASCII using Text::Unidecode. and if that module isn't available? non-ASCII data gets deleted. gone. poof. 💀

🦋 Examples 🦋

just read a file, simple simple:

my $file = read_file($path);

read a file but gimme it as a list:

my @file = read_file({ aggregate => 0 }, $path);

read a file, skipping comments:

my $file = read_file({ skip_comments => 1 }, $path);

read several files, skipping blank lines AND comments:

my @files = read_file({ skip_comments => 1, skip_blanks => 1 }, @paths);

🧚 read_files()

read_files() is just an alias for read_file() — it exists so that it look more sane when you're reading several files. grammar? immaculate. function? identical. iykyk 💜

⭐ DIAGNOSTICS ⭐

  • "Bad value '%s' for option '%s'" — (E) you gave a bad value for the indicated option. please check the documentation for the valid values. (bestie. read the docs. i literally wrote them for you 😭)
  • "This function needs at least one path" — (E) you called a function without giving it argument. she needs a path. at least one. give her something to work with 🙈

🌈 SEE ALSO 🌈

  • File::Slurp
  • IO::All

💖 AUTHOR 💖

Sebastien Aperghis-Tramoni, "<sebastien at aperghis.net>" — the original icon, we stan 👑

🐛 BUGS 🐛

please report any bugs or feature requests to bug-file-read at rt.cpan.org, or through the web interface at <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=File-Read>. he will be notified, and then you'll automatically be notified of progress on your bug as he makes changes. mutual notif relationship, slay 🔥

🫶 SUPPORT 🫶

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

perldoc File::Read

you can also look for information at:

Copyright (C) 2006, 2007 Sebastien Aperghis-Tramoni, 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 doc was served up by perl v5.36.0, dated 2022-11-27, and it's the File::Read(3pm) manual — go read some files, you got this 💅👑

📦 where this page comes from