dom(3tcl)

📦
version 0.9.6 · 4 versions
, in ubuntu resolute, ubuntu stonking

💖 NAME 💖

okay so this is dom from the 3tcl manual — Create an in-memory DOM tree from XML. yes bestie, we're building trees, and they're in memory ✨

🦋 SYNOPSIS 🦋

package require tdom

dom method ?arg arg ...?

🌸 DESCRIPTION 🌸

This command is the whole vibe for creating DOM trees in memory. In the usual case, a string holding some XML information gets parsed and converted into a DOM tree. But that's not the only glow-up available — other possible parse input may be HTML or JSON 👑

The method tells it which specific subcommand you want. Slay.

The valid methods are:

  • dom parse ?options? ?data? — parses the XML information and builds up the DOM tree in memory, handing you back a Tcl object command pointing at this DOM document object. Example:
dom parse $xml doc
$doc documentElement root

So this parses the XML sitting in the variable xml, creates the DOM tree in memory, makes a reference to the document object (visible in Tcl as a document object command), and assigns this new object name to the variable doc. 🫶 And listen — when doc gets freed, the DOM tree and the associated Tcl command object (document and all node objects) are freed automatically. no cleanup anxiety, we love that for us.

set document [dom parse $xml]
set root     [$document documentElement]

This one parses the XML in the variable xml, creates the DOM tree in memory, makes a reference to the document object (visible in Tcl as a document object command), and returns this new object name — which then gets stored in document. 💅 But heads up: to free the underlying DOM tree and the associative Tcl object commands (document + nodes + fragment nodes), the document object command has to be explicitly deleted, like this:

$document delete

or

rename $document ""
🚨 bestie this is the part where you actually have to let it go. it does not free itself in this case. periodt.

✨ the options, bestie ✨

The valid options are:

  • -simple — if -simple is specified, a simple but fast parser is used (it conforms not fully to XML recommendation). That should double parsing and DOM generation speed 🔥. The encoding of the data is not transformed inside the parser. The simple parser does not respect any encoding information in the XML declaration. It skips over the internal DTD subset and ignores any information in it. Therefore, it doesn't include defaulted attribute values into the tree, even if the according attribute declaration is in the internal subset. It also doesn't expand internal or external entity references other than the predefined entities and character references. 😭 (it's giving "fast and loose")
  • -html — if -html is specified, a fast HTML parser is used, which tries to even parse badly formed HTML into a DOM tree 🙈. If the HTML document given to parse does not have a single root element (as it was legal up to HTML 4.01) and the -forest option is not used, then a html node will be inserted as document element, with the HTML input data top level elements as children.
  • -html5 — this option is only available if tDOM was build with --enable-html5. Use the featureinfo method if you need to know if this feature is build in. If -html5 is specified, the gumbo lib html5 parser (https://github.com/google/gumbo-parser) is used to build the DOM tree. This is, as far as it goes, XML namespace-aware (which means for example that all HTML elements are in the html5 namespace). Since this probably isn't wanted by a lot of users and adds only burden for no good in a lot of use cases, -html5 can be combined with -ignorexmlns, in which case all nodes and attributes in the DOM tree are not in an XML namespace. All tag and attribute names in the DOM tree will be lower case, even for foreign elements not in the xhtml, svg or mathml namespace. The DOM tree may include nodes that the parser inserted because they are implied by the context (as <head>, <tbody>, etc.). Input longer than 4 GByte byte length is not supported by the underlying gumbo parser. 💀 (4 GByte is the limit, don't test it)
  • -json — if -json is specified, the data is expected to be a valid JSON string (according to RFC 7159). The command returns an ordinary DOM document with nesting token inside the JSON data translated into tree hierarchy. If a JSON array value is itself an object or array then container element nodes named (in a default build) arraycontainer or objectcontainer, respectively, are inserted into the tree. The JSON serialization of this document (with the domDoc method asJSON) is the same JSON information as the data, preserving JSON datatypes, allowing non-unique member names of objects while preserving their order and the full range of JSON string values. JSON datatype handling is done with an additional property "sticking" at the doc and tree nodes. This property isn't contained in an XML serialization of the document. If you need to store the JSON data represented by a document, store the JSON serialization and parse it back from there. 🎀 Apart from this JSON type information the returned doc command or handle is an ordinary DOM doc, which may be investigated or modified with the full range of the doc and node methods. Please note that the element node names and the text node values within the tree may be outside of what the appropriate XML productions allow. 👀
  • -jsonroot <document element name> — if given, makes the given element name the document element of the resulting doc. The parsed content of the JSON string will be the children of this document element node.
  • -jsonmaxnesting integer — this option only has effect if used together with the -json option. The current implementation uses a recursive descent JSON parser. In order to avoid using excess stack space, any JSON input that has more than a certain levels of nesting is considered invalid. The default maximum nesting is 2000. The option -jsonmaxnesting allows the user to adjust that. 🧚
  • -- — the option -- marks the end of options. To give this option isn't strictly necessary even in the case of JSON parsing, for which valid data may start with a -. If parsing json and if the second to last or last argument start with a - and isn't a known option name it will be treated as JSON data.
  • -keepEmpties — if -keepEmpties is specified then text nodes which contain only whitespaces will be part of the resulting DOM tree. In default case (-keepEmpties not given) those empty text nodes are removed at parsing time. 🌸
  • -keepCDATA — if -keepCDATA is specified then CDATA sections aren't added to the tree as text nodes (and, if necessary, combined with sibling text nodes into one text node) as without this option, but are added as CDATA_SECTION_NODEs to the tree. Please note that the resulting tree isn't prepared for XPath selects or to be the source or the stylesheet of an XSLT transformation. ⚠️ If not combined with -keepEmpties only not whitespace only CDATA sections will be added to the resulting DOM tree.
  • -channel <channel-ID> — if -channel <channel-ID> is specified, the input to be parsed is read from the specified channel. The encoding setting of the channel (via fconfigure -encoding) is respected, ie the data read from the channel are converted to UTF-8 according to the encoding settings before the data is parsed. 💜
  • -baseurl <baseURI> — if -baseurl <baseURI> is specified, the baseURI is used as the base URI of the document. External entities references in the document are resolved relative to this base URI. This base URI is also stored within the DOM tree.
  • -feedbackAfter <#bytes> — if -feedbackAfter <#bytes> is specified, the Tcl command given by -feedbackcmd is evaluated at the first element start within the document (or an external entity) after the start of the document or external entity or the last such call after #bytes. For backward compatibility if no -feedbackcmd is given but there is a Tcl proc named ::dom::domParseFeedback this proc is used as -feedbackcmd. If there isn't such a proc and -feedbackAfter is used it is an error to not also use -feedbackcmd. If the called script raises error, then parsing will be aborted, the dom parse call returns error, with the script error msg as error msg. If the called script return -code break, the parsing will abort and the dom parse call will return the empty string. 😭
  • -feedbackcmd <script> — if -feedbackcmd <script> is specified, the script script is evaluated at the first element start within the document (or an external entity) after the start of the document or external entity or the last such call after #bytes value given by the -feedbackAfter option. If -feedbackAfter isn't given, using this option doesn't has any effect. If the called script raises error, then parsing will be aborted, the dom parse call returns error, with the script error msg as error msg. If the called script return -code break, the parsing will abort and the dom parse call will return the empty string. 💅

okay that's the parse method and its whole option family — but bestie, we are SO not done, there's more of this page coming 👀

  • -externalentitycommand <script> — bestie, if you set this, your Tcl script gets called to resolve any external entities of the document 💖. The actual command that gets evaluated is this option plus three arguments: the base uri, the system identifier of the entity, and the public identifier of the entity. Heads up: the base uri and the public identifier may be the empty list. Your script has to return a Tcl list with three elements:
    1. the first element signals how the external entity is handed back to the processor — currently the only two allowed types are "string" and "channel";
    2. the second element has to be the (absolute) base URI of the external entity to be parsed;
    3. the third element is the data — either the already-read data out of the external entity as a string (type "string"), or the name of a Tcl channel (type "channel").
ngl this one matters: if your script returns a Tcl channel, it will not be closed by the processor. You have to close it separately if it's no longer needed. 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 👀. Also pls note: if the document also doesn't have an internal subset, the -startdoctypedeclcommand and -enddoctypedeclcommand scripts, if set, are not called.
  • -paramentityparsing <always|never|notstandalone> — this one controls whether the parser tries to resolve the external entities (including the external DTD subset) of the document while it's building the DOM tree 🌈. It requires an argument, and it must be either "always", "never", or "notstandalone":
    • "always" — the parser tries to resolve (recursively) all external entities of the XML source. This is the default when -paramentityparsing is omitted ✨.
    • "never" — only the given XML source is parsed, and no external entity (including the external subset) will be resolved and parsed 🙅.
    • "notstandalone" — all external entities will be resolved and parsed, except for documents that explicitly state standalone="yes" in their XML declaration 👑.
  • -forest — give this option and you don't need a single root 🌲! Any sequence of well-formed, balanced subtrees will be parsed into a DOM tree. This works for the expat DOM builder, the simple xml parser enabled with -simple and the simple HTML parser enabled -with -html. If you use it together with -json or -html5, this option is ignored 💀.
  • -ignorexmlns — okay so it is recommended that you only use this option with the -html5 option 🎀. If given, no node within the created DOM tree will be internally marked as placed into an XML Namespace — not even if there's a default namespace in scope for un-prefixed elements, and not even if the element has a defined namespace prefix. One consequence: XPath node expressions on such a DOM tree don't work as may be expected 😭. Prefixed element nodes can't be selected naively, and element nodes without a prefix will be seen by XPath expressions as if they're not in any namespace (no matter if they in fact should be in a default namespace). If you need to inject prefixed node names into an XPath expression, use the % syntax described in the documentation of the of the domNode command method selectNodes 💅.
  • -billionLaughsAttackProtectionMaximumAmplification <float> — <URL: https://en.wikipedia.org/wiki/Billion_laughs_attack> — this option, together with -billionLaughsAttackProtectionActivationThreshold, gives you control over the parser limits that protect against billion laugh attacks 😱. It expects a float >= 1.0 as its argument. You should never need to use this option, because the default value (100.0) should work for any real data. If you ever do need to increase this value for non-attack payload, please report 🙏.
  • -billionLaughsAttackProtectionActivationThreshold <long> — <URL: https://en.wikipedia.org/wiki/Billion_laughs_attack> — this option, together with -billionLaughsAttackProtectionMaximumAmplification, gives you control over the parser limits that protect against billion laugh attacks 😱. It expects a positiv integer as its argument. You should never need to use this option, because the default value (8388608) should work for any real data. If you ever need to increase this value for non-attack payload, please report 🙏.
  • dom createDocument docElemName ?objVar? — creates a brand new DOM document object with one element node whose node name is docElemName 🌱. The objVar controls the memory handling, as explained above ✨.
  • dom createDocumentNS uri docElemName ?objVar? — creates a new DOM document object with one element node whose node name is docElemName 🌱. Uri gives the namespace of the document element to create. The objVar controls the memory handling, as explained above ✨.
  • dom createDocumentNode ?-jsonType jsonType? ?objVar? — creates a new 'empty' DOM document object without any element node 🫧. objVar controls the memory handling, as explained above. If the option -jsonType is given, the created document node will be of the given JSON type 💜.
  • dom createFromTypedList typedList ?objVar? — creates a new DOM document from the argument typedList 📋. The objVar argument controls the memory handling, as explained above. The typedList argument must be a Tcl list and must follow the format of the output of the document command method asTypedList, see there 👀.
  • dom createNodeCmd ?-returnNodeCmd? ?-tagName name? ?-jsonType jsonType? ?-namespace URI? ?-noNamespacedAttributes? ?-notempty? (element|comment|text|cdata|pi)Node commandName — this method creates Tcl commands, which in turn create tDOM nodes 🛠️. Important vibe check: Tcl commands created by this command are only available inside a script given to the domNode methods appendFromScript or insertBeforeFromScript. If a command created with createNodeCmd is invoked in any other context, it will return error ❌. The created command commandName replaces any existing command or procedure with that name. If the commandName includes any Tcl namespace qualifiers, it's created in the specified namespace. The -tagName option is only allowed for the elementNode type. The -jsonType option is only allowed for elementNode and textNode types.

If such a command is invoked inside a script given as an argument to the domNode method appendFromScript or insertBeforeFromScript, it creates a new node and appends this node at the end of the child list of the invoking element node 🌿. If the option -returnNodeCmd was given, the command returns the created node as a Tcl command. If this option was omitted, the command returns nothing. Each command always creates the same type of node. Which type of node gets created is determined by the first argument to the createNodeCmd. The syntax of the created command depends on the type of node it creates 🦋.

If the command type to create is elementNode, the created command will create an element node, if called. Though, if the -notempty flag was used in creating the node command, the element node will only be created if it is not empty. Without the -tagName option, the tag name of the created node is commandName without Tcl namespace qualifiers. If the -tagName option was given, then the created elements will have the value of this option as tag name. If the -jsonType option was given, then the created node elements will have the given JSON type. If the -namespace option is given, the created element node will be XML namespaced and in the namespace given by the option 💫. The element name will be literal as given either by the command name or the -tagname option, if that was given. An appropriate XML namespace declaration will be automatically added, to bind the prefix (if the element name has one) or the default namespace (if the element name hasn't a prefix) to the namespace, if such a binding isn't in scope 👑

The syntax of the created command is:

elementNodeCmd ?attributeName attributeValue ...? ?script?
elementNodeCmd ?-attributeName attributeValue ...? ?script?
elementNodeCmd ?name_value_list? ?script?

The command syntax allows three different ways to specify the attributes of the resulting element 🌸. These could be specified with attributeName attributeValue argument pairs, in an "option style" way with -attriubteName attributeValue argument pairs (the - character is only syntactical sugar and will be stripped off), or as a Tcl list with elements interpreted as attribute name and the corresponding attribute value. The attribute name elements in the list may have a leading - character, which will be stripped off. If the elementNodeCmd is called with only one argument, this will be interpreted as content script ✨.

Okay so if your attributeName comes with a prefix, here's the whole deal: by default that prefix gets looked up first in the selectNodesNamespaces prefix URI list, and if it's not chillin' there, then it gets looked up in the XML namespace scope of the node. Doesn't resolve? Error, raised, periodt. 😤 But if it does resolve, then your attribute gets created in that namespace — and yes, XML namespace declarations get added if they're necessary. 💅

Unless… your elementNodeCmd was created with the -noNamespacedAttributes flag. In that case no prefix lookup happens at all, and the attribute just gets created with the name exactly as you handed it over, in no XML namespace. And heads up bestie: it's recommended to not create XML namespace declarations with this. 🙈

Every elementNodeCmd also accepts an optional Tcl script as its last argument. That script gets evaluated as a recursive appendFromScript script, with the node created by the elementNodeCmd as the parent of every node the script makes. 🌸

If the first argument of the method is textNode, the command creates a text node. If the -jsonType option was given, the created text node gets that JSON type. The syntax of the created command is:

textNodeCmd ?-disableOutputEscaping? ?data?

If the json type of the created text node is NULL, TRUE or FALSE, then the data argument is optional — otherwise it must be given.

If the json type of the created text node is the virtual type BOOLEAN, then: if the text value is a boolean as recognized by Tcl_GetBooleanFromObj(), the json value will be according; and if the text node value isn't a boolean value that Tcl understands, the value gets written as a json string.

If the optional flag -disableOutputEscaping is given, the escaping of the ampersand character (&) and the left angle bracket (<) inside the data is disabled. 👀 You should use this flag carefully.

If the first argument of the method is commentNode or cdataNode, the command creates a comment node or a CDATA section node. The syntax of the created command is:

nodeCmd data

If the first argument of the method is piNode, the command creates a processing instruction node. The syntax of the created command is:

piNodeCmd target data

Beside the node commands created by dom createNodeCmd calls, there are two more commands that automatically insert nodes into the tree inside an appendFromScript script. 🪄

tdom::fsnewNode ?-jsonType <jsonType>? ?-namespace <namespace>? ?-noNamespacedAttributes? -notempty tagName ?attributes? ?script?

Called inside a fromScript context, this command creates a new node tagName in the XML namespace namespace if the -namespace option was given, and with the JSON type jsonType if the -jsonType option was given, and appends this node at the end of the child list of the invoking element node. The other flags work exactly as if they were given at the creation of an element-creating command — go check that bit. The attributes and script arguments also get processed as if they were given to an element-creating node command. Called outside a fromScript context? This command raises error. 💀

tdom::fsinsertNode node

Called inside a fromScript context, this command — instead of creating a new node — appends the node given as argument at the end of the child list of the invoking element node. The node is unlinked from its previous place. Called outside a fromScript context, this command raises error.

Now bestie, the method lineup. Buckle in. 🎀

  • dom fromScriptContext ?objVar? — Called inside a fromScript context, this method returns the node on which the script context appends nodes to the child list. Otherwise it returns error. And a lil heads up: if you create nodeCmds with -notempty, the returned node may have vanished outside the evaluation context if it's still empty at the end of the evaluation. 🫠
  • dom setStoreLineColumn ?boolean? — Switch it on and your DOM nodes will contain line and column position information for the original XML document after parsing. The default is not to store line and column position information.
  • dom setNameCheck ?boolean? — If NameCheck is true, every method that expects an XML Name, a fully qualified name or a processing instruction target will check whether the given string is valid according to its production rule. For commands created with the createNodeCmd method for use in the context of appendFromScript, the status of the flag at creation time decides — NameCheck true at creation time means the command will check its arguments, otherwise it won't. setNameCheck sets this flag and returns the current NameCheck flag state. Default state for NameCheck is true.
  • dom setTextCheck ?boolean? — If TextCheck is true, every command that expects XML Chars, a comment, a CDATA section value or a processing instruction value will check whether the given string is valid according to its production rule. For commands created with the createNodeCmd method for use in the context of appendFromScript, the status of the flag at creation time decides — TextCheck true at creation time means the command checks its arguments, otherwise not. setTextCheck sets this flag and returns the current TextCheck flag state. Default state for TextCheck is true.
  • dom setObjectCommands ?(automatic|token|command)? — Controls whether documents and nodes get created as Tcl commands or as token to be used with the domNode and domDoc commands. automatic → methods used at Tcl commands create Tcl commands, and methods used at doc or node tokes create tokens. command → always Tcl commands get created. token → always token get created. The method returns the current mode. 🧪 This method is an experimental interface.
  • dom isName name — Returns 1 if name is a valid XML Name according to production 5 of the XML 1.0 recommendation. That means name is a valid XML element or attribute name. Otherwise returns 0.
  • dom isPIName name — Returns 1 if name is a valid XML processing instruction target according to production 17 of the XML 1.0 recommendation. Otherwise returns 0.
  • dom isNCName name — Returns 1 if name is a valid NCName according to production 4 of the Namespaces in XML recommendation. Otherwise returns 0.
  • dom isQName name — Returns 1 if name is a valid QName according to production 6 of the Namespaces in XML recommendation. Otherwise returns 0.
  • dom isCharData string — Returns 1 if every character in string is a valid XML Char according to production 2 of the XML 1.0 recommendation. Otherwise returns 0.
  • dom isHTML5CustomName string — Returns 1 if string is an HTML5 valid custom element name (according to https://html.spec.whatwg.org/#valid-custom-element-name at 26 June 2024 — it's a living standard, bestie, it moves). Otherwise returns 0.
  • dom clearString ?-replace? string — Returns the string you passed in, cleared out from any characters not allowed as XML parsed character data. If the -replace option is given, then instead of removing them, those characters get replaced with \uFFFD.
  • dom isBMPCharData string — Returns 1 if every character in string is a valid XML Char with a Unicode code point within the Basic Multilingual Plane (that means every character within the string is at most 3 bytes long). Otherwise returns 0.
  • dom isComment string — Returns 1 if string is a valid comment according to production 15 of the XML 1.0 recommendation. Otherwise returns 0.
  • dom isCDATA string — Returns 1 if string is valid according to production 20 of the XML 1.0 recommendation. Otherwise returns 0.
  • dom isPIValue string — Returns 1 if string is valid according to production 16 of the XML 1.0 recommendation. Otherwise returns 0.
  • dom jsonEscape string — Returns the given string argument escaped in a way that, if the returned string is used literary in a JSON document, it gets read by any confirming JSON parser as the original string. ✨
  • dom featureinfo feature — This method hands you info about the build options used and the expat version. The valid values for the feature argument are:
    • expatversion — returns the version of the underlying expat version as a string, something like "exapt_2.1.0". This is what the expat API function XML_ExpatVersion() returns.
    • expatmajorversion — returns the major version of the at build time used expat version as an integer.
    • expatminorversion — returns the minor version of the at build time used expat version as an integer.
    • expatmicroversion — returns the micro version of the at build time used expat version as an integer.
    • dtd — returns as boolean if built with --enable-dtd.
    • ns — returns as boolean if built with --enable-ns.
    • unknown — returns as boolean if built with --enable-unknown.
    • tdomalloc — returns as boolean if built with --enable-tdomalloc.
    • lessns — returns as boolean if built with --enable-lessns.
    • TCL_UTF_MAX — returns the TCL_UTF_MAX value of the Tcl core tDOM was built with, as an integer.
    • html5 — returns as boolean if built with --enable-html5.
    • versionhash — returns the fossil repository version hash.
    • pullparser — returns as boolean if the pullparser command is built in.
    • schema — returns as boolean if the tDOM schema features are built in.
    • largedata — returns as boolean if the expat library configuration allows pcdata content of an XML element. Could be true only if built with Tcl 9 for a 64-bit architecture, and then it depends on whether the build-in expat version is used with default configuration, or whether the used system expat library is capable enough for this (typically not).

are build in.

🔑 KEYWORDS ✨

Okay bestie, these are the little search-baes you'd type if you were grepping through docs tryna find this page again:

  • XML
  • DOM
  • document
  • node
  • parsing

That's the whole vibe. Five words. Iconic. 💅

And that's a wrap on the whole page, fr fr 🎀 — brought to you by the lovely folks over at Tcl, filed under dom(3tcl). Go build some trees, bestie, you're literally gonna slay. 🦋✨

📦 where this page comes from