Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 1400 insertions, 0 deletions

diff --git a/upstream/mageia-cauldron/man3pm/Text::Balanced.3pm b/upstream/mageia-cauldron/man3pm/Text::Balanced.3pm
new file mode 100644
index 00000000..fad168b2
--- /dev/null
+++ b/upstream/mageia-cauldron/man3pm/Text::Balanced.3pm
@@ -0,0 +1,1400 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "Text::Balanced 3pm"
+.TH Text::Balanced 3pm 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SH NAME
+Text::Balanced \- Extract delimited text sequences from strings.
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 11
+\&    use Text::Balanced qw (
+\&        extract_delimited
+\&        extract_bracketed
+\&        extract_quotelike
+\&        extract_codeblock
+\&        extract_variable
+\&        extract_tagged
+\&        extract_multiple
+\&        gen_delimited_pat
+\&        gen_extract_tagged
+\&    );
+\&
+\&    # Extract the initial substring of $text that is delimited by
+\&    # two (unescaped) instances of the first character in $delim.
+\&
+\&    ($extracted, $remainder) = extract_delimited($text,$delim);
+\&
+\&    # Extract the initial substring of $text that is bracketed
+\&    # with a delimiter(s) specified by $delim (where the string
+\&    # in $delim contains one or more of \*(Aq(){}[]<>\*(Aq).
+\&
+\&    ($extracted, $remainder) = extract_bracketed($text,$delim);
+\&
+\&    # Extract the initial substring of $text that is bounded by
+\&    # an XML tag.
+\&
+\&    ($extracted, $remainder) = extract_tagged($text);
+\&
+\&    # Extract the initial substring of $text that is bounded by
+\&    # a C<BEGIN>...C<END> pair. Don\*(Aqt allow nested C<BEGIN> tags
+\&
+\&    ($extracted, $remainder) =
+\&        extract_tagged($text,"BEGIN","END",undef,{bad=>["BEGIN"]});
+\&
+\&    # Extract the initial substring of $text that represents a
+\&    # Perl "quote or quote\-like operation"
+\&
+\&    ($extracted, $remainder) = extract_quotelike($text);
+\&
+\&    # Extract the initial substring of $text that represents a block
+\&    # of Perl code, bracketed by any of character(s) specified by $delim
+\&    # (where the string $delim contains one or more of \*(Aq(){}[]<>\*(Aq).
+\&
+\&    ($extracted, $remainder) = extract_codeblock($text,$delim);
+\&
+\&    # Extract the initial substrings of $text that would be extracted by
+\&    # one or more sequential applications of the specified functions
+\&    # or regular expressions
+\&
+\&    @extracted = extract_multiple($text,
+\&                                  [ \e&extract_bracketed,
+\&                                    \e&extract_quotelike,
+\&                                    \e&some_other_extractor_sub,
+\&                                    qr/[xyz]*/,
+\&                                    \*(Aqliteral\*(Aq,
+\&                                  ]);
+\&
+\&    # Create a string representing an optimized pattern (a la Friedl)
+\&    # that matches a substring delimited by any of the specified characters
+\&    # (in this case: any type of quote or a slash)
+\&
+\&    $patstring = gen_delimited_pat(q{\*(Aq"\`/});
+\&
+\&    # Generate a reference to an anonymous sub that is just like extract_tagged
+\&    # but pre\-compiled and optimized for a specific pair of tags, and
+\&    # consequently much faster (i.e. 3 times faster). It uses qr// for better
+\&    # performance on repeated calls.
+\&
+\&    $extract_head = gen_extract_tagged(\*(Aq<HEAD>\*(Aq,\*(Aq</HEAD>\*(Aq);
+\&    ($extracted, $remainder) = $extract_head\->($text);
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+The various \f(CW\*(C`extract_...\*(C'\fR subroutines may be used to
+extract a delimited substring, possibly after skipping a
+specified prefix string. By default, that prefix is
+optional whitespace (\f(CW\*(C`/\es*/\*(C'\fR), but you can change it to whatever
+you wish (see below).
+.PP
+The substring to be extracted must appear at the
+current \f(CW\*(C`pos\*(C'\fR location of the string's variable
+(or at index zero, if no \f(CW\*(C`pos\*(C'\fR position is defined).
+In other words, the \f(CW\*(C`extract_...\*(C'\fR subroutines \fIdon't\fR
+extract the first occurrence of a substring anywhere
+in a string (like an unanchored regex would). Rather,
+they extract an occurrence of the substring appearing
+immediately at the current matching position in the
+string (like a \f(CW\*(C`\eG\*(C'\fR\-anchored regex would).
+.SS "General Behaviour in List Contexts"
+.IX Subsection "General Behaviour in List Contexts"
+In a list context, all the subroutines return a list, the first three
+elements of which are always:
+.IP [0] 4
+.IX Item "[0]"
+The extracted string, including the specified delimiters.
+If the extraction fails \f(CW\*(C`undef\*(C'\fR is returned.
+.IP [1] 4
+.IX Item "[1]"
+The remainder of the input string (i.e. the characters after the
+extracted string). On failure, the entire string is returned.
+.IP [2] 4
+.IX Item "[2]"
+The skipped prefix (i.e. the characters before the extracted string).
+On failure, \f(CW\*(C`undef\*(C'\fR is returned.
+.PP
+Note that in a list context, the contents of the original input text (the first
+argument) are not modified in any way.
+.PP
+However, if the input text was passed in a variable, that variable's
+\&\f(CW\*(C`pos\*(C'\fR value is updated to point at the first character after the
+extracted text. That means that in a list context the various
+subroutines can be used much like regular expressions. For example:
+.PP
+.Vb 4
+\&    while ( $next = (extract_quotelike($text))[0] )
+\&    {
+\&        # process next quote\-like (in $next)
+\&    }
+.Ve
+.SS "General Behaviour in Scalar and Void Contexts"
+.IX Subsection "General Behaviour in Scalar and Void Contexts"
+In a scalar context, the extracted string is returned, having first been
+removed from the input text. Thus, the following code also processes
+each quote-like operation, but actually removes them from \f(CW$text:\fR
+.PP
+.Vb 4
+\&    while ( $next = extract_quotelike($text) )
+\&    {
+\&        # process next quote\-like (in $next)
+\&    }
+.Ve
+.PP
+Note that if the input text is a read-only string (i.e. a literal),
+no attempt is made to remove the extracted text.
+.PP
+In a void context the behaviour of the extraction subroutines is
+exactly the same as in a scalar context, except (of course) that the
+extracted substring is not returned.
+.SS "A Note About Prefixes"
+.IX Subsection "A Note About Prefixes"
+Prefix patterns are matched without any trailing modifiers (\f(CW\*(C`/gimsox\*(C'\fR etc.)
+This can bite you if you're expecting a prefix specification like
+\&'.*?(?=<H1>)' to skip everything up to the first <H1> tag. Such a prefix
+pattern will only succeed if the <H1> tag is on the current line, since
+\&. normally doesn't match newlines.
+.PP
+To overcome this limitation, you need to turn on /s matching within
+the prefix pattern, using the \f(CW\*(C`(?s)\*(C'\fR directive: '(?s).*?(?=<H1>)'
+.SS Functions
+.IX Subsection "Functions"
+.ie n .IP """extract_delimited""" 4
+.el .IP \f(CWextract_delimited\fR 4
+.IX Item "extract_delimited"
+The \f(CW\*(C`extract_delimited\*(C'\fR function formalizes the common idiom
+of extracting a single-character-delimited substring from the start of
+a string. For example, to extract a single-quote delimited string, the
+following code is typically used:
+.Sp
+.Vb 2
+\&    ($remainder = $text) =~ s/\eA(\*(Aq(\e\e.|[^\*(Aq])*\*(Aq)//s;
+\&    $extracted = $1;
+.Ve
+.Sp
+but with \f(CW\*(C`extract_delimited\*(C'\fR it can be simplified to:
+.Sp
+.Vb 1
+\&    ($extracted,$remainder) = extract_delimited($text, "\*(Aq");
+.Ve
+.Sp
+\&\f(CW\*(C`extract_delimited\*(C'\fR takes up to four scalars (the input text, the
+delimiters, a prefix pattern to be skipped, and any escape characters)
+and extracts the initial substring of the text that
+is appropriately delimited. If the delimiter string has multiple
+characters, the first one encountered in the text is taken to delimit
+the substring.
+The third argument specifies a prefix pattern that is to be skipped
+(but must be present!) before the substring is extracted.
+The final argument specifies the escape character to be used for each
+delimiter.
+.Sp
+All arguments are optional. If the escape characters are not specified,
+every delimiter is escaped with a backslash (\f(CW\*(C`\e\*(C'\fR).
+If the prefix is not specified, the
+pattern \f(CW\*(Aq\es*\*(Aq\fR \- optional whitespace \- is used. If the delimiter set
+is also not specified, the set \f(CW\*(C`/["\*(Aq\`]/\*(C'\fR is used. If the text to be processed
+is not specified either, \f(CW$_\fR is used.
+.Sp
+In list context, \f(CW\*(C`extract_delimited\*(C'\fR returns a array of three
+elements, the extracted substring (\fIincluding the surrounding
+delimiters\fR), the remainder of the text, and the skipped prefix (if
+any). If a suitable delimited substring is not found, the first
+element of the array is the empty string, the second is the complete
+original text, and the prefix returned in the third element is an
+empty string.
+.Sp
+In a scalar context, just the extracted substring is returned. In
+a void context, the extracted substring (and any prefix) are simply
+removed from the beginning of the first argument.
+.Sp
+Examples:
+.Sp
+.Vb 1
+\&    # Remove a single\-quoted substring from the very beginning of $text:
+\&
+\&        $substring = extract_delimited($text, "\*(Aq", \*(Aq\*(Aq);
+\&
+\&    # Remove a single\-quoted Pascalish substring (i.e. one in which
+\&    # doubling the quote character escapes it) from the very
+\&    # beginning of $text:
+\&
+\&        $substring = extract_delimited($text, "\*(Aq", \*(Aq\*(Aq, "\*(Aq");
+\&
+\&    # Extract a single\- or double\- quoted substring from the
+\&    # beginning of $text, optionally after some whitespace
+\&    # (note the list context to protect $text from modification):
+\&
+\&        ($substring) = extract_delimited $text, q{"\*(Aq};
+\&
+\&    # Delete the substring delimited by the first \*(Aq/\*(Aq in $text:
+\&
+\&        $text = join \*(Aq\*(Aq, (extract_delimited($text,\*(Aq/\*(Aq,\*(Aq[^/]*\*(Aq)[2,1];
+.Ve
+.Sp
+Note that this last example is \fInot\fR the same as deleting the first
+quote-like pattern. For instance, if \f(CW$text\fR contained the string:
+.Sp
+.Vb 1
+\&    "if (\*(Aq./cmd\*(Aq =~ m/$UNIXCMD/s) { $cmd = $1; }"
+.Ve
+.Sp
+then after the deletion it would contain:
+.Sp
+.Vb 1
+\&    "if (\*(Aq.$UNIXCMD/s) { $cmd = $1; }"
+.Ve
+.Sp
+not:
+.Sp
+.Vb 1
+\&    "if (\*(Aq./cmd\*(Aq =~ ms) { $cmd = $1; }"
+.Ve
+.Sp
+See "extract_quotelike" for a (partial) solution to this problem.
+.ie n .IP """extract_bracketed""" 4
+.el .IP \f(CWextract_bracketed\fR 4
+.IX Item "extract_bracketed"
+Like \f(CW"extract_delimited"\fR, the \f(CW\*(C`extract_bracketed\*(C'\fR function takes
+up to three optional scalar arguments: a string to extract from, a delimiter
+specifier, and a prefix pattern. As before, a missing prefix defaults to
+optional whitespace and a missing text defaults to \f(CW$_\fR. However, a missing
+delimiter specifier defaults to \f(CW\*(Aq{}()[]<>\*(Aq\fR (see below).
+.Sp
+\&\f(CW\*(C`extract_bracketed\*(C'\fR extracts a balanced-bracket-delimited
+substring (using any one (or more) of the user-specified delimiter
+brackets: '(..)', '{..}', '[..]', or '<..>'). Optionally it will also
+respect quoted unbalanced brackets (see below).
+.Sp
+A "delimiter bracket" is a bracket in list of delimiters passed as
+\&\f(CW\*(C`extract_bracketed\*(C'\fR's second argument. Delimiter brackets are
+specified by giving either the left or right (or both!) versions
+of the required bracket(s). Note that the order in which
+two or more delimiter brackets are specified is not significant.
+.Sp
+A "balanced-bracket-delimited substring" is a substring bounded by
+matched brackets, such that any other (left or right) delimiter
+bracket \fIwithin\fR the substring is also matched by an opposite
+(right or left) delimiter bracket \fIat the same level of nesting\fR. Any
+type of bracket not in the delimiter list is treated as an ordinary
+character.
+.Sp
+In other words, each type of bracket specified as a delimiter must be
+balanced and correctly nested within the substring, and any other kind of
+("non-delimiter") bracket in the substring is ignored.
+.Sp
+For example, given the string:
+.Sp
+.Vb 1
+\&    $text = "{ an \*(Aq[irregularly :\-(] {} parenthesized >:\-)\*(Aq string }";
+.Ve
+.Sp
+then a call to \f(CW\*(C`extract_bracketed\*(C'\fR in a list context:
+.Sp
+.Vb 1
+\&    @result = extract_bracketed( $text, \*(Aq{}\*(Aq );
+.Ve
+.Sp
+would return:
+.Sp
+.Vb 1
+\&    ( "{ an \*(Aq[irregularly :\-(] {} parenthesized >:\-)\*(Aq string }" , "" , "" )
+.Ve
+.Sp
+since both sets of \f(CW\*(Aq{..}\*(Aq\fR brackets are properly nested and evenly balanced.
+(In a scalar context just the first element of the array would be returned. In
+a void context, \f(CW$text\fR would be replaced by an empty string.)
+.Sp
+Likewise the call in:
+.Sp
+.Vb 1
+\&    @result = extract_bracketed( $text, \*(Aq{[\*(Aq );
+.Ve
+.Sp
+would return the same result, since all sets of both types of specified
+delimiter brackets are correctly nested and balanced.
+.Sp
+However, the call in:
+.Sp
+.Vb 1
+\&    @result = extract_bracketed( $text, \*(Aq{([<\*(Aq );
+.Ve
+.Sp
+would fail, returning:
+.Sp
+.Vb 1
+\&    ( undef , "{ an \*(Aq[irregularly :\-(] {} parenthesized >:\-)\*(Aq string }"  );
+.Ve
+.Sp
+because the embedded pairs of \f(CW\*(Aq(..)\*(Aq\fRs and \f(CW\*(Aq[..]\*(Aq\fRs are "cross-nested" and
+the embedded \f(CW\*(Aq>\*(Aq\fR is unbalanced. (In a scalar context, this call would
+return an empty string. In a void context, \f(CW$text\fR would be unchanged.)
+.Sp
+Note that the embedded single-quotes in the string don't help in this
+case, since they have not been specified as acceptable delimiters and are
+therefore treated as non-delimiter characters (and ignored).
+.Sp
+However, if a particular species of quote character is included in the
+delimiter specification, then that type of quote will be correctly handled.
+for example, if \f(CW$text\fR is:
+.Sp
+.Vb 1
+\&    $text = \*(Aq<A HREF=">>>>">link</A>\*(Aq;
+.Ve
+.Sp
+then
+.Sp
+.Vb 1
+\&    @result = extract_bracketed( $text, \*(Aq<">\*(Aq );
+.Ve
+.Sp
+returns:
+.Sp
+.Vb 1
+\&    ( \*(Aq<A HREF=">>>>">\*(Aq, \*(Aqlink</A>\*(Aq, "" )
+.Ve
+.Sp
+as expected. Without the specification of \f(CW\*(C`"\*(C'\fR as an embedded quoter:
+.Sp
+.Vb 1
+\&    @result = extract_bracketed( $text, \*(Aq<>\*(Aq );
+.Ve
+.Sp
+the result would be:
+.Sp
+.Vb 1
+\&    ( \*(Aq<A HREF=">\*(Aq, \*(Aq>>>">link</A>\*(Aq, "" )
+.Ve
+.Sp
+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
+quoting (i.e. q{string}, qq{string}, etc) can be specified by including the
+letter 'q' as a delimiter. Hence:
+.Sp
+.Vb 1
+\&    @result = extract_bracketed( $text, \*(Aq<q>\*(Aq );
+.Ve
+.Sp
+would correctly match something like this:
+.Sp
+.Vb 1
+\&    $text = \*(Aq<leftop: conj /and/ conj>\*(Aq;
+.Ve
+.Sp
+See also: \f(CW"extract_quotelike"\fR and \f(CW"extract_codeblock"\fR.
+.ie n .IP """extract_variable""" 4
+.el .IP \f(CWextract_variable\fR 4
+.IX Item "extract_variable"
+\&\f(CW\*(C`extract_variable\*(C'\fR extracts any valid Perl variable or
+variable-involved expression, including scalars, arrays, hashes, array
+accesses, hash look-ups, method calls through objects, subroutine calls
+through subroutine references, etc.
+.Sp
+The subroutine takes up to two optional arguments:
+.RS 4
+.IP 1. 4
+A string to be processed (\f(CW$_\fR if the string is omitted or \f(CW\*(C`undef\*(C'\fR)
+.IP 2. 4
+A string specifying a pattern to be matched as a prefix (which is to be
+skipped). If omitted, optional whitespace is skipped.
+.RE
+.RS 4
+.Sp
+On success in a list context, an array of 3 elements is returned. The
+elements are:
+.IP [0] 4
+.IX Item "[0]"
+the extracted variable, or variablish expression
+.IP [1] 4
+.IX Item "[1]"
+the remainder of the input text,
+.IP [2] 4
+.IX Item "[2]"
+the prefix substring (if any),
+.RE
+.RS 4
+.Sp
+On failure, all of these values (except the remaining text) are \f(CW\*(C`undef\*(C'\fR.
+.Sp
+In a scalar context, \f(CW\*(C`extract_variable\*(C'\fR returns just the complete
+substring that matched a variablish expression. \f(CW\*(C`undef\*(C'\fR is returned on
+failure. In addition, the original input text has the returned substring
+(and any prefix) removed from it.
+.Sp
+In a void context, the input text just has the matched substring (and
+any specified prefix) removed.
+.RE
+.ie n .IP """extract_tagged""" 4
+.el .IP \f(CWextract_tagged\fR 4
+.IX Item "extract_tagged"
+\&\f(CW\*(C`extract_tagged\*(C'\fR extracts and segments text between (balanced)
+specified tags.
+.Sp
+The subroutine takes up to five optional arguments:
+.RS 4
+.IP 1. 4
+A string to be processed (\f(CW$_\fR if the string is omitted or \f(CW\*(C`undef\*(C'\fR)
+.IP 2. 4
+A string specifying a pattern (i.e. regex) to be matched as the opening tag.
+If the pattern string is omitted (or \f(CW\*(C`undef\*(C'\fR) then a pattern
+that matches any standard XML tag is used.
+.IP 3. 4
+A string specifying a pattern to be matched at the closing tag.
+If the pattern string is omitted (or \f(CW\*(C`undef\*(C'\fR) then the closing
+tag is constructed by inserting a \f(CW\*(C`/\*(C'\fR after any leading bracket
+characters in the actual opening tag that was matched (\fInot\fR the pattern
+that matched the tag). For example, if the opening tag pattern
+is specified as \f(CW\*(Aq{{\ew+}}\*(Aq\fR and actually matched the opening tag
+\&\f(CW"{{DATA}}"\fR, then the constructed closing tag would be \f(CW"{{/DATA}}"\fR.
+.IP 4. 4
+A string specifying a pattern to be matched as a prefix (which is to be
+skipped). If omitted, optional whitespace is skipped.
+.IP 5. 4
+A hash reference containing various parsing options (see below)
+.RE
+.RS 4
+.Sp
+The various options that can be specified are:
+.ie n .IP """reject => $listref""" 4
+.el .IP "\f(CWreject => $listref\fR" 4
+.IX Item "reject => $listref"
+The list reference contains one or more strings specifying patterns
+that must \fInot\fR appear within the tagged text.
+.Sp
+For example, to extract
+an HTML link (which should not contain nested links) use:
+.Sp
+.Vb 1
+\&        extract_tagged($text, \*(Aq<A>\*(Aq, \*(Aq</A>\*(Aq, undef, {reject => [\*(Aq<A>\*(Aq]} );
+.Ve
+.ie n .IP """ignore => $listref""" 4
+.el .IP "\f(CWignore => $listref\fR" 4
+.IX Item "ignore => $listref"
+The list reference contains one or more strings specifying patterns
+that are \fInot\fR to be treated as nested tags within the tagged text
+(even if they would match the start tag pattern).
+.Sp
+For example, to extract an arbitrary XML tag, but ignore "empty" elements:
+.Sp
+.Vb 1
+\&        extract_tagged($text, undef, undef, undef, {ignore => [\*(Aq<[^>]*/>\*(Aq]} );
+.Ve
+.Sp
+(also see "gen_delimited_pat" below).
+.ie n .IP """fail => $str""" 4
+.el .IP "\f(CWfail => $str\fR" 4
+.IX Item "fail => $str"
+The \f(CW\*(C`fail\*(C'\fR option indicates the action to be taken if a matching end
+tag is not encountered (i.e. before the end of the string or some
+\&\f(CW\*(C`reject\*(C'\fR pattern matches). By default, a failure to match a closing
+tag causes \f(CW\*(C`extract_tagged\*(C'\fR to immediately fail.
+.Sp
+However, if the string value associated with <reject> is "MAX", then
+\&\f(CW\*(C`extract_tagged\*(C'\fR returns the complete text up to the point of failure.
+If the string is "PARA", \f(CW\*(C`extract_tagged\*(C'\fR returns only the first paragraph
+after the tag (up to the first line that is either empty or contains
+only whitespace characters).
+If the string is "", the default behaviour (i.e. failure) is reinstated.
+.Sp
+For example, suppose the start tag "/para" introduces a paragraph, which then
+continues until the next "/endpara" tag or until another "/para" tag is
+encountered:
+.Sp
+.Vb 1
+\&        $text = "/para line 1\en\enline 3\en/para line 4";
+\&
+\&        extract_tagged($text, \*(Aq/para\*(Aq, \*(Aq/endpara\*(Aq, undef,
+\&                                {reject => \*(Aq/para\*(Aq, fail => MAX );
+\&
+\&        # EXTRACTED: "/para line 1\en\enline 3\en"
+.Ve
+.Sp
+Suppose instead, that if no matching "/endpara" tag is found, the "/para"
+tag refers only to the immediately following paragraph:
+.Sp
+.Vb 1
+\&        $text = "/para line 1\en\enline 3\en/para line 4";
+\&
+\&        extract_tagged($text, \*(Aq/para\*(Aq, \*(Aq/endpara\*(Aq, undef,
+\&                        {reject => \*(Aq/para\*(Aq, fail => MAX );
+\&
+\&        # EXTRACTED: "/para line 1\en"
+.Ve
+.Sp
+Note that the specified \f(CW\*(C`fail\*(C'\fR behaviour applies to nested tags as well.
+.RE
+.RS 4
+.Sp
+On success in a list context, an array of 6 elements is returned. The elements are:
+.IP [0] 4
+.IX Item "[0]"
+the extracted tagged substring (including the outermost tags),
+.IP [1] 4
+.IX Item "[1]"
+the remainder of the input text,
+.IP [2] 4
+.IX Item "[2]"
+the prefix substring (if any),
+.IP [3] 4
+.IX Item "[3]"
+the opening tag
+.IP [4] 4
+.IX Item "[4]"
+the text between the opening and closing tags
+.IP [5] 4
+.IX Item "[5]"
+the closing tag (or "" if no closing tag was found)
+.RE
+.RS 4
+.Sp
+On failure, all of these values (except the remaining text) are \f(CW\*(C`undef\*(C'\fR.
+.Sp
+In a scalar context, \f(CW\*(C`extract_tagged\*(C'\fR returns just the complete
+substring that matched a tagged text (including the start and end
+tags). \f(CW\*(C`undef\*(C'\fR is returned on failure. In addition, the original input
+text has the returned substring (and any prefix) removed from it.
+.Sp
+In a void context, the input text just has the matched substring (and
+any specified prefix) removed.
+.RE
+.ie n .IP """gen_extract_tagged""" 4
+.el .IP \f(CWgen_extract_tagged\fR 4
+.IX Item "gen_extract_tagged"
+\&\f(CW\*(C`gen_extract_tagged\*(C'\fR generates a new anonymous subroutine which
+extracts text between (balanced) specified tags. In other words,
+it generates a function identical in function to \f(CW\*(C`extract_tagged\*(C'\fR.
+.Sp
+The difference between \f(CW\*(C`extract_tagged\*(C'\fR and the anonymous
+subroutines generated by
+\&\f(CW\*(C`gen_extract_tagged\*(C'\fR, is that those generated subroutines:
+.RS 4
+.IP \(bu 4
+do not have to reparse tag specification or parsing options every time
+they are called (whereas \f(CW\*(C`extract_tagged\*(C'\fR has to effectively rebuild
+its tag parser on every call);
+.IP \(bu 4
+make use of the new qr// construct to pre-compile the regexes they use
+(whereas \f(CW\*(C`extract_tagged\*(C'\fR uses standard string variable interpolation
+to create tag-matching patterns).
+.RE
+.RS 4
+.Sp
+The subroutine takes up to four optional arguments (the same set as
+\&\f(CW\*(C`extract_tagged\*(C'\fR except for the string to be processed). It returns
+a reference to a subroutine which in turn takes a single argument (the text to
+be extracted from).
+.Sp
+In other words, the implementation of \f(CW\*(C`extract_tagged\*(C'\fR is exactly
+equivalent to:
+.Sp
+.Vb 6
+\&        sub extract_tagged
+\&        {
+\&                my $text = shift;
+\&                $extractor = gen_extract_tagged(@_);
+\&                return $extractor\->($text);
+\&        }
+.Ve
+.Sp
+(although \f(CW\*(C`extract_tagged\*(C'\fR is not currently implemented that way).
+.Sp
+Using \f(CW\*(C`gen_extract_tagged\*(C'\fR to create extraction functions for specific tags
+is a good idea if those functions are going to be called more than once, since
+their performance is typically twice as good as the more general-purpose
+\&\f(CW\*(C`extract_tagged\*(C'\fR.
+.RE
+.ie n .IP """extract_quotelike""" 4
+.el .IP \f(CWextract_quotelike\fR 4
+.IX Item "extract_quotelike"
+\&\f(CW\*(C`extract_quotelike\*(C'\fR attempts to recognize, extract, and segment any
+one of the various Perl quotes and quotelike operators (see
+\&\fBperlop\fR\|(3)) Nested backslashed delimiters, embedded balanced bracket
+delimiters (for the quotelike operators), and trailing modifiers are
+all caught. For example, in:
+.Sp
+.Vb 1
+\&        extract_quotelike \*(Aqq # an octothorpe: \e# (not the end of the q!) #\*(Aq
+\&
+\&        extract_quotelike \*(Aq  "You said, \e"Use sed\e"."  \*(Aq
+\&
+\&        extract_quotelike \*(Aq s{([A\-Z]{1,8}\e.[A\-Z]{3})} /\eL$1\eE/; \*(Aq
+\&
+\&        extract_quotelike \*(Aq tr/\e\e\e/\e\e\e\e/\e\e\e//ds; \*(Aq
+.Ve
+.Sp
+the full Perl quotelike operations are all extracted correctly.
+.Sp
+Note too that, when using the /x modifier on a regex, any comment
+containing the current pattern delimiter will cause the regex to be
+immediately terminated. In other words:
+.Sp
+.Vb 5
+\&        \*(Aqm /
+\&                (?i)            # CASE INSENSITIVE
+\&                [a\-z_]          # LEADING ALPHABETIC/UNDERSCORE
+\&                [a\-z0\-9]*       # FOLLOWED BY ANY NUMBER OF ALPHANUMERICS
+\&           /x\*(Aq
+.Ve
+.Sp
+will be extracted as if it were:
+.Sp
+.Vb 3
+\&        \*(Aqm /
+\&                (?i)            # CASE INSENSITIVE
+\&                [a\-z_]          # LEADING ALPHABETIC/\*(Aq
+.Ve
+.Sp
+This behaviour is identical to that of the actual compiler.
+.Sp
+\&\f(CW\*(C`extract_quotelike\*(C'\fR takes two arguments: the text to be processed and
+a prefix to be matched at the very beginning of the text. If no prefix
+is specified, optional whitespace is the default. If no text is given,
+\&\f(CW$_\fR is used.
+.Sp
+In a list context, an array of 11 elements is returned. The elements are:
+.RS 4
+.IP [0] 4
+.IX Item "[0]"
+the extracted quotelike substring (including trailing modifiers),
+.IP [1] 4
+.IX Item "[1]"
+the remainder of the input text,
+.IP [2] 4
+.IX Item "[2]"
+the prefix substring (if any),
+.IP [3] 4
+.IX Item "[3]"
+the name of the quotelike operator (if any),
+.IP [4] 4
+.IX Item "[4]"
+the left delimiter of the first block of the operation,
+.IP [5] 4
+.IX Item "[5]"
+the text of the first block of the operation
+(that is, the contents of
+a quote, the regex of a match or substitution or the target list of a
+translation),
+.IP [6] 4
+.IX Item "[6]"
+the right delimiter of the first block of the operation,
+.IP [7] 4
+.IX Item "[7]"
+the left delimiter of the second block of the operation
+(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),
+.IP [8] 4
+.IX Item "[8]"
+the text of the second block of the operation
+(that is, the replacement of a substitution or the translation list
+of a translation),
+.IP [9] 4
+.IX Item "[9]"
+the right delimiter of the second block of the operation (if any),
+.IP [10] 4
+.IX Item "[10]"
+the trailing modifiers on the operation (if any).
+.RE
+.RS 4
+.Sp
+For each of the fields marked "(if any)" the default value on success is
+an empty string.
+On failure, all of these values (except the remaining text) are \f(CW\*(C`undef\*(C'\fR.
+.Sp
+In a scalar context, \f(CW\*(C`extract_quotelike\*(C'\fR returns just the complete substring
+that matched a quotelike operation (or \f(CW\*(C`undef\*(C'\fR on failure). In a scalar or
+void context, the input text has the same substring (and any specified
+prefix) removed.
+.Sp
+Examples:
+.Sp
+.Vb 1
+\&        # Remove the first quotelike literal that appears in text
+\&
+\&                $quotelike = extract_quotelike($text,\*(Aq.*?\*(Aq);
+\&
+\&        # Replace one or more leading whitespace\-separated quotelike
+\&        # literals in $_ with "<QLL>"
+\&
+\&                do { $_ = join \*(Aq<QLL>\*(Aq, (extract_quotelike)[2,1] } until $@;
+\&
+\&
+\&        # Isolate the search pattern in a quotelike operation from $text
+\&
+\&                ($op,$pat) = (extract_quotelike $text)[3,5];
+\&                if ($op =~ /[ms]/)
+\&                {
+\&                        print "search pattern: $pat\en";
+\&                }
+\&                else
+\&                {
+\&                        print "$op is not a pattern matching operation\en";
+\&                }
+.Ve
+.RE
+.ie n .IP """extract_quotelike""" 4
+.el .IP \f(CWextract_quotelike\fR 4
+.IX Item "extract_quotelike"
+\&\f(CW\*(C`extract_quotelike\*(C'\fR can successfully extract "here documents" from an input
+string, but with an important caveat in list contexts.
+.Sp
+Unlike other types of quote-like literals, a here document is rarely
+a contiguous substring. For example, a typical piece of code using
+here document might look like this:
+.Sp
+.Vb 4
+\&        <<\*(AqEOMSG\*(Aq || die;
+\&        This is the message.
+\&        EOMSG
+\&        exit;
+.Ve
+.Sp
+Given this as an input string in a scalar context, \f(CW\*(C`extract_quotelike\*(C'\fR
+would correctly return the string "<<'EOMSG'\enThis is the message.\enEOMSG",
+leaving the string " || die;\enexit;" in the original variable. In other words,
+the two separate pieces of the here document are successfully extracted and
+concatenated.
+.Sp
+In a list context, \f(CW\*(C`extract_quotelike\*(C'\fR would return the list
+.RS 4
+.IP [0] 4
+.IX Item "[0]"
+"<<'EOMSG'\enThis is the message.\enEOMSG\en" (i.e. the full extracted here document,
+including fore and aft delimiters),
+.IP [1] 4
+.IX Item "[1]"
+" || die;\enexit;" (i.e. the remainder of the input text, concatenated),
+.IP [2] 4
+.IX Item "[2]"
+"" (i.e. the prefix substring \-\- trivial in this case),
+.IP [3] 4
+.IX Item "[3]"
+"<<" (i.e. the "name" of the quotelike operator)
+.IP [4] 4
+.IX Item "[4]"
+"'EOMSG'" (i.e. the left delimiter of the here document, including any quotes),
+.IP [5] 4
+.IX Item "[5]"
+"This is the message.\en" (i.e. the text of the here document),
+.IP [6] 4
+.IX Item "[6]"
+"EOMSG" (i.e. the right delimiter of the here document),
+.IP [7..10] 4
+.IX Item "[7..10]"
+"" (a here document has no second left delimiter, second text, second right
+delimiter, or trailing modifiers).
+.RE
+.RS 4
+.Sp
+However, the matching position of the input variable would be set to
+"exit;" (i.e. \fIafter\fR the closing delimiter of the here document),
+which would cause the earlier " || die;\enexit;" to be skipped in any
+sequence of code fragment extractions.
+.Sp
+To avoid this problem, when it encounters a here document whilst
+extracting from a modifiable string, \f(CW\*(C`extract_quotelike\*(C'\fR silently
+rearranges the string to an equivalent piece of Perl:
+.Sp
+.Vb 5
+\&        <<\*(AqEOMSG\*(Aq
+\&        This is the message.
+\&        EOMSG
+\&        || die;
+\&        exit;
+.Ve
+.Sp
+in which the here document \fIis\fR contiguous. It still leaves the
+matching position after the here document, but now the rest of the line
+on which the here document starts is not skipped.
+.Sp
+To prevent <extract_quotelike> from mucking about with the input in this way
+(this is the only case where a list-context \f(CW\*(C`extract_quotelike\*(C'\fR does so),
+you can pass the input variable as an interpolated literal:
+.Sp
+.Vb 1
+\&        $quotelike = extract_quotelike("$var");
+.Ve
+.RE
+.ie n .IP """extract_codeblock""" 4
+.el .IP \f(CWextract_codeblock\fR 4
+.IX Item "extract_codeblock"
+\&\f(CW\*(C`extract_codeblock\*(C'\fR attempts to recognize and extract a balanced
+bracket delimited substring that may contain unbalanced brackets
+inside Perl quotes or quotelike operations. That is, \f(CW\*(C`extract_codeblock\*(C'\fR
+is like a combination of \f(CW"extract_bracketed"\fR and
+\&\f(CW"extract_quotelike"\fR.
+.Sp
+\&\f(CW\*(C`extract_codeblock\*(C'\fR takes the same initial three parameters as \f(CW\*(C`extract_bracketed\*(C'\fR:
+a text to process, a set of delimiter brackets to look for, and a prefix to
+match first. It also takes an optional fourth parameter, which allows the
+outermost delimiter brackets to be specified separately (see below),
+and a fifth parameter used only by Parse::RecDescent.
+.Sp
+Omitting the first argument (input text) means process \f(CW$_\fR instead.
+Omitting the second argument (delimiter brackets) indicates that only \f(CW\*(Aq{\*(Aq\fR is to be used.
+Omitting the third argument (prefix argument) implies optional whitespace at the start.
+Omitting the fourth argument (outermost delimiter brackets) indicates that the
+value of the second argument is to be used for the outermost delimiters.
+.Sp
+Once the prefix and the outermost opening delimiter bracket have been
+recognized, code blocks are extracted by stepping through the input text and
+trying the following alternatives in sequence:
+.RS 4
+.IP 1. 4
+Try and match a closing delimiter bracket. If the bracket was the same
+species as the last opening bracket, return the substring to that
+point. If the bracket was mismatched, return an error.
+.IP 2. 4
+Try to match a quote or quotelike operator. If found, call
+\&\f(CW\*(C`extract_quotelike\*(C'\fR to eat it. If \f(CW\*(C`extract_quotelike\*(C'\fR fails, return
+the error it returned. Otherwise go back to step 1.
+.IP 3. 4
+Try to match an opening delimiter bracket. If found, call
+\&\f(CW\*(C`extract_codeblock\*(C'\fR recursively to eat the embedded block. If the
+recursive call fails, return an error. Otherwise, go back to step 1.
+.IP 4. 4
+Unconditionally match a bareword or any other single character, and
+then go back to step 1.
+.RE
+.RS 4
+.Sp
+Examples:
+.Sp
+.Vb 1
+\&        # Find a while loop in the text
+\&
+\&                if ($text =~ s/.*?while\es*\e{/{/)
+\&                {
+\&                        $loop = "while " . extract_codeblock($text);
+\&                }
+\&
+\&        # Remove the first round\-bracketed list (which may include
+\&        # round\- or curly\-bracketed code blocks or quotelike operators)
+\&
+\&                extract_codeblock $text, "(){}", \*(Aq[^(]*\*(Aq;
+.Ve
+.Sp
+The ability to specify a different outermost delimiter bracket is useful
+in some circumstances. For example, in the Parse::RecDescent module,
+parser actions which are to be performed only on a successful parse
+are specified using a \f(CW\*(C`<defer:...>\*(C'\fR directive. For example:
+.Sp
+.Vb 2
+\&        sentence: subject verb object
+\&                        <defer: {$::theVerb = $item{verb}} >
+.Ve
+.Sp
+Parse::RecDescent uses \f(CW\*(C`extract_codeblock($text, \*(Aq{}<>\*(Aq)\*(C'\fR to extract the code
+within the \f(CW\*(C`<defer:...>\*(C'\fR directive, but there's a problem.
+.Sp
+A deferred action like this:
+.Sp
+.Vb 1
+\&                        <defer: {if ($count>10) {$count\-\-}} >
+.Ve
+.Sp
+will be incorrectly parsed as:
+.Sp
+.Vb 1
+\&                        <defer: {if ($count>
+.Ve
+.Sp
+because the "less than" operator is interpreted as a closing delimiter.
+.Sp
+But, by extracting the directive using
+\&\f(CW\*(C`extract_codeblock($text,\ \*(Aq{}\*(Aq,\ undef,\ \*(Aq<>\*(Aq)\*(C'\fR
+the '>' character is only treated as a delimited at the outermost
+level of the code block, so the directive is parsed correctly.
+.RE
+.ie n .IP """extract_multiple""" 4
+.el .IP \f(CWextract_multiple\fR 4
+.IX Item "extract_multiple"
+The \f(CW\*(C`extract_multiple\*(C'\fR subroutine takes a string to be processed and a
+list of extractors (subroutines or regular expressions) to apply to that string.
+.Sp
+In an array context \f(CW\*(C`extract_multiple\*(C'\fR returns an array of substrings
+of the original string, as extracted by the specified extractors.
+In a scalar context, \f(CW\*(C`extract_multiple\*(C'\fR returns the first
+substring successfully extracted from the original string. In both
+scalar and void contexts the original string has the first successfully
+extracted substring removed from it. In all contexts
+\&\f(CW\*(C`extract_multiple\*(C'\fR starts at the current \f(CW\*(C`pos\*(C'\fR of the string, and
+sets that \f(CW\*(C`pos\*(C'\fR appropriately after it matches.
+.Sp
+Hence, the aim of a call to \f(CW\*(C`extract_multiple\*(C'\fR in a list context
+is to split the processed string into as many non-overlapping fields as
+possible, by repeatedly applying each of the specified extractors
+to the remainder of the string. Thus \f(CW\*(C`extract_multiple\*(C'\fR is
+a generalized form of Perl's \f(CW\*(C`split\*(C'\fR subroutine.
+.Sp
+The subroutine takes up to four optional arguments:
+.RS 4
+.IP 1. 4
+A string to be processed (\f(CW$_\fR if the string is omitted or \f(CW\*(C`undef\*(C'\fR)
+.IP 2. 4
+A reference to a list of subroutine references and/or qr// objects and/or
+literal strings and/or hash references, specifying the extractors
+to be used to split the string. If this argument is omitted (or
+\&\f(CW\*(C`undef\*(C'\fR) the list:
+.Sp
+.Vb 5
+\&        [
+\&                sub { extract_variable($_[0], \*(Aq\*(Aq) },
+\&                sub { extract_quotelike($_[0],\*(Aq\*(Aq) },
+\&                sub { extract_codeblock($_[0],\*(Aq{}\*(Aq,\*(Aq\*(Aq) },
+\&        ]
+.Ve
+.Sp
+is used.
+.IP 3. 4
+An number specifying the maximum number of fields to return. If this
+argument is omitted (or \f(CW\*(C`undef\*(C'\fR), split continues as long as possible.
+.Sp
+If the third argument is \fIN\fR, then extraction continues until \fIN\fR fields
+have been successfully extracted, or until the string has been completely
+processed.
+.Sp
+Note that in scalar and void contexts the value of this argument is
+automatically reset to 1 (under \f(CW\*(C`\-w\*(C'\fR, a warning is issued if the argument
+has to be reset).
+.IP 4. 4
+A value indicating whether unmatched substrings (see below) within the
+text should be skipped or returned as fields. If the value is true,
+such substrings are skipped. Otherwise, they are returned.
+.RE
+.RS 4
+.Sp
+The extraction process works by applying each extractor in
+sequence to the text string.
+.Sp
+If the extractor is a subroutine it is called in a list context and is
+expected to return a list of a single element, namely the extracted
+text. It may optionally also return two further arguments: a string
+representing the text left after extraction (like $' for a pattern
+match), and a string representing any prefix skipped before the
+extraction (like $` in a pattern match). Note that this is designed
+to facilitate the use of other Text::Balanced subroutines with
+\&\f(CW\*(C`extract_multiple\*(C'\fR. Note too that the value returned by an extractor
+subroutine need not bear any relationship to the corresponding substring
+of the original text (see examples below).
+.Sp
+If the extractor is a precompiled regular expression or a string,
+it is matched against the text in a scalar context with a leading
+\&'\eG' and the gc modifiers enabled. The extracted value is either
+\&\f(CW$1\fR if that variable is defined after the match, or else the
+complete match (i.e. $&).
+.Sp
+If the extractor is a hash reference, it must contain exactly one element.
+The value of that element is one of the
+above extractor types (subroutine reference, regular expression, or string).
+The key of that element is the name of a class into which the successful
+return value of the extractor will be blessed.
+.Sp
+If an extractor returns a defined value, that value is immediately
+treated as the next extracted field and pushed onto the list of fields.
+If the extractor was specified in a hash reference, the field is also
+blessed into the appropriate class,
+.Sp
+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
+assumed to have failed to extract.
+If none of the extractor subroutines succeeds, then one
+character is extracted from the start of the text and the extraction
+subroutines reapplied. Characters which are thus removed are accumulated and
+eventually become the next field (unless the fourth argument is true, in which
+case they are discarded).
+.Sp
+For example, the following extracts substrings that are valid Perl variables:
+.Sp
+.Vb 3
+\&        @fields = extract_multiple($text,
+\&                                   [ sub { extract_variable($_[0]) } ],
+\&                                   undef, 1);
+.Ve
+.Sp
+This example separates a text into fields which are quote delimited,
+curly bracketed, and anything else. The delimited and bracketed
+parts are also blessed to identify them (the "anything else" is unblessed):
+.Sp
+.Vb 5
+\&        @fields = extract_multiple($text,
+\&                   [
+\&                        { Delim => sub { extract_delimited($_[0],q{\*(Aq"}) } },
+\&                        { Brack => sub { extract_bracketed($_[0],\*(Aq{}\*(Aq) } },
+\&                   ]);
+.Ve
+.Sp
+This call extracts the next single substring that is a valid Perl quotelike
+operator (and removes it from \f(CW$text\fR):
+.Sp
+.Vb 4
+\&        $quotelike = extract_multiple($text,
+\&                                      [
+\&                                        sub { extract_quotelike($_[0]) },
+\&                                      ], undef, 1);
+.Ve
+.Sp
+Finally, here is yet another way to do comma-separated value parsing:
+.Sp
+.Vb 8
+\&        $csv_text = "a,\*(Aqx b\*(Aq,c";
+\&        @fields = extract_multiple($csv_text,
+\&                                  [
+\&                                        sub { extract_delimited($_[0],q{\*(Aq"}) },
+\&                                        qr/([^,]+)/,
+\&                                  ],
+\&                                  undef,1);
+\&        # @fields is now (\*(Aqa\*(Aq, "\*(Aqx b\*(Aq", \*(Aqc\*(Aq)
+.Ve
+.Sp
+The list in the second argument means:
+\&\fI"Try and extract a ' or " delimited string, otherwise extract anything up to a comma..."\fR.
+The undef third argument means:
+\&\fI"...as many times as possible..."\fR,
+and the true value in the fourth argument means
+\&\fI"...discarding anything else that appears (i.e. the commas)"\fR.
+.Sp
+If you wanted the commas preserved as separate fields (i.e. like split
+does if your split pattern has capturing parentheses), you would
+just make the last parameter undefined (or remove it).
+.RE
+.ie n .IP """gen_delimited_pat""" 4
+.el .IP \f(CWgen_delimited_pat\fR 4
+.IX Item "gen_delimited_pat"
+The \f(CW\*(C`gen_delimited_pat\*(C'\fR subroutine takes a single (string) argument and
+builds a Friedl-style optimized regex that matches a string delimited
+by any one of the characters in the single argument. For example:
+.Sp
+.Vb 1
+\&        gen_delimited_pat(q{\*(Aq"})
+.Ve
+.Sp
+returns the regex:
+.Sp
+.Vb 1
+\&        (?:\e"(?:\e\e\e"|(?!\e").)*\e"|\e\*(Aq(?:\e\e\e\*(Aq|(?!\e\*(Aq).)*\e\*(Aq)
+.Ve
+.Sp
+Note that the specified delimiters are automatically quotemeta'd.
+.Sp
+A typical use of \f(CW\*(C`gen_delimited_pat\*(C'\fR would be to build special purpose tags
+for \f(CW\*(C`extract_tagged\*(C'\fR. For example, to properly ignore "empty" XML elements
+(which might contain quoted strings):
+.Sp
+.Vb 1
+\&        my $empty_tag = \*(Aq<(\*(Aq . gen_delimited_pat(q{\*(Aq"}) . \*(Aq|.)+/>\*(Aq;
+\&
+\&        extract_tagged($text, undef, undef, undef, {ignore => [$empty_tag]} );
+.Ve
+.Sp
+\&\f(CW\*(C`gen_delimited_pat\*(C'\fR may also be called with an optional second argument,
+which specifies the "escape" character(s) to be used for each delimiter.
+For example to match a Pascal-style string (where ' is the delimiter
+and '' is a literal ' within the string):
+.Sp
+.Vb 1
+\&        gen_delimited_pat(q{\*(Aq},q{\*(Aq});
+.Ve
+.Sp
+Different escape characters can be specified for different delimiters.
+For example, to specify that '/' is the escape for single quotes
+and '%' is the escape for double quotes:
+.Sp
+.Vb 1
+\&        gen_delimited_pat(q{\*(Aq"},q{/%});
+.Ve
+.Sp
+If more delimiters than escape chars are specified, the last escape char
+is used for the remaining delimiters.
+If no escape char is specified for a given specified delimiter, '\e' is used.
+.ie n .IP """delimited_pat""" 4
+.el .IP \f(CWdelimited_pat\fR 4
+.IX Item "delimited_pat"
+Note that \f(CW\*(C`gen_delimited_pat\*(C'\fR was previously called \f(CW\*(C`delimited_pat\*(C'\fR.
+That name may still be used, but is now deprecated.
+.SH DIAGNOSTICS
+.IX Header "DIAGNOSTICS"
+In a list context, all the functions return \f(CW\*(C`(undef,$original_text)\*(C'\fR
+on failure. In a scalar context, failure is indicated by returning \f(CW\*(C`undef\*(C'\fR
+(in this case the input text is not modified in any way).
+.PP
+In addition, on failure in \fIany\fR context, the \f(CW$@\fR variable is set.
+Accessing \f(CW\*(C`$@\->{error}\*(C'\fR returns one of the error diagnostics listed
+below.
+Accessing \f(CW\*(C`$@\->{pos}\*(C'\fR returns the offset into the original string at
+which the error was detected (although not necessarily where it occurred!)
+Printing \f(CW$@\fR directly produces the error message, with the offset appended.
+On success, the \f(CW$@\fR variable is guaranteed to be \f(CW\*(C`undef\*(C'\fR.
+.PP
+The available diagnostics are:
+.ie n .IP """Did not find a suitable bracket: ""%s""""" 4
+.el .IP "\f(CWDid not find a suitable bracket: ""%s""\fR" 4
+.IX Item "Did not find a suitable bracket: ""%s"""
+The delimiter provided to \f(CW\*(C`extract_bracketed\*(C'\fR was not one of
+\&\f(CW\*(Aq()[]<>{}\*(Aq\fR.
+.ie n .IP """Did not find prefix: /%s/""" 4
+.el .IP "\f(CWDid not find prefix: /%s/\fR" 4
+.IX Item "Did not find prefix: /%s/"
+A non-optional prefix was specified but wasn't found at the start of the text.
+.ie n .IP """Did not find opening bracket after prefix: ""%s""""" 4
+.el .IP "\f(CWDid not find opening bracket after prefix: ""%s""\fR" 4
+.IX Item "Did not find opening bracket after prefix: ""%s"""
+\&\f(CW\*(C`extract_bracketed\*(C'\fR or \f(CW\*(C`extract_codeblock\*(C'\fR was expecting a
+particular kind of bracket at the start of the text, and didn't find it.
+.ie n .IP """No quotelike operator found after prefix: ""%s""""" 4
+.el .IP "\f(CWNo quotelike operator found after prefix: ""%s""\fR" 4
+.IX Item "No quotelike operator found after prefix: ""%s"""
+\&\f(CW\*(C`extract_quotelike\*(C'\fR didn't find one of the 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 at the start of the substring
+it was extracting.
+.ie n .IP """Unmatched closing bracket: ""%c""""" 4
+.el .IP "\f(CWUnmatched closing bracket: ""%c""\fR" 4
+.IX Item "Unmatched closing bracket: ""%c"""
+\&\f(CW\*(C`extract_bracketed\*(C'\fR, \f(CW\*(C`extract_quotelike\*(C'\fR or \f(CW\*(C`extract_codeblock\*(C'\fR encountered
+a closing bracket where none was expected.
+.ie n .IP """Unmatched opening bracket(s): ""%s""""" 4
+.el .IP "\f(CWUnmatched opening bracket(s): ""%s""\fR" 4
+.IX Item "Unmatched opening bracket(s): ""%s"""
+\&\f(CW\*(C`extract_bracketed\*(C'\fR, \f(CW\*(C`extract_quotelike\*(C'\fR or \f(CW\*(C`extract_codeblock\*(C'\fR ran
+out of characters in the text before closing one or more levels of nested
+brackets.
+.ie n .IP """Unmatched embedded quote (%s)""" 4
+.el .IP "\f(CWUnmatched embedded quote (%s)\fR" 4
+.IX Item "Unmatched embedded quote (%s)"
+\&\f(CW\*(C`extract_bracketed\*(C'\fR attempted to match an embedded quoted substring, but
+failed to find a closing quote to match it.
+.ie n .IP """Did not find closing delimiter to match \*(Aq%s\*(Aq""" 4
+.el .IP "\f(CWDid not find closing delimiter to match \*(Aq%s\*(Aq\fR" 4
+.IX Item "Did not find closing delimiter to match %s"
+\&\f(CW\*(C`extract_quotelike\*(C'\fR was unable to find a closing delimiter to match the
+one that opened the quote-like operation.
+.ie n .IP """Mismatched closing bracket: expected ""%c"" but found ""%s""""" 4
+.el .IP "\f(CWMismatched closing bracket: expected ""%c"" but found ""%s""\fR" 4
+.IX Item "Mismatched closing bracket: expected ""%c"" but found ""%s"""
+\&\f(CW\*(C`extract_bracketed\*(C'\fR, \f(CW\*(C`extract_quotelike\*(C'\fR or \f(CW\*(C`extract_codeblock\*(C'\fR found
+a valid bracket delimiter, but it was the wrong species. This usually
+indicates a nesting error, but may indicate incorrect quoting or escaping.
+.ie n .IP """No block delimiter found after quotelike ""%s""""" 4
+.el .IP "\f(CWNo block delimiter found after quotelike ""%s""\fR" 4
+.IX Item "No block delimiter found after quotelike ""%s"""
+\&\f(CW\*(C`extract_quotelike\*(C'\fR or \f(CW\*(C`extract_codeblock\*(C'\fR found one of the
+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
+without a suitable block after it.
+.ie n .IP """Did not find leading dereferencer""" 4
+.el .IP "\f(CWDid not find leading dereferencer\fR" 4
+.IX Item "Did not find leading dereferencer"
+\&\f(CW\*(C`extract_variable\*(C'\fR was expecting one of '$', '@', or '%' at the start of
+a variable, but didn't find any of them.
+.ie n .IP """Bad identifier after dereferencer""" 4
+.el .IP "\f(CWBad identifier after dereferencer\fR" 4
+.IX Item "Bad identifier after dereferencer"
+\&\f(CW\*(C`extract_variable\*(C'\fR found a '$', '@', or '%' indicating a variable, but that
+character was not followed by a legal Perl identifier.
+.ie n .IP """Did not find expected opening bracket at %s""" 4
+.el .IP "\f(CWDid not find expected opening bracket at %s\fR" 4
+.IX Item "Did not find expected opening bracket at %s"
+\&\f(CW\*(C`extract_codeblock\*(C'\fR failed to find any of the outermost opening brackets
+that were specified.
+.ie n .IP """Improperly nested codeblock at %s""" 4
+.el .IP "\f(CWImproperly nested codeblock at %s\fR" 4
+.IX Item "Improperly nested codeblock at %s"
+A nested code block was found that started with a delimiter that was specified
+as being only to be used as an outermost bracket.
+.ie n .IP """Missing second block for quotelike ""%s""""" 4
+.el .IP "\f(CWMissing second block for quotelike ""%s""\fR" 4
+.IX Item "Missing second block for quotelike ""%s"""
+\&\f(CW\*(C`extract_codeblock\*(C'\fR or \f(CW\*(C`extract_quotelike\*(C'\fR found one of the
+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.
+.ie n .IP """No match found for opening bracket""" 4
+.el .IP "\f(CWNo match found for opening bracket\fR" 4
+.IX Item "No match found for opening bracket"
+\&\f(CW\*(C`extract_codeblock\*(C'\fR failed to find a closing bracket to match the outermost
+opening bracket.
+.ie n .IP """Did not find opening tag: /%s/""" 4
+.el .IP "\f(CWDid not find opening tag: /%s/\fR" 4
+.IX Item "Did not find opening tag: /%s/"
+\&\f(CW\*(C`extract_tagged\*(C'\fR did not find a suitable opening tag (after any specified
+prefix was removed).
+.ie n .IP """Unable to construct closing tag to match: /%s/""" 4
+.el .IP "\f(CWUnable to construct closing tag to match: /%s/\fR" 4
+.IX Item "Unable to construct closing tag to match: /%s/"
+\&\f(CW\*(C`extract_tagged\*(C'\fR matched the specified opening tag and tried to
+modify the matched text to produce a matching closing tag (because
+none was specified). It failed to generate the closing tag, almost
+certainly because the opening tag did not start with a
+bracket of some kind.
+.ie n .IP """Found invalid nested tag: %s""" 4
+.el .IP "\f(CWFound invalid nested tag: %s\fR" 4
+.IX Item "Found invalid nested tag: %s"
+\&\f(CW\*(C`extract_tagged\*(C'\fR found a nested tag that appeared in the "reject" list
+(and the failure mode was not "MAX" or "PARA").
+.ie n .IP """Found unbalanced nested tag: %s""" 4
+.el .IP "\f(CWFound unbalanced nested tag: %s\fR" 4
+.IX Item "Found unbalanced nested tag: %s"
+\&\f(CW\*(C`extract_tagged\*(C'\fR found a nested opening tag that was not matched by a
+corresponding nested closing tag (and the failure mode was not "MAX" or "PARA").
+.ie n .IP """Did not find closing tag""" 4
+.el .IP "\f(CWDid not find closing tag\fR" 4
+.IX Item "Did not find closing tag"
+\&\f(CW\*(C`extract_tagged\*(C'\fR reached the end of the text without finding a closing tag
+to match the original opening tag (and the failure mode was not
+"MAX" or "PARA").
+.SH EXPORTS
+.IX Header "EXPORTS"
+The following symbols are, or can be, exported by this module:
+.IP "Default Exports" 4
+.IX Item "Default Exports"
+\&\fINone\fR.
+.IP "Optional Exports" 4
+.IX Item "Optional Exports"
+\&\f(CW\*(C`extract_delimited\*(C'\fR,
+\&\f(CW\*(C`extract_bracketed\*(C'\fR,
+\&\f(CW\*(C`extract_quotelike\*(C'\fR,
+\&\f(CW\*(C`extract_codeblock\*(C'\fR,
+\&\f(CW\*(C`extract_variable\*(C'\fR,
+\&\f(CW\*(C`extract_tagged\*(C'\fR,
+\&\f(CW\*(C`extract_multiple\*(C'\fR,
+\&\f(CW\*(C`gen_delimited_pat\*(C'\fR,
+\&\f(CW\*(C`gen_extract_tagged\*(C'\fR,
+\&\f(CW\*(C`delimited_pat\*(C'\fR.
+.IP "Export Tags" 4
+.IX Item "Export Tags"
+.RS 4
+.PD 0
+.ie n .IP """:ALL""" 4
+.el .IP \f(CW:ALL\fR 4
+.IX Item ":ALL"
+.PD
+\&\f(CW\*(C`extract_delimited\*(C'\fR,
+\&\f(CW\*(C`extract_bracketed\*(C'\fR,
+\&\f(CW\*(C`extract_quotelike\*(C'\fR,
+\&\f(CW\*(C`extract_codeblock\*(C'\fR,
+\&\f(CW\*(C`extract_variable\*(C'\fR,
+\&\f(CW\*(C`extract_tagged\*(C'\fR,
+\&\f(CW\*(C`extract_multiple\*(C'\fR,
+\&\f(CW\*(C`gen_delimited_pat\*(C'\fR,
+\&\f(CW\*(C`gen_extract_tagged\*(C'\fR,
+\&\f(CW\*(C`delimited_pat\*(C'\fR.
+.RE
+.RS 4
+.RE
+.SH "KNOWN BUGS"
+.IX Header "KNOWN BUGS"
+See <https://rt.cpan.org/Dist/Display.html?Status=Active&Queue=Text\-Balanced>.
+.SH FEEDBACK
+.IX Header "FEEDBACK"
+Patches, bug reports, suggestions or any other feedback is welcome.
+.PP
+Patches can be sent as GitHub pull requests at
+<https://github.com/steve\-m\-hay/Text\-Balanced/pulls>.
+.PP
+Bug reports and suggestions can be made on the CPAN Request Tracker at
+<https://rt.cpan.org/Public/Bug/Report.html?Queue=Text\-Balanced>.
+.PP
+Currently active requests on the CPAN Request Tracker can be viewed at
+<https://rt.cpan.org/Public/Dist/Display.html?Status=Active;Queue=Text\-Balanced>.
+.PP
+Please test this distribution.  See CPAN Testers Reports at
+<https://www.cpantesters.org/> for details of how to get involved.
+.PP
+Previous test results on CPAN Testers Reports can be viewed at
+<https://www.cpantesters.org/distro/T/Text\-Balanced.html>.
+.PP
+Please rate this distribution on CPAN Ratings at
+<https://cpanratings.perl.org/rate/?distribution=Text\-Balanced>.
+.SH AVAILABILITY
+.IX Header "AVAILABILITY"
+The latest version of this module is available from CPAN (see
+"CPAN" in perlmodlib for details) at
+.PP
+<https://metacpan.org/release/Text\-Balanced> or
+.PP
+<https://www.cpan.org/authors/id/S/SH/SHAY/> or
+.PP
+<https://www.cpan.org/modules/by\-module/Text/>.
+.PP
+The latest source code is available from GitHub at
+<https://github.com/steve\-m\-hay/Text\-Balanced>.
+.SH INSTALLATION
+.IX Header "INSTALLATION"
+See the \fIINSTALL\fR file.
+.SH AUTHOR
+.IX Header "AUTHOR"
+Damian Conway <damian@conway.org <mailto:damian@conway.org>>.
+.PP
+Steve Hay <shay@cpan.org <mailto:shay@cpan.org>> is now maintaining
+Text::Balanced as of version 2.03.
+.SH COPYRIGHT
+.IX Header "COPYRIGHT"
+Copyright (C) 1997\-2001 Damian Conway.  All rights reserved.
+.PP
+Copyright (C) 2009 Adam Kennedy.
+.PP
+Copyright (C) 2015, 2020, 2022 Steve Hay and other contributors.  All rights
+reserved.
+.SH LICENCE
+.IX Header "LICENCE"
+This module is free software; you can redistribute it and/or modify it under the
+same terms as Perl itself, i.e. under the terms of either the GNU General Public
+License or the Artistic License, as specified in the \fILICENCE\fR file.
+.SH VERSION
+.IX Header "VERSION"
+Version 2.06
+.SH DATE
+.IX Header "DATE"
+05 Jun 2022
+.SH HISTORY
+.IX Header "HISTORY"
+See the \fIChanges\fR file.