————————package
App::Pgrep::Results;
use
warnings;
use
strict;
use
App::Pgrep;
=head1 NAME
App::Pgrep::Results - PPI-powered grep results object
=head1 VERSION
Version 0.01
=cut
our
$VERSION
=
'0.01'
;
=head1 SYNOPSIS
OO interface to pgrep's results
use App::Pgrep::Results;
my $found = App::Pgrep::Results->new( {
file => $file,
} );
$found->add_results( $token => \@results );
print $found->file, "\n";
while ( my $result = $found->next ) {
print $result->token, "matched:\n";
while ( my $item = $result->next ) {
print "\t$item\n";
}
}
=head1 METHODS
=head2 Class Methods
=head3 C<new>
my $pgrep = App::Pgrep::Results->new( { file => $file } );
=cut
sub
_initialize {
my
(
$self
,
$arg_for
) =
@_
;
$self
->file(
delete
$arg_for
->{file} );
$self
->{results} = [];
return
$self
;
}
=head2 Instance Methods
=head3 C<file>
my $file = $result->file;
$result->file($file);
Get or set the filename the results pertain to. Will C<croak> if the file
does not exist.
=cut
sub
file {
my
$self
=
shift
;
return
$self
->{file}
unless
@_
;
my
$file
=
shift
;
unless
( -e
$file
) {
$self
->_croak(
"Cannot find file ($file)"
);
}
$self
->{file} =
$file
;
return
$self
;
}
=head3 C<have_results>
if ( $found->have_results ) { ... }
Boolean accessor indicating if we have results for the search.
=cut
sub
have_results {
return
scalar
@{
shift
->{results} } }
=head3 C<add_results>
$found->add_results( 'heredoc' => \@array_ref_of_strings );
Add results to the result object. Takes two arguments:
=over 4
=item * token
This should be a string representing the result type (e.g., C<comment>,
C<pod>, etc).
Will C<croak> if C<App::Pgrep> does not recognize the result type.
=item * results
This should be an array reference of strings. These are the actual results.
Will C<croak> if something other than an array reference is passed.
=back
=cut
sub
add_results {
my
(
$self
,
$elem
,
$results
) =
@_
;
push
@{
$self
->{results} } => App::Pgrep::Results::Token->new( {
token
=>
$elem
,
results
=>
$results
,
} );
return
$self
;
}
=head3 C<filename_only>
if ( $result->filename_only ) {
...
}
$result->filename_only(1);
A boolean getter/setter for whether or not results are 'filename only'. These
are returned to indicated that a file matched the criteria. The actual
matches will not be returned.
=cut
sub
filename_only {
my
$self
=
shift
;
return
$self
->{filename_only}
unless
@_
;
my
$filename_only
=
shift
;
$self
->{filename_only} =
$filename_only
;
return
$self
;
}
=head3 C<next>
while ( defined ( my $result = $found->next ) ) {
...
}
Returns the next result found.
Will C<croak> if results are requested from a 'filename_only' object.
Note that the iterator is destructive.
=cut
sub
next
{
my
$self
=
shift
;
if
(
$self
->filename_only ) {
$self
->_croak(
"No results available for 'filename_only' results objects"
);
}
my
$next
=
shift
@{
$self
->{results} };
}
=head1 AUTHOR
Curtis Poe, C<< <ovid at cpan.org> >>
=head1 BUGS
Please report any bugs or feature requests to
C<bug-app-pgrep at rt.cpan.org>, 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.
=head1 SUPPORT
You can find documentation for this module with the perldoc command.
perldoc App::Pgrep::Results
You can also look for information at:
=over 4
=item * AnnoCPAN: Annotated CPAN documentation
=item * CPAN Ratings
=item * RT: CPAN's request tracker
=item * Search CPAN
=back
=head1 ACKNOWLEDGEMENTS
=head1 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.
=cut
1;