Grepper -- simple way to grep through files and save results

== Description

The Grepper class greps through files, and returns a result
set of Grepper::Result objects. Each Result object represents the matches
found in a single file. The Result contains a set of
Grepper::Match objects. Each Match object represents a line (the
line that matched) and before- and after-context arrays. If no before
or after lines were requested, those context values will be nil.

To use, you prepare a Grepper object; call <tt>run</tt> on it; and
walk through the result set. This distribution comes with the
Grepper::Formatter class, which is built on top of Grepper and provides
fairly canonical-looking output by walking through Grepper objects.
(See <tt>lib/formatter.rb</tt>.) Meanwhile, here are the details.

== Preparing a Grepper object

You instantiate Grepper, and provide it with:

* a pattern, in the form of a regular expression
* zero or more options, as an array
* an array of filenames

=== Setting the grepper's pattern

To specify a pattern for the Grepper object:

grepper.pattern = /abc/

=== Setting the grepper's file list

grepper.files = ["file1.txt", "file2.txt"]
grepper.files = Dir["grep_me/*.txt"]

=== Options

To set options, you provide an array of strings. For example, for a
reverse grep with two lines of after-context you would do:

grepper.options = %w{ v A2 }

Available options are:

* <tt>v</tt> -- negate the sense of the match
* <tt>An</tt> -- provide n lines of after-context
* <tt>Bn</tt> -- provide b lines of before-context
* <tt>o</tt> -- store only the part of the line that matched the pattern
* <tt>w</tt> -- count only complete-word matches

== Generating the result set

To generate the result set, you call <tt>run</tt>.

grepper.run

Now you can access grepper.results, and walk through all the
matches.

== Walking through the result set and match set

Given a <tt>Grepper</tt> object <tt>grepper</tt>, the result set
will be at <tt>grepper.results</tt>.
It will iterate per entry, yielding
the filename and the corresponding set of matches.

grepper.results.each do |filename, matches|
...
end

For each match set, you can iterate like this:

matches.each do |lineno, before, line, after|
...
end

If you want to walk through either set and just get the
objects, not broken out into their properties, you can do:

grepper.results.each_result do |result|

and

matches.each_match do |match|

== Version

0.9.3, January 13, 2009

== Author

David A. Black ([email protected])

== Copyright and license

Copyright (c) 2008-2009, Ruby Power and Light, LLC

Released under the Ruby license. No warranty of any kind. Use
entirely at your own risk.