pod::simple::subclassing.3

视频监控网络部分的协议ddns,的模块的实现代码,请大家大胆指正.

.\" 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 "Pod::Simple::Subclassing 3"
.TH Pod::Simple::Subclassing 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"
Pod::Simple::Subclassing \-\- write a formatter as a Pod::Simple subclass
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 5
\&  package Pod::SomeFormatter;
\&  use Pod::Simple;
\&  @ISA = qw(Pod::Simple);
\&  $VERSION = \*(Aq1.01\*(Aq;
\&  use strict;
\&
\&  sub _handle_element_start {
\&    my($parser, $element_name, $attr_hash_r) = @_;
\&    ...
\&  }
\&
\&  sub _handle_element_end {
\&    my($parser, $element_name) = @_;
\&    ...
\&  }
\&
\&  sub _handle_text {
\&    my($parser, $text) = @_;
\&    ...
\&  }
\&  1;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This document is about using Pod::Simple to write a Pod processor,
generally a Pod formatter. If you just want to know about using an
existing Pod formatter, instead see its documentation and see also the
docs in Pod::Simple.
.PP
The zeroeth step in writing a Pod formatter is to make sure that there
isn't already a decent one in \s-1CPAN\s0. See <http://search.cpan.org/>, and
run a search on the name of the format you want to render to. Also
consider joining the Pod People list
<http://lists.perl.org/showlist.cgi?name=pod\-people> and asking whether
anyone has a formatter for that format \*(-- maybe someone cobbled one
together but just hasn't released it.
.PP
The first step in writing a Pod processor is to read perlpodspec,
which contains notes information on writing a Pod parser (which has been
largely taken care of by Pod::Simple), but also a lot of requirements
and recommendations for writing a formatter.
.PP
The second step is to actually learn the format you're planning to
format to \*(-- or at least as much as you need to know to represent Pod,
which probably isn't much.
.PP
The third step is to pick which of Pod::Simple's interfaces you want to
use \*(-- the basic interface via Pod::Simple or Pod::Simple::Methody is
event-based, sort of like HTML::Parser's interface, or sort of like
XML::Parser's \*(L"Handlers\*(R" interface), but Pod::Simple::PullParser
provides a token-stream interface, sort of like HTML::TokeParser's
interface; Pod::Simple::SimpleTree provides a simple tree interface,
rather like XML::Parser's \*(L"Tree\*(R" interface. Users familiar with
XML-handling will find one of these styles relatively familiar; but if
you would be even more at home with \s-1XML\s0, there are classes that produce
an \s-1XML\s0 representation of the Pod stream, notably
Pod::Simple::XMLOutStream; you can feed the output of such a class to
whatever \s-1XML\s0 parsing system you are most at home with.
.PP
The last step is to write your code based on how the events (or tokens,
or tree-nodes, or the \s-1XML\s0, or however you're parsing) will map to
constructs in the output format. Also sure to consider how to escape
text nodes containing arbitrary text, and also what to do with text
nodes that represent preformatted text (from verbatim sections).
.SH "Events"
.IX Header "Events"
\&\s-1TODO\s0 intro... mention that events are supplied for implicits, like for
missing >'s
.PP
In the following section, we use \s-1XML\s0 to represent the event structure
associated with a particular construct.  That is, \s-1TODO\s0
.ie n .IP """$parser\->_handle_element_start( \f(CIelement_name\f(CW, \f(CIattr_hashref\f(CW )""" 4
.el .IP "\f(CW$parser\->_handle_element_start( \f(CIelement_name\f(CW, \f(CIattr_hashref\f(CW )\fR" 4
.IX Item "$parser->_handle_element_start( element_name, attr_hashref )"
.PD 0
.ie n .IP """$parser\->_handle_element_end( \f(CIelement_name\f(CW  )""" 4
.el .IP "\f(CW$parser\->_handle_element_end( \f(CIelement_name\f(CW  )\fR" 4
.IX Item "$parser->_handle_element_end( element_name  )"
.ie n .IP """$parser\->_handle_text(  \f(CItext_string\f(CW  )""" 4
.el .IP "\f(CW$parser\->_handle_text(  \f(CItext_string\f(CW  )\fR" 4
.IX Item "$parser->_handle_text(  text_string  )"
.PD
.PP
\&\s-1TODO\s0 describe
.IP "events with an element_name of Document" 4
.IX Item "events with an element_name of Document"
Parsing a document produces this event structure:
.Sp
.Vb 3
\&  <Document start_line="543">
\&    ...all events...
\&  </Document>
.Ve
.Sp
The value of the \fIstart_line\fR attribute will be the line number of the first
Pod directive in the document.
.Sp
If there is no Pod in the given document, then the 
event structure will be this:
.Sp
.Vb 2
\&  <Document contentless="1" start_line="543">
\&  </Document>
.Ve
.Sp
In that case, the value of the \fIstart_line\fR attribute will not be meaningful;
under current implementations, it will probably be the line number of the
last line in the file.
.IP "events with an element_name of Para" 4
.IX Item "events with an element_name of Para"
Parsing a plain (non-verbatim, non-directive, non-data) paragraph in
a Pod document produces this event structure:
.Sp
.Vb 3
\&    <Para start_line="543">
\&      ...all events in this paragraph...
\&    </Para>
.Ve
.Sp
The value of the \fIstart_line\fR attribute will be the line number of the start
of the paragraph.
.Sp
For example, parsing this paragraph of Pod:
.Sp
.Vb 2
\&  The value of the I<start_line> attribute will be the
\&  line number of the start of the paragraph.
.Ve
.Sp
produces this event structure:
.Sp
.Vb 8
\&    <Para start_line="129">
\&      The value of the 
\&      <I>
\&        start_line
\&      </I>
\&       attribute will be the line number of the first Pod directive
\&      in the document.
\&    </Para>
.Ve
.IP "events with an element_name of B, C, F, or I." 4
.IX Item "events with an element_name of B, C, F, or I."
Parsing a B<...> formatting code (or of course any of its
semantically identical syntactic variants
B<<\ ...\ >>,
or B<<<<\ ...\ >>>>, etc.)
produces this event structure:
.Sp
.Vb 3
\&      <B>
\&        ...stuff...
\&      </B>
.Ve
.Sp
Currently, there are no attributes conveyed.
.Sp
Parsing C, F, or I codes produce the same structure, with only a
different element name.
.Sp
If your parser object has been set to accept other formatting codes,
then they will be presented like these B/C/F/I codes \*(-- i.e., without
any attributes.
.IP "events with an element_name of S" 4
.IX Item "events with an element_name of S"
Normally, parsing an S<...> sequence produces this event
structure, just as if it were a B/C/F/I code:
.Sp
.Vb 3
\&      <S>
\&        ...stuff...
\&      </S>
.Ve
.Sp
However, Pod::Simple (and presumably all derived parsers) offers the
\&\f(CW\*(C`nbsp_for_S\*(C'\fR option which, if enabled, will suppress all S events, and
instead change all spaces in the content to non-breaking spaces. This is
intended for formatters that output to a format that has no code that
means the same as S<...>, but which has a code/character that
means non-breaking space.
.IP "events with an element_name of X" 4
.IX Item "events with an element_name of X"
Normally, parsing an X<...> sequence produces this event
structure, just as if it were a B/C/F/I code:
.Sp
.Vb 3
\&      <X>
\&        ...stuff...
\&      </X>
.Ve
.Sp
However, Pod::Simple (and presumably all derived parsers) offers the
\&\f(CW\*(C`nix_X_codes\*(C'\fR option which, if enabled, will suppress all X events
and ignore their content.  For formatters/processors that don't use
X events, this is presumably quite useful.
.IP "events with an element_name of L" 4
.IX Item "events with an element_name of L"
Because the L<...> is the most complex construct in the
language, it should not surprise you that the events it generates are
the most complex in the language. Most of complexity is hidden away in
the attribute values, so for those of you writing a Pod formatter that
produces a non-hypertextual format, you can just ignore the attributes
and treat an L event structure like a formatting element that
(presumably) doesn't actually produce a change in formatting.  That is,
the content of the L event structure (as opposed to its
attributes) is always what text should be displayed.
.Sp
There are, at first glance, three kinds of L links: \s-1URL\s0, man, and pod.
.Sp
When a L<\fIsome_url\fR> code is parsed, it produces this event
structure:
.Sp
.Vb 3
\&  <L content\-implicit="yes" to="that_url" type="url">
\&    that_url
\&  </L>
.Ve
.Sp
The \f(CW\*(C`type="url"\*(C'\fR attribute is always specified for this type of
L code.
.Sp
For example, this Pod source:
.Sp
.Vb 1
\&  L<http://www.perl.com/CPAN/authors/>
.Ve
.Sp
produces this event structure: