App::Grepl - PPI-powered grep
Version 0.01
Use PPI to search through Perl documents.
use App::Grepl; my $grepl = App::Grepl->new( { dir => $some_dir, look_for => [ 'pod', 'heredoc' ], pattern => $some_regex, } ); $grepl->search;
This is Alpha code. Probably has bugs and the output format of grepl is likely to change at some point. Also, we'll add more things you can search for in the future. Right now, you should just need to add them to the %HANDLER_FOR hash.
grepl
%HANDLER_FOR
This software allows you to 'grep' through Perl documents. Further, you can specify which parts of the documents you wish to search through. While you can use the class API directly, generally you'll use the grepl program which is automatically installed. For example, to search all comments for 'XXX' or 'xxx':
grepl --dir lib/ --pattern '(?i:XXX)' --search comments
See perldoc grepl for more examples of that interface.
perldoc grepl
See "Allowed Tokens" for what you can search through. This will be expanded as time goes on. Patches very welcome.
new
my $grepl = App::Grepl->new( { dir => $some_dir, look_for => [ 'pod', 'heredoc' ], } );
The constructor takes a hashref of a rich variety of arguments. This is because the nature of what we're looking for can be quite complex.
The following keys are allowed (all are optional).
dir
Specify the directory to search in. Cannot be used with the files argument.
files
Specify an exact list of files to search in. Cannot be used with the dir argument.
look_for
A scalar or array ref of the items (referred to as 'tokens') in Perl files to look for. If this key is omitted, default to:
[ 'quote', 'heredoc' ]
See "Allowed Tokens" for a list of which tokens you can search against.
pattern
Specify a pattern to search against. This may be any valid Perl regular expression. Only results matching the pattern will be returned.
Will croak if the pattern is not a valid regular expression.
croak
warnings
By default, warnings are off. Passing this a true value will enable warnings. Currently, the only warning generated is when PPI cannot parse the file. This may be useful for debugging.
PPI
filename_only
By default, this value is false. If passed a true value, only filenames whose contents match the pattern for the tokens will be returned.
Note that This is optimized internally. Once any match is found, we stop searching the document. Thus, individual results are not available if filename_only is true.
Additional keys may be added in the future.
Allowed Tokens
The following token types are currently searchable:
quote
Matches quoted strings (but not heredocs).
heredoc
Matches heredocs.
pod
Matches POD.
comment
Matches comments.
Note that for convenience, you may specify a plural version of each token type ('heredocs' instead of 'heredoc').
handler_for
if ( App::Grepl->handler_for('heredoc') ) { ... }
Returns a boolean value indicating whether or not a particular token type can be handled. Generally used internally..
my $dir = $grepl->dir; $grepl->dir($dir);
Getter/setter for the directory to search in.
Will croak if the directory cannot be found.
my $files = $grepl->files; # array ref my @files = $grepl->files; $grepl->files(\@files); $grepl->files($file); # convenience
Getter/setter for files to search in.
Will croak if any of the files cannot be found or read.
my $look_for = $grepl->look_for; # array ref my @look_for = $grepl->look_for; $grepl->look_for( [qw/ pod heredoc /] ); $grepl->look_for('pod'); # convenience
Getter/setter for the token types to search.
Will croak if any of the token types cannot be found.
my $pattern = $grepl->pattern; $grepl->pattern($patten);
Getter/setter for the pattern to search for. Defaults to the empty string. The pattern must be a valid Perl regular expression.
Will croak if if supplied with an invalid pattern.
if ( $grepl->warnings ) { warn $some_message; } $grepl->warnings(0); # turn warnings off $grepl->warnings(1); # turn warnings on
Turn warnings on or off. By defalt, warnings are off.
if ( $grepl->filename_only ) { ... } $grepl->filename_only(1);
Boolean getter/setter for whether to only report matching filenames. If true, result objects returned from search will only report a matching filename and attempting to fetch results from the will croak.
search
$grepl->search;
This method searches the chosen directories or files for the chosen pattern. Only tokens listed in look_for will be searched.
If called in void context, will print the results, if any to STDOUT. If filename_only is true, will only print the filenames of matching files.
STDOUT
If results are found, returns a list or array reference (depending upon whether it's called in list or scalar context) of App::Grepl::Results objects. If you prefer to use the App::Grepl API instead of the grepl program, you can process the results as follows:
App::Grepl::Results
App::Grepl
my @results = $grepl->search; foreach my $found (@results) { print $found->file, "\n"; while ( my $result = $found->next ) { print $result->token, "matched:\n"; while ( my $item = $result->next ) { print "\t$item\n"; } } }
Curtis Poe, <ovid at cpan.org>
<ovid at cpan.org>
Please report any bugs or feature requests to bug-app-grepl at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=App-Grepl. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
bug-app-grepl at rt.cpan.org
Currently line numbers are not available.
You can find documentation for this module with the perldoc command.
perldoc App::Grepl
You can also look for information at:
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/App-Grepl
CPAN Ratings
http://cpanratings.perl.org/d/App-Grepl
RT: CPAN's request tracker
http://rt.cpan.org/NoAuth/Bugs.html?Dist=App-Grepl
Search CPAN
http://search.cpan.org/dist/App-Grepl
Copyright 2007 Curtis Poe, all rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install App::Grepl, copy and paste the appropriate command in to your terminal.
cpanm
cpanm App::Grepl
CPAN shell
perl -MCPAN -e shell install App::Grepl
For more information on module installation, please visit the detailed CPAN module installation guide.