text::balanced.3

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

.\" Automatically generated by Pod::Man 2.16 (Pod::Simple 3.05)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.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
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'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 turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Text::Balanced 3"
.TH Text::Balanced 3 "2007-12-18" "perl v5.10.0" "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 8
\& 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,
\&                                      ]);
.Ve
.PP
# 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)
.PP
.Vb 1
\&        $patstring = gen_delimited_pat(q{\*(Aq"\`/});
.Ve
.PP
# 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, so it only works under Perl 5.005 or later.
.PP
.Vb 1
\&        $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).
.Sh "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
.Sh "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.
.Sh "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>)'
.ie n .Sh """extract_delimited"""
.el .Sh "\f(CWextract_delimited\fP"
.IX Subsection "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:
.PP
.Vb 2
\&        ($remainder = $text) =~ s/\eA(\*(Aq(\e\e.|[^\*(Aq])*\*(Aq)//s;
\&        $extracted = $1;
.Ve
.PP
but with \f(CW\*(C`extract_delimited\*(C'\fR it can be simplified to:
.PP
.Vb 1
\&        ($extracted,$remainder) = extract_delimited($text, "\*(Aq");
.Ve
.PP
\&\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.
.PP
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.
.PP