#!/usr/bin/env perl
# podgrep -- grep in pod sections only
# tchrist@perl.com
use Getopt::Std qw(getopts);
getopts("fhpi")
|| die "usage: $0 [-i] [-f] [-h] [-p] pattern [podfiles ...]";
$/ = '';
$only_header = $opt_h;
$orig_pattern = $pattern = shift;
$pattern = '^=.*' . $pattern if $only_header;
$pattern .= '(?i)' if $opt_i;
if ($opt_p) {
unless ($pager = $ENV{PAGER}) {
require Config;
$pager = $Config::Config{"pager"} || "more";
}
}
if ($opt_f) {
if ($opt_p) {
open(STDOUT, "| pod2text | $pager '+/$orig_pattern'");
} else {
open(STDOUT, "| pod2text");
}
}
elsif ($opt_p) {
open(STDOUT, "| $pager '+/$orig_pattern'");
}
($file, $chunk) = ('-', 0);
while (<>) {
if ($inpod && /^=cut/) {
$inmatch = $inpod = 0;
next;
}
if (! $inpod && /^=(?!cut)\w+/) {
$inpod = 1;
}
if ($inmatch && /^=\w+/) {
$inmatch = 0;
}
if ($inpod && !$inmatch && /$pattern/o) {
print "=head1 $ARGV chunk $.\n\n"
unless $file eq $ARGV && $chunk+1 == $.;
($file, $chunk) = ($ARGV, $.);
print;
$inmatch = 1 if $only_header;
next;
}
print if $inmatch;
} continue {
if (eof) {
$inmatch = $inpod = 0;
($file, $chunk) = ('-', 0);
close ARGV;
}
}
close STDOUT;
__END__
=head1 NAME
podgrep - grep in pod sections only
=head1 SYNOPSIS
podgrep [B<-i>] [B<-p>] [B<-f>] [B<-h>] I<pattern> [ I<files> ... ]
=head1 DESCRIPTION
This program searches each paragraph in a pod document and prints each
paragraph that matches the supplied pattern. This pod may be mixed with
program code, such as in a module.
Options are:
=over 4
=item -i
means case insensitive match
=item -p
means page output though the user's pager. The pager will be primed
with an argument to search for the string. This highlights the result.
=item -f
means format output though the I<pod2text> program.
=item -h
means check for matches in pod C<=head> and C<=item> headers alone,
and to keep printing podagraphs until the next header is found.
=back
=head1 EXAMPLES
$ podgrep mail `pmpath CGI`
(prints out podagraphs from the CGI.pm manpage that mention mail)
$ podgrep -i destructor `sitepods`
(prints out podagraphs that mention destructors in the
site-installed pods)
$ podgrep -i 'type.?glob' `stdpods`
(prints out podagraphs that mention typeglob in the
standard pods)
$ podgrep -hpfi "lock" `faqpods`
(prints out all podagraphs with "lock" in the headers
case-insensitively, then then formats these with pod2text, then
shows them in the pager with matches high-lighted)
$ podgrep -fh seek `podpath perlfunc`
(prints out and formats podagraphs from the standard perlfunc manpage
whose headers or items contain "seek".)
=head1 SEE ALSO
faqpods(1),
pfcat(1),
pmpath(1),
pod2text(1),
podpath(1),
sitepods(1),
stdpods(1),
and
tcgrep(1).
=head1 NOTE
For a pager, the author likes these environment settings (in the login
startup, of course):
$ENV{PAGER} = "less";
$ENV{LESS} = "MQeicsnf";
=head1 AUTHORS and COPYRIGHTS
Copyright (C) 1999 Tom Christiansen.
Copyright (C) 2006-2008 Mark Leighton Fisher.
This is free software; you can redistribute it and/or modify it
under the terms of either:
(a) the GNU General Public License as published by the Free
Software Foundation; either version 1, or (at your option) any
later version, or
(b) the Perl "Artistic License".
(This is the Perl 5 licensing scheme.)
Please note this is a change from the
original pmtools-1.00 (still available on CPAN),
as pmtools-1.00 were licensed only under the
Perl "Artistic License".