.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Grep 3pm" .TH Grep 3pm "2023-01-22" "perl v5.36.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" File::Grep \- Find matches to a pattern in a series of files and related functions .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& 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\e.html/ } glob "/var/log/httpd/access.log.*"), \& " times\en"; \& \& # Array context \& my @matches = fgrep { /index\e.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\en"; \& \& # More complex handling \& my @matchcount; \& fdo { my ( $file, $pos, $line ) = @_; \& $matchcount[$file]++ if ( $line =~ /keyword/ ); \& } @filelist; .Ve .SH "DESCRIPTION" .IX Header "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 \s-1UNIX\s0 grep command, but more powerful as the pattern can be any legal perl function. .PP The main functions provided by this module are: .IP "fgrep \s-1BLOCK LIST\s0" 4 .IX Item "fgrep BLOCK LIST" Performs a grep operation on the files in \s-1LIST,\s0 using \s-1BLOCK\s0 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. .Sp When entering \s-1BLOCK,\s0 the \f(CW$_\fR variable will be localized to the current line. In addition, you will be given the position in \s-1LIST\s0 of the current file, the line number in that file, and the line itself as arguments to this function. While you can change \f(CW$_\fR 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). .Sp The \s-1LIST\s0 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 \s-1IO\s0 may be reported to \s-1STDERR\s0 by setting the class variable, \f(CW$File::Grep::SILENT\fR to false; otherwise, no error indication is given. .IP "fmap \s-1BLOCK LIST\s0" 4 .IX Item "fmap BLOCK LIST" Performs a map operation on the files in \s-1LIST,\s0 using \s-1BLOCK\s0 as the mapping function. The results from \s-1BLOCK\s0 will be appended to the list that is returned at the end of the call. .IP "fdo \s-1BLOCK LIST\s0" 4 .IX Item "fdo BLOCK LIST" Performs the equivalent of a foreach operation on the files in \s-1LIST,\s0 performing \s-1BLOCK\s0 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. .PP 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 \*(L"_fgrep_process \s-1BLOCK LIST\*(R"\s0 except that you can control when the fucntion 'short circuits' by the return value from \s-1BLOCK.\s0 If, after processing a line, the \s-1BLOCK\s0 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. .SH "EXPORT" .IX Header "EXPORT" \&\*(L"fgrep\*(R", \*(L"fmap\*(R", and \*(L"fdo\*(R" may be exported, but these are not set by default. .SH "AUTHOR" .IX Header "AUTHOR" Michael K. Neylon, .SH "SEE ALSO" .IX Header "SEE ALSO" perl.