tnc(3tcl)

💖 NAME 💖

tnc — bestie, this is the tnc(3tcl) page, and here's the whole vibe: tnc is an expat parser object extension that validates the XML stream against the document DTD while it's parsing. like, validation and parsing at the same time, multitasking icon behavior 👑

🌸 SYNOPSIS 🌸

package require tdom
package require tnc

set parser [expat]

tnc $parser enable

✨ DESCRIPTION ✨

okay so: tnc adds the C handler set "tnc" to a tcl expat parser obj. that handler set is literally just a simple DTD validator. and if the validator detects a validation error, it sets the interp result, signals error, and stops parsing. that's the whole response. there isn't any validation error recovering — not even a little 🫶. as a consequence, only valid documents are completely parsed. that's just how she runs.

this handler set has only three methods:

• tnc parserObj enable — adds the tnc C handler set to a Tcl expat parser object 💅
• tnc parserObj remove — removes the tnc validatore from the parser parserObj and frees all information, stored by it. (yes, "validatore". she's iconic, we don't correct her 💀)
• tnc parserObj getValidateCmd ?validateCmdName? — returns a new created validation command, if one is available from the parser command, otherwise it signals error. the name of the validation command is the validateCmdName, if this optional argument was given, or a random chosen name.

so when is a validation command actually available from a parser command? lowkey specific: when the parser with tnc enabled was previously used to parse an XML document with a valid doctype declaration, a valid external subset (if one was given by the doctype declaration), and a valid internal subset. the further document doesn't need to be valid for the validation command to become available — ngl that's generous of her. and heads up: the validation command can only get received one time from the parser command. one. single. use. no take-backsies 🌸

the created validation command has this syntax:

validationCmd method ?args?

🎀 the valid methods 🎀

• validateDocument domDocument ?varName? — checks if the given domDocument is valid against the DTD information represented by the validation command. returns 1 if the document ist valid, 0 otherwise. if the varName argument is given, then the variable it names is set to the detected reason for the validation error, or to the empty string in case of a valid document 🦋
• validateTree elementNode ?varName? — checks if the given subtree with domNode as root element is a possible valid subtree of a document conforming to the DTD information represented by the validation command. IDREF could not checked, while validating only a subtree, but it is checked that every known ID attribute in the subtree is unique. returns 1 if the subtree is OK, 0 otherwise. if the varName argument is given, then the variable it names is set to the detected reason for the validation error, or to the empty string in case of a valid subtree ⭐
• validateAttributes elementNode ?varName? — checks if there is an element declaration for the name of the elementNode in the DTD represented by the validation command and, if yes, if the attributes of the elementNode are conform to the ATTLIST declarations for that element in the DTD. returns 1 if the attributes and there value types are OK, 0 otherwise. if the varName argument is given, then the variable it names is set to the detected reason for the validation error, or to the empty string in case the element has all its required attributes, only declared attributes, and the values of the attributes matches there type 💜
• delete — deletes the validation command and frees the memory used by it. returns the empty string ✨

💀 BUGS 💀

okay bestie, the not-so-great parts. keeping it real:

the validation error reports could be much more informative and user-friendly. she's trying her best but the error messages are giving cryptic 😭

the validator doesn't detect ambiguous content models (see XML recomendation Section 3.2.1 and Appendix E). most Java validators also doesn't, but handle such content models right anyhow. Tnc does not; if your DTD has such ambiguous content models, tnc can not used to validate documents against such (not completely XML spec compliant) DTDs. so like, know your DTD before you come for her 🙈

it isn't possible to validate XML documents with standalone="yes" in the XML Declaration. nope. not happening.

and finally — violations of the validity constraints Proper Group/PE Nesting and Proper Conditional Section/PE Nesting are not detected. they could only happen inside a invalid DTD, not in the content of a document. so it's a niche little blind spot, but a blind spot regardless 🎀

🌈 KEYWORDS 🌈

Validation, DTD

and that's the whole page, fr fr 🫶 she's from the Tcl crew, this is tnc(3tcl), and if you read all the way down here you are genuinely the main character. slay 💅👑