.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.07)
.\"
.\" 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
..
.\" 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 (.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.
.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 "MKDoc::XML::Token 3pm"
.TH MKDoc::XML::Token 3pm "2004-10-06" "perl v5.10.1" "User Contributed Perl Documentation"
.\" 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"
MKDoc::XML::Token \- XML Token Object
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 10
\&  my $tokens = MKDoc::XML::Tokenizer\->process_data ($some_xml);
\&  foreach my $token (@{$tokens})
\&  {
\&      print "\*(Aq" . $token\->as_string() . "\*(Aq is text\en" if (defined $token\->text());
\&      print "\*(Aq" . $token\->as_string() . "\*(Aq is a self closing tag\en" if (defined $token\->tag_self_close());
\&      print "\*(Aq" . $token\->as_string() . "\*(Aq is an opening tag\en" if (defined $token\->tag_open());
\&      print "\*(Aq" . $token\->as_string() . "\*(Aq is a closing tag\en" if (defined $token\->tag_close());
\&      print "\*(Aq" . $token\->as_string() . "\*(Aq is a processing instruction\en" if (defined $token\->pi());
\&      print "\*(Aq" . $token\->as_string() . "\*(Aq is a declaration\en" if (defined $token\->declaration());
\&      print "\*(Aq" . $token\->as_string() . "\*(Aq is a comment\en" if (defined $token\->comment());
\&      print "\*(Aq" . $token\->as_string() . "\*(Aq is a tag\en" if (defined $token\->tag());
\&      print "\*(Aq" . $token\->as_string() . "\*(Aq is a pseudo\-tag (NOT text and NOT tag)\en" if (defined $token\->pseudotag());
\&      print "\*(Aq" . $token\->as_string() . "\*(Aq is a leaf token (NOT opening tag)\en" if (defined $token\->leaf());
\&  }
.Ve
.SH "SUMMARY"
.IX Header "SUMMARY"
MKDoc::XML::Token is an object representing an \s-1XML\s0 token produced by MKDoc::XML::Tokenizer.
.PP
It has a set of methods to identify the type of token it is, as well as to help building a parsed
tree as in MKDoc::XML::TreeBuilder.
.SH "API"
.IX Header "API"
.ie n .SS "my $token = new MKDoc::XML::Token ($string_token);"
.el .SS "my \f(CW$token\fP = new MKDoc::XML::Token ($string_token);"
.IX Subsection "my $token = new MKDoc::XML::Token ($string_token);"
Constructs a new MKDoc::XML::Token object.
.ie n .SS "my $string_token = $token\->\fIas_string()\fP;"
.el .SS "my \f(CW$string_token\fP = \f(CW$token\fP\->\fIas_string()\fP;"
.IX Subsection "my $string_token = $token->as_string();"
Returns the string representation of this token so that:
.PP
.Vb 1
\&  MKDoc::XML::Token\->new ($token)\->as_string eq $token
.Ve
.PP
is a tautology.
.ie n .SS "my $node = $token\->\fIleaf()\fP;"
.el .SS "my \f(CW$node\fP = \f(CW$token\fP\->\fIleaf()\fP;"
.IX Subsection "my $node = $token->leaf();"
If this token is not an opening tag, this method will return its corresponding
node structure as returned by \f(CW$token\fR\->\fItext()\fR, \f(CW$token\fR\->\fItag_self_close()\fR,
etc.
.PP
Returns undef otherwise.
.ie n .SS "my $node = $token\->\fIpseudotag()\fP;"
.el .SS "my \f(CW$node\fP = \f(CW$token\fP\->\fIpseudotag()\fP;"
.IX Subsection "my $node = $token->pseudotag();"
If this token is a comment, declaration or processing instruction,
this method will return \f(CW$token\fR\->\fItag_comment()\fR, $\fItoken_declaration()\fR
or \f(CW$token\fR\->\fIpi()\fR resp.
.PP
Returns undef otherwise.
.ie n .SS "my $node = $token\->\fItag()\fP;"
.el .SS "my \f(CW$node\fP = \f(CW$token\fP\->\fItag()\fP;"
.IX Subsection "my $node = $token->tag();"
If this token is an opening, closing, or self closing tag, this
method will return \f(CW$token\fR\->\fItag_open()\fR, \f(CW$token\fR\->\fItag_close()\fR
or \f(CW$token\fR\->\fItag_self_close()\fR resp.
.PP
Returns undef otherwise.
.ie n .SS "my $node = $token\->\fIcomment()\fP;"
.el .SS "my \f(CW$node\fP = \f(CW$token\fP\->\fIcomment()\fP;"
.IX Subsection "my $node = $token->comment();"
If this token object represents a declaration, the following structure
is returned:
.PP
.Vb 5
\&  # this is <!\-\- I like Pie. Pie is good \-\->
\&  {
\&      _tag   => \*(Aq~comment\*(Aq,
\&      text   => \*(Aq I like Pie. Pie is good \*(Aq,
\&  }
.Ve
.PP
Returns undef otherwise.
.ie n .SS "my $node = $token\->\fIdeclaration()\fP;"
.el .SS "my \f(CW$node\fP = \f(CW$token\fP\->\fIdeclaration()\fP;"
.IX Subsection "my $node = $token->declaration();"
If this token object represents a declaration, the following structure
is returned:
.PP
.Vb 5
\&  # this is <!DOCTYPE foo>
\&  {
\&      _tag   => \*(Aq~declaration\*(Aq,
\&      text   => \*(AqDOCTYPE foo\*(Aq,
\&  }
.Ve
.PP
Returns undef otherwise.
.ie n .SS "my $node = $token\->\fIpi()\fP;"
.el .SS "my \f(CW$node\fP = \f(CW$token\fP\->\fIpi()\fP;"
.IX Subsection "my $node = $token->pi();"
If this token object represents a processing instruction, the following structure
is returned:
.PP
.Vb 5
\&  # this is <?xml version="1.0" charset="UTF\-8"?>
\&  {
\&      _tag   => \*(Aq~pi\*(Aq,
\&      text   => \*(Aqxml version="1.0" charset="UTF\-8"\*(Aq,
\&  }
.Ve
.PP
Returns undef otherwise.
.ie n .SS "my $node = $token\->\fItag_open()\fP;"
.el .SS "my \f(CW$node\fP = \f(CW$token\fP\->\fItag_open()\fP;"
.IX Subsection "my $node = $token->tag_open();"
If this token object represents an opening tag, the following structure
is returned:
.PP
.Vb 8
\&  # this is <aTag foo="bar" baz="buz">
\&  {
\&      _tag   => \*(AqaTag\*(Aq,
\&      _open  => 1,
\&      _close => 0,
\&      foo    => \*(Aqbar\*(Aq,
\&      baz    => \*(Aqbuz\*(Aq,
\&  }
.Ve
.PP
Returns undef otherwise.
.ie n .SS "my $node = $token\->\fItag_close()\fP;"
.el .SS "my \f(CW$node\fP = \f(CW$token\fP\->\fItag_close()\fP;"
.IX Subsection "my $node = $token->tag_close();"
If this token object represents a closing tag, the following structure
is returned:
.PP
.Vb 6
\&  # this is </aTag>
\&  {
\&      _tag   => \*(AqaTag\*(Aq,
\&      _open  => 0,
\&      _close => 1,
\&  }
.Ve
.PP
Returns undef otherwise.
.ie n .SS "my $node = $token\->\fItag_self_close()\fP;"
.el .SS "my \f(CW$node\fP = \f(CW$token\fP\->\fItag_self_close()\fP;"
.IX Subsection "my $node = $token->tag_self_close();"
If this token object represents a self-closing tag, the following structure
is returned:
.PP
.Vb 8
\&  # this is <aTag foo="bar" baz="buz" />
\&  {
\&      _tag   => \*(AqaTag\*(Aq,
\&      _open  => 1,
\&      _close => 1,
\&      foo    => \*(Aqbar\*(Aq,
\&      baz    => \*(Aqbuz\*(Aq,
\&  }
.Ve
.PP
Returns undef otherwise.
.ie n .SS "my $node = $token\->\fItext()\fP;"
.el .SS "my \f(CW$node\fP = \f(CW$token\fP\->\fItext()\fP;"
.IX Subsection "my $node = $token->text();"
If this token object represents a piece of text, then this text is returned.
Returns undef otherwise. \s-1TRAP\s0! \f(CW$token\fR\->\fItext()\fR returns a false value if this
text happens to be '0' or ''. So really you should use:
.PP
.Vb 3
\&  if (defined $token\->text()) {
\&    ... do stuff...
\&  }
.Ve
.SH "NOTES"
.IX Header "NOTES"
MKDoc::XML::Token works with MKDoc::XML::Tokenizer, which can be used
when building a full tree is not necessary. If you need to build a tree, look
at MKDoc::XML::TreeBuilder.
.SH "AUTHOR"
.IX Header "AUTHOR"
Copyright 2003 \- MKDoc Holdings Ltd.
.PP
Author: Jean-Michel Hiver
.PP
This module is free software and is distributed under the same license as Perl
itself. Use it at your own risk.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
MKDoc::XML::Tokenizer
MKDoc::XML::TreeBuilder