expat(3tcl)

📦

version 0.9.6 · 3 versions

0.9.6 · debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking (latest)
0.9.2 · ubuntu jammy
0.9.3 · debian bookworm, ubuntu noble

, in debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

🦋 expat 🦋

ok so real talk, this is the expat(3tcl) page — like, the actual manual page for expat from the Tcl world. bestie, grab a strawberry 🍓 and let's get into it.

✨ NAME ✨

expat — creates an instance of an expat parser object. that's it, that's the whole vibe. 💅

✨ SYNOPSIS ✨

package require tdom

expat ?parsername? ?-namespace? ?arg arg ..

xml::parser ?parsername? ?-namespace? ?arg arg ..

✨ DESCRIPTION ✨

okay so, the parser you get from expat or xml::parser (which is literally just another name for the exact same command, living in its own namespace — same girl, different outfit 💖) can parse any kind of well-formed XML. no cap.

these parsers are stream oriented XML parsers. what that means is: you register handler scripts with the parser before you start the parse. then those handler scripts get called whenever the parser stumbles across the associated structures in the document it's parsing. a start tag is, like, the classic example of a structure you'd register a handler script for. 🌸

the parsers always check the input for XML well-formedness — and yes, they report an error if the input isn't well-formed, they are not letting that slide. they parse the internal DTD and, on request, the external DTD and external entities — but only if you resolve the identifier of those external entities with the -externalentitycommand script (see below, iykyk). and if you use the -validateCmd option (also see below), then the input gets additionally validated. extra credit fr fr.

additionally (yes the original spells it "Additionly", iconic typo, we move), the Tcl extension code that implements this command provides an API for adding C level coded handlers. up to now, there's the parser extension command "tdom". the handler set that this extension installs builds an in-memory "tDOM" DOM tree while the parser is parsing the input. main character energy honestly. 👑

and here's the fun part: it's possible to register an arbitrary amount of different handler scripts and C level handlers for most of the events. when the event happens, they get called in turn. no fighting, everyone gets a turn. 🫶

✨ COMMAND OPTIONS ✨

okay bestie, this is the long part. every single one, here we go. 🎀

-namespace — enables namespace parsing. ⚠️ you must use this option while you're creating the parser with the expat or xml::parser command. you can't enable it (nor disable it) later with <parserobj> configure .... — it's a now-or-never situation, periodt.
-namespaceseparator char — this one only does anything if you're also using -namespace. if you give it, it decides which character gets inserted between the namespace URI and the local name when reporting an XML element name to a handler script. the default is the character ':'. the value has to be a one-character string that's less than or equal to \u00FF, and preferably a 7-bit ASCII character or the empty string. if the value is the empty string (and also if the value is \x00), then the namespace URI and the local name just get concatenated with no separator at all. zero drama. 🦋
-final boolean — tells you whether the document data you're about to hand to the parse method is the final part of the document. a value of "0" means more data is expected. a value of "1" means nothing more is coming. the default value is "1".

if this option is set to "0", then the parser will not report certain errors if the XML data isn't well-formed upon end of input — things like unclosed or unbalanced start or end tags. instead, some data may get saved by the parser until the next call to the parse method, which means the reporting of some of the data gets delayed. it's giving "we'll deal with it later" 🙈

if this option is set to "1", then documents that aren't well-formed upon end of input will generate an error. no mercy.

-validateCmd <tdom schema cmd> — this option expects the name of a tDOM schema command. if you give it, then the input gets also validated. and heads up: if the schema command hasn't set a reportcmd, then the first validation error will stop further parsing (it gets treated the same as a well-formedness error). 😭
-baseurl url — reports the base url of the document to the parser. simple, clean, iconic. ✨
-fastcall boolean — by default this option is 0 (off). if you turn it on, then any handler installed from that moment on by the options -elementstartcommand, -elementendcommand and -characterdatacommand gets installed in a way where calling it has less overhead than usual. you can switch this option on and off between callback handler (re-)installations as much as you want, whenever you want. 💅

⚠️ but there are some requirements, and bestie, these are not optional. the handler proc has to be defined before it's used as a callback. if it isn't, then the callback just gets installed as usual (no speedup, no harm). and the handler proc must not be removed or re-defined for as long as it's being used as a callback. if you do that, the program probably will crash — but it also may execute arbitrary code. yeah. that's a real one. don't do it. 💀

the callback handler installed while this option is on will not be traced when they're executed.

-keepTextStart boolean — by default this option is 0 (off). if you turn it on, then the position information of the start of a text or CDATA node gets kept across the collecting of the sometimes-by-expat-delivered cdata pieces. with this option on, the position information returned by the parser in a -characterdatacommand proc will be correct — otherwise, not so much. but listen: called in all other handler code, the parser always returns the correct position results, no matter what value this option has. it's off by default because it's rarely needed and it saves a few cpu cycles this way. efficiency queen. ⭐
-elementstartcommand script — specifies a Tcl command to associate with the start tag of an element. the actual command consists of this option followed by at least two arguments: the element type name and the attribute list.

the attribute list is a Tcl list made of name/value pairs, suitable for passing straight to the array set Tcl command. perfect for it. 🌈

example:

proc HandleStart {name attlist} {
    puts stderr "Element start ==> $name has attributes $attlist"
}

$parser configure -elementstartcommand HandleStart

$parser parse {<test id="123"></test>}

this would result in the following command being invoked:

HandleStart text {id 123}

-elementendcommand script — specifies a Tcl command to associate with the end tag of an element. the actual command consists of this option followed by at least one argument: the element type name. plus, if the -reportempty option is set, then the command may be invoked with the -empty configuration option to indicate whether it's an empty element. peep the description of the -reportempty option for an example. 👀

example:

proc HandleEnd {name} {
    puts stderr "Element end ==> $name"
}

$parser configure -elementendcommand HandleEnd

$parser parse {<test id="123"></test>}

this would result in the following command being invoked:

HandleEnd test

-characterdatacommand script — specifies a Tcl command to associate with character data in the document, ie. text. the actual command consists of this option followed by one argument: the text.

and here's the good news: other than with the C API of the expat parser, it is guaranteed that character data will be passed to the application in a single call to this command. no tiny fragment chaos. we love that for us. 💖

example:

proc HandleText {data} {
    puts stderr "Character data ==> $data"
}

$parser configure -characterdatacommand HandleText

$parser parse {<test>this is a test document</test>}

this would result in the following command being invoked:

HandleText {this is a test document}

-processinginstructioncommand script — specifies a Tcl command to associate with processing instructions in the document. the actual command consists of this option followed by two arguments: the PI target and the PI data.

example:

proc HandlePI {target data} {
    puts stderr "Processing instruction ==> $target $data"
}

$parser configure -processinginstructioncommand HandlePI

$parser parse {<test><?special this is a processing instruction?></test>}

this would result in the following command being invoked:

HandlePI special {this is a processing instruction}

-notationdeclcommand script — specifies a Tcl command to associate with notation declaration in the document. the actual command consists of this option followed by four arguments: the notation name, the base uri of the document (and by that I mean whatever was set by the -baseurl option), the system identifier and the public identifier. the notation name is never empty; the other arguments may be. 🤷
-externalentitycommand script — specifies a Tcl command to associate with references to external entities in the document. the actual command consists of this option followed by three arguments: the base uri, the system identifier of the entity and the public identifier of the entity. the base uri and the public identifier may be the empty list.

this handler script has to return a tcl list consisting of three elements. the first element of this list signals how the external entity is returned to the processor. at the moment, the three allowed types are "string", "channel" and "filename". the second element of the list has to be the (absolute) base URI of the external entity to be parsed. the third element of the list is the data — either the already-read data out of the external entity as a string, in the case of type "string"; or the name of a tcl channel, in the case of type "channel"; or the path to the external entity to be read, in the case of type "filename". behind the scene, the external entity referenced by that returned Tcl channel, string or file name will be parsed with an expat external entity parser that has the same handler sets as the main parser. 🧚

⚠️ if parsing of the external entity fails, the whole parsing is stopped with an error message.

and if a Tcl command registered as externalentitycommand isn't able to resolve an external entity, it's allowed to return TCL_CONTINUE. in that case, the wrapper gives the next registered externalentitycommand a try. and if no externalentitycommand is able to handle the external entity, parsing stops with an error. 🔥

example:

proc externalEntityRefHandler {base systemId publicId} {
    if {![regexp {^[a-zA-Z]+:/} $systemId]}  {
        regsub {^[a-zA-Z]+:} $base {} base
        set basedir [file dirname $base]
        set systemId "[set basedir]/[set systemId]"
    } else {
        regsub {^[a-zA-Z]+:} $systemId systemId
    }
    if {[catch {set fd [open $systemId]}]} {
        return -code error \
                -errorinfo "Failed to open external entity $systemId"
    }
    return [list channel $systemId $fd]
}

set parser [expat -externalentitycommand externalEntityRefHandler \
                  -baseurl "file:///local/doc/doc.xml" \
                  -paramentityparsing notstandalone]
$parser parse {<?xml version='1.0'?>
<!DOCTYPE test SYSTEM "test.dtd">
<test/>}

and bestie, that would result in this exact command being invoked:

externalEntityRefHandler file:///local/doc/doc.xml test.dtd {}

okay so here's the tea ☕ — external entities are only tried to resolve via this handler script if necessary. Like, only when it's actually needed. That means external parameter entities trigger this handler only if -paramentityparsing is used with argument "always", or if -paramentityparsing is used with argument "notstandalone" and the document isn't marked as standalone. ✨

-unknownencodingcommand script — ngl this one's just not a thing at the Tcl level. Not implemented at Tcl level. 💀
-startnamespacedeclcommand script — names a Tcl command to associate with the start scope of namespace declarations in the document. The actual command is this option followed by two arguments: the namespace prefix and the namespace URI. For an xmlns attribute, prefix will be the empty list. For an xmlns="" attribute, uri will be the empty list. And the call to the start and end element handlers occur between the calls to the start and end namespace declaration handlers. 🎀
-endnamespacedeclcommand script — names a Tcl command to associate with the end scope of namespace declarations in the document. The actual command is this option followed by the namespace prefix as argument. In case of an xmlns attribute, prefix will be the empty list. And again: the call to the start and end element handlers occur between the calls to the start and end namespace declaration handlers. 🫶
-commentcommand script — names a Tcl command to associate with comments in the document. The actual command is this option followed by one argument: the comment data.

Example, periodt:

proc HandleComment {data} {
    puts stderr "Comment ==> $data"
}

$parser configure -commentcommand HandleComment

$parser parse {<test><!-- this is <obviously> a comment --></test>}

and that would result in this command being invoked:

HandleComment { this is <obviously> a comment }

-notstandalonecommand script — this Tcl command gets called if the document is not standalone (meaning it has an external subset or a reference to a parameter entity, but does not have standalone="yes"). It's called with no additional arguments. 👑
-startcdatasectioncommand script — names a Tcl command to associate with the start of a CDATA section. It's called with no additional arguments. 🌈
-endcdatasectioncommand script — names a Tcl command to associate with the end of a CDATA section. It's called with no additional arguments. 🦋
-elementdeclcommand script — names a Tcl command to associate with element declarations. The actual command is this option followed by two arguments: the name of the element and the content model. The content model arg is a tcl list of four elements. The first list element specifies the type of the XML element; the six different possible types are reported as "MIXED", "NAME", "EMPTY", "CHOICE", "SEQ" or "ANY". The second list element reports the quantifier to the content model in XML Syntax ("?", "*" or "+") or is the empty list. If the type is "MIXED", then the quantifier will be "{}", indicating an PCDATA only element, or "*", with the allowed elements to intermix with PCDATA as tcl list as the fourth argument. If the type is "NAME", the name is the third arg; otherwise the third argument is the empty list. If the type is "CHOICE" or "SEQ" the fourth argument will contain a list of content models build like this one. The "EMPTY", "ANY", and "MIXED" types will only occur at top level. 💅

Examples, bestie:

proc elDeclHandler {name content} {
     puts "$name $content"
}

set parser [expat -elementdeclcommand elDeclHandler]
$parser parse {<?xml version='1.0'?>
<!DOCTYPE test [
<!ELEMENT test (#PCDATA)>
]>
<test>foo</test>}

This would result in the following command being invoked:

test {MIXED {} {} {}}

$parser reset
$parser parse {<?xml version='1.0'?>
<!DOCTYPE test [
<!ELEMENT test (a|b)>
]>
<test><a/></test>}

This would result in the following command being invoked:

elDeclHandler test {CHOICE {} {} {{NAME {} a {}} {NAME {} b {}}}}

-attlistdeclcommand script — names a Tcl command to associate with attlist declarations. The actual command is this option followed by five arguments. The Attlist declaration handler is called for each attribute. So a single Attlist declaration with multiple attributes declared will generate multiple calls to this handler. one declaration, many calls — it's giving overachiever. The arguments are the element name this attribute belongs to, the name of the attribute, the type of the attribute, the default value (may be the empty list) and a required flag. If this flag is true and the default value is not the empty list, then this is a "#FIXED" default.

Example:

proc attlistHandler {elname name type default isRequired} {
    puts "$elname $name $type $default $isRequired"
}

set parser [expat -attlistdeclcommand attlistHandler]
$parser parse {<?xml version='1.0'?>
<!DOCTYPE test [
<!ELEMENT test EMPTY>
<!ATTLIST test
          id      ID      #REQUIRED
          name    CDATA   #IMPLIED>
]>
<test/>}

This would result in the following commands being invoked:

attlistHandler test id ID {} 1
attlistHandler test name CDATA {} 0

-startdoctypedeclcommand script — names a Tcl command to associate with the start of the DOCTYPE declaration. This command is called before any DTD or internal subset is parsed. The actual command is this option followed by four arguments: the doctype name, the system identifier, the public identifier and a boolean, that shows if the DOCTYPE has an internal subset. 🔥
-enddoctypedeclcommand script — names a Tcl command to associate with the end of the DOCTYPE declaration. This command is called after processing any external subset. It's called with no additional arguments. ⭐
-paramentityparsing never|notstandalone|always — "never" disables expansion of parameter entities, "always" expands always and "notstandalone" only if the document isn't "standalone='no'". The default ist "never". 🧚
-entitydeclcommand script — names a Tcl command to associate with any entity declaration. The actual command is this option followed by seven arguments: the entity name, a boolean identifying parameter entities, the value of the entity, the base uri, the system identifier, the public identifier and the notation name. According to the type of entity declaration some of this arguments may be the empty list. 🙈
-ignorewhitecdata boolean — if this flag is set, element content which contain only whitespaces isn't reported with the -characterdatacommand. 💜
-ignorewhitespace boolean — another name for -ignorewhitecdata; see there. 🍓
-handlerset name — this option sets the Tcl handler set scope for the configure options. Any option value pair following this option in the same call to the parser are modifying the named Tcl handler set. If you don't use this option, you are modifying the default Tcl handler set, named "default". 👑
-noexpand boolean — normally, the parser will try to expand references to entities defined in the internal subset. If this option is set to a true value this entities are not expanded, but reported literal via the default handler.

⚠️ Warning, bestie, listen up: if you set this option to true and doesn't install a default handler (with the -defaultcommand option) for every handler set of the parser, all internal entities are silent lost for the handler sets without a default handler. Silent. Lost. No cap. 😭

-useForeignDTD <boolean> — if <boolean> is true and the document does not have an external subset, the parser will call the -externalentitycommand script with empty values for the systemId and publicID arguments. This option must be set, before the first piece of data is parsed. Setting this option, after the parsing has started has no effect. The default is not to use a foreign DTD. The default is restored, after resetting the parser.

💀 Pleace notice, that a -paramentityparsing value of "never" (which is the default) suppresses any call to the -externalentitycommand script.

💀 Pleace notice, that, if the document also doesn't have an internal subset, the -startdoctypedeclcommand and enddoctypedeclcommand scripts, if set, are not called.

-billionLaughsAttackProtectionMaximumAmplification <float> — bestie. okay. so. there's a whole Wikipedia article about this at <https://en.wikipedia.org/wiki/Billion_laughs_attack> and you should lowkey read it 💀. This option, together with -billionLaughsAttackProtectionActivationThreshold, is what gives you control over the parser limits that protect against billion laughs attacks. It wants a float that's >= 1.0, nothing less. And honestly? You should never need to touch this one, because the default value (100.0) should already work for any real data. If you ever find yourself needing to raise it for some non-attack payload, please report that — like, actually report it, that's a real thing they want to know 🫶.
-billionLaughsAttackProtectionActivationThreshold <long> — same Wikipedia article, same link, <https://en.wikipedia.org/wiki/Billion_laughs_attack>. This one is the other half of the billion-laughs-defense duo, working together with -billionLaughsAttackProtectionMaximumAmplification to control the parser limits that protect against billion laughs attacks. It expects a positive integer as its argument. Again: you should never need to use this option, because the default (8388608) should work for any real data. And again: if you ever do need to bump it for non-attack payload, please report it. periodt ✨.

🎀 COMMAND METHODS 🎀

These are the methods you call on your parser command. Say hi to your parser, it's the main character now 👑.

parser configure option value ?option value? — sets configuration options for the parser. Every command option can be set or modified through this method… except -namespace, that one does not play. One exception, that's it, that's the rule 💅.
parser cget ?-handlerset name? option — returns the current configuration value of option for the parser. And if you pass in the -handlerset option? Then you get the configuration back for the named handler set instead. Slay, per-set configs 🌸.
parser currentmarkup — hands you the current markup as found in the XML, but only if you call it from inside one of its markup event handler scripts (-elementstartcommand, -elementendcommand, -commentcommand, and -processinginstructioncommand). Call it from literally anywhere else and it returns the empty string. No markup for you, bestie, empty string only 🫥.
parser delete — deletes the parser and the parser command. Gone. Poof. But a parser cannot be deleted from within one of its handler callbacks — neither directly nor indirectly — and if you try it anyway it will raise a Tcl error in this case. Don't do it. It's giving chaos.
parser free — just another name to call the method delete, go look up there ⬆️. Same thing, different name, iconic behavior.
parser get — takes exactly one of these, and you can only request one value at a time:
- -specifiedattributecount — returns the number of attribute/value pairs passed in the last call to the elementstartcommand that were actually specified in the start-tag rather than defaulted in. Each attribute/value pair counts as 2, so this corresponds to an index into the attribute list passed to the elementstartcommand. Math, but make it fashion 🔢.
- -idattributeindex — returns the index of the ID attribute passed in the last call to XML_StartElementHandler, or -1 if there is no ID attribute. Each attribute/value pair counts as 2, so this corresponds to an index into the attributes list passed to the elementstartcommand.
- -currentbytecount — returns the number of bytes in the current event. Returns 0 if the event is in an internal entity. Also, if you use this option, consider whether you may need the parser option -keepTextStart 👀.
- -currentlinenumber — returns the line number of the current parse location. And yep, if you use this option, consider whether you may need the parser option -keepTextStart.
- -currentcolumnnumber — returns the column number of the current parse location. And again, if you use this option, consider whether you may need the parser option -keepTextStart.
- -currentbyteindex — returns the byte index of the current parse location. And once more for the people in the back: if you use this option, consider whether you may need the parser option -keepTextStart.
parser parse data — parses the XML string data. The event callback scripts get called as their triggering events happen. This method cannot be used from within a callback (neither directly nor indirectly) of the parser that's being used, and it will raise an error in this case. Read that again. Not from a callback. Not even indirectly 🙅.
parser parsechannel channelID — reads the XML data out of the Tcl channel channelID (starting at the current access position, without any seek) up to the end of file condition, and parses that data. The channel encoding is respected, as it should be 💖. Use the helper proc tDOM::xmlOpenFile out of the tDOM script library to open a file if you want to use this method. And this method cannot be used from within a callback (neither directly nor indirectly) of the parser to be used, and it will raise an error in this case.
parser parsefile filename — reads the XML data directly out of the file named filename and parses that data. This is done with low-level file operations, very demure, very mindful 🧚. The XML data must be in US-ASCII, ISO-8859-1, UTF-8, or UTF-16 encoding. If applicable, this is the fastest way to parse XML data — speed queen 👑. And this method cannot be used from within a callback (neither directly nor indirectly) of the parser to be used, and it will raise an error in this case.
parser reset — resets the parser in preparation for parsing another document. Fresh start, clean slate, new era 🌈. But a parser cannot be reset from within one of its handler callbacks (neither directly nor indirectly) and will raise a Tcl error in these cases.

💀 Callback Command Return Codes 💀

A script invoked for any of the parser callback commands — think -elementstartcommand, -elementendcommand, etc. — may return an error code other than "ok" or "error". And all callbacks may, in addition, return "break" or "continue". So many options, so much power ✨.

If a callback script returns an "error" error code, then processing of the document is terminated and the error is propagated in the usual fashion. It's over, the doc stops right there 😭.
If a callback script returns a "break" error code, then all further processing of every handler script out of this Tcl handler set is suppressed for the further parsing. This does not influence any other handler set. Stay in your lane, handler set 🎀.
If a callback script returns a "continue" error code, then processing of the current element, and its children, ceases for every handler script out of this Tcl handler set, and processing continues with the next (sibling) element. And nope, this does not influence any other handler set either. Siblings only, bestie 🦋.
If a callback script returns a "return" error code, then parsing is canceled altogether, but no error is raised. Just… quietly leaving the function. No drama, no error, no cap 💅.

🔍 SEE ALSO 🔍

expatapi, tdom

⭐ KEYWORDS ⭐

SAX, push, pushparser

okay that's the whole page, you made it, I'm so proud of you 🥹💖 This one's from the Tcl manual pages — source/version tag Tcl with the page marker expat(3tcl), so if you ever need to cite it, that's the drip. Go forth and parse responsibly, bestie. Mwah 🫶✨

📦 where this page comes from

debian trixie: tdom 0.9.5.1-3 · MPL-2.0
ubuntu questing: tdom 0.9.5.1-3
ubuntu resolute: tdom 0.9.6-2 · MPL-2.0
ubuntu stonking: tdom 0.9.6-3 · MPL-2.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms