view release on metacpan or  search on metacpan

lib/App/Grepl.pm  view on Meta::CPAN

        quote   => { stringify => sub { shift->string } },
        heredoc => {
            class     => 'Token::HereDoc',
            stringify => sub {
                
                # heredoc lines are terminated with newlines
                my @strings = shift->heredoc;
                return join '' => @strings;
            },
        },
        pod     => { 
            stringify => sub {
                
                # pod lines lines are *not* terminated with newlines
                my @strings = shift->lines;
                return join "\n" => @strings;
            },
        },
        comment => { stringify => sub { shift->content } }
    );
    foreach my $token ( keys %HANDLER_FOR ) {
        $HANDLER_FOR{$token}{class} ||= "Token::\u$token";

        # let them make it plural if they want
        $HANDLER_FOR{ $token . 's' }{class} = $HANDLER_FOR{$token}{class};
        $HANDLER_FOR{ $token . 's' }{stringify} =
          $HANDLER_FOR{$token}{stringify};
    }
}

=head1 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;

=head1 DESCRIPTION

This is B<Alpha> code.  Probably has bugs and the output format of C<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
C<%HANDLER_FOR> hash.

This software allows you to 'grep' through Perl documents.  Further, you can
specify which I<parts> of the documents you wish to search through.  While you
can use the class API directly, generally you'll use the C<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 C<perldoc grepl> for more examples of that interface.

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

=head1 METHODS

=head2 Class Methods

=head3 C<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).

=over 4

=item * C<dir>

Specify the directory to search in.  Cannot be used with the C<files>
argument.

=item * C<files>

Specify an exact list of files to search in.  Cannot be used with the C<dir>
argument.

=item * C<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 L<Allowed Tokens> for a list of which tokens you can search against.

=item * C<pattern>

Specify a pattern to search against.  This may be any valid Perl regular
expression.  Only results matching the pattern will be returned.

Will C<croak> if the pattern is not a valid regular expression.

=item * C<warnings>

By default, warnings are off.  Passing this a true value will enable warnings.
Currently, the only warning generated is when C<PPI> cannot parse the file.
This may be useful for debugging.

=item * C<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 I<any> match is found, we stop
searching the document.  Thus, individual results are not available if
C<filename_only> is true.