Debian Codegraph @

upstream/debian-unstable/man3/Text::ParseWords.3perl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "Text::ParseWords 3perl"
58 .TH Text::ParseWords 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 Text::ParseWords \- parse text into an array of tokens or array of arrays
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 6
68 \& use Text::ParseWords;
69 \& @lists = nested_quotewords($delim, $keep, @lines);
70 \& @words = quotewords($delim, $keep, @lines);
71 \& @words = shellwords(@lines);
72 \& @words = parse_line($delim, $keep, $line);
73 \& @words = old_shellwords(@lines); # DEPRECATED!
74 .Ve
75 .SH DESCRIPTION
76 .IX Header "DESCRIPTION"
77 The \f(CWnested_quotewords()\fR and \f(CWquotewords()\fR functions accept a delimiter
78 (which can be a regular expression)
79 and a list of lines and then breaks those lines up into a list of
80 words ignoring delimiters that appear inside quotes. \f(CWquotewords()\fR
81 returns all of the tokens in a single long list, while \f(CWnested_quotewords()\fR
82 returns a list of token lists corresponding to the elements of \f(CW@lines\fR.
83 \&\f(CWparse_line()\fR does tokenizing on a single string. The \f(CW*quotewords()\fR
84 functions simply call \f(CWparse_line()\fR, so if you're only splitting
85 one line you can call \f(CWparse_line()\fR directly and save a function
86 call.
87 .PP
88 The \f(CW$keep\fR controls what happens with delimters and special characters:
89 .IP true 4
90 .IX Item "true"
91 If true, then the tokens are split on the specified delimiter,
92 but all other characters (including quotes and backslashes)
93 are kept in the tokens.
94 .IP false 4
95 .IX Item "false"
96 If \f(CW$keep\fR is false then the \f(CW*quotewords()\fR functions
97 remove all quotes and backslashes that are
98 not themselves backslash-escaped or inside of single quotes (i.e.,
99 \&\f(CWquotewords()\fR tries to interpret these characters just like the Bourne
100 shell). NB: these semantics are significantly different from the
101 original version of this module shipped with Perl 5.000 through 5.004.
102 .ie n .IP """delimiters""" 4
103 .el .IP "\f(CW""delimiters""\fR" 4
104 .IX Item """delimiters"""
105 As an additional feature, \f(CW$keep\fR may be the keyword "delimiters" which
106 causes the functions to preserve the delimiters in each string as
107 tokens in the token lists, in addition to preserving quote and
108 backslash characters.
109 .PP
110 \&\f(CWshellwords()\fR is written as a special case of \f(CWquotewords()\fR, and it
111 does token parsing with whitespace as a delimiter\-\- similar to most
112 Unix shells.
113 .SH EXAMPLES
114 .IX Header "EXAMPLES"
115 The sample program:
116 .PP
117 .Vb 7
118 \& use Text::ParseWords;
119 \& @words = quotewords(\*(Aq\es+\*(Aq, 0, q{this is "a test" of\e quotewords \e"for you});
120 \& $i = 0;
121 \& foreach (@words) {
122 \& print "$i: <$_>\en";
123 \& $i++;
124 \& }
125 .Ve
126 .PP
127 produces:
128 .PP
129 .Vb 6
130 \& 0: <this>
131 \& 1: <is>
132 \& 2: <a test>
133 \& 3: <of quotewords>
134 \& 4: <"for>
135 \& 5: <you>
136 .Ve
137 .PP
138 demonstrating:
139 .IP 0 4
140 a simple word
141 .IP 1 4
142 .IX Item "1"
143 multiple spaces are skipped because of our \f(CW$delim\fR
144 .IP 2 4
145 .IX Item "2"
146 use of quotes to include a space in a word
147 .IP 3 4
148 .IX Item "3"
149 use of a backslash to include a space in a word
150 .IP 4 4
151 .IX Item "4"
152 use of a backslash to remove the special meaning of a double-quote
153 .IP 5 4
154 .IX Item "5"
155 another simple word (note the lack of effect of the
156 backslashed double-quote)
157 .PP
158 Replacing \f(CW\*(C`quotewords(\*(Aq\es+\*(Aq, 0, q{this is...})\*(C'\fR
159 with \f(CW\*(C`shellwords(q{this is...})\*(C'\fR
160 is a simpler way to accomplish the same thing.
161 .SH "SEE ALSO"
162 .IX Header "SEE ALSO"
163 Text::CSV \- for parsing CSV files
164 .SH AUTHORS
165 .IX Header "AUTHORS"
166 The original author is unknown,
167 but presumably this evolved from \f(CW\*(C`shellwords.pl\*(C'\fR in Perl 4.
168 .PP
169 Much of the code for \f(CWparse_line()\fR
170 (including the primary regexp)
171 came from Joerk Behrends <[email protected]>.
172 .PP
173 Examples section and other documentation provided by
174 John Heidemann <[email protected]>.
175 .PP
176 Hal Pomeranz <[email protected]>
177 maintained this from 1994 through 1999,
178 and did the first CPAN release.
179 .PP
180 Alexandr Ciornii <alexchornyATgmail.com>
181 maintained this from 2008 to 2015.
182 .PP
183 Many other people have contributed,
184 with special thanks due to
185 Michael Schwern <[email protected]>
186 and
187 Jeff Friedl <jfriedl@yahoo\-inc.com>.
188 .SH "COPYRIGHT AND LICENSE"
189 .IX Header "COPYRIGHT AND LICENSE"
190 This library is free software; you may redistribute and/or modify it
191 under the same terms as Perl itself.