From fc22b3d6507c6745911b9dfcc68f1e665ae13dbc Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Mon, 15 Apr 2024 21:43:11 +0200 Subject: Adding upstream version 4.22.0. Signed-off-by: Daniel Baumann --- upstream/mageia-cauldron/man3pm/Text::Balanced.3pm | 1400 ++++++++++++++++++++ 1 file changed, 1400 insertions(+) create mode 100644 upstream/mageia-cauldron/man3pm/Text::Balanced.3pm (limited to 'upstream/mageia-cauldron/man3pm/Text::Balanced.3pm') 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...C pair. Don\*(Aqt allow nested C 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\*(Aq,\*(Aq\*(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 +\&'.*?(?=

)' to skip everything up to the first

tag. Such a prefix +pattern will only succeed if the

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).*?(?=

)' +.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 = \*(Aqlink\*(Aq; +.Ve +.Sp +then +.Sp +.Vb 1 +\& @result = extract_bracketed( $text, \*(Aq<">\*(Aq ); +.Ve +.Sp +returns: +.Sp +.Vb 1 +\& ( \*(Aq\*(Aq, \*(Aqlink\*(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 +\& ( \*(Aqlink\*(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\*(Aq ); +.Ve +.Sp +would correctly match something like this: +.Sp +.Vb 1 +\& $text = \*(Aq\*(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\*(Aq, \*(Aq\*(Aq, undef, {reject => [\*(Aq\*(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 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 "" +\& +\& do { $_ = join \*(Aq\*(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 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`\*(C'\fR directive. For example: +.Sp +.Vb 2 +\& sentence: subject verb object +\& +.Ve +.Sp +Parse::RecDescent uses \f(CW\*(C`extract_codeblock($text, \*(Aq{}<>\*(Aq)\*(C'\fR to extract the code +within the \f(CW\*(C`\*(C'\fR directive, but there's a problem. +.Sp +A deferred action like this: +.Sp +.Vb 1 +\& 10) {$count\-\-}} > +.Ve +.Sp +will be incorrectly parsed as: +.Sp +.Vb 1 +\& +.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 . +.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 +. +.PP +Bug reports and suggestions can be made on the CPAN Request Tracker at +. +.PP +Currently active requests on the CPAN Request Tracker can be viewed at +. +.PP +Please test this distribution. See CPAN Testers Reports at + for details of how to get involved. +.PP +Previous test results on CPAN Testers Reports can be viewed at +. +.PP +Please rate this distribution on CPAN Ratings at +. +.SH AVAILABILITY +.IX Header "AVAILABILITY" +The latest version of this module is available from CPAN (see +"CPAN" in perlmodlib for details) at +.PP + or +.PP + or +.PP +. +.PP +The latest source code is available from GitHub at +. +.SH INSTALLATION +.IX Header "INSTALLATION" +See the \fIINSTALL\fR file. +.SH AUTHOR +.IX Header "AUTHOR" +Damian Conway >. +.PP +Steve Hay > 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. -- cgit v1.2.3