Acme::Grep2D - Grep in 2 dimensions

Version 0.01

    use Acme::Grep2D;

    my $foo = Acme::Grep2D->new(text => ??);
    ...

For testing another module, I needed the ability to grep in 2 dimensions, hence this module.

This module can grep forwards, backwards, up, down, and diagonally in a given text string. Given the text:

  THIST  T S
  .H  H H  II
  ..I II SIHTH
  ...SS    T  T

We can find all occurances of THIS.

Full Perl regexp is allowed, with a few limitations. Unlike regular grep, you get back (for each match) an array containing array references with the following contents:

  [$length, $x, $y, $dx, $dy, ??]

Operational note: there is one more argument at the end of the returned array reference (as indicated by ??). Don't mess with this. It's reserved for future use.

  $g2d = Acme::Grep2D->new(text => ??);

Constructor. Specify text pattern to be grepped (multiline, with newlines).

Example:

  my $text = <<'EOF';
  foobarf
  .o,,,o
  ,,o?f?fr
  <<,b ooa
  ##a#a ob
  @r@@@rbo
  ------ao
  ~~~~~~rf
  EOF

  $g2d = Acme::Grep2D->new(text => $text);

Now, our grep will have no problem finding all of the "foobar" strings in the text (see Grep or other more directional methods).

The author is interested in any novel use you might find for this module (other than solving newspaper puzzles).

  $g2d->Grep($re);  

Find the regular expression ($re) no matter where it occurs in text.

The difference from a regular grep is that "coordinate" information is returned for matches. This is the length of the found match, x and y coordinates, along with directional movement information (dx, dy). It's easiest to use extract to access matches.

  @matches = $g2d->grep_hf($re);

Search text normally, left to right.

  @matches = $g2d->grep_hf($re);

Search text normally, but right to left.

  @matches = $g2d->grep_h($re);

Search text normally, in both directions.

  @matches = grep_vf($re);

Search text vertically, down.

  @matches = grep_vr($re);

Search text vertically, up.

  @matches = $g2d->grep_v($re);

Search text vertically, both directions.

  @matches = $g2d->grep_rlf($re);

Search the R->L vector top to bottom.

  @matches = $g2d->grep_rlr($re);

Search the R->L vector bottom to top.

  @matches = $g2d->grep_rlf($re);

Search the R->L both directions.

  @matches = $g2d->grep_lrf($re);

Search the L->R top to bottom.

  @matches = $g2d->grep_lrr($re);

Search the L->R bottom to top.

  @matches = $g2d->grep_lr($re);

Search the L->R both directions.

  $result = $g2d->extract($info);

Extract pattern match described by $info, which is a single return from Grep. E.g.

  my @matches = $g2d->Grep(qr(foo\w+));
  map {
      print "Matched ", $g2d->extract($_), "\n";
  } @matches;

  $textRef = $g2d->text();

Return an array reference to our internal text buffer. This is for future use. Don't mess with the return, or bad things may happen.

X Cramps, <cramps.the at gmail.com>

Please report any bugs or feature requests to bug-acme-grep2d at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Acme-Grep2D. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

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

    perldoc Acme::Grep2D

You can also look for information at:

* RT: CPAN's request tracker

http://rt.cpan.org/NoAuth/Bugs.html?Dist=Acme-Grep2D

* AnnoCPAN: Annotated CPAN documentation

http://annocpan.org/dist/Acme-Grep2D

* CPAN Ratings

http://cpanratings.perl.org/d/Acme-Grep2D

* Search CPAN

http://search.cpan.org/dist/Acme-Grep2D/

Captain Beefheart and the Magic Band. Fast & bulbous. Tight, also.

Copyright 2009 X Cramps, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.