.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Text::Context::EitherSide 3pm"
.TH Text::Context::EitherSide 3pm "2022-11-21" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Text::Context::EitherSide \- Get n words either side of search keywords
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  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",
.Ve
.PP
Or, if you don't believe in all this \s-1OO\s0 rubbish:
.PP
.Vb 3
\&  use Text::Context::EitherSide qw(get_context);
\&  get_context(1, $text, "fox", "jumped", "dog") 
\&        # "... brown fox jumped over ... lazy dog"
.Ve
.SH "DESCRIPTION"
.IX Header "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.
.PP
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
.PP
.Vb 1
\&    the quick brown fox jumped over the lazy dog
.Ve
.PP
and you extract two words either side of \*(L"fox\*(R", \*(L"jumped\*(R" and \*(L"dog\*(R", you
really don't want to end up with
.PP
.Vb 1
\&    quick brown fox jumped over brown fox jumped over the the lazy dog
.Ve
.PP
so you need a small amount of smarts. This module has a small amount of
smarts.
.SH "EXPORTABLE"
.IX Header "EXPORTABLE"
.SS "get_context"
.IX Subsection "get_context"
This is primarily an object-oriented module. If you don't care about
that, just import the \f(CW\*(C`get_context\*(C'\fR subroutine, and call it like so:
.PP
.Vb 1
\&    get_context($num_of_words, $text, @words_to_find)
.Ve
.PP
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...
.SH "METHODS"
.IX Header "METHODS"
.SS "new"
.IX Subsection "new"
.Vb 1
\&    my $c = Text::Context::EitherSite\->new($text [, context=> $n]);
.Ve
.PP
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.)
.SS "context"
.IX Subsection "context"
.Vb 1
\&    $c\->context(5);
.Ve
.PP
Allows you to get and set the number of the words on either side.
.SS "as_sparse_list"
.IX Subsection "as_sparse_list"
.Vb 1
\&    $c\->as_sparse_list(@keywords)
.Ve
.PP
Returns the keywords, plus \fIn\fR 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 \f(CW\*(C`undef\*(C'\fRs. (That's not actually how it works,
but conceptually, it's the same.)
.SS "as_list"
.IX Subsection "as_list"
.Vb 1
\&    $c\->as_list(@keywords)
.Ve
.PP
The same as \f(CW\*(C`as_sparse_list\*(C'\fR, but single or multiple \f(CW\*(C`undef\*(C'\fRs are
collapsed into a single ellipsis:
.PP
.Vb 1
\&    (undef, "foo", undef, undef, undef, "bar")
.Ve
.PP
becomes
.PP
.Vb 1
\&    ("...", "foo", "...", "bar")
.Ve
.SS "as_string"
.IX Subsection "as_string"
.Vb 1
\&    $c\->as_string(@keywords)
.Ve
.PP
Takes the \f(CW\*(C`as_list\*(C'\fR output above and joins them all together into a
string. This is what most people want from \f(CW\*(C`Text::Context::EitherSide\*(C'\fR.
.SS "\s-1EXPORT\s0"
.IX Subsection "EXPORT"
\&\f(CW\*(C`get_context\*(C'\fR is available as a shortcut for
.PP
.Vb 1
\&   Text::Context::EitherSide\->new($text, context => $n)\->as_string(@words);
.Ve
.PP
but needs to be explicitly imported. Nothing is exported by default.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Text::Context is an even smarter way of extracting a contextual
string.
.SH "AUTHOR"
.IX Header "AUTHOR"
Current maintainer: Tony Bowden
.PP
Original author: Simon Cozens
.SH "BUGS and QUERIES"
.IX Header "BUGS and QUERIES"
Please direct all correspondence regarding this module to:
  bug\-Text\-Context\-EitherSide@rt.cpan.org
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright 2002\-2005 by Kasei Limited, http://www.kasei.com/
.PP
You may use and redistribute this module under the terms of the
Artistic License 2.0.
.PP
http://www.perlfoundation.org/artistic_license_2_0