Curtis "Ovid" Poe > App-Grepl-0.01 > App::Grepl

Download:
App-Grepl-0.01.tar.gz

Dependencies

Annotate this POD

CPAN RT

New  2
Open  0
View/Report Bugs
Module Version: 0.01   Source  

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

Additional keys may be added in the future.

Allowed Tokens

The following token types are currently searchable:

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.

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.

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.

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.

syntax highlighting: