pullparser(n)

💖 pullparser(n) 💖

okay bestie, gather round, because we're about to make a pull parser and it's gonna be so much fun, no cap ✨

---

🎀 NAME 🎀

tdom::pullparser — creates an XML pull parser command. that's the whole vibe. one command, endless possibilities, main character energy fr fr 💅

---

🌸 SYNOPSIS 🌸

package require tdom

tdom::pullparser cmdName  ? -ignorewhitecdata ?

---

🦋 DESCRIPTION 🦋

so this command makes XML pull parser commands with a simple API, in the style of a basic StAX parser. lowkey elegant, highkey useful. 🫶

okay but here's the thing — after you create it, you have to set an input source before it'll do literally anything useful. no input, no vibes. for that, go look at the input, inputchannel and inputfile methods. they're your besties here 💜

the parser always has a state. that's just how it lives. you start parsing the XML data until some next state, do whatever needs doing, then skip along to the next state. and if there's an XML well-formedness error along the way? it gets reported as TCL_ERROR with extra info in the error message. so pay attention 👀

now, the lore:

• these pull parsers don't follow external entities and they're XML 1.0 only
• they know nothing about XML Namespaces. zero. nada. 🙈
• you get the tags and attribute names as in the source
• you aren't notified about comments, processing instructions and external entities — they're silently ignored for you. like they're not even there
• CDATA Sections are handled as if their content had been provided without using a CDATA Section

but on the brighter side ☀️ — character entity and attribute default declarations in the internal subset are respected (because it uses expat as the underlying parser 🧚). it's probably somewhat faster than a comparable implementation with the SAX interface. it's a nice programming model. it's a slim interface. slay.

if the option -ignorewhitecdata is given, the created XML pull parser command will ignore any white space only (' ', \t, \n and \r) text content between START_TAG and START_TAG / END_TAG. the parser won't stop at such input, and will create TEXT state events only for not white space only text. periodt.

not all methods are valid in every state!! if you call a method in a state it isn't valid for, the parser raises TCL_ERROR. respect the boundaries bestie 😤

the valid methods of the created commands are:

• state — this method is valid in all parser states. the possible return values and their meanings are:
  • READY — the parser is created or reset, but no input is set.
  • START_DOCUMENT — input is set, parser is ready to start parsing.
  • START_TAG — parser has stopped parsing at a start tag.
  • END_TAG — parser has stopped parsing at an end tag.
  • TEXT — parser has stopped parsing to report text between tags.
  • END_DOKUMENT — parser has finished parsing without error. (yes, that's spelled END_DOKUMENT, i don't make the rules 💀)
  • PARSE_ERROR — parser stopped parsing at XML error in input.
• input data — only valid in state READY. it prepares the parser to use data as the XML input to parse, and switches the parser into state START_DOCUMENT. ✨
• inputchannel channel — only valid in state READY. it prepares the parser to read the XML input to parse out of channel, and switches the parser into state START_DOCUMENT.
• inputfile filename — only valid in state READY. it opens filename and prepares the parser to read the XML input to parse out of that file. it returns TCL_ERROR if the file could not be opened in read mode. otherwise it switches the parser into state START_DOCUMENT.
• next — valid in state START_DOCUMENT, START_TAG, END_TAG and TEXT. it continues parsing the XML input until the next event, which it will return. go off 👑
• tag — only valid in states START_TAG and END_TAG. it returns the tag name of the current start or end tag.
• attributes — only valid in state START_TAG. it returns all attributes of the element in a name value list.
• text — only valid in state TEXT. it returns the character data of the event. there will always be at most one TEXT event between START_TAG and the next START_TAG or END_TAG event.
• skip — only valid in state START_TAG. it skips to the corresponding end tag, ignores all events on the way (but not XML parsing errors, those still come for you 😭), and returns the new state END_TAG.
• find-element ? tagname | -names tagnames ? — only valid in states START_DOCUMENT, START_TAG and END_TAG. it skips forward until the next element start tag with tag name tagname and returns the new state START_TAG. if a list of tagnames is provided with the -names option, any of the tagnames match. if there isn't such an element, the parser stops at the end of the input and returns END_DOCUMENT. it's giving search bar energy 🔍
• reset — valid in all parser states. it resets the parser into READY state and returns that. fresh start, new me 🧖
• delete — valid in all parser states. it deletes the parser command. bye bestie 💀

💫 Miscellaneous methods 💫

• line — valid in all parser states except READY and TEXT. it returns the line number of the parsing position. line counting starts with 1.
• column — valid in all parser states except READY and TEXT. it returns the offset, from the beginning of the current line, of the parsing position. column counting starts with 0.

---

⭐ KEYWORDS ⭐

XML, pull, parsing

---

okay that's the whole page 🫶 this came to you from the Tcl corner of the universe, manual name pullparser(n) — and that's on periodt 💅✨🌈