# perldoc > Text::Balanced --- type: CommandReference command: Text::Balanced mode: perldoc section: source: perldoc --- ## Quick Reference - `extract_delimited($text, $delim)` — extract initial substring delimited by characters - `extract_bracketed($text, $delim)` — extract balanced bracket-delimited substring - `extract_quotelike($text)` — extract Perl quote or quotelike operation - `extract_codeblock($text, $delim)` — extract balanced bracket-delimited substring with embedded quotes - `extract_variable($text)` — extract Perl variable or variablish expression - `extract_tagged($text, $start_tag, $end_tag)` — extract text between balanced tags - `extract_multiple($text, \@extractors)` — sequentially extract substrings using multiple extractors - `gen_delimited_pat($delim_chars)` — generate optimized regex for delimited strings ## Name Extract delimited text sequences from strings. ## Synopsis perl use Text::Balanced qw( extract_delimited extract_bracketed extract_quotelike extract_codeblock extract_variable extract_tagged extract_multiple gen_delimited_pat gen_extract_tagged ); ($extracted, $remainder) = extract_delimited($text, $delim); ($extracted, $remainder) = extract_bracketed($text, $delim); ($extracted, $remainder) = extract_tagged($text); ($extracted, $remainder) = extract_tagged($text, "BEGIN", "END", undef, {bad=>["BEGIN"]}); ($extracted, $remainder) = extract_quotelike($text); ($extracted, $remainder) = extract_codeblock($text, $delim); @extracted = extract_multiple($text, [ \&extract_bracketed, \&extract_quotelike, ... ]); $patstring = gen_delimited_pat(q{'"`/}); $extract_head = gen_extract_tagged('', ''); ($extracted, $remainder) = $extract_head->($text); ## Options ### extract_delimited - `- $text` — string to extract from (default $_) - `- $delim` — delimiter characters (default `'/"`'`) - `- $prefix` — pattern to skip before extraction (default `'\s*'`) - `- $escape` — escape characters for each delimiter (default `\` for all) - Returns list: `($extracted, $remainder, $prefix)` on success; `(undef, $original_text)` on failure. ### extract_bracketed - `- $text` — string to extract from (default $_) - `- $delim` — bracket characters to match (default `'{}()[]<>'`) - `- $prefix` — pattern to skip (default `'\s*'`) - Returns list: `($extracted, $remainder, $prefix)`. Handles embedded quotes if quote characters are included in delimiters. Also supports `'q'` to handle Perl quotelike quoting. ### extract_tagged - `- $text` — string to extract from (default $_) - `- $start_tag` — pattern for opening tag (default any XML tag) - `- $end_tag` — pattern for closing tag (default constructed from matched opening tag) - `- $prefix` — pattern to skip (default `'\s*'`) - `- \%options` — hashref with keys: `reject` (listref of patterns to reject), `ignore` (listref of patterns to ignore as nested tags), `fail` (action on missing end tag: `'MAX'` returns text up to failure, `'PARA'` returns first paragraph, `''` reverts to default failure) - Returns list: `($extracted, $remainder, $prefix, $opening_tag, $inner_text, $closing_tag)`. ### extract_quotelike - `- $text` — string to extract from (default $_) - `- $prefix` — pattern to skip (default `'\s*'`) - Returns list of 11 elements: `($extracted, $remainder, $prefix, $operator, $left_delim1, $text1, $right_delim1, $left_delim2, $text2, $right_delim2, $modifiers)`. Handles here documents with rearrangement. ### extract_codeblock - `- $text` — string to extract from (default $_) - `- $delim` — delimiter brackets (default `'{}'`) - `- $prefix` — pattern to skip (default `'\s*'`) - `- $outer_delim` — outermost delimiter brackets (default same as $delim) - Returns list: `($extracted, $remainder, $prefix)`. ### extract_variable - `- $text` — string to extract from (default $_) - `- $prefix` — pattern to skip (default `'\s*'`) - Returns list: `($extracted, $remainder, $prefix)`. ### extract_multiple - `- $text` — string to extract from (default $_) - `- \@extractors` — list of subroutines, regexes, strings, or hashrefs (blessing) - `- $max_fields` — maximum number of fields (default unlimited) - `- $skip_unmatched` — if true, discard unmatched substrings; otherwise return them as fields - Returns array of extracted fields in list context, first field in scalar context. ### gen_delimited_pat - `- $delim_chars` — string of delimiter characters - `- $escape_chars` — optional escape characters for each delimiter (default `\`) - Returns optimized regex pattern string. ### gen_extract_tagged - Arguments: same as `extract_tagged` except no text argument. - Returns reference to a subroutine that takes a single text argument and extracts tagged text. ## Examples perl # Remove a single-quoted substring from the very beginning of $text: $substring = extract_delimited($text, "'", ''); # Extract a single- or double-quoted substring, optionally after whitespace: ($substring) = extract_delimited $text, q{"'}; # Delete the substring delimited by the first '/' in $text: $text = join '', (extract_delimited($text,'/','[^/]*')[2,1]); # Extract an HTML link (no nested links): ($extracted, $remainder) = extract_tagged($text, '', '', undef, {reject => ['']}); # Extract a Perl quotelike operation: ($extracted, $remainder) = extract_quotelike('q # an octothorpe: \# (not the end of the q!) #'); # Remove the first quote-like literal from text: $quotelike = extract_quotelike($text, '.*?'); # Extract the search pattern from a quotelike: ($op, $pat) = (extract_quotelike $text)[3,5]; # Find a while loop in text: if ($text =~ s/.*?while\s*\{/{/) { $loop = "while " . extract_codeblock($text); } # Extract fields from CSV: @fields = extract_multiple($csv_text, [ sub { extract_delimited($_[0], q{'"}) }, qr/([^,]+)(.*)/ ], undef, 1); # Generate and use optimized tag extractor: $extract_head = gen_extract_tagged('', ''); ($extracted, $remainder) = $extract_head->($text); ## See Also - [perlop](https://metacpan.org/pod/perlop) — Perl operators and quote-like operators - [Parse::RecDescent](https://metacpan.org/pod/Parse::RecDescent) — uses `extract_codeblock` for parsing - [Text::Balanced on CPAN](https://metacpan.org/pod/Text::Balanced) ## Diagnostics On failure, `$@` is set to a hashref with keys `error` (diagnostic string) and `pos` (offset). Common errors: - "Did not find a suitable bracket: %s" - "Did not find prefix: /%s/" - "Did not find opening bracket after prefix: %s" - "No quotelike operator found after prefix: %s" - "Unmatched closing bracket: %c" - "Unmatched opening bracket(s): %s" - "Unmatched embedded quote (%s)" - "Did not find closing delimiter to match '%s'" - "Mismatched closing bracket: expected %c but found %s" - "No block delimiter found after quotelike %s" - "Did not find leading dereferencer" - "Bad identifier after dereferencer" - "Did not find expected opening bracket at %s" - "Improperly nested codeblock at %s" - "Missing second block for quotelike %s" - "No match found for opening bracket" - "Did not find opening tag: /%s/" - "Unable to construct closing tag to match: /%s/" - "Found invalid nested tag: %s" - "Found unbalanced nested tag: %s" - "Did not find closing tag"