Debian Codegraph @

upstream/opensuse-tumbleweed/man3/Text::ParseWords.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (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 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "Text::ParseWords 3pm"
61 .TH Text::ParseWords 3pm 2026-03-09 "perl v5.42.1" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 Text::ParseWords \- parse text into an array of tokens or array of arrays
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 6
71 \& use Text::ParseWords;
72 \& @lists = nested_quotewords($delim, $keep, @lines);
73 \& @words = quotewords($delim, $keep, @lines);
74 \& @words = shellwords(@lines);
75 \& @words = parse_line($delim, $keep, $line);
76 \& @words = old_shellwords(@lines); # DEPRECATED!
77 .Ve
78 .SH DESCRIPTION
79 .IX Header "DESCRIPTION"
80 The \f(CWnested_quotewords()\fR and \f(CWquotewords()\fR functions accept a delimiter
81 (which can be a regular expression)
82 and a list of lines and then breaks those lines up into a list of
83 words ignoring delimiters that appear inside quotes. \f(CWquotewords()\fR
84 returns all of the tokens in a single long list, while \f(CWnested_quotewords()\fR
85 returns a list of token lists corresponding to the elements of \f(CW@lines\fR.
86 \&\f(CWparse_line()\fR does tokenizing on a single string. The \f(CW*quotewords()\fR
87 functions simply call \f(CWparse_line()\fR, so if you\*(Aqre only splitting
88 one line you can call \f(CWparse_line()\fR directly and save a function
89 call.
90 .PP
91 The \f(CW$keep\fR controls what happens with delimters and special characters:
92 .IP true 4
93 .IX Item "true"
94 If true, then the tokens are split on the specified delimiter,
95 but all other characters (including quotes and backslashes)
96 are kept in the tokens.
97 .IP false 4
98 .IX Item "false"
99 If \f(CW$keep\fR is false then the \f(CW*quotewords()\fR functions
100 remove all quotes and backslashes that are
101 not themselves backslash\-escaped or inside of single quotes (i.e.,
102 \&\f(CWquotewords()\fR tries to interpret these characters just like the Bourne
103 shell). NB: these semantics are significantly different from the
104 original version of this module shipped with Perl 5.000 through 5.004.
105 .ie n .IP """delimiters""" 4
106 .el .IP "\f(CW""delimiters""\fR" 4
107 .IX Item """delimiters"""
108 As an additional feature, \f(CW$keep\fR may be the keyword "delimiters" which
109 causes the functions to preserve the delimiters in each string as
110 tokens in the token lists, in addition to preserving quote and
111 backslash characters.
112 .PP
113 \&\f(CWshellwords()\fR is written as a special case of \f(CWquotewords()\fR, and it
114 does token parsing with whitespace as a delimiter\-\- similar to most
115 Unix shells.
116 .SH EXAMPLES
117 .IX Header "EXAMPLES"
118 The sample program:
119 .PP
120 .Vb 7
121 \& use Text::ParseWords;
122 \& @words = quotewords(\*(Aq\es+\*(Aq, 0, q{this is "a test" of\e quotewords \e"for you});
123 \& $i = 0;
124 \& foreach (@words) {
125 \& print "$i: <$_>\en";
126 \& $i++;
127 \& }
128 .Ve
129 .PP
130 produces:
131 .PP
132 .Vb 6
133 \& 0: <this>
134 \& 1: <is>
135 \& 2: <a test>
136 \& 3: <of quotewords>
137 \& 4: <"for>
138 \& 5: <you>
139 .Ve
140 .PP
141 demonstrating:
142 .IP 0 4
143 a simple word
144 .IP 1 4
145 .IX Item "1"
146 multiple spaces are skipped because of our \f(CW$delim\fR
147 .IP 2 4
148 .IX Item "2"
149 use of quotes to include a space in a word
150 .IP 3 4
151 .IX Item "3"
152 use of a backslash to include a space in a word
153 .IP 4 4
154 .IX Item "4"
155 use of a backslash to remove the special meaning of a double\-quote
156 .IP 5 4
157 .IX Item "5"
158 another simple word (note the lack of effect of the
159 backslashed double\-quote)
160 .PP
161 Replacing \f(CW\*(C`quotewords(\*(Aq\es+\*(Aq, 0, q{this is...})\*(C'\fR
162 with \f(CW\*(C`shellwords(q{this is...})\*(C'\fR
163 is a simpler way to accomplish the same thing.
164 .SH "SEE ALSO"
165 .IX Header "SEE ALSO"
166 Text::CSV \- for parsing CSV files
167 .SH AUTHORS
168 .IX Header "AUTHORS"
169 The original author is unknown,
170 but presumably this evolved from \f(CW\*(C`shellwords.pl\*(C'\fR in Perl 4.
171 .PP
172 Much of the code for \f(CWparse_line()\fR
173 (including the primary regexp)
174 came from Joerk Behrends <[email protected]>.
175 .PP
176 Examples section and other documentation provided by
177 John Heidemann <[email protected]>.
178 .PP
179 Hal Pomeranz <[email protected]>
180 maintained this from 1994 through 1999,
181 and did the first CPAN release.
182 .PP
183 Alexandr Ciornii <alexchornyATgmail.com>
184 maintained this from 2008 to 2015.
185 .PP
186 Many other people have contributed,
187 with special thanks due to
188 Michael Schwern <[email protected]>
189 and
190 Jeff Friedl <jfriedl@yahoo\-inc.com>.
191 .SH "COPYRIGHT AND LICENSE"
192 .IX Header "COPYRIGHT AND LICENSE"
193 This library is free software; you may redistribute and/or modify it
194 under the same terms as Perl itself.