MKDoc:...::Token(3pm)

🌸 MKDoc:...::Token ✨

okay bestie, grab a boba because we're about to talk about a whole module — it's MKDoc::...::Token, a lil Perl thingy that lives in the User Contributed Perl Documentation section of your man pages. think of it as one (1) single XML token, in object form. tiny. iconic. does exactly one job. we love her 💅

---

💖 NAME 💖

MKDoc::XML::Token — it's an XML Token Object. that's the whole vibe. one token, one object, no cap ✨

---

🎀 SYNOPSIS 🎀

here's the whole flex, verbatim, because we do not paraphrase code in this house:

my $tokens = MKDoc::XML::Tokenizer->process_data ($some_xml);
foreach my $token (@{$tokens})
{
    print "'" . $token->as_string() . "' is text\n" if (defined $token->text());
    print "'" . $token->as_string() . "' is a self closing tag\n" if (defined $token->tag_self_close());
    print "'" . $token->as_string() . "' is an opening tag\n" if (defined $token->tag_open());
    print "'" . $token->as_string() . "' is a closing tag\n" if (defined $token->tag_close());
    print "'" . $token->as_string() . "' is a processing instruction\n" if (defined $token->pi());
    print "'" . $token->as_string() . "' is a declaration\n" if (defined $token->declaration());
    print "'" . $token->as_string() . "' is a comment\n" if (defined $token->comment());
    print "'" . $token->as_string() . "' is a tag\n" if (defined $token->tag());
    print "'" . $token->as_string() . "' is a pseudo-tag (NOT text and NOT tag)\n" if (defined $token->pseudotag());
    print "'" . $token->as_string() . "' is a leaf token (NOT opening tag)\n" if (defined $token->leaf());
}

so you loop through your tokens, you ask each one "bestie what ARE you", and she tells you. it's giving ✨ main character energy ✨ but for XML parsing. fr fr.

---

🌈 SUMMARY 🌈

okay so MKDoc::XML::Token is an object that represents an XML token produced by MKDoc::XML::Tokenizer. that's the whole origin story. no tragic backstory, just tokens 🦋

she comes with a whole set of methods so you can figure out what type of token she is, plus some extra ones that help you build a parsed tree — exactly like the ones in MKDoc::XML::TreeBuilder. so like, she's a helper, she's a queen, she does both 👑

---

👑 API 👑

💜 my $token = new MKDoc::XML::Token ($string_token);

constructs a brand new MKDoc::XML::Token object. fresh out the box. newborn token, zero thoughts, just vibes 💜

💜 my $string_token = $token->as_string();

hands you back the string representation of this token, and the way she does it means that:

MKDoc::XML::Token->new ($token)->as_string eq $token

is a tautology. like, round-trip so clean it's basically a mirror. you put a string in, you get that exact string out. no notes. perfection 🌸

💜 my $node = $token->leaf();

if this token is NOT an opening tag, this method returns her corresponding node structure — the same thing you'd get from $token->text(), $token->tag_self_close(), etc.

otherwise, bestie, you get undef. 🙈

💜 my $node = $token->pseudotag();

if this token is a comment, a declaration or a processing instruction, this returns $token->tag_comment(), $token_declaration() or $token->pi() respectively.

otherwise? undef. 💀

💜 my $node = $token->tag();

if this token is an opening, closing or self closing tag, you get $token->tag_open(), $token->tag_close() or $token->tag_self_close() respectively.

otherwise: undef. that's the pattern, get used to her 🎀

💜 my $node = $token->comment();

if this token object represents a declaration, here's the structure you get back:

# this is <!-- I like Pie. Pie is good -->
{
    _tag   => '~comment',
    text   => ' I like Pie. Pie is good ',
}

(and yes, the original really does say "declaration" right there in the comment method. we don't fix it, we just report it 😭)

otherwise: undef.

💜 my $node = $token->declaration();

if this token object represents a declaration, you get this structure:

# this is <!DOCTYPE foo>
{
    _tag   => '~declaration',
    text   => 'DOCTYPE foo',
}

otherwise: undef. classic.

💜 my $node = $token->pi();

if this token object represents a processing instruction, you get:

# this is <?xml version="1.0" charset="UTF-8"?>
{
    _tag   => '~pi',
    text   => 'xml version="1.0" charset="UTF-8"',
}

otherwise: undef. as always ✨

💜 my $node = $token->tag_open();

if this token object represents an opening tag, you get:

# this is <aTag foo="bar" baz="buz">
{
    _tag   => 'aTag',
    _open  => 1,
    _close => 0,
    foo    => 'bar',
    baz    => 'buz',
}

look at those attributes just... living there as hash keys. obsessed. 😍

otherwise: undef.

💜 my $node = $token->tag_close();

if this token object represents a closing tag, you get:

# this is </aTag>
{
    _tag   => 'aTag',
    _open  => 0,
    _close => 1,
}

notice she flipped _open and _close. balanced. symmetrical. slay 🌸

otherwise: undef.

💜 my $node = $token->tag_self_close();

if this token object represents a self-closing tag, you get:

# this is <aTag foo="bar" baz="buz" />
{
    _tag   => 'aTag',
    _open  => 1,
    _close => 1,
    foo    => 'bar',
    baz    => 'buz',
}

_open AND _close both true — because she is literally both, she contains multitudes, she's the moment 🌈

otherwise: undef.

💜 my $node = $token->text();

if this token object represents a piece of text, then that text is what you get back. otherwise: undef.

⚠️ TRAP! $token->text() returns a FALSE value if the text happens to be '0' or ''. so like, the text could absolutely be there and you'd still get a falsey answer. so really, bestie, you should use: perl if (defined $token->text()) { ... do stuff... } check with defined, not truthiness. do not get got. i am begging 🙏💀

---

🧚 NOTES 🧚

MKDoc::XML::Token works together with MKDoc::XML::Tokenizer — and that combo is the move when building a full tree is not necessary. if you DO need a tree though? go look at MKDoc::XML::TreeBuilder. different tool, different vibe, same family 🫶

---

✨ AUTHOR ✨

Copyright 2003 - MKDoc Holdings Ltd.

Author: Jean-Michel Hiver

This module is free software and is distributed under the same license as Perl itself. Use it at your own risk. (yes bestie, at your OWN risk, we said what we said 💅)

---

🌟 SEE ALSO 🌟

• MKDoc::XML::Tokenizer
• MKDoc::XML::TreeBuilder

go read them, they're her friends 🦋

---

and that's the whole page, bestie!! this one shipped as perl v5.36.0, dated 2022-10-13, straight out of the MKDoc:...::Token(3pm) man page. mwah. go parse something beautiful 💖✨🎀