TEXT::PARSEWORDS(3perl)

💖 Text::ParseWords — the Text::ParseWords(3perl) manual, but make it make sense 💖

okay bestie, sit down, we're learning Text::ParseWords and honestly? it's giving "tiny module, big power". no cap.

✨ NAME ✨

Text::ParseWords — parse text into an array of tokens or array of arrays 🎀

---

🌸 SYNOPSIS 🌸

use Text::ParseWords;
@lists = nested_quotewords($delim, $keep, @lines);
@words = quotewords($delim, $keep, @lines);
@words = shellwords(@lines);
@words = parse_line($delim, $keep, $line);
@words = old_shellwords(@lines); # DEPRECATED!

💀 bestie that last one says DEPRECATED! and we do NOT ignore that. it's literally written in the source. do not be the person shipping old_shellwords.

---

🦋 DESCRIPTION 🦋

so nested_quotewords() and quotewords() take a delimiter (and yes, it can be a regular expression, she's flexible like that 💅) plus a list of lines, and then breaks those lines up into a list of words — while ignoring delimiters that appear inside quotes. iconic behavior.

• quotewords() hands you back all the tokens in one single long list. one big list, no notes.
• nested_quotewords() hands you back a list of token lists, and each inner list matches up with a corresponding element of @lines. very organized, very demure.
• parse_line() does the tokenizing on just one single string.

and here's the tea ☕ — the *quotewords() functions just call parse_line() underneath. so if you're only splitting one line, just call parse_line() directly and save yourself a whole function call. free real estate. 🔥

🧚 the $keep drama 🧚

$keep controls what happens with delimiters and special characters. three moods:

• true — if true, tokens are split on the specified delimiter, but all other characters (including quotes and backslashes) are kept in the tokens. nothing gets thrown away ✨
• false — if $keep is false, the *quotewords() functions remove all quotes and backslashes that are not themselves backslash-escaped or inside of single quotes (i.e. quotewords() tries to interpret these characters just like the Bourne shell).

🚨 NB: these semantics are significantly different from the original version of this module shipped with Perl 5.000 through 5.004. letting you know fr fr.

• "delimiters" — as an extra lil feature, $keep can also be the keyword "delimiters". that makes the functions preserve the delimiters in each string as tokens in the token lists, on top of preserving quote and backslash characters. bonus content 🎁

and shellwords()? she's written as a special case of quotewords(), and she does token parsing with whitespace as a delimiter — similar to most Unix shells. that's the vibe 🐚

---

🌈 EXAMPLES 🌈

sample program, go:

use Text::ParseWords;
@words = quotewords('\s+', 0, q{this   is "a test" of\ quotewords \"for you});
$i = 0;
foreach (@words) {
    print "$i: <$_>\n";
    $i++;
}

and it produces:

0: <this>
1: <is>
2: <a test>
3: <of quotewords>
4: <"for>
5: <you>

which is demonstrating, one by one:

0. a simple word 👑
1. multiple spaces are skipped because of our $delim ✨
2. use of quotes to include a space in a word 🎀
3. use of a backslash to include a space in a word 💅
4. use of a backslash to remove the special meaning of a double-quote 😭
5. another simple word — and note the lack of effect of the backslashed double-quote 🫶

and the glow-up: replacing quotewords('\s+', 0, q{this is...}) with shellwords(q{this is...}) is literally a simpler way to accomplish the same thing. shorter, cuter, same result. periodt.

---

🍓 SEE ALSO 🍓

• Text::CSV — for parsing CSV files

---

💜 AUTHORS 💜

• the original author is unknown, but presumably this evolved from shellwords.pl in Perl 4.
• much of the code for parse_line() (including the primary regexp) came from Joerk Behrends <jbehrends@multimediaproduzenten.de>.
• Examples section and other documentation provided by John Heidemann <johnh@ISI.EDU>.
• Hal Pomeranz <pomeranz@netcom.com> maintained this from 1994 through 1999, and did the first CPAN release.
• Alexandr Ciornii <alexchornyATgmail.com> maintained this from 2008 to 2015.
• many other people have contributed, with special thanks due to Michael Schwern <schwern@envirolink.org> and Jeff Friedl <jfriedl@yahoo-inc.com>.

---

👑 COPYRIGHT AND LICENSE 👑

This library is free software; you may redistribute and/or modify it under the same terms as Perl itself. slay, that's the whole license.

---

okay that's the whole page, you ate that 🫶 go tokenize something. this was perl v5.44.0, dated 2026-10-17, and the page is Text::ParseWords(3perl) — love u, bye 💖✨