/ 
App-Grepl-0.01
River stage zero No dependents
/ App::Grepl

NAME

App::Grepl - PPI-powered grep

VERSION

Version 0.01

SYNOPSIS

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;

DESCRIPTION

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.

METHODS

Class Methods

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.

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

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

Instance Methods

dir

my $dir = $grepl->dir;
$grepl->dir($dir);

Getter/setter for the directory to search in.

Will croak if the directory cannot be found.

files

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.

look_for

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.

pattern

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.

warnings

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.

filename_only

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.

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

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";
        }
    }
}

AUTHOR

Curtis Poe, <ovid at cpan.org>

BUGS

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.

  • Currently line numbers are not available.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc App::Grepl

You can also look for information at:

ACKNOWLEDGEMENTS

COPYRIGHT & LICENSE

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.