Changeset 13334 in project for wiki/eggref/4/sxml-tools

Timestamp:

02/18/09 00:16:03 (12 years ago)

Author:

sjamaan

Message:

Add documentation for the sxpath-ext bit that was added to sxml-tools egg in release 4 branch

File:

• wiki/eggref/4/sxml-tools (modified) (3 diffs)

wiki/eggref/4/sxml-tools

@@ -13 +13 @@
 This egg provides some utilities from the sxml-tools available in the
 SSAX/SXML Sourceforge project.  It consists of the extensions defined
-in {{sxml-tools.scm}} plus {{sxpathlib}}.
+in {{sxml-tools.scm}} plus {{sxpathlib}} and {{sxpath-ext}}.  This is
+equivalent to the "low-level sxpath interface" described at
+[[http://www196.pair.com/lisovsky/query/sxpath/|the introduction to SXPath]].
 
 These utilities are useful when you want to query SXML document trees,
-but sxpath would be overkill.  Most of these procedures are faster than
-their sxpath equivalent, because they are very specific.  But this
-also means they are very low-level, so you should use them only if you
-know what you're doing.
+but full sxpath would be overkill.  Most of these procedures are
+faster than their sxpath equivalent, because they are very specific.
+But this also means they are very low-level, so you should use them
+only if you know what you're doing.
 
 Much documentation is available at
@@ -822 +824 @@
 <procedure>(sxml:parent test-pred?)</procedure>
 
-Given a predicate, it returns a function 
-  RootNode -> Converter
-which in turn yields a 
-  node -> parent 
-converter when applied to a rootnode.
-
-Thus, such a converter may be constructed using
-  ((sxml:parent test-pred) rootnode)
-and returns a parent of a node it is applied to.
-
-If applied to a nodelist, it returns the list of parents of nodes in
-the nodelist. The rootnode does not have to be the root node of the
+Returns a procedure that accepts a root-node, and returns another
+procedure.  This second procedure accepts a nodeset (or a node) and
+returns the immediate parents of the nodes in the set, but only if
+for those parents that match the predicate.
+
+The root-node does not have to be the root node of the
 whole SXML tree -- it may be a root node of a branch of interest.
 
@@ -860 +856 @@
 
 This is equivalent to {{((select-kids sxml:element?) node)}}.
+
+=== Procedures from sxpath-ext
+
+==== SXML counterparts to W3C XPath Core Functions Library
+
+<procedure>(sxml:string object)</procedure>
+
+The counterpart to XPath 'string' function (section 4.2 XPath 1.0 Rec.).
+Converts a given object to a string.
+
+Notes:
+# When converting a nodeset, document order is not preserved
+# {{number->string}} returns the result in a form which is slightly different from XPath Rec. specification
+
+<procedure>(sxml:boolean object)</procedure>
+
+The counterpart to XPath 'boolean' function (section 4.3 XPath Rec.).
+Converts its argument to a boolean.
+
+<procedure>(sxml:number object)</procedure>
+
+The counterpart to XPath 'number' function (section 4.4 XPath Rec.).
+Converts its argument to a number.
+
+Notes: 
+# The argument is not optional (yet?)
+# string->number conversion is not IEEE 754 round-to-nearest
+# NaN is represented as 0
+
+<procedure>(sxml:string-value node)</procedure>
+
+Returns a string value for a given node in accordance to
+XPath Rec. 5.1 - 5.7
+
+<procedure>(sxml:id id-index)</procedure>
+
+Returns a procedure that accepts a nodeset and returns a nodeset
+containing the elements in the id-index that match the string-values
+of each entry of the nodeset.  XPath Rec. 4.1
+
+The {{id-index}} is an alist with unique IDs as key, and elements as
+values:
+
+  id-index = ( (id-value . element) (id-value . element) ... )
+
+==== Comparators for XPath objects
+
+<procedure>(sxml:list-head list n)</procedure>
+
+Returns the {{n}} first members of {{list}}.  Mostly equivalent to
+SRFI-1's {{take}} procedure, except it returns the {{list}} if {{n}}
+is larger than the length of said list, instead of throwing an error.
+
+<procedure>(sxml:merge-sort less-than? list)</procedure>
+
+Returns the sorted list, the smallest member first.
+  less-than? ::= (lambda (obj1 obj2) ...)
+{{less-than?}} returns {{#t}} if {{obj1 < obj2}} with respect to the
+given ordering.
+
+<procedure>(sxml:equality-cmp bool=? number=? string=?)</procedure>
+
+A helper for XPath equality operations: {{=}} , {{!=}}.  The
+{{bool=?}}, {{number=?}} and {{string=?}} arguments are comparison
+operations for booleans, numbers and strings respectively.
+
+Returns a procedure that accepts two objects, looks at the first
+object's type and applies the correct comparison predicate to it.
+Type coercion takes place depending on the rules described in the
+XPath 1.0 spec, section 3.4 ("Booleans").
+
+<procedure>(sxml:equal? obj1 obj2)</procedure>
+<procedure>(sxml:not-equal? obj1 obj2)</procedure>
+
+Equality procedures with the default comparison operators {{eq?}},
+{{=}} and {{string=?}}, or their inverse, respectively.
+
+<procedure>(sxml:relational-cmp op)</procedure>
+
+A helper for XPath relational operations: {{<}}, {{>}}, {{<=}}, {{>=}}
+for two XPath objects.  {{op}} is one of these operators.
+
+Returns a procedure that accepts two objects and returns the value of
+the procedure applied to these objects, converted according to the
+coercion rules described in the XPath 1.0 spec, section 3.4
+("Booleans").
+
+==== XPath axes
+
+<procedure>(sxml:ancestor test-pred?)</procedure>
+
+Like {{sxml:parent}}, except it returns all the ancestors that match
+{{test-pred?}}, not just the immediate parent.
+
+<procedure>(sxml:ancestor-or-self test-pred?)</procedure>
+
+Like {{sxml:ancestor}}, except also allows the node itself to match
+the predicate.
+
+<procedure>(sxml:descendant test-pred?)</procedure>
+
+Like {{node-closure}}, except the resulting nodeset is in depth-first
+order instead of breadth-first.
+
+<procedure>(sxml:descendant-or-self test-pred?)</procedure>
+
+Like {{sxml:descendant}}, except also allows the node itself to match
+the predicate.
+
+<procedure>(sxml:following test-pred?)</procedure>
+
+Returns a procedure that accepts a root node and returns a new
+procedure that accepts a node and returns all nodes following this
+node in the document source matching the predicate.
+
+<procedure>(sxml:following-sibling test-pred?)</procedure>
+
+Like {{sxml:following}}, except only siblings (nodes at the same level
+under the same parent) are returned.
+
+<procedure>(sxml:preceding test-pred?)</procedure>
+
+Returns a procedure that accepts a root node and returns a new
+procedure that accepts a node and returns all nodes preceding this
+node in the document source matching the predicate.
+
+<procedure>(sxml:preceding-sibling test-pred?)</procedure>
+
+Like {{sxml:preceding}}, except only siblings (nodes at the same level
+under the same parent) are returned.
+
+<procedure>(sxml:namespace test-pred?)</procedure>
+
+Returns a procedure that accepts a nodeset and returns the namespace
+lists of the nodes matching {{test-pred?}}.
+
 
 == About this egg