Debian Codegraph @

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