NAME

       Text::Context::EitherSide - Get n words either side of search keywords

SYNOPSIS

         use Text::Context::EitherSide;

         my $text = "The quick brown fox jumped over the lazy dog";
         my $context = Text::Context::EitherSide->new($text);

         $context->as_string("fox") # "... quick brown fox jumped over ..."

         $context->as_string("fox", "jumped")
           # "... quick brown fox jumped over the ..."

         my $context = Text::Context::EitherSide->new($text, context => 1);
           # 1 word on either side

         $context->as_string("fox", "jumped", "dog");
           # "... brown fox jumped over ... lazy dog",

       Or, if you don't believe in all this OO rubbish:

         use Text::Context::EitherSide qw(get_context);
         get_context(1, $text, "fox", "jumped", "dog")
               # "... brown fox jumped over ... lazy dog"

DESCRIPTION

       Suppose you have a large piece of text - typically, say, a web page or a mail message. And
       now suppose you've done some kind of full-text search on that text for a bunch of
       keywords, and you want to display the context in which you found the keywords inside the
       body of the text.

       A simple-minded way to do that would be just to get the two words either side of each
       keyword. But hey, don't be too simple minded, because you've got to make sure that the
       list doesn't overlap. If you have

           the quick brown fox jumped over the lazy dog

       and you extract two words either side of "fox", "jumped" and "dog", you really don't want
       to end up with

           quick brown fox jumped over brown fox jumped over the the lazy dog

       so you need a small amount of smarts. This module has a small amount of smarts.

EXPORTABLE

   get_context
       This is primarily an object-oriented module. If you don't care about that, just import the
       "get_context" subroutine, and call it like so:

           get_context($num_of_words, $text, @words_to_find)

       and you'll get back a string with ellipses as in the synopsis. That's all that most people
       need to know. But if you want to do clever stuff...

METHODS

   new
           my $c = Text::Context::EitherSite->new($text [, context=> $n]);

       Create a new object storing some text to be searched, plus optionally some information
       about how many words on either side you want. (If you don't like the default of 2.)

   context
           $c->context(5);

       Allows you to get and set the number of the words on either side.

   as_sparse_list
           $c->as_sparse_list(@keywords)

       Returns the keywords, plus n words on either side, as a sparse list; the original text is
       split into an array of words, and non-contextual elements are replaced with "undef"s.
       (That's not actually how it works, but conceptually, it's the same.)

   as_list
           $c->as_list(@keywords)

       The same as "as_sparse_list", but single or multiple "undef"s are collapsed into a single
       ellipsis:

           (undef, "foo", undef, undef, undef, "bar")

       becomes

           ("...", "foo", "...", "bar")

   as_string
           $c->as_string(@keywords)

       Takes the "as_list" output above and joins them all together into a string. This is what
       most people want from "Text::Context::EitherSide".

   EXPORT
       "get_context" is available as a shortcut for

          Text::Context::EitherSide->new($text, context => $n)->as_string(@words);

       but needs to be explicitly imported. Nothing is exported by default.

SEE ALSO

       Text::Context is an even smarter way of extracting a contextual string.

AUTHOR

       Current maintainer: Tony Bowden

       Original author: Simon Cozens

BUGS and QUERIES

       Please direct all correspondence regarding this module to:
         bug-Text-Context-EitherSide@rt.cpan.org

COPYRIGHT AND LICENSE

       Copyright 2002-2005 by Kasei Limited, http://www.kasei.com/

       You may use and redistribute this module under the terms of the Artistic License 2.0.

       http://www.perlfoundation.org/artistic_license_2_0