xpathFunc(3tcl)

✨ xpathFunc — the tea on scripted XPath functions ✨

okay bestie, so this is xpathFunc(3tcl), and ngl it's kind of a whole vibe. it's the page about teaching tDOM's XPath engine your own custom functions, written in Tcl. no cap, it's giving "make XPath do tricks it was never built for." 💅

---

🌸 NAME 🌸

::dom::xpathFunc — Scripted XPath functions 🦋

---

✨ SYNOPSIS ✨

::dom::xpathFunc::funcName ctxNode pos nodeListType nodeList ?type arg type arg...?
::dom::xpathFunc::namespaceURL::funcName ctxNode pos nodeListType nodeList ?type arg type arg...?

like. that's the shape of it. two ways to be called, and you're about to find out why 💖

---

🫶 DESCRIPTION 🫶

so tDOM's XPath engine is literally built different — it supports custom XPath functions implemented by Tcl commands. here's the whole plot:

when the engine bumps into a function call to a name it doesn't know and there's no namespace qualifier, it goes looking for a Tcl command with that same name inside the ::dom::xpathFunc namespace. simple. iconic. 🎀

but when it bumps into an unknown namespace-qualified function call, it does the two-step: it looks for a Tcl namespace whose name is equal to the function's full namespace URI inside ::dom::xpathFunc, and then looks for a Tcl command named for the local part of the function's name inside that namespace. iykyk.

and the moment it finds such a Tcl command? it runs it, feeding it at least these args to describe the current XPath context:

• ctxNode — the domNode object command of the XPath context node. that's the main character rn.
• pos — the XPath context position, in zero-based form. meaning: the value the standard XPath position() function would return in that context is $pos - 1. yeah, it's off by one, and that's just how it is 🙈
• nodeListType — the type name for nodeList, exactly like the selectNodes method's typeVar.
• nodeList — the list of the current worked-on XPath step result (as selectNodes would return them) in document order. and ctxNode will be equal to [lindex $nodeList $pos]. cute, right?

now, if the function call has any arguments, two arguments get appended to the command's argument list for each one:

• type — the argument's type name, same as for selectNodes's typeVar.
• val — the argument's value, as selectNodes would return it in an XPath expression's result set.

and here's the part where you gotta show up and deliver: the command is required to return a 1- or 2-element Tcl list to provide the result of the XPath function call.

if the result list has two elements, the first is the result's XPath type name and the second is an appropriately encoded value. oh and heads up — the attrnodes type name is not supported here, bestie, don't try it 💀

• bool — Tcl boolean value acceptable to Tcl_GetBooleanFromObj.
• number — Tcl numeric value acceptable to Tcl_GetSizeIntFromObj or Tcl_GetDoubleFromObj.
• string — Simple string.
• nodes — Tcl list of domNode object commands.
• attrvalues — Alias for string.

if the result list has only one element, it's treated as a simple string. periodt.

it is an error for the result to have zero elements, more than two elements, or to be invalid as a Tcl list. and it is an error if the val of a two-part result does not match the requirements described above for its type. so like... don't be messy about it 😭

---

🧚 EXAMPLES 🧚

here's a simple workalike for the XPath 2/3 fn:matches() function — which, fyi, is not otherwise available in an XPath 1.0 engine like tDOM's. so we make our own. slay.

proc ::dom::xpathFunc::regmatch {
    ctxNode pos nodeListType nodeList
    inputType inputVal patternType patternVal
} {
    set input [::dom::xpathFuncHelper::coerce2string $inputType $inputVal]
    set pattern [::dom::xpathFuncHelper::coerce2string $patternType $patternVal]
    return [list bool [regexp -- $pattern $input]]
}

---

💜 HELPER PROCS 💜

the ::dom::xpathFuncHelper namespace contains helper procs, for the convenience of scripted XPath functions. they're here to help you, not to judge you 🫶

coerce2number type val

given a type and val as provided to scripted XPath functions in their argument lists, convert the val to a number in a manner appropriate for its type:

• empty — Always zero.
• number — Unchanged.
• string — Unchanged. (note that no error is raised if val is not numeric.)
• attrvalues — value's first element.
• nodes — The result of the number() XPath function called on the first node in the list.
• attrnodes — The value of the single attribute assumed to be in value. note that no error is raised if this value is non-numeric.

coerce2string type val

as for coerce2number, but convert val to a pure string:

• empty — The empty string.
• number — Unchanged.
• string — Unchanged.
• attrvalues — value's first element.
• nodes — The result of the string() XPath function called on the first node in the list.
• attrnodes — The value of the single attribute assumed to be in value.

---

🌈 LIMITS 🌈

okay so here's the fine print, and it's lowkey important:

• custom XPath function names are limited to 200 characters, including any namespace URI and the :: Tcl namespace separator between it and the local part.
• function calls may have a maximum of 22 arguments (the argument values themselves may be large nodesets).
• if you really need more, these limits may be adjusted by build time defines.
• Tcl commands created with the deprecated Tcl_CreateCommand interface cannot be used as scripted XPath functions. rip to that interface, but it's different.

you must not alter any of the DOM trees from which nodes are provided to a scripted XPath function as argument. this is true for the ctxNode argument as well as for the nodes in the nodeList argument. use them strictly read-only. ignoring this advice may have any unpredictable results, including segmentation faults or security problems. 😭 bestie this is the scary part. do not touch. read only. fr fr.

---

⭐ KEYWORDS ⭐

XPath

---

and that's the whole page, mwah 💖 this was xpathFunc(3tcl) from the Tcl manual pages — Tcl, section 3tcl, no date on this one so we're just vibing with it as-is. go write some unhinged custom XPath functions, you're gonna eat 👑