lib/Text/Balanced.pm

7 # the same terms as Perl itself, i.e. under the terms of either the GNU General
1103     # Extract the initial substring of $text that is delimited by
1104     # two (unescaped) instances of the first character in $delim.
1108     # Extract the initial substring of $text that is bracketed
1110     # in $delim contains one or more of '(){}[]<>').
1114     # Extract the initial substring of $text that is bounded by
1119     # Extract the initial substring of $text that is bounded by
1125     # Extract the initial substring of $text that represents a
1130     # Extract the initial substring of $text that represents a block
1131     # of Perl code, bracketed by any of character(s) specified by $delim
1132     # (where the string $delim contains one or more of '(){}[]<>').
1136     # Extract the initial substrings of $text that would be extracted by
1137     # one or more sequential applications of the specified functions
1149     # that matches a substring delimited by any of the specified characters
1150     # (in this case: any type of quote or a slash)
1155     # but pre-compiled and optimized for a specific pair of tags, and
1171 current C<pos> location of the string's variable
1174 extract the first occurrence of a substring anywhere
1176 they extract an occurrence of the substring appearing
1183 elements of which are always:
1194 The remainder of the input string (i.e. the characters after the
1204 Note that in a list context, the contents of the original input text (the first
1231 In a void context the behaviour of the extraction subroutines is
1232 exactly the same as in a scalar context, except (of course) that the
1253 of extracting a single-character-delimited substring from the start of
1266 and extracts the initial substring of the text that
1282 In list context, C<extract_delimited> returns a array of three
1284 delimiters>), the remainder of the text, and the skipped prefix (if
1286 element of the array is the empty string, the second is the complete
1292 removed from the beginning of the first argument.
1296     # Remove a single-quoted substring from the very beginning of $text:
1302     # beginning of $text:
1307     # beginning of $text, optionally after some whitespace
1340 substring (using any one (or more) of the user-specified delimiter
1344 A "delimiter bracket" is a bracket in list of delimiters passed as
1347 of the required bracket(s). Note that the order in which
1353 (right or left) delimiter bracket I<at the same level of nesting>. Any
1354 type of bracket not in the delimiter list is treated as an ordinary
1357 In other words, each type of bracket specified as a delimiter must be
1358 balanced and correctly nested within the substring, and any other kind of
1373 since both sets of C<'{..}'> brackets are properly nested and evenly balanced.
1374 (In a scalar context just the first element of the array would be returned. In
1381 would return the same result, since all sets of both types of specified
1392 because the embedded pairs of C<'(..)'>s and C<'[..]'>s are "cross-nested" and
1400 However, if a particular species of quote character is included in the
1401 delimiter specification, then that type of quote will be correctly handled.
1414 as expected. Without the specification of C<"> as an embedded quoter:
1456 On success in a list context, an array of 3 elements is returned. The
1467 the remainder of the input text,
1475 On failure, all of these values (except the remaining text) are C<undef>.
1554 tag is not encountered (i.e. before the end of the string or some
1559 C<extract_tagged> returns the complete text up to the point of failure.
1590 On success in a list context, an array of 6 elements is returned. The elements are:
1600 the remainder of the input text,
1620 On failure, all of these values (except the remaining text) are C<undef>.
1650 make use of the new qr// construct to pre-compile the regexes they use
1661 In other words, the implementation of C<extract_tagged> is exactly
1681 one of the various Perl quotes and quotelike operators (see
1686         extract_quotelike 'q # an octothorpe: \# (not the end of the q!) #'
1712 This behaviour is identical to that of the actual compiler.
1715 a prefix to be matched at the very beginning of the text. If no prefix
1719 In a list context, an array of 11 elements is returned. The elements are:
1729 the remainder of the input text,
1737 the name of the quotelike operator (if any),
1741 the left delimiter of the first block of the operation,
1745 the text of the first block of the operation
1746 (that is, the contents of
1747 a quote, the regex of a match or substitution or the target list of a
1752 the right delimiter of the first block of the operation,
1756 the left delimiter of the second block of the operation
1761 the text of the second block of the operation
1762 (that is, the replacement of a substitution or the translation list
1763 of a translation),
1767 the right delimiter of the second block of the operation (if any),
1775 For each of the fields marked "(if any)" the default value on success is
1777 On failure, all of these values (except the remaining text) are C<undef>.
1813 Unlike other types of quote-like literals, a here document is rarely
1814 a contiguous substring. For example, a typical piece of code using
1825 the two separate pieces of the here document are successfully extracted and
1839 " || die;\nexit;" (i.e. the remainder of the input text, concatenated),
1847 "<<" (i.e. the "name" of the quotelike operator)
1851 "'EOMSG'" (i.e. the left delimiter of the here document, including any quotes),
1855 "This is the message.\n" (i.e. the text of the here document),
1859 "EOMSG" (i.e. the right delimiter of the here document),
1868 However, the matching position of the input variable would be set to
1869 "exit;" (i.e. I<after> the closing delimiter of the here document),
1871 sequence of code fragment extractions.
1875 rearranges the string to an equivalent piece of Perl:
1884 matching position after the here document, but now the rest of the line
1898 is like a combination of C<"extract_bracketed"> and
1902 a text to process, a set of delimiter brackets to look for, and a prefix to
1911 value of the second argument is to be used for the outermost delimiters.
1983 level of the code block, so the directive is parsed correctly.
1988 list of extractors (subroutines or regular expressions) to apply to that string.
1990 In an array context C<extract_multiple> returns an array of substrings
1991 of the original string, as extracted by the specified extractors.
1996 C<extract_multiple> starts at the current C<pos> of the string, and
1999 Hence, the aim of a call to C<extract_multiple> in a list context
2001 possible, by repeatedly applying each of the specified extractors
2002 to the remainder of the string. Thus C<extract_multiple> is
2003 a generalized form of Perl's C<split> subroutine.
2015 A reference to a list of subroutine references and/or qr// objects and/or
2030 An number specifying the maximum number of fields to return. If this
2037 Note that in scalar and void contexts the value of this argument is
2053 expected to return a list of a single element, namely the extracted
2058 to facilitate the use of other Text::Balanced subroutines with
2061 of the original text (see examples below).
2070 The value of that element is one of the
2072 The key of that element is the name of a class into which the successful
2073 return value of the extractor will be blessed.
2076 treated as the next extracted field and pushed onto the list of fields.
2080 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
2082 If none of the extractor subroutines succeeds, then one
2083 character is extracted from the start of the text and the extraction
2138 by any one of the characters in the single argument. For example:
2148 A typical use of C<gen_delimited_pat> would be to build special purpose tags
2187 Accessing C<$@-E<gt>{error}> returns one of the error diagnostics listed
2200 The delimiter provided to C<extract_bracketed> was not one of
2205 A non-optional prefix was specified but wasn't found at the start of the text.
2210 particular kind of bracket at the start of the text, and didn't find it.
2214 C<extract_quotelike> didn't find one of the quotelike operators C<q>,
2215 C<qq>, C<qw>, C<qx>, C<s>, C<tr> or C<y> at the start of the substring
2226 out of characters in the text before closing one or more levels of nested
2247 C<extract_quotelike> or C<extract_codeblock> found one of the
2253 C<extract_variable> was expecting one of '$', '@', or '%' at the start of
2254 a variable, but didn't find any of them.
2263 C<extract_codeblock> failed to find any of the outermost opening brackets
2273 C<extract_codeblock> or C<extract_quotelike> found one of the
2292 bracket of some kind.
2306 C<extract_tagged> reached the end of the text without finding a closing tag
2374 L<https://www.cpantesters.org/> for details of how to get involved.
2384 The latest version of this module is available from CPAN (see
2405 Text::Balanced as of version 2.03.
2419 same terms as Perl itself, i.e. under the terms of either the GNU General Public