Text::...herSide(3pm)

✨ Text::...herSide(3pm) ✨

okay bestie, welcome to the manual page for Text::Context::EitherSide (the file itself is literally named Text::...herSide(3pm) because apparently even manpage filenames gotta be mysterious 💅). this is the Perl module that grabs you n words on either side of your search keywords so you can show people the receipts without dumping the whole text. let's get into it 🎀

---

🌸 NAME 🌸

Text::Context::EitherSide — Get n words either side of search keywords. that's the whole vibe. n words. either side. iconic.

---

🦋 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"

like, both paths are valid, bestie. pick your fighter 🫶

---

💖 DESCRIPTION 💖

so picture this. you've got 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. classic main character problem, honestly.

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

no no no 😭 that's giving word salad. so you need a small amount of smarts. and guess what — this module has a small amount of smarts. exactly the right amount. periodt. ✨

---

🎀 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.)

ngl the default of 2 is lowkey perfect but you do you, bestie 💖

context

$c->context(5);

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

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")

the glow-up fr fr 🌈

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". the people's choice award goes to... this one 👑

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. no freebies, bestie.

---

🔥 SEE ALSO 🔥

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

lowkey a little sibling rivalry moment but we support both 💜

---

🌟 AUTHOR 🌟

Current maintainer: Tony Bowden

Original author: Simon Cozens

legends, honestly 👑

---

💀 BUGS and QUERIES 💀

Please direct all correspondence regarding this module to:

bug-Text-Context-EitherSide@rt.cpan.org

found a bug? email it. queries? email it. we're listening 🫶

---

🎀 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

---

okay that's the whole page, you ate it, no cap ✨ this was Text::...herSide(3pm) — the manual name right there in the header — brought to you by perl v5.36.0, dated 2022-11-21. thanks for reading bestie, go extract some context 💖🎀🦋