Debian Codegraph @

upstream/opensuse-tumbleweed/man3/Text::Balanced.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::Balanced 3pm"
61 .TH Text::Balanced 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::Balanced \- Extract delimited text sequences from strings.
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 11
71 \& use Text::Balanced qw (
72 \& extract_delimited
73 \& extract_bracketed
74 \& extract_quotelike
75 \& extract_codeblock
76 \& extract_variable
77 \& extract_tagged
78 \& extract_multiple
79 \& gen_delimited_pat
80 \& gen_extract_tagged
81 \& );
82 \&
83 \& # Extract the initial substring of $text that is delimited by
84 \& # two (unescaped) instances of the first character in $delim.
85 \&
86 \& ($extracted, $remainder) = extract_delimited($text,$delim);
87 \&
88 \& # Extract the initial substring of $text that is bracketed
89 \& # with a delimiter(s) specified by $delim (where the string
90 \& # in $delim contains one or more of \*(Aq(){}[]<>\*(Aq).
91 \&
92 \& ($extracted, $remainder) = extract_bracketed($text,$delim);
93 \&
94 \& # Extract the initial substring of $text that is bounded by
95 \& # an XML tag.
96 \&
97 \& ($extracted, $remainder) = extract_tagged($text);
98 \&
99 \& # Extract the initial substring of $text that is bounded by
100 \& # a C<BEGIN>...C<END> pair. Don\*(Aqt allow nested C<BEGIN> tags
101 \&
102 \& ($extracted, $remainder) =
103 \& extract_tagged($text,"BEGIN","END",undef,{bad=>["BEGIN"]});
104 \&
105 \& # Extract the initial substring of $text that represents a
106 \& # Perl "quote or quote\-like operation"
107 \&
108 \& ($extracted, $remainder) = extract_quotelike($text);
109 \&
110 \& # Extract the initial substring of $text that represents a block
111 \& # of Perl code, bracketed by any of character(s) specified by $delim
112 \& # (where the string $delim contains one or more of \*(Aq(){}[]<>\*(Aq).
113 \&
114 \& ($extracted, $remainder) = extract_codeblock($text,$delim);
115 \&
116 \& # Extract the initial substrings of $text that would be extracted by
117 \& # one or more sequential applications of the specified functions
118 \& # or regular expressions
119 \&
120 \& @extracted = extract_multiple($text,
121 \& [ \e&extract_bracketed,
122 \& \e&extract_quotelike,
123 \& \e&some_other_extractor_sub,
124 \& qr/[xyz]*/,
125 \& \*(Aqliteral\*(Aq,
126 \& ]);
127 \&
128 \& # Create a string representing an optimized pattern (a la Friedl)
129 \& # that matches a substring delimited by any of the specified characters
130 \& # (in this case: any type of quote or a slash)
131 \&
132 \& $patstring = gen_delimited_pat(q{\*(Aq"\`/});
133 \&
134 \& # Generate a reference to an anonymous sub that is just like extract_tagged
135 \& # but pre\-compiled and optimized for a specific pair of tags, and
136 \& # consequently much faster (i.e. 3 times faster). It uses qr// for better
137 \& # performance on repeated calls.
138 \&
139 \& $extract_head = gen_extract_tagged(\*(Aq<HEAD>\*(Aq,\*(Aq</HEAD>\*(Aq);
140 \& ($extracted, $remainder) = $extract_head\->($text);
141 .Ve
142 .SH DESCRIPTION
143 .IX Header "DESCRIPTION"
144 The various \f(CW\*(C`extract_...\*(C'\fR subroutines may be used to
145 extract a delimited substring, possibly after skipping a
146 specified prefix string. By default, that prefix is
147 optional whitespace (\f(CW\*(C`/\es*/\*(C'\fR), but you can change it to whatever
148 you wish (see below).
149 .PP
150 The substring to be extracted must appear at the
151 current \f(CW\*(C`pos\*(C'\fR location of the string\*(Aqs variable
152 (or at index zero, if no \f(CW\*(C`pos\*(C'\fR position is defined).
153 In other words, the \f(CW\*(C`extract_...\*(C'\fR subroutines \fIdon\*(Aqt\fR
154 extract the first occurrence of a substring anywhere
155 in a string (like an unanchored regex would). Rather,
156 they extract an occurrence of the substring appearing
157 immediately at the current matching position in the
158 string (like a \f(CW\*(C`\eG\*(C'\fR\-anchored regex would).
159 .SS "General Behaviour in List Contexts"
160 .IX Subsection "General Behaviour in List Contexts"
161 In a list context, all the subroutines return a list, the first three
162 elements of which are always:
163 .IP [0] 4
164 .IX Item "[0]"
165 The extracted string, including the specified delimiters.
166 If the extraction fails \f(CW\*(C`undef\*(C'\fR is returned.
167 .IP [1] 4
168 .IX Item "[1]"
169 The remainder of the input string (i.e. the characters after the
170 extracted string). On failure, the entire string is returned.
171 .IP [2] 4
172 .IX Item "[2]"
173 The skipped prefix (i.e. the characters before the extracted string).
174 On failure, \f(CW\*(C`undef\*(C'\fR is returned.
175 .PP
176 Note that in a list context, the contents of the original input text (the first
177 argument) are not modified in any way.
178 .PP
179 However, if the input text was passed in a variable, that variable\*(Aqs
180 \&\f(CW\*(C`pos\*(C'\fR value is updated to point at the first character after the
181 extracted text. That means that in a list context the various
182 subroutines can be used much like regular expressions. For example:
183 .PP
184 .Vb 4
185 \& while ( $next = (extract_quotelike($text))[0] )
186 \& {
187 \& # process next quote\-like (in $next)
188 \& }
189 .Ve
190 .SS "General Behaviour in Scalar and Void Contexts"
191 .IX Subsection "General Behaviour in Scalar and Void Contexts"
192 In a scalar context, the extracted string is returned, having first been
193 removed from the input text. Thus, the following code also processes
194 each quote\-like operation, but actually removes them from \f(CW$text:\fR
195 .PP
196 .Vb 4
197 \& while ( $next = extract_quotelike($text) )
198 \& {
199 \& # process next quote\-like (in $next)
200 \& }
201 .Ve
202 .PP
203 Note that if the input text is a read\-only string (i.e. a literal),
204 no attempt is made to remove the extracted text.
205 .PP
206 In a void context the behaviour of the extraction subroutines is
207 exactly the same as in a scalar context, except (of course) that the
208 extracted substring is not returned.
209 .SS "A Note About Prefixes"
210 .IX Subsection "A Note About Prefixes"
211 Prefix patterns are matched without any trailing modifiers (\f(CW\*(C`/gimsox\*(C'\fR etc.)
212 This can bite you if you\*(Aqre expecting a prefix specification like
213 \&\*(Aq.*?(?=<H1>)\*(Aq to skip everything up to the first <H1> tag. Such a prefix
214 pattern will only succeed if the <H1> tag is on the current line, since
215 \&. normally doesn\*(Aqt match newlines.
216 .PP
217 To overcome this limitation, you need to turn on /s matching within
218 the prefix pattern, using the \f(CW\*(C`(?s)\*(C'\fR directive: \*(Aq(?s).*?(?=<H1>)\*(Aq
219 .SS Functions
220 .IX Subsection "Functions"
221 .ie n .IP """extract_delimited""" 4
222 .el .IP \f(CWextract_delimited\fR 4
223 .IX Item "extract_delimited"
224 The \f(CW\*(C`extract_delimited\*(C'\fR function formalizes the common idiom
225 of extracting a single\-character\-delimited substring from the start of
226 a string. For example, to extract a single\-quote delimited string, the
227 following code is typically used:
228 .Sp
229 .Vb 2
230 \& ($remainder = $text) =~ s/\eA(\*(Aq(\e\e.|[^\*(Aq])*\*(Aq)//s;
231 \& $extracted = $1;
232 .Ve
233 .Sp
234 but with \f(CW\*(C`extract_delimited\*(C'\fR it can be simplified to:
235 .Sp
236 .Vb 1
237 \& ($extracted,$remainder) = extract_delimited($text, "\*(Aq");
238 .Ve
239 .Sp
240 \&\f(CW\*(C`extract_delimited\*(C'\fR takes up to four scalars (the input text, the
241 delimiters, a prefix pattern to be skipped, and any escape characters)
242 and extracts the initial substring of the text that
243 is appropriately delimited. If the delimiter string has multiple
244 characters, the first one encountered in the text is taken to delimit
245 the substring.
246 The third argument specifies a prefix pattern that is to be skipped
247 (but must be present!) before the substring is extracted.
248 The final argument specifies the escape character to be used for each
249 delimiter.
250 .Sp
251 All arguments are optional. If the escape characters are not specified,
252 every delimiter is escaped with a backslash (\f(CW\*(C`\e\*(C'\fR).
253 If the prefix is not specified, the
254 pattern \f(CW\*(Aq\es*\*(Aq\fR \- optional whitespace \- is used. If the delimiter set
255 is also not specified, the set \f(CW\*(C`/["\*(Aq\`]/\*(C'\fR is used. If the text to be processed
256 is not specified either, \f(CW$_\fR is used.
257 .Sp
258 In list context, \f(CW\*(C`extract_delimited\*(C'\fR returns a array of three
259 elements, the extracted substring (\fIincluding the surrounding
260 delimiters\fR), the remainder of the text, and the skipped prefix (if
261 any). If a suitable delimited substring is not found, the first
262 element of the array is the empty string, the second is the complete
263 original text, and the prefix returned in the third element is an
264 empty string.
265 .Sp
266 In a scalar context, just the extracted substring is returned. In
267 a void context, the extracted substring (and any prefix) are simply
268 removed from the beginning of the first argument.
269 .Sp
270 Examples:
271 .Sp
272 .Vb 1
273 \& # Remove a single\-quoted substring from the very beginning of $text:
274 \&
275 \& $substring = extract_delimited($text, "\*(Aq", \*(Aq\*(Aq);
276 \&
277 \& # Remove a single\-quoted Pascalish substring (i.e. one in which
278 \& # doubling the quote character escapes it) from the very
279 \& # beginning of $text:
280 \&
281 \& $substring = extract_delimited($text, "\*(Aq", \*(Aq\*(Aq, "\*(Aq");
282 \&
283 \& # Extract a single\- or double\- quoted substring from the
284 \& # beginning of $text, optionally after some whitespace
285 \& # (note the list context to protect $text from modification):
286 \&
287 \& ($substring) = extract_delimited $text, q{"\*(Aq};
288 \&
289 \& # Delete the substring delimited by the first \*(Aq/\*(Aq in $text:
290 \&
291 \& $text = join \*(Aq\*(Aq, (extract_delimited($text,\*(Aq/\*(Aq,\*(Aq[^/]*\*(Aq)[2,1];
292 .Ve
293 .Sp
294 Note that this last example is \fInot\fR the same as deleting the first
295 quote\-like pattern. For instance, if \f(CW$text\fR contained the string:
296 .Sp
297 .Vb 1
298 \& "if (\*(Aq./cmd\*(Aq =~ m/$UNIXCMD/s) { $cmd = $1; }"
299 .Ve
300 .Sp
301 then after the deletion it would contain:
302 .Sp
303 .Vb 1
304 \& "if (\*(Aq.$UNIXCMD/s) { $cmd = $1; }"
305 .Ve
306 .Sp
307 not:
308 .Sp
309 .Vb 1
310 \& "if (\*(Aq./cmd\*(Aq =~ ms) { $cmd = $1; }"
311 .Ve
312 .Sp
313 See "extract_quotelike" for a (partial) solution to this problem.
314 .ie n .IP """extract_bracketed""" 4
315 .el .IP \f(CWextract_bracketed\fR 4
316 .IX Item "extract_bracketed"
317 Like \f(CW"extract_delimited"\fR, the \f(CW\*(C`extract_bracketed\*(C'\fR function takes
318 up to three optional scalar arguments: a string to extract from, a delimiter
319 specifier, and a prefix pattern. As before, a missing prefix defaults to
320 optional whitespace and a missing text defaults to \f(CW$_\fR. However, a missing
321 delimiter specifier defaults to \f(CW\*(Aq{}()[]<>\*(Aq\fR (see below).
322 .Sp
323 \&\f(CW\*(C`extract_bracketed\*(C'\fR extracts a balanced\-bracket\-delimited
324 substring (using any one (or more) of the user\-specified delimiter
325 brackets: \*(Aq(..)\*(Aq, \*(Aq{..}\*(Aq, \*(Aq[..]\*(Aq, or \*(Aq<..>\*(Aq). Optionally it will also
326 respect quoted unbalanced brackets (see below).
327 .Sp
328 A "delimiter bracket" is a bracket in list of delimiters passed as
329 \&\f(CW\*(C`extract_bracketed\*(C'\fR\*(Aqs second argument. Delimiter brackets are
330 specified by giving either the left or right (or both!) versions
331 of the required bracket(s). Note that the order in which
332 two or more delimiter brackets are specified is not significant.
333 .Sp
334 A "balanced\-bracket\-delimited substring" is a substring bounded by
335 matched brackets, such that any other (left or right) delimiter
336 bracket \fIwithin\fR the substring is also matched by an opposite
337 (right or left) delimiter bracket \fIat the same level of nesting\fR. Any
338 type of bracket not in the delimiter list is treated as an ordinary
339 character.
340 .Sp
341 In other words, each type of bracket specified as a delimiter must be
342 balanced and correctly nested within the substring, and any other kind of
343 ("non\-delimiter") bracket in the substring is ignored.
344 .Sp
345 For example, given the string:
346 .Sp
347 .Vb 1
348 \& $text = "{ an \*(Aq[irregularly :\-(] {} parenthesized >:\-)\*(Aq string }";
349 .Ve
350 .Sp
351 then a call to \f(CW\*(C`extract_bracketed\*(C'\fR in a list context:
352 .Sp
353 .Vb 1
354 \& @result = extract_bracketed( $text, \*(Aq{}\*(Aq );
355 .Ve
356 .Sp
357 would return:
358 .Sp
359 .Vb 1
360 \& ( "{ an \*(Aq[irregularly :\-(] {} parenthesized >:\-)\*(Aq string }" , "" , "" )
361 .Ve
362 .Sp
363 since both sets of \f(CW\*(Aq{..}\*(Aq\fR brackets are properly nested and evenly balanced.
364 (In a scalar context just the first element of the array would be returned. In
365 a void context, \f(CW$text\fR would be replaced by an empty string.)
366 .Sp
367 Likewise the call in:
368 .Sp
369 .Vb 1
370 \& @result = extract_bracketed( $text, \*(Aq{[\*(Aq );
371 .Ve
372 .Sp
373 would return the same result, since all sets of both types of specified
374 delimiter brackets are correctly nested and balanced.
375 .Sp
376 However, the call in:
377 .Sp
378 .Vb 1
379 \& @result = extract_bracketed( $text, \*(Aq{([<\*(Aq );
380 .Ve
381 .Sp
382 would fail, returning:
383 .Sp
384 .Vb 1
385 \& ( undef , "{ an \*(Aq[irregularly :\-(] {} parenthesized >:\-)\*(Aq string }" );
386 .Ve
387 .Sp
388 because the embedded pairs of \f(CW\*(Aq(..)\*(Aq\fRs and \f(CW\*(Aq[..]\*(Aq\fRs are "cross\-nested" and
389 the embedded \f(CW\*(Aq>\*(Aq\fR is unbalanced. (In a scalar context, this call would
390 return an empty string. In a void context, \f(CW$text\fR would be unchanged.)
391 .Sp
392 Note that the embedded single\-quotes in the string don\*(Aqt help in this
393 case, since they have not been specified as acceptable delimiters and are
394 therefore treated as non\-delimiter characters (and ignored).
395 .Sp
396 However, if a particular species of quote character is included in the
397 delimiter specification, then that type of quote will be correctly handled.
398 for example, if \f(CW$text\fR is:
399 .Sp
400 .Vb 1
401 \& $text = \*(Aq<A HREF=">>>>">link</A>\*(Aq;
402 .Ve
403 .Sp
404 then
405 .Sp
406 .Vb 1
407 \& @result = extract_bracketed( $text, \*(Aq<">\*(Aq );
408 .Ve
409 .Sp
410 returns:
411 .Sp
412 .Vb 1
413 \& ( \*(Aq<A HREF=">>>>">\*(Aq, \*(Aqlink</A>\*(Aq, "" )
414 .Ve
415 .Sp
416 as expected. Without the specification of \f(CW\*(C`"\*(C'\fR as an embedded quoter:
417 .Sp
418 .Vb 1
419 \& @result = extract_bracketed( $text, \*(Aq<>\*(Aq );
420 .Ve
421 .Sp
422 the result would be:
423 .Sp
424 .Vb 1
425 \& ( \*(Aq<A HREF=">\*(Aq, \*(Aq>>>">link</A>\*(Aq, "" )
426 .Ve
427 .Sp
428 In addition to the quote delimiters \f(CW\*(C`\*(Aq\*(C'\fR, \f(CW\*(C`"\*(C'\fR, and \f(CW\*(C`\`\*(C'\fR, full Perl quote\-like
429 quoting (i.e. q{string}, qq{string}, etc) can be specified by including the
430 letter \*(Aqq\*(Aq as a delimiter. Hence:
431 .Sp
432 .Vb 1
433 \& @result = extract_bracketed( $text, \*(Aq<q>\*(Aq );
434 .Ve
435 .Sp
436 would correctly match something like this:
437 .Sp
438 .Vb 1
439 \& $text = \*(Aq<leftop: conj /and/ conj>\*(Aq;
440 .Ve
441 .Sp
442 See also: \f(CW"extract_quotelike"\fR and \f(CW"extract_codeblock"\fR.
443 .ie n .IP """extract_variable""" 4
444 .el .IP \f(CWextract_variable\fR 4
445 .IX Item "extract_variable"
446 \&\f(CW\*(C`extract_variable\*(C'\fR extracts any valid Perl variable or
447 variable\-involved expression, including scalars, arrays, hashes, array
448 accesses, hash look\-ups, method calls through objects, subroutine calls
449 through subroutine references, etc.
450 .Sp
451 The subroutine takes up to two optional arguments:
452 .RS 4
453 .IP 1. 4
454 A string to be processed (\f(CW$_\fR if the string is omitted or \f(CW\*(C`undef\*(C'\fR)
455 .IP 2. 4
456 A string specifying a pattern to be matched as a prefix (which is to be
457 skipped). If omitted, optional whitespace is skipped.
458 .RE
459 .RS 4
460 .Sp
461 On success in a list context, an array of 3 elements is returned. The
462 elements are:
463 .IP [0] 4
464 .IX Item "[0]"
465 the extracted variable, or variablish expression
466 .IP [1] 4
467 .IX Item "[1]"
468 the remainder of the input text,
469 .IP [2] 4
470 .IX Item "[2]"
471 the prefix substring (if any),
472 .RE
473 .RS 4
474 .Sp
475 On failure, all of these values (except the remaining text) are \f(CW\*(C`undef\*(C'\fR.
476 .Sp
477 In a scalar context, \f(CW\*(C`extract_variable\*(C'\fR returns just the complete
478 substring that matched a variablish expression. \f(CW\*(C`undef\*(C'\fR is returned on
479 failure. In addition, the original input text has the returned substring
480 (and any prefix) removed from it.
481 .Sp
482 In a void context, the input text just has the matched substring (and
483 any specified prefix) removed.
484 .RE
485 .ie n .IP """extract_tagged""" 4
486 .el .IP \f(CWextract_tagged\fR 4
487 .IX Item "extract_tagged"
488 \&\f(CW\*(C`extract_tagged\*(C'\fR extracts and segments text between (balanced)
489 specified tags.
490 .Sp
491 The subroutine takes up to five optional arguments:
492 .RS 4
493 .IP 1. 4
494 A string to be processed (\f(CW$_\fR if the string is omitted or \f(CW\*(C`undef\*(C'\fR)
495 .IP 2. 4
496 A string specifying a pattern (i.e. regex) to be matched as the opening tag.
497 If the pattern string is omitted (or \f(CW\*(C`undef\*(C'\fR) then a pattern
498 that matches any standard XML tag is used.
499 .IP 3. 4
500 A string specifying a pattern to be matched at the closing tag.
501 If the pattern string is omitted (or \f(CW\*(C`undef\*(C'\fR) then the closing
502 tag is constructed by inserting a \f(CW\*(C`/\*(C'\fR after any leading bracket
503 characters in the actual opening tag that was matched (\fInot\fR the pattern
504 that matched the tag). For example, if the opening tag pattern
505 is specified as \f(CW\*(Aq{{\ew+}}\*(Aq\fR and actually matched the opening tag
506 \&\f(CW"{{DATA}}"\fR, then the constructed closing tag would be \f(CW"{{/DATA}}"\fR.
507 .IP 4. 4
508 A string specifying a pattern to be matched as a prefix (which is to be
509 skipped). If omitted, optional whitespace is skipped.
510 .IP 5. 4
511 A hash reference containing various parsing options (see below)
512 .RE
513 .RS 4
514 .Sp
515 The various options that can be specified are:
516 .ie n .IP """reject => $listref""" 4
517 .el .IP "\f(CWreject => $listref\fR" 4
518 .IX Item "reject => $listref"
519 The list reference contains one or more strings specifying patterns
520 that must \fInot\fR appear within the tagged text.
521 .Sp
522 For example, to extract
523 an HTML link (which should not contain nested links) use:
524 .Sp
525 .Vb 1
526 \& extract_tagged($text, \*(Aq<A>\*(Aq, \*(Aq</A>\*(Aq, undef, {reject => [\*(Aq<A>\*(Aq]} );
527 .Ve
528 .ie n .IP """ignore => $listref""" 4
529 .el .IP "\f(CWignore => $listref\fR" 4
530 .IX Item "ignore => $listref"
531 The list reference contains one or more strings specifying patterns
532 that are \fInot\fR to be treated as nested tags within the tagged text
533 (even if they would match the start tag pattern).
534 .Sp
535 For example, to extract an arbitrary XML tag, but ignore "empty" elements:
536 .Sp
537 .Vb 1
538 \& extract_tagged($text, undef, undef, undef, {ignore => [\*(Aq<[^>]*/>\*(Aq]} );
539 .Ve
540 .Sp
541 (also see "gen_delimited_pat" below).
542 .ie n .IP """fail => $str""" 4
543 .el .IP "\f(CWfail => $str\fR" 4
544 .IX Item "fail => $str"
545 The \f(CW\*(C`fail\*(C'\fR option indicates the action to be taken if a matching end
546 tag is not encountered (i.e. before the end of the string or some
547 \&\f(CW\*(C`reject\*(C'\fR pattern matches). By default, a failure to match a closing
548 tag causes \f(CW\*(C`extract_tagged\*(C'\fR to immediately fail.
549 .Sp
550 However, if the string value associated with <reject> is "MAX", then
551 \&\f(CW\*(C`extract_tagged\*(C'\fR returns the complete text up to the point of failure.
552 If the string is "PARA", \f(CW\*(C`extract_tagged\*(C'\fR returns only the first paragraph
553 after the tag (up to the first line that is either empty or contains
554 only whitespace characters).
555 If the string is "", the default behaviour (i.e. failure) is reinstated.
556 .Sp
557 For example, suppose the start tag "/para" introduces a paragraph, which then
558 continues until the next "/endpara" tag or until another "/para" tag is
559 encountered:
560 .Sp
561 .Vb 1
562 \& $text = "/para line 1\en\enline 3\en/para line 4";
563 \&
564 \& extract_tagged($text, \*(Aq/para\*(Aq, \*(Aq/endpara\*(Aq, undef,
565 \& {reject => \*(Aq/para\*(Aq, fail => MAX );
566 \&
567 \& # EXTRACTED: "/para line 1\en\enline 3\en"
568 .Ve
569 .Sp
570 Suppose instead, that if no matching "/endpara" tag is found, the "/para"
571 tag refers only to the immediately following paragraph:
572 .Sp
573 .Vb 1
574 \& $text = "/para line 1\en\enline 3\en/para line 4";
575 \&
576 \& extract_tagged($text, \*(Aq/para\*(Aq, \*(Aq/endpara\*(Aq, undef,
577 \& {reject => \*(Aq/para\*(Aq, fail => MAX );
578 \&
579 \& # EXTRACTED: "/para line 1\en"
580 .Ve
581 .Sp
582 Note that the specified \f(CW\*(C`fail\*(C'\fR behaviour applies to nested tags as well.
583 .RE
584 .RS 4
585 .Sp
586 On success in a list context, an array of 6 elements is returned. The elements are:
587 .IP [0] 4
588 .IX Item "[0]"
589 the extracted tagged substring (including the outermost tags),
590 .IP [1] 4
591 .IX Item "[1]"
592 the remainder of the input text,
593 .IP [2] 4
594 .IX Item "[2]"
595 the prefix substring (if any),
596 .IP [3] 4
597 .IX Item "[3]"
598 the opening tag
599 .IP [4] 4
600 .IX Item "[4]"
601 the text between the opening and closing tags
602 .IP [5] 4
603 .IX Item "[5]"
604 the closing tag (or "" if no closing tag was found)
605 .RE
606 .RS 4
607 .Sp
608 On failure, all of these values (except the remaining text) are \f(CW\*(C`undef\*(C'\fR.
609 .Sp
610 In a scalar context, \f(CW\*(C`extract_tagged\*(C'\fR returns just the complete
611 substring that matched a tagged text (including the start and end
612 tags). \f(CW\*(C`undef\*(C'\fR is returned on failure. In addition, the original input
613 text has the returned substring (and any prefix) removed from it.
614 .Sp
615 In a void context, the input text just has the matched substring (and
616 any specified prefix) removed.
617 .RE
618 .ie n .IP """gen_extract_tagged""" 4
619 .el .IP \f(CWgen_extract_tagged\fR 4
620 .IX Item "gen_extract_tagged"
621 \&\f(CW\*(C`gen_extract_tagged\*(C'\fR generates a new anonymous subroutine which
622 extracts text between (balanced) specified tags. In other words,
623 it generates a function identical in function to \f(CW\*(C`extract_tagged\*(C'\fR.
624 .Sp
625 The difference between \f(CW\*(C`extract_tagged\*(C'\fR and the anonymous
626 subroutines generated by
627 \&\f(CW\*(C`gen_extract_tagged\*(C'\fR, is that those generated subroutines:
628 .RS 4
629 .IP \(bu 4
630 do not have to reparse tag specification or parsing options every time
631 they are called (whereas \f(CW\*(C`extract_tagged\*(C'\fR has to effectively rebuild
632 its tag parser on every call);
633 .IP \(bu 4
634 make use of the new qr// construct to pre\-compile the regexes they use
635 (whereas \f(CW\*(C`extract_tagged\*(C'\fR uses standard string variable interpolation
636 to create tag\-matching patterns).
637 .RE
638 .RS 4
639 .Sp
640 The subroutine takes up to four optional arguments (the same set as
641 \&\f(CW\*(C`extract_tagged\*(C'\fR except for the string to be processed). It returns
642 a reference to a subroutine which in turn takes a single argument (the text to
643 be extracted from).
644 .Sp
645 In other words, the implementation of \f(CW\*(C`extract_tagged\*(C'\fR is exactly
646 equivalent to:
647 .Sp
648 .Vb 6
649 \& sub extract_tagged
650 \& {
651 \& my $text = shift;
652 \& $extractor = gen_extract_tagged(@_);
653 \& return $extractor\->($text);
654 \& }
655 .Ve
656 .Sp
657 (although \f(CW\*(C`extract_tagged\*(C'\fR is not currently implemented that way).
658 .Sp
659 Using \f(CW\*(C`gen_extract_tagged\*(C'\fR to create extraction functions for specific tags
660 is a good idea if those functions are going to be called more than once, since
661 their performance is typically twice as good as the more general\-purpose
662 \&\f(CW\*(C`extract_tagged\*(C'\fR.
663 .RE
664 .ie n .IP """extract_quotelike""" 4
665 .el .IP \f(CWextract_quotelike\fR 4
666 .IX Item "extract_quotelike"
667 \&\f(CW\*(C`extract_quotelike\*(C'\fR attempts to recognize, extract, and segment any
668 one of the various Perl quotes and quotelike operators (see
669 \&\fBperlop\fR\|(3)) Nested backslashed delimiters, embedded balanced bracket
670 delimiters (for the quotelike operators), and trailing modifiers are
671 all caught. For example, in:
672 .Sp
673 .Vb 1
674 \& extract_quotelike \*(Aqq # an octothorpe: \e# (not the end of the q!) #\*(Aq
675 \&
676 \& extract_quotelike \*(Aq "You said, \e"Use sed\e"." \*(Aq
677 \&
678 \& extract_quotelike \*(Aq s{([A\-Z]{1,8}\e.[A\-Z]{3})} /\eL$1\eE/; \*(Aq
679 \&
680 \& extract_quotelike \*(Aq tr/\e\e\e/\e\e\e\e/\e\e\e//ds; \*(Aq
681 .Ve
682 .Sp
683 the full Perl quotelike operations are all extracted correctly.
684 .Sp
685 Note too that, when using the /x modifier on a regex, any comment
686 containing the current pattern delimiter will cause the regex to be
687 immediately terminated. In other words:
688 .Sp
689 .Vb 5
690 \& \*(Aqm /
691 \& (?i) # CASE INSENSITIVE
692 \& [a\-z_] # LEADING ALPHABETIC/UNDERSCORE
693 \& [a\-z0\-9]* # FOLLOWED BY ANY NUMBER OF ALPHANUMERICS
694 \& /x\*(Aq
695 .Ve
696 .Sp
697 will be extracted as if it were:
698 .Sp
699 .Vb 3
700 \& \*(Aqm /
701 \& (?i) # CASE INSENSITIVE
702 \& [a\-z_] # LEADING ALPHABETIC/\*(Aq
703 .Ve
704 .Sp
705 This behaviour is identical to that of the actual compiler.
706 .Sp
707 \&\f(CW\*(C`extract_quotelike\*(C'\fR takes two arguments: the text to be processed and
708 a prefix to be matched at the very beginning of the text. If no prefix
709 is specified, optional whitespace is the default. If no text is given,
710 \&\f(CW$_\fR is used.
711 .Sp
712 In a list context, an array of 11 elements is returned. The elements are:
713 .RS 4
714 .IP [0] 4
715 .IX Item "[0]"
716 the extracted quotelike substring (including trailing modifiers),
717 .IP [1] 4
718 .IX Item "[1]"
719 the remainder of the input text,
720 .IP [2] 4
721 .IX Item "[2]"
722 the prefix substring (if any),
723 .IP [3] 4
724 .IX Item "[3]"
725 the name of the quotelike operator (if any),
726 .IP [4] 4
727 .IX Item "[4]"
728 the left delimiter of the first block of the operation,
729 .IP [5] 4
730 .IX Item "[5]"
731 the text of the first block of the operation
732 (that is, the contents of
733 a quote, the regex of a match or substitution or the target list of a
734 translation),
735 .IP [6] 4
736 .IX Item "[6]"
737 the right delimiter of the first block of the operation,
738 .IP [7] 4
739 .IX Item "[7]"
740 the left delimiter of the second block of the operation
741 (that is, if it is a \f(CW\*(C`s\*(C'\fR, \f(CW\*(C`tr\*(C'\fR, or \f(CW\*(C`y\*(C'\fR),
742 .IP [8] 4
743 .IX Item "[8]"
744 the text of the second block of the operation
745 (that is, the replacement of a substitution or the translation list
746 of a translation),
747 .IP [9] 4
748 .IX Item "[9]"
749 the right delimiter of the second block of the operation (if any),
750 .IP [10] 4
751 .IX Item "[10]"
752 the trailing modifiers on the operation (if any).
753 .RE
754 .RS 4
755 .Sp
756 For each of the fields marked "(if any)" the default value on success is
757 an empty string.
758 On failure, all of these values (except the remaining text) are \f(CW\*(C`undef\*(C'\fR.
759 .Sp
760 In a scalar context, \f(CW\*(C`extract_quotelike\*(C'\fR returns just the complete substring
761 that matched a quotelike operation (or \f(CW\*(C`undef\*(C'\fR on failure). In a scalar or
762 void context, the input text has the same substring (and any specified
763 prefix) removed.
764 .Sp
765 Examples:
766 .Sp
767 .Vb 1
768 \& # Remove the first quotelike literal that appears in text
769 \&
770 \& $quotelike = extract_quotelike($text,\*(Aq.*?\*(Aq);
771 \&
772 \& # Replace one or more leading whitespace\-separated quotelike
773 \& # literals in $_ with "<QLL>"
774 \&
775 \& do { $_ = join \*(Aq<QLL>\*(Aq, (extract_quotelike)[2,1] } until $@;
776 \&
777 \&
778 \& # Isolate the search pattern in a quotelike operation from $text
779 \&
780 \& ($op,$pat) = (extract_quotelike $text)[3,5];
781 \& if ($op =~ /[ms]/)
782 \& {
783 \& print "search pattern: $pat\en";
784 \& }
785 \& else
786 \& {
787 \& print "$op is not a pattern matching operation\en";
788 \& }
789 .Ve
790 .RE
791 .ie n .IP """extract_quotelike""" 4
792 .el .IP \f(CWextract_quotelike\fR 4
793 .IX Item "extract_quotelike"
794 \&\f(CW\*(C`extract_quotelike\*(C'\fR can successfully extract "here documents" from an input
795 string, but with an important caveat in list contexts.
796 .Sp
797 Unlike other types of quote\-like literals, a here document is rarely
798 a contiguous substring. For example, a typical piece of code using
799 here document might look like this:
800 .Sp
801 .Vb 4
802 \& <<\*(AqEOMSG\*(Aq || die;
803 \& This is the message.
804 \& EOMSG
805 \& exit;
806 .Ve
807 .Sp
808 Given this as an input string in a scalar context, \f(CW\*(C`extract_quotelike\*(C'\fR
809 would correctly return the string "<<\*(AqEOMSG\*(Aq\enThis is the message.\enEOMSG",
810 leaving the string " || die;\enexit;" in the original variable. In other words,
811 the two separate pieces of the here document are successfully extracted and
812 concatenated.
813 .Sp
814 In a list context, \f(CW\*(C`extract_quotelike\*(C'\fR would return the list
815 .RS 4
816 .IP [0] 4
817 .IX Item "[0]"
818 "<<\*(AqEOMSG\*(Aq\enThis is the message.\enEOMSG\en" (i.e. the full extracted here document,
819 including fore and aft delimiters),
820 .IP [1] 4
821 .IX Item "[1]"
822 " || die;\enexit;" (i.e. the remainder of the input text, concatenated),
823 .IP [2] 4
824 .IX Item "[2]"
825 "" (i.e. the prefix substring \-\- trivial in this case),
826 .IP [3] 4
827 .IX Item "[3]"
828 "<<" (i.e. the "name" of the quotelike operator)
829 .IP [4] 4
830 .IX Item "[4]"
831 "\*(AqEOMSG\*(Aq" (i.e. the left delimiter of the here document, including any quotes),
832 .IP [5] 4
833 .IX Item "[5]"
834 "This is the message.\en" (i.e. the text of the here document),
835 .IP [6] 4
836 .IX Item "[6]"
837 "EOMSG" (i.e. the right delimiter of the here document),
838 .IP [7..10] 4
839 .IX Item "[7..10]"
840 "" (a here document has no second left delimiter, second text, second right
841 delimiter, or trailing modifiers).
842 .RE
843 .RS 4
844 .Sp
845 However, the matching position of the input variable would be set to
846 "exit;" (i.e. \fIafter\fR the closing delimiter of the here document),
847 which would cause the earlier " || die;\enexit;" to be skipped in any
848 sequence of code fragment extractions.
849 .Sp
850 To avoid this problem, when it encounters a here document whilst
851 extracting from a modifiable string, \f(CW\*(C`extract_quotelike\*(C'\fR silently
852 rearranges the string to an equivalent piece of Perl:
853 .Sp
854 .Vb 5
855 \& <<\*(AqEOMSG\*(Aq
856 \& This is the message.
857 \& EOMSG
858 \& || die;
859 \& exit;
860 .Ve
861 .Sp
862 in which the here document \fIis\fR contiguous. It still leaves the
863 matching position after the here document, but now the rest of the line
864 on which the here document starts is not skipped.
865 .Sp
866 To prevent <extract_quotelike> from mucking about with the input in this way
867 (this is the only case where a list\-context \f(CW\*(C`extract_quotelike\*(C'\fR does so),
868 you can pass the input variable as an interpolated literal:
869 .Sp
870 .Vb 1
871 \& $quotelike = extract_quotelike("$var");
872 .Ve
873 .RE
874 .ie n .IP """extract_codeblock""" 4
875 .el .IP \f(CWextract_codeblock\fR 4
876 .IX Item "extract_codeblock"
877 \&\f(CW\*(C`extract_codeblock\*(C'\fR attempts to recognize and extract a balanced
878 bracket delimited substring that may contain unbalanced brackets
879 inside Perl quotes or quotelike operations. That is, \f(CW\*(C`extract_codeblock\*(C'\fR
880 is like a combination of \f(CW"extract_bracketed"\fR and
881 \&\f(CW"extract_quotelike"\fR.
882 .Sp
883 \&\f(CW\*(C`extract_codeblock\*(C'\fR takes the same initial three parameters as \f(CW\*(C`extract_bracketed\*(C'\fR:
884 a text to process, a set of delimiter brackets to look for, and a prefix to
885 match first. It also takes an optional fourth parameter, which allows the
886 outermost delimiter brackets to be specified separately (see below),
887 and a fifth parameter used only by Parse::RecDescent.
888 .Sp
889 Omitting the first argument (input text) means process \f(CW$_\fR instead.
890 Omitting the second argument (delimiter brackets) indicates that only \f(CW\*(Aq{\*(Aq\fR is to be used.
891 Omitting the third argument (prefix argument) implies optional whitespace at the start.
892 Omitting the fourth argument (outermost delimiter brackets) indicates that the
893 value of the second argument is to be used for the outermost delimiters.
894 .Sp
895 Once the prefix and the outermost opening delimiter bracket have been
896 recognized, code blocks are extracted by stepping through the input text and
897 trying the following alternatives in sequence:
898 .RS 4
899 .IP 1. 4
900 Try and match a closing delimiter bracket. If the bracket was the same
901 species as the last opening bracket, return the substring to that
902 point. If the bracket was mismatched, return an error.
903 .IP 2. 4
904 Try to match a quote or quotelike operator. If found, call
905 \&\f(CW\*(C`extract_quotelike\*(C'\fR to eat it. If \f(CW\*(C`extract_quotelike\*(C'\fR fails, return
906 the error it returned. Otherwise go back to step 1.
907 .IP 3. 4
908 Try to match an opening delimiter bracket. If found, call
909 \&\f(CW\*(C`extract_codeblock\*(C'\fR recursively to eat the embedded block. If the
910 recursive call fails, return an error. Otherwise, go back to step 1.
911 .IP 4. 4
912 Unconditionally match a bareword or any other single character, and
913 then go back to step 1.
914 .RE
915 .RS 4
916 .Sp
917 Examples:
918 .Sp
919 .Vb 1
920 \& # Find a while loop in the text
921 \&
922 \& if ($text =~ s/.*?while\es*\e{/{/)
923 \& {
924 \& $loop = "while " . extract_codeblock($text);
925 \& }
926 \&
927 \& # Remove the first round\-bracketed list (which may include
928 \& # round\- or curly\-bracketed code blocks or quotelike operators)
929 \&
930 \& extract_codeblock $text, "(){}", \*(Aq[^(]*\*(Aq;
931 .Ve
932 .Sp
933 The ability to specify a different outermost delimiter bracket is useful
934 in some circumstances. For example, in the Parse::RecDescent module,
935 parser actions which are to be performed only on a successful parse
936 are specified using a \f(CW\*(C`<defer:...>\*(C'\fR directive. For example:
937 .Sp
938 .Vb 2
939 \& sentence: subject verb object
940 \& <defer: {$::theVerb = $item{verb}} >
941 .Ve
942 .Sp
943 Parse::RecDescent uses \f(CW\*(C`extract_codeblock($text, \*(Aq{}<>\*(Aq)\*(C'\fR to extract the code
944 within the \f(CW\*(C`<defer:...>\*(C'\fR directive, but there\*(Aqs a problem.
945 .Sp
946 A deferred action like this:
947 .Sp
948 .Vb 1
949 \& <defer: {if ($count>10) {$count\-\-}} >
950 .Ve
951 .Sp
952 will be incorrectly parsed as:
953 .Sp
954 .Vb 1
955 \& <defer: {if ($count>
956 .Ve
957 .Sp
958 because the "less than" operator is interpreted as a closing delimiter.
959 .Sp
960 But, by extracting the directive using
961 \&\f(CW\*(C`extract_codeblock($text,\ \*(Aq{}\*(Aq,\ undef,\ \*(Aq<>\*(Aq)\*(C'\fR
962 the \*(Aq>\*(Aq character is only treated as a delimited at the outermost
963 level of the code block, so the directive is parsed correctly.
964 .RE
965 .ie n .IP """extract_multiple""" 4
966 .el .IP \f(CWextract_multiple\fR 4
967 .IX Item "extract_multiple"
968 The \f(CW\*(C`extract_multiple\*(C'\fR subroutine takes a string to be processed and a
969 list of extractors (subroutines or regular expressions) to apply to that string.
970 .Sp
971 In an array context \f(CW\*(C`extract_multiple\*(C'\fR returns an array of substrings
972 of the original string, as extracted by the specified extractors.
973 In a scalar context, \f(CW\*(C`extract_multiple\*(C'\fR returns the first
974 substring successfully extracted from the original string. In both
975 scalar and void contexts the original string has the first successfully
976 extracted substring removed from it. In all contexts
977 \&\f(CW\*(C`extract_multiple\*(C'\fR starts at the current \f(CW\*(C`pos\*(C'\fR of the string, and
978 sets that \f(CW\*(C`pos\*(C'\fR appropriately after it matches.
979 .Sp
980 Hence, the aim of a call to \f(CW\*(C`extract_multiple\*(C'\fR in a list context
981 is to split the processed string into as many non\-overlapping fields as
982 possible, by repeatedly applying each of the specified extractors
983 to the remainder of the string. Thus \f(CW\*(C`extract_multiple\*(C'\fR is
984 a generalized form of Perl\*(Aqs \f(CW\*(C`split\*(C'\fR subroutine.
985 .Sp
986 The subroutine takes up to four optional arguments:
987 .RS 4
988 .IP 1. 4
989 A string to be processed (\f(CW$_\fR if the string is omitted or \f(CW\*(C`undef\*(C'\fR)
990 .IP 2. 4
991 A reference to a list of subroutine references and/or qr// objects and/or
992 literal strings and/or hash references, specifying the extractors
993 to be used to split the string. If this argument is omitted (or
994 \&\f(CW\*(C`undef\*(C'\fR) the list:
995 .Sp
996 .Vb 5
997 \& [
998 \& sub { extract_variable($_[0], \*(Aq\*(Aq) },
999 \& sub { extract_quotelike($_[0],\*(Aq\*(Aq) },
1000 \& sub { extract_codeblock($_[0],\*(Aq{}\*(Aq,\*(Aq\*(Aq) },
1001 \& ]
1002 .Ve
1003 .Sp
1004 is used.
1005 .IP 3. 4
1006 An number specifying the maximum number of fields to return. If this
1007 argument is omitted (or \f(CW\*(C`undef\*(C'\fR), split continues as long as possible.
1008 .Sp
1009 If the third argument is \fIN\fR, then extraction continues until \fIN\fR fields
1010 have been successfully extracted, or until the string has been completely
1011 processed.
1012 .Sp
1013 Note that in scalar and void contexts the value of this argument is
1014 automatically reset to 1 (under \f(CW\*(C`\-w\*(C'\fR, a warning is issued if the argument
1015 has to be reset).
1016 .IP 4. 4
1017 A value indicating whether unmatched substrings (see below) within the
1018 text should be skipped or returned as fields. If the value is true,
1019 such substrings are skipped. Otherwise, they are returned.
1020 .RE
1021 .RS 4
1022 .Sp
1023 The extraction process works by applying each extractor in
1024 sequence to the text string.
1025 .Sp
1026 If the extractor is a subroutine it is called in a list context and is
1027 expected to return a list of a single element, namely the extracted
1028 text. It may optionally also return two further arguments: a string
1029 representing the text left after extraction (like $\*(Aq for a pattern
1030 match), and a string representing any prefix skipped before the
1031 extraction (like $\` in a pattern match). Note that this is designed
1032 to facilitate the use of other Text::Balanced subroutines with
1033 \&\f(CW\*(C`extract_multiple\*(C'\fR. Note too that the value returned by an extractor
1034 subroutine need not bear any relationship to the corresponding substring
1035 of the original text (see examples below).
1036 .Sp
1037 If the extractor is a precompiled regular expression or a string,
1038 it is matched against the text in a scalar context with a leading
1039 \&\*(Aq\eG\*(Aq and the gc modifiers enabled. The extracted value is either
1040 \&\f(CW$1\fR if that variable is defined after the match, or else the
1041 complete match (i.e. $&).
1042 .Sp
1043 If the extractor is a hash reference, it must contain exactly one element.
1044 The value of that element is one of the
1045 above extractor types (subroutine reference, regular expression, or string).
1046 The key of that element is the name of a class into which the successful
1047 return value of the extractor will be blessed.
1048 .Sp
1049 If an extractor returns a defined value, that value is immediately
1050 treated as the next extracted field and pushed onto the list of fields.
1051 If the extractor was specified in a hash reference, the field is also
1052 blessed into the appropriate class,
1053 .Sp
1054 If the extractor fails to match (in the case of a regex extractor), or returns an empty list or an undefined value (in the case of a subroutine extractor), it is
1055 assumed to have failed to extract.
1056 If none of the extractor subroutines succeeds, then one
1057 character is extracted from the start of the text and the extraction
1058 subroutines reapplied. Characters which are thus removed are accumulated and
1059 eventually become the next field (unless the fourth argument is true, in which
1060 case they are discarded).
1061 .Sp
1062 For example, the following extracts substrings that are valid Perl variables:
1063 .Sp
1064 .Vb 3
1065 \& @fields = extract_multiple($text,
1066 \& [ sub { extract_variable($_[0]) } ],
1067 \& undef, 1);
1068 .Ve
1069 .Sp
1070 This example separates a text into fields which are quote delimited,
1071 curly bracketed, and anything else. The delimited and bracketed
1072 parts are also blessed to identify them (the "anything else" is unblessed):
1073 .Sp
1074 .Vb 5
1075 \& @fields = extract_multiple($text,
1076 \& [
1077 \& { Delim => sub { extract_delimited($_[0],q{\*(Aq"}) } },
1078 \& { Brack => sub { extract_bracketed($_[0],\*(Aq{}\*(Aq) } },
1079 \& ]);
1080 .Ve
1081 .Sp
1082 This call extracts the next single substring that is a valid Perl quotelike
1083 operator (and removes it from \f(CW$text\fR):
1084 .Sp
1085 .Vb 4
1086 \& $quotelike = extract_multiple($text,
1087 \& [
1088 \& sub { extract_quotelike($_[0]) },
1089 \& ], undef, 1);
1090 .Ve
1091 .Sp
1092 Finally, here is yet another way to do comma\-separated value parsing:
1093 .Sp
1094 .Vb 8
1095 \& $csv_text = "a,\*(Aqx b\*(Aq,c";
1096 \& @fields = extract_multiple($csv_text,
1097 \& [
1098 \& sub { extract_delimited($_[0],q{\*(Aq"}) },
1099 \& qr/([^,]+)/,
1100 \& ],
1101 \& undef,1);
1102 \& # @fields is now (\*(Aqa\*(Aq, "\*(Aqx b\*(Aq", \*(Aqc\*(Aq)
1103 .Ve
1104 .Sp
1105 The list in the second argument means:
1106 \&\fI"Try and extract a \*(Aq or " delimited string, otherwise extract anything up to a comma..."\fR.
1107 The undef third argument means:
1108 \&\fI"...as many times as possible..."\fR,
1109 and the true value in the fourth argument means
1110 \&\fI"...discarding anything else that appears (i.e. the commas)"\fR.
1111 .Sp
1112 If you wanted the commas preserved as separate fields (i.e. like split
1113 does if your split pattern has capturing parentheses), you would
1114 just make the last parameter undefined (or remove it).
1115 .RE
1116 .ie n .IP """gen_delimited_pat""" 4
1117 .el .IP \f(CWgen_delimited_pat\fR 4
1118 .IX Item "gen_delimited_pat"
1119 The \f(CW\*(C`gen_delimited_pat\*(C'\fR subroutine takes a single (string) argument and
1120 builds a Friedl\-style optimized regex that matches a string delimited
1121 by any one of the characters in the single argument. For example:
1122 .Sp
1123 .Vb 1
1124 \& gen_delimited_pat(q{\*(Aq"})
1125 .Ve
1126 .Sp
1127 returns the regex:
1128 .Sp
1129 .Vb 1
1130 \& (?:\e"(?:\e\e\e"|(?!\e").)*\e"|\e\*(Aq(?:\e\e\e\*(Aq|(?!\e\*(Aq).)*\e\*(Aq)
1131 .Ve
1132 .Sp
1133 Note that the specified delimiters are automatically quotemeta\*(Aqd.
1134 .Sp
1135 A typical use of \f(CW\*(C`gen_delimited_pat\*(C'\fR would be to build special purpose tags
1136 for \f(CW\*(C`extract_tagged\*(C'\fR. For example, to properly ignore "empty" XML elements
1137 (which might contain quoted strings):
1138 .Sp
1139 .Vb 1
1140 \& my $empty_tag = \*(Aq<(\*(Aq . gen_delimited_pat(q{\*(Aq"}) . \*(Aq|.)+/>\*(Aq;
1141 \&
1142 \& extract_tagged($text, undef, undef, undef, {ignore => [$empty_tag]} );
1143 .Ve
1144 .Sp
1145 \&\f(CW\*(C`gen_delimited_pat\*(C'\fR may also be called with an optional second argument,
1146 which specifies the "escape" character(s) to be used for each delimiter.
1147 For example to match a Pascal\-style string (where \*(Aq is the delimiter
1148 and \*(Aq\*(Aq is a literal \*(Aq within the string):
1149 .Sp
1150 .Vb 1
1151 \& gen_delimited_pat(q{\*(Aq},q{\*(Aq});
1152 .Ve
1153 .Sp
1154 Different escape characters can be specified for different delimiters.
1155 For example, to specify that \*(Aq/\*(Aq is the escape for single quotes
1156 and \*(Aq%\*(Aq is the escape for double quotes:
1157 .Sp
1158 .Vb 1
1159 \& gen_delimited_pat(q{\*(Aq"},q{/%});
1160 .Ve
1161 .Sp
1162 If more delimiters than escape chars are specified, the last escape char
1163 is used for the remaining delimiters.
1164 If no escape char is specified for a given specified delimiter, \*(Aq\e\*(Aq is used.
1165 .ie n .IP """delimited_pat""" 4
1166 .el .IP \f(CWdelimited_pat\fR 4
1167 .IX Item "delimited_pat"
1168 Note that \f(CW\*(C`gen_delimited_pat\*(C'\fR was previously called \f(CW\*(C`delimited_pat\*(C'\fR.
1169 That name may still be used, but is now deprecated.
1170 .SH DIAGNOSTICS
1171 .IX Header "DIAGNOSTICS"
1172 In a list context, all the functions return \f(CW\*(C`(undef,$original_text)\*(C'\fR
1173 on failure. In a scalar context, failure is indicated by returning \f(CW\*(C`undef\*(C'\fR
1174 (in this case the input text is not modified in any way).
1175 .PP
1176 In addition, on failure in \fIany\fR context, the \f(CW$@\fR variable is set.
1177 Accessing \f(CW\*(C`$@\->{error}\*(C'\fR returns one of the error diagnostics listed
1178 below.
1179 Accessing \f(CW\*(C`$@\->{pos}\*(C'\fR returns the offset into the original string at
1180 which the error was detected (although not necessarily where it occurred!)
1181 Printing \f(CW$@\fR directly produces the error message, with the offset appended.
1182 On success, the \f(CW$@\fR variable is guaranteed to be \f(CW\*(C`undef\*(C'\fR.
1183 .PP
1184 The available diagnostics are:
1185 .ie n .IP """Did not find a suitable bracket: ""%s""""" 4
1186 .el .IP "\f(CWDid not find a suitable bracket: ""%s""\fR" 4
1187 .IX Item "Did not find a suitable bracket: ""%s"""
1188 The delimiter provided to \f(CW\*(C`extract_bracketed\*(C'\fR was not one of
1189 \&\f(CW\*(Aq()[]<>{}\*(Aq\fR.
1190 .ie n .IP """Did not find prefix: /%s/""" 4
1191 .el .IP "\f(CWDid not find prefix: /%s/\fR" 4
1192 .IX Item "Did not find prefix: /%s/"
1193 A non\-optional prefix was specified but wasn\*(Aqt found at the start of the text.
1194 .ie n .IP """Did not find opening bracket after prefix: ""%s""""" 4
1195 .el .IP "\f(CWDid not find opening bracket after prefix: ""%s""\fR" 4
1196 .IX Item "Did not find opening bracket after prefix: ""%s"""
1197 \&\f(CW\*(C`extract_bracketed\*(C'\fR or \f(CW\*(C`extract_codeblock\*(C'\fR was expecting a
1198 particular kind of bracket at the start of the text, and didn\*(Aqt find it.
1199 .ie n .IP """No quotelike operator found after prefix: ""%s""""" 4
1200 .el .IP "\f(CWNo quotelike operator found after prefix: ""%s""\fR" 4
1201 .IX Item "No quotelike operator found after prefix: ""%s"""
1202 \&\f(CW\*(C`extract_quotelike\*(C'\fR didn\*(Aqt find one of the quotelike operators \f(CW\*(C`q\*(C'\fR,
1203 \&\f(CW\*(C`qq\*(C'\fR, \f(CW\*(C`qw\*(C'\fR, \f(CW\*(C`qx\*(C'\fR, \f(CW\*(C`s\*(C'\fR, \f(CW\*(C`tr\*(C'\fR or \f(CW\*(C`y\*(C'\fR at the start of the substring
1204 it was extracting.
1205 .ie n .IP """Unmatched closing bracket: ""%c""""" 4
1206 .el .IP "\f(CWUnmatched closing bracket: ""%c""\fR" 4
1207 .IX Item "Unmatched closing bracket: ""%c"""
1208 \&\f(CW\*(C`extract_bracketed\*(C'\fR, \f(CW\*(C`extract_quotelike\*(C'\fR or \f(CW\*(C`extract_codeblock\*(C'\fR encountered
1209 a closing bracket where none was expected.
1210 .ie n .IP """Unmatched opening bracket(s): ""%s""""" 4
1211 .el .IP "\f(CWUnmatched opening bracket(s): ""%s""\fR" 4
1212 .IX Item "Unmatched opening bracket(s): ""%s"""
1213 \&\f(CW\*(C`extract_bracketed\*(C'\fR, \f(CW\*(C`extract_quotelike\*(C'\fR or \f(CW\*(C`extract_codeblock\*(C'\fR ran
1214 out of characters in the text before closing one or more levels of nested
1215 brackets.
1216 .ie n .IP """Unmatched embedded quote (%s)""" 4
1217 .el .IP "\f(CWUnmatched embedded quote (%s)\fR" 4
1218 .IX Item "Unmatched embedded quote (%s)"
1219 \&\f(CW\*(C`extract_bracketed\*(C'\fR attempted to match an embedded quoted substring, but
1220 failed to find a closing quote to match it.
1221 .ie n .IP """Did not find closing delimiter to match \*(Aq%s\*(Aq""" 4
1222 .el .IP "\f(CWDid not find closing delimiter to match \*(Aq%s\*(Aq\fR" 4
1223 .IX Item "Did not find closing delimiter to match '%s'"
1224 \&\f(CW\*(C`extract_quotelike\*(C'\fR was unable to find a closing delimiter to match the
1225 one that opened the quote\-like operation.
1226 .ie n .IP """Mismatched closing bracket: expected ""%c"" but found ""%s""""" 4
1227 .el .IP "\f(CWMismatched closing bracket: expected ""%c"" but found ""%s""\fR" 4
1228 .IX Item "Mismatched closing bracket: expected ""%c"" but found ""%s"""
1229 \&\f(CW\*(C`extract_bracketed\*(C'\fR, \f(CW\*(C`extract_quotelike\*(C'\fR or \f(CW\*(C`extract_codeblock\*(C'\fR found
1230 a valid bracket delimiter, but it was the wrong species. This usually
1231 indicates a nesting error, but may indicate incorrect quoting or escaping.
1232 .ie n .IP """No block delimiter found after quotelike ""%s""""" 4
1233 .el .IP "\f(CWNo block delimiter found after quotelike ""%s""\fR" 4
1234 .IX Item "No block delimiter found after quotelike ""%s"""
1235 \&\f(CW\*(C`extract_quotelike\*(C'\fR or \f(CW\*(C`extract_codeblock\*(C'\fR found one of the
1236 quotelike operators \f(CW\*(C`q\*(C'\fR, \f(CW\*(C`qq\*(C'\fR, \f(CW\*(C`qw\*(C'\fR, \f(CW\*(C`qx\*(C'\fR, \f(CW\*(C`s\*(C'\fR, \f(CW\*(C`tr\*(C'\fR or \f(CW\*(C`y\*(C'\fR
1237 without a suitable block after it.
1238 .ie n .IP """Did not find leading dereferencer""" 4
1239 .el .IP "\f(CWDid not find leading dereferencer\fR" 4
1240 .IX Item "Did not find leading dereferencer"
1241 \&\f(CW\*(C`extract_variable\*(C'\fR was expecting one of \*(Aq$\*(Aq, \*(Aq@\*(Aq, or \*(Aq%\*(Aq at the start of
1242 a variable, but didn\*(Aqt find any of them.
1243 .ie n .IP """Bad identifier after dereferencer""" 4
1244 .el .IP "\f(CWBad identifier after dereferencer\fR" 4
1245 .IX Item "Bad identifier after dereferencer"
1246 \&\f(CW\*(C`extract_variable\*(C'\fR found a \*(Aq$\*(Aq, \*(Aq@\*(Aq, or \*(Aq%\*(Aq indicating a variable, but that
1247 character was not followed by a legal Perl identifier.
1248 .ie n .IP """Did not find expected opening bracket at %s""" 4
1249 .el .IP "\f(CWDid not find expected opening bracket at %s\fR" 4
1250 .IX Item "Did not find expected opening bracket at %s"
1251 \&\f(CW\*(C`extract_codeblock\*(C'\fR failed to find any of the outermost opening brackets
1252 that were specified.
1253 .ie n .IP """Improperly nested codeblock at %s""" 4
1254 .el .IP "\f(CWImproperly nested codeblock at %s\fR" 4
1255 .IX Item "Improperly nested codeblock at %s"
1256 A nested code block was found that started with a delimiter that was specified
1257 as being only to be used as an outermost bracket.
1258 .ie n .IP """Missing second block for quotelike ""%s""""" 4
1259 .el .IP "\f(CWMissing second block for quotelike ""%s""\fR" 4
1260 .IX Item "Missing second block for quotelike ""%s"""
1261 \&\f(CW\*(C`extract_codeblock\*(C'\fR or \f(CW\*(C`extract_quotelike\*(C'\fR found one of the
1262 quotelike operators \f(CW\*(C`s\*(C'\fR, \f(CW\*(C`tr\*(C'\fR or \f(CW\*(C`y\*(C'\fR followed by only one block.
1263 .ie n .IP """No match found for opening bracket""" 4
1264 .el .IP "\f(CWNo match found for opening bracket\fR" 4
1265 .IX Item "No match found for opening bracket"
1266 \&\f(CW\*(C`extract_codeblock\*(C'\fR failed to find a closing bracket to match the outermost
1267 opening bracket.
1268 .ie n .IP """Did not find opening tag: /%s/""" 4
1269 .el .IP "\f(CWDid not find opening tag: /%s/\fR" 4
1270 .IX Item "Did not find opening tag: /%s/"
1271 \&\f(CW\*(C`extract_tagged\*(C'\fR did not find a suitable opening tag (after any specified
1272 prefix was removed).
1273 .ie n .IP """Unable to construct closing tag to match: /%s/""" 4
1274 .el .IP "\f(CWUnable to construct closing tag to match: /%s/\fR" 4
1275 .IX Item "Unable to construct closing tag to match: /%s/"
1276 \&\f(CW\*(C`extract_tagged\*(C'\fR matched the specified opening tag and tried to
1277 modify the matched text to produce a matching closing tag (because
1278 none was specified). It failed to generate the closing tag, almost
1279 certainly because the opening tag did not start with a
1280 bracket of some kind.
1281 .ie n .IP """Found invalid nested tag: %s""" 4
1282 .el .IP "\f(CWFound invalid nested tag: %s\fR" 4
1283 .IX Item "Found invalid nested tag: %s"
1284 \&\f(CW\*(C`extract_tagged\*(C'\fR found a nested tag that appeared in the "reject" list
1285 (and the failure mode was not "MAX" or "PARA").
1286 .ie n .IP """Found unbalanced nested tag: %s""" 4
1287 .el .IP "\f(CWFound unbalanced nested tag: %s\fR" 4
1288 .IX Item "Found unbalanced nested tag: %s"
1289 \&\f(CW\*(C`extract_tagged\*(C'\fR found a nested opening tag that was not matched by a
1290 corresponding nested closing tag (and the failure mode was not "MAX" or "PARA").
1291 .ie n .IP """Did not find closing tag""" 4
1292 .el .IP "\f(CWDid not find closing tag\fR" 4
1293 .IX Item "Did not find closing tag"
1294 \&\f(CW\*(C`extract_tagged\*(C'\fR reached the end of the text without finding a closing tag
1295 to match the original opening tag (and the failure mode was not
1296 "MAX" or "PARA").
1297 .SH EXPORTS
1298 .IX Header "EXPORTS"
1299 The following symbols are, or can be, exported by this module:
1300 .IP "Default Exports" 4
1301 .IX Item "Default Exports"
1302 \&\fINone\fR.
1303 .IP "Optional Exports" 4
1304 .IX Item "Optional Exports"
1305 \&\f(CW\*(C`extract_delimited\*(C'\fR,
1306 \&\f(CW\*(C`extract_bracketed\*(C'\fR,
1307 \&\f(CW\*(C`extract_quotelike\*(C'\fR,
1308 \&\f(CW\*(C`extract_codeblock\*(C'\fR,
1309 \&\f(CW\*(C`extract_variable\*(C'\fR,
1310 \&\f(CW\*(C`extract_tagged\*(C'\fR,
1311 \&\f(CW\*(C`extract_multiple\*(C'\fR,
1312 \&\f(CW\*(C`gen_delimited_pat\*(C'\fR,
1313 \&\f(CW\*(C`gen_extract_tagged\*(C'\fR,
1314 \&\f(CW\*(C`delimited_pat\*(C'\fR.
1315 .IP "Export Tags" 4
1316 .IX Item "Export Tags"
1317 .RS 4
1318 .PD 0
1319 .ie n .IP """:ALL""" 4
1320 .el .IP \f(CW:ALL\fR 4
1321 .IX Item ":ALL"
1322 .PD
1323 \&\f(CW\*(C`extract_delimited\*(C'\fR,
1324 \&\f(CW\*(C`extract_bracketed\*(C'\fR,
1325 \&\f(CW\*(C`extract_quotelike\*(C'\fR,
1326 \&\f(CW\*(C`extract_codeblock\*(C'\fR,
1327 \&\f(CW\*(C`extract_variable\*(C'\fR,
1328 \&\f(CW\*(C`extract_tagged\*(C'\fR,
1329 \&\f(CW\*(C`extract_multiple\*(C'\fR,
1330 \&\f(CW\*(C`gen_delimited_pat\*(C'\fR,
1331 \&\f(CW\*(C`gen_extract_tagged\*(C'\fR,
1332 \&\f(CW\*(C`delimited_pat\*(C'\fR.
1333 .RE
1334 .RS 4
1335 .RE
1336 .SH "KNOWN BUGS"
1337 .IX Header "KNOWN BUGS"
1338 See <https://rt.cpan.org/Dist/Display.html?Status=Active&Queue=Text\-Balanced>.
1339 .SH FEEDBACK
1340 .IX Header "FEEDBACK"
1341 Patches, bug reports, suggestions or any other feedback is welcome.
1342 .PP
1343 Patches can be sent as GitHub pull requests at
1344 <https://github.com/steve\-m\-hay/Text\-Balanced/pulls>.
1345 .PP
1346 Bug reports and suggestions can be made on the CPAN Request Tracker at
1347 <https://rt.cpan.org/Public/Bug/Report.html?Queue=Text\-Balanced>.
1348 .PP
1349 Currently active requests on the CPAN Request Tracker can be viewed at
1350 <https://rt.cpan.org/Public/Dist/Display.html?Status=Active;Queue=Text\-Balanced>.
1351 .PP
1352 Please test this distribution. See CPAN Testers Reports at
1353 <https://www.cpantesters.org/> for details of how to get involved.
1354 .PP
1355 Previous test results on CPAN Testers Reports can be viewed at
1356 <https://www.cpantesters.org/distro/T/Text\-Balanced.html>.
1357 .PP
1358 Please rate this distribution on CPAN Ratings at
1359 <https://cpanratings.perl.org/rate/?distribution=Text\-Balanced>.
1360 .SH AVAILABILITY
1361 .IX Header "AVAILABILITY"
1362 The latest version of this module is available from CPAN (see
1363 "CPAN" in perlmodlib for details) at
1364 .PP
1365 <https://metacpan.org/release/Text\-Balanced> or
1366 .PP
1367 <https://www.cpan.org/authors/id/S/SH/SHAY/> or
1368 .PP
1369 <https://www.cpan.org/modules/by\-module/Text/>.
1370 .PP
1371 The latest source code is available from GitHub at
1372 <https://github.com/steve\-m\-hay/Text\-Balanced>.
1373 .SH INSTALLATION
1374 .IX Header "INSTALLATION"
1375 See the \fIINSTALL\fR file.
1376 .SH AUTHOR
1377 .IX Header "AUTHOR"
1378 Damian Conway <[email protected] <mailto:[email protected]>>.
1379 .PP
1380 Steve Hay <[email protected] <mailto:[email protected]>> is now maintaining
1381 Text::Balanced as of version 2.03.
1382 .SH COPYRIGHT
1383 .IX Header "COPYRIGHT"
1384 Copyright (C) 1997\-2001 Damian Conway. All rights reserved.
1385 .PP
1386 Copyright (C) 2009 Adam Kennedy.
1387 .PP
1388 Copyright (C) 2015, 2020, 2022 Steve Hay and other contributors. All rights
1389 reserved.
1390 .SH LICENCE
1391 .IX Header "LICENCE"
1392 This module is free software; you can redistribute it and/or modify it under the
1393 same terms as Perl itself, i.e. under the terms of either the GNU General Public
1394 License or the Artistic License, as specified in the \fILICENCE\fR file.
1395 .SH VERSION
1396 .IX Header "VERSION"
1397 Version 2.06
1398 .SH DATE
1399 .IX Header "DATE"
1400 05 Jun 2022
1401 .SH HISTORY
1402 .IX Header "HISTORY"
1403 See the \fIChanges\fR file.