NAME

App::Greple::Grep - Greple grep engine module

SYNOPSIS

use App::Greple::Grep;

my $grep = App::Greple::Grep->new(
    text     => \$text,
    filename => $filename,
    pattern  => $pattern_holder,
    ...
)->run;

for my $result ($grep->result) {
    my $block = $result->block;
    for my $match ($result->matched) {
        # process each match
    }
}

DESCRIPTION

This module provides the core grep engine for the greple command. It is typically not used directly, but can be accessed through the --postgrep option to manipulate search results.

CLASSES

App::Greple::Grep::Block

Represents a text block containing matched patterns.

min

Start position of the block (0-origin byte offset).

max

End position of the block.

number

Block number (1-origin).

App::Greple::Grep::Match

Represents an individual match within a block.

min

Start position of the match.

max

End position of the match.

index

Pattern index (0-origin) indicating which pattern matched. Used for colorization with --colorindex option.

callback

Callback function to be called when this match is output. The callback receives the following arguments:

For CODE reference:

$callback->($start, $end, $index, $matched_string)

For Getopt::EX::Func object:

$callback->call(
    &FILELABEL => $file,
    start => $start,
    end   => $end,
    index => $index,
    match => $matched_string,
)

The callback should return the string to be output. If it returns undef, the original matched string is used.

App::Greple::Grep::Result

Represents the search result for a single block.

block

Returns the App::Greple::Grep::Block object.

matched

Returns a list of App::Greple::Grep::Match objects.

min, max, number

Shortcuts for $result->block->min, etc.

METHODS

App::Greple::Grep

result

Returns a list of App::Greple::Grep::Result objects.

result_ref

Returns a reference to the result array. This can be used to modify the results in a --postgrep function.

matched

Returns the total number of matches.

blocks

Returns a list of all blocks.

cut($from, $to)

Returns the substring of the text from position $from to $to.

slice_result($result)

Returns a list of strings alternating between unmatched and matched portions within the block.

USING --postgrep OPTION

The --postgrep option allows you to process the Grep object after the search is complete. The function receives the Grep object as its argument.

sub postgrep {
    my $grep = shift;
    for my $result ($grep->result) {
        for my $match ($result->matched) {
            # Modify match attributes
            $match->callback = sub { ... };
        }
    }
}

CALLBACK EXAMPLE

The App::Greple::subst module uses callbacks to replace matched text:

my $callback = sub {
    my($start, $end, $index, $matched) = @_;
    # Return replacement string
    return $replacement;
};

for my $match ($result->matched) {
    $match->callback = $callback;
}

SEE ALSO

greple, App::Greple::subst