README
1NAME
2
3 Text::Balanced - Extract delimited text sequences from strings.
4
5SYNOPSIS
6
7 use Text::Balanced qw (
8 extract_delimited
9 extract_bracketed
10 extract_quotelike
11 extract_codeblock
12 extract_variable
13 extract_tagged
14 extract_multiple
15 gen_delimited_pat
16 gen_extract_tagged
17 );
18
19 # Extract the initial substring of $text that is delimited by
20 # two (unescaped) instances of the first character in $delim.
21
22 ($extracted, $remainder) = extract_delimited($text,$delim);
23
24 # Extract the initial substring of $text that is bracketed
25 # with a delimiter(s) specified by $delim (where the string
26 # in $delim contains one or more of '(){}[]<>').
27
28 ($extracted, $remainder) = extract_bracketed($text,$delim);
29
30 # Extract the initial substring of $text that is bounded by
31 # an XML tag.
32
33 ($extracted, $remainder) = extract_tagged($text);
34
35 # Extract the initial substring of $text that is bounded by
36 # a C<BEGIN>...C<END> pair. Don't allow nested C<BEGIN> tags
37
38 ($extracted, $remainder) =
39 extract_tagged($text,"BEGIN","END",undef,{bad=>["BEGIN"]});
40
41 # Extract the initial substring of $text that represents a
42 # Perl "quote or quote-like operation"
43
44 ($extracted, $remainder) = extract_quotelike($text);
45
46 # Extract the initial substring of $text that represents a block
47 # of Perl code, bracketed by any of character(s) specified by $delim
48 # (where the string $delim contains one or more of '(){}[]<>').
49
50 ($extracted, $remainder) = extract_codeblock($text,$delim);
51
52 # Extract the initial substrings of $text that would be extracted by
53 # one or more sequential applications of the specified functions
54 # or regular expressions
55
56 @extracted = extract_multiple($text,
57 [ \&extract_bracketed,
58 \&extract_quotelike,
59 \&some_other_extractor_sub,
60 qr/[xyz]*/,
61 'literal',
62 ]);
63
64 # Create a string representing an optimized pattern (a la Friedl)
65 # that matches a substring delimited by any of the specified characters
66 # (in this case: any type of quote or a slash)
67
68 $patstring = gen_delimited_pat(q{'"`/});
69
70 # Generate a reference to an anonymous sub that is just like extract_tagged
71 # but pre-compiled and optimized for a specific pair of tags, and
72 # consequently much faster (i.e. 3 times faster). It uses qr// for better
73 # performance on repeated calls.
74
75 $extract_head = gen_extract_tagged('<HEAD>','</HEAD>');
76 ($extracted, $remainder) = $extract_head->($text);
77
78DESCRIPTION
79
80 The various extract_... subroutines may be used to extract a delimited
81 substring, possibly after skipping a specified prefix string. By default,
82 that prefix is optional whitespace (/\s*/), but you can change it to
83 whatever you wish (see below).
84
85 The substring to be extracted must appear at the current pos location of the
86 string's variable (or at index zero, if no pos position is defined). In
87 other words, the extract_... subroutines *don't* extract the first
88 occurrence of a substring anywhere in a string (like an unanchored regex
89 would). Rather, they extract an occurrence of the substring appearing
90 immediately at the current matching position in the string (like a
91 \G-anchored regex would).
92
93INSTALLATION
94
95 See the INSTALL file.
96
97COPYRIGHT
98
99 Copyright (C) 1997-2001 Damian Conway. All rights reserved.
100 Copyright (C) 2009 Adam Kennedy.
101 Copyright (C) 2015, 2020 Steve Hay. All rights reserved.
102
103LICENCE
104
105 This distribution is free software; you can redistribute it and/or modify it
106 under the same terms as Perl itself, i.e. under the terms of either the GNU
107 General Public License or the Artistic License, as specified in the LICENCE
108 file.
109