xpathFunc(n)

✨ xpathFunc(n) ✨

okay bestie, this is the Tcl manual page for xpathFunc(n) and we're gonna make it make sense 💖

---

🎀 NAME 🎀

::dom::xpathFunc — Scripted XPath functions. no cap, that's the whole name section 💅

---

🌸 SYNOPSIS 🌸

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

---

🦋 DESCRIPTION 🦋

So here's the tea, bestie: tDOM's XPath engine lets you write custom XPath functions as Tcl commands. It's giving DIY but make it iconic. 🫶

When the engine runs into a function call to an unknown function name with no namespace qualifier, it goes looking for a Tcl command with that same name inside the ::dom::xpathFunc namespace. And if it runs into an unknown namespace-qualified function call? Then it looks for a Tcl namespace whose name equals the function's full namespace URI, living inside ::dom::xpathFunc, and inside that namespace it hunts for a Tcl command named for the local part of the function's name. ✨

If it finds such a Tcl command, it gets executed with at least these arguments, which describe the current XPath context:

• ctxNode — the domNode object command of the XPath context node. your main character node 👑
• pos — the XPath context position, in zero-based form. literally: the return value of the standard XPath position() function in that context would be $pos - 1. yeah. off by one. we love that for us. 😭
• nodeListType — the type name for nodeList, as for the selectNodes method's typeVar.
• nodeList — the list of the current worked-on XPath step result (as selectNodes would return them), in document order. ctxNode will be equal to [lindex $nodeList $pos].

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

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

💫 the return value (vibe check) 💫

Your 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 one is the result's XPath type name, and the second is an appropriately encoded value. > heads up bestie: the attrnodes type name is not supported here 💀

• 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. 💅

🚨 and now the rules, no negotiating: it is an error for the result to have zero elements, more than two elements, or to be invalid as a Tcl list. It is also an error if the val of a two-part result does not match the requirements described above for its type. so like. get it right the first time fr fr 😤

---

🌈 EXAMPLES 🌈

Here's a simple workalike for the XPath 2/3 fn:matches() function, which is not otherwise available in an XPath 1.0 engine such as tDOM's:

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 your little backstage crew 🧚

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 ⚠️

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 itself may be large nodesets). If you really need more, this limits may be adjusted by build time defines. And heads up: Tcl commands created with the deprecated Tcl_CreateCommand interface cannot be used as scripted XPath functions. 💀

🛑 BIG ONE, DO NOT SKIP THIS 🛑 — 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. like. bestie. please. read-only. 🙈

---

⭐ KEYWORDS ⭐

XPath

---

and that's the whole page, gorgeous 💖 this was xpathFunc(n) from the Tcl manual — Tcl on one side, xpathFunc(n) on the other, just like the footer says. go write some unhinged little XPath functions, you absolute icon 👑🌸🦋