Changeset 13334 in project


Ignore:
Timestamp:
02/18/09 00:16:03 (11 years ago)
Author:
sjamaan
Message:

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

File:
1 edited

Legend:

Unmodified
Added
Removed
  • wiki/eggref/4/sxml-tools

    r13316 r13334  
    1313This egg provides some utilities from the sxml-tools available in the
    1414SSAX/SXML Sourceforge project.  It consists of the extensions defined
    15 in {{sxml-tools.scm}} plus {{sxpathlib}}.
     15in {{sxml-tools.scm}} plus {{sxpathlib}} and {{sxpath-ext}}.  This is
     16equivalent to the "low-level sxpath interface" described at
     17[[http://www196.pair.com/lisovsky/query/sxpath/|the introduction to SXPath]].
    1618
    1719These utilities are useful when you want to query SXML document trees,
    18 but sxpath would be overkill.  Most of these procedures are faster than
    19 their sxpath equivalent, because they are very specific.  But this
    20 also means they are very low-level, so you should use them only if you
    21 know what you're doing.
     20but full sxpath would be overkill.  Most of these procedures are
     21faster than their sxpath equivalent, because they are very specific.
     22But this also means they are very low-level, so you should use them
     23only if you know what you're doing.
    2224
    2325Much documentation is available at
     
    822824<procedure>(sxml:parent test-pred?)</procedure>
    823825
    824 Given a predicate, it returns a function
    825   RootNode -> Converter
    826 which in turn yields a
    827   node -> parent
    828 converter when applied to a rootnode.
    829 
    830 Thus, such a converter may be constructed using
    831   ((sxml:parent test-pred) rootnode)
    832 and returns a parent of a node it is applied to.
    833 
    834 If applied to a nodelist, it returns the list of parents of nodes in
    835 the nodelist. The rootnode does not have to be the root node of the
     826Returns a procedure that accepts a root-node, and returns another
     827procedure.  This second procedure accepts a nodeset (or a node) and
     828returns the immediate parents of the nodes in the set, but only if
     829for those parents that match the predicate.
     830
     831The root-node does not have to be the root node of the
    836832whole SXML tree -- it may be a root node of a branch of interest.
    837833
     
    860856
    861857This is equivalent to {{((select-kids sxml:element?) node)}}.
     858
     859=== Procedures from sxpath-ext
     860
     861==== SXML counterparts to W3C XPath Core Functions Library
     862
     863<procedure>(sxml:string object)</procedure>
     864
     865The counterpart to XPath 'string' function (section 4.2 XPath 1.0 Rec.).
     866Converts a given object to a string.
     867
     868Notes:
     869# When converting a nodeset, document order is not preserved
     870# {{number->string}} returns the result in a form which is slightly different from XPath Rec. specification
     871
     872<procedure>(sxml:boolean object)</procedure>
     873
     874The counterpart to XPath 'boolean' function (section 4.3 XPath Rec.).
     875Converts its argument to a boolean.
     876
     877<procedure>(sxml:number object)</procedure>
     878
     879The counterpart to XPath 'number' function (section 4.4 XPath Rec.).
     880Converts its argument to a number.
     881
     882Notes:
     883# The argument is not optional (yet?)
     884# string->number conversion is not IEEE 754 round-to-nearest
     885# NaN is represented as 0
     886
     887<procedure>(sxml:string-value node)</procedure>
     888
     889Returns a string value for a given node in accordance to
     890XPath Rec. 5.1 - 5.7
     891
     892<procedure>(sxml:id id-index)</procedure>
     893
     894Returns a procedure that accepts a nodeset and returns a nodeset
     895containing the elements in the id-index that match the string-values
     896of each entry of the nodeset.  XPath Rec. 4.1
     897
     898The {{id-index}} is an alist with unique IDs as key, and elements as
     899values:
     900
     901  id-index = ( (id-value . element) (id-value . element) ... )
     902
     903==== Comparators for XPath objects
     904
     905<procedure>(sxml:list-head list n)</procedure>
     906
     907Returns the {{n}} first members of {{list}}.  Mostly equivalent to
     908SRFI-1's {{take}} procedure, except it returns the {{list}} if {{n}}
     909is larger than the length of said list, instead of throwing an error.
     910
     911<procedure>(sxml:merge-sort less-than? list)</procedure>
     912
     913Returns the sorted list, the smallest member first.
     914  less-than? ::= (lambda (obj1 obj2) ...)
     915{{less-than?}} returns {{#t}} if {{obj1 < obj2}} with respect to the
     916given ordering.
     917
     918<procedure>(sxml:equality-cmp bool=? number=? string=?)</procedure>
     919
     920A helper for XPath equality operations: {{=}} , {{!=}}.  The
     921{{bool=?}}, {{number=?}} and {{string=?}} arguments are comparison
     922operations for booleans, numbers and strings respectively.
     923
     924Returns a procedure that accepts two objects, looks at the first
     925object's type and applies the correct comparison predicate to it.
     926Type coercion takes place depending on the rules described in the
     927XPath 1.0 spec, section 3.4 ("Booleans").
     928
     929<procedure>(sxml:equal? obj1 obj2)</procedure>
     930<procedure>(sxml:not-equal? obj1 obj2)</procedure>
     931
     932Equality procedures with the default comparison operators {{eq?}},
     933{{=}} and {{string=?}}, or their inverse, respectively.
     934
     935<procedure>(sxml:relational-cmp op)</procedure>
     936
     937A helper for XPath relational operations: {{<}}, {{>}}, {{<=}}, {{>=}}
     938for two XPath objects.  {{op}} is one of these operators.
     939
     940Returns a procedure that accepts two objects and returns the value of
     941the procedure applied to these objects, converted according to the
     942coercion rules described in the XPath 1.0 spec, section 3.4
     943("Booleans").
     944
     945==== XPath axes
     946
     947<procedure>(sxml:ancestor test-pred?)</procedure>
     948
     949Like {{sxml:parent}}, except it returns all the ancestors that match
     950{{test-pred?}}, not just the immediate parent.
     951
     952<procedure>(sxml:ancestor-or-self test-pred?)</procedure>
     953
     954Like {{sxml:ancestor}}, except also allows the node itself to match
     955the predicate.
     956
     957<procedure>(sxml:descendant test-pred?)</procedure>
     958
     959Like {{node-closure}}, except the resulting nodeset is in depth-first
     960order instead of breadth-first.
     961
     962<procedure>(sxml:descendant-or-self test-pred?)</procedure>
     963
     964Like {{sxml:descendant}}, except also allows the node itself to match
     965the predicate.
     966
     967<procedure>(sxml:following test-pred?)</procedure>
     968
     969Returns a procedure that accepts a root node and returns a new
     970procedure that accepts a node and returns all nodes following this
     971node in the document source matching the predicate.
     972
     973<procedure>(sxml:following-sibling test-pred?)</procedure>
     974
     975Like {{sxml:following}}, except only siblings (nodes at the same level
     976under the same parent) are returned.
     977
     978<procedure>(sxml:preceding test-pred?)</procedure>
     979
     980Returns a procedure that accepts a root node and returns a new
     981procedure that accepts a node and returns all nodes preceding this
     982node in the document source matching the predicate.
     983
     984<procedure>(sxml:preceding-sibling test-pred?)</procedure>
     985
     986Like {{sxml:preceding}}, except only siblings (nodes at the same level
     987under the same parent) are returned.
     988
     989<procedure>(sxml:namespace test-pred?)</procedure>
     990
     991Returns a procedure that accepts a nodeset and returns the namespace
     992lists of the nodes matching {{test-pred?}}.
     993
    862994
    863995== About this egg
Note: See TracChangeset for help on using the changeset viewer.