perlfind - perldoc on steroids

Every time I use perldoc for any term slightly unusual, I struggle. Have you tried to use it to find UNITCHECK? Now you can. Instead of remembering which of these to use (and none of these will find UNITCHECK):

You can just type:

perlfind --all UNITCHECK

In the last case above, the --all is needed to do a brute force search. Ordinarily, you just do perlfind searchterm, regardless of whether it's a module name, function, variable, or faq keyword and it will return the first result found (searched in the order I just mentioned). Otherwise, it will tell you to use --all if you really want a brute force search to find out where that term is used.

Here's a gist I tossed out there. Patches welcome. I should bundle this up and put it on the CPAN (and handle older perldoc versions).

NAME

perlfind - perldoc on steroids


SYNOPSIS

 perlfind '$@'
 perlfind Scalar::Util
 perlfind file
 perlfind die
 perlfind __DATA__ --all


DESCRIPTION

Tired of perldoc? Try perlfind anything. It will return the first matching perldoc document found for anything, in the following precedence order.

  1. perldoc MODULE
  2. perldoc -f FUNCTION
  3. perldoc -v VARIABLE
  4. perldoc -q FAQKEYWORD
  5. A brute force grep of @INC and $ENV{PERL5LIB.

Note that the brute force grep requires Term::ProgressBar and File::Find::Rule. You must also specify the --all option.


OPTIONS

 --perldoc=/path/to/perldoc   Force an explicit path to your perldoc
 --verbose                    Show how we're searching
 --all                        Fall back to brute force if we fail


CAVEATS

It's a hack.


BUGS

Probably.


AUTHOR

Curtis "Ovid" Poe


LICENSE

Copyright (c) 2012 Curtis "Ovid" Poe (ovid@cpan.org) All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

6 Comments

I foresee myself using this at least once a week for the rest of my life. Can't believe I didn't write it myself. Thanks Ovid!

I wrote something similar that finds Perl modules. Unlike perldoc, it ignores case and allows wildcards. It's available for download at github.

There is App::perlzonji, which does something like this, and is also pluggable, but it's got a weird name, so it's my own fault that people don't find it. :) Anyway, I've blogged about perlzonji now.

Hi Folks

Thanx for the ideas.

And, wouldn't it be great if perlvar referenced FILE, LINE, PACKAGE, etc!

Cheers Ron

You can actually get surprisingly far with just a bit of shell:


export PODINDEX=/tmp/foo.idx

function podindex {
    find $(perl -e 'pop@INC; print "@INC"') -name \*.pm -or -name \*.pod \
        | xargs grep -ne '^=head\|^X $PODINDEX
}

function podsearch {
    if [ "x$1" = x ]; then
        echo "Must supply a search pattern."
        return
    fi
    if [ "x$1" = x-v ]; then
        grep -i ":.*$2" $PODINDEX
    else
        grep -i ":.*$1" $PODINDEX | cut -d: -f1 | sort | uniq -c | sort -rn
    fi
}

Yes! I've had similar ideas about coercing perldoc to do this for a while now. Why should I have to remember to use some option or other when the software could help me out by spinning a few CPU cycles to see if there are any matches.

Though in my fantasy perldoc it wouldn't prioritize modules over functions over variables, it would search them all and give all of the matches and you could still use the command line switch to limit the results to just those search types that you wanted (think of it the same as ack). But the basic idea is the same; when searching for some unknown thing in the Perl documentation "perldoc thing" should give me some answers.

Leave a comment

About Ovid

user-pic Have Perl; Will Travel. Freelance Perl/Testing/Agile consultant. Photo by http://www.circle23.com/. Warning: that site is not safe for work. The photographer is a good friend of mine, though, and it's appropriate to credit his work.