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...?
_________________________________________________________________

DESCRIPTION

       tDOM's  XPath  engine  supports  custom XPath functions implemented by Tcl commands. When it encounters a
       function call to an unknown function name without a namespace qualifier, the XPath engine looks for a Tcl
       command of the same name in the ::dom::xpathFunc  namespace.  If  it  encounters  an  unknown  namespace-
       qualified  function call, it looks for a Tcl namespace with a name equal to the function's full namespace
       URI inside ::dom::xpathFunc, and a Tcl command named for the local part of  the  function's  name  inside
       that  namespace. If it finds such a Tcl command, it is executed with at least the following arguments, to
       describe the current XPath context:

       ctxNode
              The domNode object command of the XPath context node.

       pos    The XPath context position, in zero-based form - that is, the return value of the  standard  XPath
              position() function in the context would be $pos - 1.

       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].

       If  the  function  call  includes any arguments, two arguments will be 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 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 (note that the attrnodes type name is not supported):

       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 is treated as a simple string.  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.

EXAMPLES

       A  simple  workalike  for  the  XPath  2/3 fn:matches() function, 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:

       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. Tcl commands created with the deprecated Tcl_CreateCommand interface cannot  be  used
       as scripted XPath functions.

       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.

KEYWORDS

       XPath

Tcl                                                                                              xpathFunc(3tcl)