text::balanced.3

来自「视频监控网络部分的协议ddns,的模块的实现代码,请大家大胆指正.」· 3 代码 · 共 1,363 行 · 第 1/4 页

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.
.PP
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.
.PP
Examples:
.PP
.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
.PP
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:
.PP
.Vb 1
\&        "if (\*(Aq./cmd\*(Aq =~ m/$UNIXCMD/s) { $cmd = $1; }"
.Ve
.PP
then after the deletion it would contain:
.PP
.Vb 1
\&        "if (\*(Aq.$UNIXCMD/s) { $cmd = $1; }"
.Ve
.PP
not:
.PP
.Vb 1
\&        "if (\*(Aq./cmd\*(Aq =~ ms) { $cmd = $1; }"
.Ve
.PP
See \*(L"extract_quotelike\*(R" for a (partial) solution to this problem.
.ie n .Sh """extract_bracketed"""
.el .Sh "\f(CWextract_bracketed\fP"
.IX Subsection "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).
.PP
\&\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).
.PP
A \*(L"delimiter bracket\*(R" 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.
.PP
A \*(L"balanced-bracket-delimited substring\*(R" 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.
.PP
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
(\*(L"non-delimiter\*(R") bracket in the substring is ignored.
.PP
For example, given the string:
.PP
.Vb 1
\&        $text = "{ an \*(Aq[irregularly :\-(] {} parenthesized >:\-)\*(Aq string }";
.Ve
.PP
then a call to \f(CW\*(C`extract_bracketed\*(C'\fR in a list context:
.PP
.Vb 1
\&        @result = extract_bracketed( $text, \*(Aq{}\*(Aq );
.Ve
.PP
would return:
.PP
.Vb 1
\&        ( "{ an \*(Aq[irregularly :\-(] {} parenthesized >:\-)\*(Aq string }" , "" , "" )
.Ve
.PP
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.)
.PP
Likewise the call in:
.PP
.Vb 1
\&        @result = extract_bracketed( $text, \*(Aq{[\*(Aq );
.Ve
.PP
would return the same result, since all sets of both types of specified
delimiter brackets are correctly nested and balanced.
.PP
However, the call in:
.PP
.Vb 1
\&        @result = extract_bracketed( $text, \*(Aq{([<\*(Aq );
.Ve
.PP
would fail, returning:
.PP
.Vb 1
\&        ( undef , "{ an \*(Aq[irregularly :\-(] {} parenthesized >:\-)\*(Aq string }"  );
.Ve
.PP
because the embedded pairs of \f(CW\*(Aq(..)\*(Aq\fRs and \f(CW\*(Aq[..]\*(Aq\fRs are \*(L"cross-nested\*(R" 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.)
.PP
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).
.PP
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:
.PP
.Vb 1
\&        $text = \*(Aq<A HREF=">>>>">link</A>\*(Aq;
.Ve
.PP
then
.PP
.Vb 1
\&        @result = extract_bracketed( $text, \*(Aq<">\*(Aq );
.Ve
.PP
returns:
.PP
.Vb 1
\&        ( \*(Aq<A HREF=">>>>">\*(Aq, \*(Aqlink</A>\*(Aq, "" )
.Ve
.PP
as expected. Without the specification of \f(CW\*(C`"\*(C'\fR as an embedded quoter:
.PP
.Vb 1
\&        @result = extract_bracketed( $text, \*(Aq<>\*(Aq );
.Ve
.PP
the result would be:
.PP
.Vb 1
\&        ( \*(Aq<A HREF=">\*(Aq, \*(Aq>>>">link</A>\*(Aq, "" )
.Ve
.PP
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:
.PP
.Vb 1
\&        @result = extract_bracketed( $text, \*(Aq<q>\*(Aq );
.Ve
.PP
would correctly match something like this:
.PP
.Vb 1
\&        $text = \*(Aq<leftop: conj /and/ conj>\*(Aq;
.Ve
.PP
See also: \f(CW"extract_quotelike"\fR and \f(CW"extract_codeblock"\fR.
.ie n .Sh """extract_variable"""
.el .Sh "\f(CWextract_variable\fP"
.IX Subsection "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.
.PP
The subroutine takes up to two optional arguments:
.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.
.PP
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),
.PP
On failure, all of these values (except the remaining text) are \f(CW\*(C`undef\*(C'\fR.
.PP
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.
.PP
In a void context, the input text just has the matched substring (and
any specified prefix) removed.
.ie n .Sh """extract_tagged"""
.el .Sh "\f(CWextract_tagged\fP"
.IX Subsection "extract_tagged"
\&\f(CW\*(C`extract_tagged\*(C'\fR extracts and segments text between (balanced)
specified tags.
.PP
The subroutine takes up to five optional arguments:
.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 the opening tag.
If the pattern string is omitted (or \f(CW\*(C`undef\*(C'\fR) then a pattern
that matches any standard \s-1XML\s0 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)
.PP
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 \s-1HTML\s0 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 be 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 \s-1XML\s0 tag, but ignore \*(L"empty\*(R" elements:
.Sp
.Vb 1
\&        extract_tagged($text, undef, undef, undef, {ignore => [\*(Aq<[^>]*/>\*(Aq]} );
.Ve
.Sp
(also see \*(L"gen_delimited_pat\*(R" 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 \*(L"\s-1MAX\s0\*(R", then
\&\f(CW\*(C`extract_tagged\*(C'\fR returns the complete text up to the point of failure.
If the string is \*(L"\s-1PARA\s0\*(R", \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 the default behaviour (i.e. failure) is reinstated.
.Sp
For example, suppose the start tag \*(L"/para\*(R" introduces a paragraph, which then
continues until the next \*(L"/endpara\*(R" tag or until another \*(L"/para\*(R" 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 \*(L"/endpara\*(R" tag is found, the \*(L"/para\*(R"
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.
.PP
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)
.PP
On failure, all of these values (except the remaining text) are \f(CW\*(C`undef\*(C'\fR.
.PP
In a scalar context, \f(CW\*(C`extract_tagged\*(C'\fR returns just the complete