.\" 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::ParseWords 3"
.TH Text::ParseWords 3 "2022-04-12" "perl v5.34.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::ParseWords \- parse text into an array of tokens or array of arrays
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 6
\&  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!
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \f(CW\*(C`nested_quotewords()\*(C'\fR and \f(CW\*(C`quotewords()\*(C'\fR functions accept a delimiter 
(which can be a regular expression)
and a list of lines and then breaks those lines up into a list of
words ignoring delimiters that appear inside quotes.  \f(CW\*(C`quotewords()\*(C'\fR
returns all of the tokens in a single long list, while \f(CW\*(C`nested_quotewords()\*(C'\fR
returns a list of token lists corresponding to the elements of \f(CW@lines\fR.
\&\f(CW\*(C`parse_line()\*(C'\fR does tokenizing on a single string.  The \f(CW\*(C`*quotewords()\*(C'\fR
functions simply call \f(CW\*(C`parse_line()\*(C'\fR, so if you're only splitting
one line you can call \f(CW\*(C`parse_line()\*(C'\fR directly and save a function
call.
.PP
The \f(CW$keep\fR controls what happens with delimters and special characters:
.IP "true" 4
.IX Item "true"
If true, then the tokens are split on the specified delimiter,
but all other characters (including quotes and backslashes)
are kept in the tokens.
.IP "false" 4
.IX Item "false"
If \f(CW$keep\fR is false then the \f(CW\*(C`*quotewords()\*(C'\fR functions
remove all quotes and backslashes that are
not themselves backslash-escaped or inside of single quotes (i.e.,
\&\f(CW\*(C`quotewords()\*(C'\fR tries to interpret these characters just like the Bourne
shell).  \s-1NB:\s0 these semantics are significantly different from the
original version of this module shipped with Perl 5.000 through 5.004.
.ie n .IP """delimiters""" 4
.el .IP "\f(CW``delimiters''\fR" 4
.IX Item """delimiters"""
As an additional feature, \f(CW$keep\fR may be the keyword \*(L"delimiters\*(R" which
causes the functions to preserve the delimiters in each string as
tokens in the token lists, in addition to preserving quote and
backslash characters.
.PP
\&\f(CW\*(C`shellwords()\*(C'\fR is written as a special case of \f(CW\*(C`quotewords()\*(C'\fR, and it
does token parsing with whitespace as a delimiter\*(-- similar to most
Unix shells.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
The sample program:
.PP
.Vb 7
\&  use Text::ParseWords;
\&  @words = quotewords(\*(Aq\es+\*(Aq, 0, q{this   is "a test" of\e quotewords \e"for you});
\&  $i = 0;
\&  foreach (@words) {
\&      print "$i: <$_>\en";
\&      $i++;
\&  }
.Ve
.PP
produces:
.PP
.Vb 6
\&  0: <this>
\&  1: <is>
\&  2: <a test>
\&  3: <of quotewords>
\&  4: <"for>
\&  5: <you>
.Ve
.PP
demonstrating:
.IP "0" 4
a simple word
.IP "1" 4
.IX Item "1"
multiple spaces are skipped because of our \f(CW$delim\fR
.IP "2" 4
.IX Item "2"
use of quotes to include a space in a word
.IP "3" 4
.IX Item "3"
use of a backslash to include a space in a word
.IP "4" 4
.IX Item "4"
use of a backslash to remove the special meaning of a double-quote
.IP "5" 4
.IX Item "5"
another simple word (note the lack of effect of the
backslashed double-quote)
.PP
Replacing \f(CW\*(C`quotewords(\*(Aq\es+\*(Aq, 0, q{this   is...})\*(C'\fR
with \f(CW\*(C`shellwords(q{this   is...})\*(C'\fR
is a simpler way to accomplish the same thing.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Text::CSV \- for parsing \s-1CSV\s0 files
.SH "AUTHORS"
.IX Header "AUTHORS"
The original author is unknown,
but presumably this evolved from \f(CW\*(C`shellwords.pl\*(C'\fR in Perl 4.
.PP
Much of the code for \f(CW\*(C`parse_line()\*(C'\fR
(including the primary regexp)
came from Joerk Behrends <jbehrends@multimediaproduzenten.de>.
.PP
Examples section and other documentation provided by
John Heidemann <johnh@ISI.EDU>.
.PP
Hal Pomeranz <pomeranz@netcom.com>
maintained this from 1994 through 1999,
and did the first \s-1CPAN\s0 release.
.PP
Alexandr Ciornii <alexchornyATgmail.com>
maintained this from 2008 to 2015.
.PP
Many other people have contributed,
with special thanks due to 
Michael Schwern <schwern@envirolink.org>
and
Jeff Friedl <jfriedl@yahoo\-inc.com>.
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This library is free software; you may redistribute and/or modify it
under the same terms as Perl itself.