Posted to tcl by oldlaptop at Sat May 24 03:23:24 GMT 2025view raw

  1. I'm increasingly uncertain about what attrvalues is actually supposed to be.
  2.  
  3. Index: doc/domNode.xml
  4. ==================================================================
  5. --- doc/domNode.xml
  6. +++ doc/domNode.xml
  7. @@ -701,10 +701,11 @@
  8. <ref>domDoc</ref>
  9. </seealso>
  10.  
  11. <keywords>
  12. <keyword>XML</keyword>
  13. + <keyword>XPath</keyword>
  14. <keyword>DOM</keyword>
  15. <keyword>document</keyword>
  16. <keyword>node</keyword>
  17. <keyword>parsing</keyword>
  18. </keywords>
  19.  
  20. Index: doc/tDOM.xml
  21. ==================================================================
  22. --- doc/tDOM.xml
  23. +++ doc/tDOM.xml
  24. @@ -1,9 +1,11 @@
  25. <!DOCTYPE manual PUBLIC "-//jenglish//DTD TMML 0.5//EN" "tmml.dtd" [
  26. <!ENTITY dom SYSTEM "dom.xml">
  27. <!ENTITY domDoc SYSTEM "domDoc.xml">
  28. <!ENTITY domNode SYSTEM "domNode.xml">
  29. +<!ENTITY xpathFunc SYSTEM "xpathFunc.xml">
  30. +<!ENTITY xpathFuncHelper SYSTEM "xpathFuncHelper.xml">
  31. <!ENTITY expat SYSTEM "expat.xml">
  32. <!ENTITY expatapi SYSTEM "expatapi.xml">
  33. <!ENTITY pullparser SYSTEM "pullparser.xml">
  34. <!ENTITY schema SYSTEM "schema.xml">
  35. <!ENTITY tdomcmd SYSTEM "tdomcmd.xml">
  36. @@ -16,10 +18,14 @@
  37.  
  38. &domDoc;
  39.  
  40. &domNode;
  41.  
  42. +&xpathFunc;
  43. +
  44. +&xpathFuncHelper;
  45. +
  46. &expat;
  47.  
  48. &expatapi;
  49.  
  50. &pullparser;
  51.  
  52. ADDED doc/xpathFunc.xml
  53. Index: doc/xpathFunc.xml
  54. ==================================================================
  55. --- /dev/null
  56. +++ doc/xpathFunc.xml
  57. @@ -0,0 +1,151 @@
  58. +<manpage id="xpathFunc" title="xpathFunc" cat="misc">
  59. + <namesection>
  60. + <name>::dom::xpathFunc</name>
  61. + <desc>Scripted XPath functions</desc>
  62. + </namesection>
  63. +
  64. + <synopsis>
  65. + <syntax>::dom::xpathFunc::<m>funcName</m> <m>ctxNode</m> <m>pos</m> <m>nodeListType</m> <m>nodeList</m> ?<m>type arg type arg...</m>?
  66. +::dom::xpathFunc::<m>namespaceURL</m>::<m>funcName</m> <m>ctxNode</m> <m>pos</m> <m>nodeListType</m> <m>nodeList</m> ?<m>type arg type arg...</m>?</syntax>
  67. + </synopsis>
  68. +
  69. + <section>
  70. + <title>DESCRIPTION</title>
  71. + <p>
  72. + tDOM's XPath engine supports custom XPath functions implemented by Tcl
  73. + commands. When it encounters a function call to an unknown function name
  74. + without a namespace qualifier, the XPath engine looks for a Tcl command of
  75. + the same name in the <l>::dom::xpathFunc</l> namespace. If it encounters
  76. + an unknown namespace-qualified function call, it looks for a Tcl namespace
  77. + with a name equal to the function's full namespace URI inside
  78. + <l>::dom::xpathFunc</l>, and a Tcl command named for the local part of the
  79. + function's name inside that namespace. If it finds such a Tcl command, it
  80. + is executed with at least the following arguments, to describe the current
  81. + XPath context:
  82. + </p>
  83. +
  84. + <dl>
  85. + <dle>
  86. + <dt>ctxNode</dt>
  87. + <dd>The <l>domNode</l> object command of the XPath context node.</dd>
  88. + </dle>
  89. + <dle>
  90. + <dt>pos</dt>
  91. + <dd>
  92. + The XPath context position, in zero-based form - that is, the return
  93. + value of the standard XPath <l>position()</l> function in the context
  94. + would be <l>$pos - 1</l>.
  95. + </dd>
  96. + </dle>
  97. + <dle>
  98. + <dt>nodeListType</dt>
  99. + <dd>
  100. + The type name for <m>nodeList</m>, as for the
  101. + <method>selectNodes</method> method's <m>typeVar</m>.
  102. + </dd>
  103. + </dle>
  104. + <dle>
  105. + <dt>nodeList</dt>
  106. + <dd>
  107. + A list of the values (as <method>selectNodes</method> would return
  108. + them) of the context node and all of its siblings, in document order.
  109. + <m>ctxNode</m> will be equal to <l>[lindex $nodeList $pos]</l>.
  110. + </dd>
  111. + </dle>
  112. + </dl>
  113. +
  114. + <p>
  115. + If the function call includes any arguments, two arguments will be
  116. + appended to the command's argument list for each one:
  117. + </p>
  118. + <dl>
  119. + <dle>
  120. + <dt>type</dt>
  121. + <dd>
  122. + The argument's type name, as for <method>selectNodes</method>'s
  123. + <m>typeVar</m>.
  124. + </dd>
  125. + </dle>
  126. + <dle>
  127. + <dt>val</dt>
  128. + <dd>
  129. + The argument's value, as <method>selectNodes</method> would return
  130. + it in an XPath expression's result set.
  131. + </dd>
  132. + </dle>
  133. + </dl>
  134. +
  135. + <p>
  136. + The command is required to return a 1- or 2-element Tcl list to provide
  137. + the result of the XPath function call. If the result list has two
  138. + elements, the first is the result's XPath type name, and the second is an
  139. + appropriately encoded value (note that the <m>attrnodes</m> type name is
  140. + not supported):
  141. + </p>
  142. + <dl>
  143. + <dle>
  144. + <dt>bool</dt>
  145. + <dd>Tcl boolean value acceptable to <fun>Tcl_GetBooleanFromObj</fun>.</dd>
  146. + </dle>
  147. + <dle>
  148. + <dt>number</dt>
  149. + <dd>
  150. + Tcl numeric value acceptable to <fun>Tcl_GetSizeIntFromObj</fun> or
  151. + <fun>Tcl_GetDoubleFromObj</fun>.
  152. + </dd>
  153. + </dle>
  154. + <dle>
  155. + <dt>string</dt><dd>Simple string.</dd>
  156. + </dle>
  157. + <dle>
  158. + <dt>nodes</dt><dd>Tcl list of <l>domNode</l> object commands.</dd>
  159. + </dle>
  160. + <dle>
  161. + <dt>attrvalues</dt><dd>Alias for <m>string</m>.</dd>
  162. + </dle>
  163. + </dl>
  164. + <p>
  165. + If the result list has only one element, it is treated as a simple string.
  166. + It is an error for the result to have zero elements, more than two
  167. + elements, or to be invalid as a Tcl list, and it is an error if the
  168. + <m>val</m> of a two-part result does not match the requirements described
  169. + above for its <m>type</m>.
  170. + </p>
  171. + </section>
  172. +
  173. + <section>
  174. + <title>EXAMPLES</title>
  175. + <p>
  176. + A simple workalike for the XPath 2/3 <l>fn:matches()</l> function, not
  177. + otherwise available in an XPath 1.0 engine such as tDOM's:
  178. + </p>
  179. + <example>proc ::dom::xpathFunc::regmatch {
  180. + ctxNode pos nodeListType nodeList
  181. + inputType inputVal patternType patternVal
  182. +} {
  183. + set input [::dom::xpathFuncHelper::coerce2string $inputType $inputVal]
  184. + set pattern [::dom::xpathFuncHelper::coerce2string $patternType $patternVal]
  185. + return [list bool [regexp -- $pattern $input]]
  186. +}</example>
  187. + </section>
  188. +
  189. + <section>
  190. + <title>LIMITS</title>
  191. + <p>
  192. + Function names are limited to 200 characters, including any namespace URI
  193. + and the <l>::</l> Tcl namespace separator between it and the local part.
  194. + Function calls may have a maximum of 22 arguments. Tcl commands created
  195. + with the deprecated <fun>Tcl_CreateCommand</fun> interface cannot be used
  196. + as scripted XPath functions.
  197. + </p>
  198. + </section>
  199. +
  200. + <seealso>
  201. + <ref>domNode</ref>
  202. + <ref>xpathFuncHelper</ref>
  203. + </seealso>
  204. +
  205. + <keywords>
  206. + <keyword>XPath</keyword>
  207. + </keywords>
  208. +</manpage>
  209.  
  210. ADDED doc/xpathFuncHelper.xml
  211. Index: doc/xpathFuncHelper.xml
  212. ==================================================================
  213. --- /dev/null
  214. +++ doc/xpathFuncHelper.xml
  215. @@ -0,0 +1,105 @@
  216. +<manpage id="xpathFuncHelper" title="xpathFuncHelper" cat="cmd">
  217. + <namesection>
  218. + <name>::dom::xpathFuncHelper</name>
  219. + <desc>Helper procs for scripted XPath function implementations</desc>
  220. + </namesection>
  221. +
  222. + <synopsis>
  223. + <syntax>package require tdom
  224. + ::dom::xpathFuncHelper::coerce2number <m>type</m> <m>val</m>
  225. + ::dom::xpathFuncHelper::coerce2string <m>type</m> <m>val</m></syntax>
  226. + </synopsis>
  227. +
  228. + <section>
  229. + <title>DESCRIPTION</title>
  230. + <p>
  231. + The <l>::dom::xpathFuncHelper</l> namespace contains helper procs for the
  232. + convenience of scripted XPath functions:
  233. + </p>
  234. +
  235. + <commandlist>
  236. + <commanddef>
  237. + <command>coerce2number <m>type</m> <m>val</m></command>
  238. + <desc>
  239. + Given a <m>type</m> and <m>val</m> as provided to scripted XPath
  240. + functions in their argument lists, convert the <m>val</m> to a number in a
  241. + manner appropriate for its <m>type</m>:
  242. + <dl>
  243. + <dle>
  244. + <dt>empty</dt><dd>Always zero.</dd>
  245. + </dle>
  246. + <dle>
  247. + <dt>number</dt><dd>Unchanged.</dd>
  248. + </dle>
  249. + <dle>
  250. + <dt>string</dt>
  251. + <dd>
  252. + Unchanged. (Note that no error is raised if <m>val</m> is not
  253. + numeric.)
  254. + </dd>
  255. + </dle>
  256. + <dle>
  257. + <dt>attrvalues</dt><dd><m>value</m>'s first element.</dd>
  258. + </dle>
  259. + <dle>
  260. + <dt>nodes</dt>
  261. + <dd>
  262. + The result of the <l>number()</l> XPath function called on the
  263. + first node in the list.
  264. + </dd>
  265. + </dle>
  266. + <dle>
  267. + <dt>attrnodes</dt>
  268. + <dd>
  269. + The value of the single attribute assumed to be in <m>value</m>.
  270. + Note that no error is raised if this value is non-numeric.
  271. + </dd>
  272. + </dle>
  273. + </dl>
  274. + </desc>
  275. + </commanddef>
  276. + <commanddef>
  277. + <command>coerce2string <m>type</m> <m>val</m></command>
  278. + <desc>
  279. + As for <command>coerce2number</command>, but convert <m>val</m> to a
  280. + pure string:
  281. + <dl>
  282. + <dle>
  283. + <dt>empty</dt><dd>The empty string.</dd>
  284. + </dle>
  285. + <dle>
  286. + <dt>number</dt><dd>Unchanged.</dd>
  287. + </dle>
  288. + <dle>
  289. + <dt>string</dt><dd>Unchanged.</dd>
  290. + </dle>
  291. + <dle>
  292. + <dt>attrvalues</dt><dd><m>value</m>'s first element.</dd>
  293. + </dle>
  294. + <dle>
  295. + <dt>nodes</dt>
  296. + <dd>
  297. + The result of the <l>string()</l> XPath function called on the
  298. + first node in the list.
  299. + </dd>
  300. + </dle>
  301. + <dle>
  302. + <dt>attrnodes</dt>
  303. + <dd>
  304. + The value of the single attribute assumed to be in <m>value</m>.
  305. + </dd>
  306. + </dle>
  307. + </dl>
  308. + </desc>
  309. + </commanddef>
  310. + </commandlist>
  311. + </section>
  312. +
  313. + <seealso>
  314. + <ref>xpathFunc</ref>
  315. + </seealso>
  316. +
  317. + <keywords>
  318. + <keyword>XPath</keyword>
  319. + </keywords>
  320. +</manpage>
  321.  
  322.  

Add a comment

Please note that this site uses the meta tags nofollow,noindex for all pages that contain comments.
Items are closed for new comments after 1 week