NAME

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

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

       File::Grep mimics the functionality of the grep function in perl, but applying it to files instead of a
       list.  This is similar in nature to the UNIX grep command, but more powerful as the pattern can be any
       legal perl function.

       The main functions provided by this module are:

       fgrep BLOCK LIST
           Performs  a  grep operation on the files in LIST, using BLOCK as the critiria for accepting a line or
           not.  Any lines that match will be added to an array that will be returned to the caller.  Note  that
           in void context, this function will immediate return true on the first match, false otherwise, and in
           scalar context, it will only return the number of matches.

           When entering BLOCK, the $_ variable will be localized to the current line.  In addition, you will be
           given  the position in LIST of the current file, the line number in that file, and the line itself as
           arguments to this function.  While you can change $_ if necessary, only the  original  value  of  the
           line  will be added to the returned list.  If you need to get the modified value, use fmap (described
           below).

           The LIST can contain either scalars or filehandle (or filehandle-like objects).  If  the  item  is  a
           scalar,  it  will be attempted to be opened and read in as normal.  Otherwise it will be treated as a
           filehandle.  Any errors resulting from IO may be reported to STDERR by setting  the  class  variable,
           $File::Grep::SILENT to false; otherwise, no error indication is given.

       fmap BLOCK LIST
           Performs a map operation on the files in LIST, using BLOCK as the mapping function.  The results from
           BLOCK will be appended to the list that is returned at the end of the call.

       fdo BLOCK LIST
           Performs  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, you can use this function.

       In addition, if you need additional fine control, you can use the internal function _fgrep_process.  This
       is  called  just  like fgrep/fmap/fdo, as in "_fgrep_process BLOCK LIST" except that you can control when
       the fucntion 'short circuits' by the return value from BLOCK.  If, after processing  a  line,  the  BLOCK
       returns  a  negative number, the entire process is aborted, closing any open filehandles that were opened
       by the function.  If the return value is 0, the current file is aborted, closed if 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.

EXPORT

       "fgrep", "fmap", and "fdo" may be exported, but these are not set by default.

AUTHOR

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

SEE ALSO

       perl.

perl v5.36.0                                       2023-01-22                                          Grep(3pm)