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,
    } );


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.

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.

See "Allowed Tokens" for what you can search through. This will be expanded as time goes on. Patches very welcome.


Class Methods


    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.

  • 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.

  • 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').


 if ( App::Grepl->handler_for('heredoc') ) {

Returns a boolean value indicating whether or not a particular token type can be handled. Generally used internally..

Instance Methods


 my $dir = $grepl->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($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;

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 ) { ... }

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.


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.

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:

 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>


Please report any bugs or feature requests to bug-app-grepl at, or through the web interface at I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

  • 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:



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.