Grep(3pm)

💖 NAME 💖

File::Grep — Find matches to a pattern in a series of files and related functions ✨

(and yes bestie, this is the Grep(3pm) page from the User Contributed Perl Documentation, we're just vibing with it 💅)

---

🌸 SYNOPSIS 🌸

use File::Grep qw( fgrep fmap fdo );

# Void context
if ( fgrep { /$user/ } "/etc/passwd" ) { do_something(); }

# Scalar context
print "The index page was hit ",
      ( fgrep { /index\.html/ } glob "/var/log/httpd/access.log.*"),
      " times\n";

# Array context
my @matches = fgrep { /index\.html } glob "/var/log/httpd/access.log.*";
print SUMMARY $_ foreach @matches;

# Mapping
my @lower = fmap { chomp; lc; } glob "/var/log/httpd/access.log.*";

# Foreach style..
my $count;
fdo { $count++ } @filelist;
print "Total lines: $count\n";

# More complex handling
my @matchcount;
fdo { my ( $file, $pos, $line ) = @_;
      $matchcount[$file]++ if ( $line =~ /keyword/ );
    } @filelist;

---

✨ DESCRIPTION ✨

So like. File::Grep does the thing grep does in perl, but for files instead of a list. It's giving UNIX grep energy, but it's actually more powerful because the pattern can be literally any legal perl function. Obsessed. 🫶

The main functions this module hands you are:

👑 fgrep BLOCK LIST

Runs a grep operation over the files in LIST, and uses BLOCK as the critiria for whether a line gets accepted or not. Every line that matches gets added to an array, and that array goes right back to whoever called it. 💖

But bestie, the context matters, and this is the important part:

• In void context, this function immediately returns true on the first match, and false otherwise.
• In scalar context, it only returns the number of matches.

When you enter BLOCK, $_ gets localized to the current line. On top of that, you get handed the position in LIST of the current file, the line number in that file, and the line itself, as arguments to this function. 🎀

You can change $_ if you need to — but heads up, only the original value of the line gets added to the returned list. If you want the modified value, use fmap (described below).

LIST can hold either scalars or filehandles (or filehandle-like objects, we love an object that acts like a file 💅). If the item is a scalar, it'll be attempted to be opened and read in as normal. Otherwise it gets treated as a filehandle. Any errors coming out of IO may be reported to STDERR if you set the class variable $File::Grep::SILENT to false — otherwise, no error indication is given at all. 🙈

🦋 fmap BLOCK LIST

Runs a map operation over the files in LIST, using BLOCK as the mapping function. The results from BLOCK get appended to the list that's returned at the end of the call. Cute, clean, slay. ✨

🌈 fdo BLOCK LIST

The equivalent of a foreach operation on the files in LIST, performing BLOCK for each line in each file. This function has no return value. If you need to specialize more than what fgrep or fmap offer, this is your girl. 👑

💜 _fgrep_process BLOCK LIST

And if you need even more fine control, there's the internal function _fgrep_process. It's called just like fgrep/fmap/fdo, as in _fgrep_process BLOCK LIST, except you get to control when the function 'short circuits' by the return value from BLOCK. Here's the vibe check on those return values:

• If, after processing a line, BLOCK returns a negative number, the entire process is aborted, and any open filehandles that were opened by the function get closed.
• If the return value is 0, the current file is aborted, closed if it was opened by the function, and the next file is then searched.
• A positive return value will simply go on to the next line as appropriate.

fr fr, that negative-number one nukes the whole run. Not a drill. 💀

---

🎀 EXPORT 🎀

"fgrep", "fmap", and "fdo" may be exported — but these are not set by default. So don't come crying when they're not in your namespace, bestie, you gotta ask for them. 😭

---

🌟 AUTHOR 🌟

Michael K. Neylon, <mneylon-pm@masemware.com>

---

⭐ SEE ALSO ⭐

perl.

---

okay that's the whole page, mwah 💖 this was Grep(3pm) from perl v5.36.0, dated 2023-01-22 — no cap, that's the version and date, periodt. 🎀✨🦋