Scroll to navigation

xpathFunc(3tcl) xpathFunc(3tcl) 





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:



  

  
The domNode object command of the XPath context node.

  

  
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.

  

  
The type name for nodeList, as for the selectNodes method's
      typeVar.

  

  
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:



  

  
The argument's type name, as for selectNodes's typeVar.

  

  
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):



  

  
Tcl boolean value acceptable to Tcl_GetBooleanFromObj.

  

  
Tcl numeric value acceptable to Tcl_GetSizeIntFromObj or
      Tcl_GetDoubleFromObj.

  

  
Simple string.

  

  
Tcl list of domNode object commands.

  

  
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:



  

  
 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:







  

  
Always zero.

  

  
Unchanged.

  

  
Unchanged. (Note that no error is raised if val is not
    numeric.)

  

  
value's first element.

  

  
The result of the number() XPath function called on the first node
      in the list.

  

  
The value of the single attribute assumed to be in value. Note that
      no error is raised if this value is non-numeric.







  

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







  

  
The empty string.

  

  
Unchanged.

  

  
Unchanged.

  

  
value's first element.

  

  
The result of the string() XPath function called on the first node
      in the list.

  

  
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