Changeset 13366 in project


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

Document the new 'sxpath' module (not that there's much to document, but still)

File:
1 edited

Legend:

Unmodified
Added
Removed
  • wiki/eggref/4/sxpath

    r13357 r13366  
    88
    99The sxpath parts of the [[http://cvs.sourceforge.net/viewcvs.py/ssax/sxml-tools/|sxml-tools]] from the [[http://ssax.sf.net|SSAX project]] at Sourceforge.
     10Because txpath and sxpath are interwoven, this egg also includes txpath parts.
    1011
    1112== Documentation
     
    1314This egg provides the sxpath-related tools from the sxml-tools available
    1415in the SSAX/SXML Sourceforge project.
     16
     17Much documentation is available at
     18[[http://www196.pair.com/lisovsky/xml/index.html|Lisovsky's XML page]]
     19and the [[http://ssax.sf.net|SSAX homepage]].
     20
     21The initial documentation on this wiki page came straight from the
     22comments in the extremely well-documented source code. It's
     23recommended you read the code if you want to learn more.
     24
     25== sxpath
     26
     27This is the preferred interface to use.  It allows you to query the
     28SXML document tree using an s-expression based language, in which you
     29can also use arbitrary procedures and even "classic" textual XPath
     30(see [#txpath|below] for docs on that).
     31
     32A complete description on how to use this is outside the scope of this
     33egg documentation. See
     34[[http://www196.pair.com/lisovsky/query/sxpath/|the introduction to SXPath]]
     35for that.
     36
     37<procedure>(sxpath path [ns-binding])</procedure>
     38
     39Returns a procedure that accepts an SXML document tree and returns a
     40nodeset (list of nodes) that match the {{path}} expression.
     41
     42The optional {{ns-binding}} argument is an alist of namespace
     43bindings.  It is used to map abbreviated namespace prefixes to full
     44URI strings.
     45
     46<examples>
     47<example>
     48<expr>
     49;; selects all the 'item' elements that have an 'olist' parent
     50;; (which is not root) and that are in the same document as the context node
     51;;
     52;; XPath equivalent of //olist/item
     53;;
     54((sxpath `(// olist item))
     55 '(doc (olist (item "1")) (item "2") (nested (olist (item "3")))))
     56</expr>
     57<result>
     58((item "1") (item "3"))
     59</result>
     60</example>
     61<example>
     62<expr>
     63;; selects the 'chapter' children of the context node that have one or
     64;; more 'title' children with string-value equal to 'Introduction'
     65;;
     66;; XPath equivalent of chapter[title='Introduction']
     67;;
     68(sxpath '((chapter ((equal? (title "Introduction")))))
     69 '(text  (chapter (title "Introduction"))  (chapter "No title for this chapter")  (chapter (title "Conclusion"))))
     70</expr>
     71<result>
     72((chapter (title "Introduction")))
     73</result>
     74</example>
     75</examples>
     76
     77TODO: find out how ns-binding works and give an example that uses this.
     78
     79<procedure>(if-sxpath path)</procedure>
     80
     81Like {{sxpath}}, only returns {{#f}} instead of the empty list if
     82nothing matches (so it does ''not'' always return a nodeset).
     83
     84<procedure>(car-sxpath path)</procedure>
     85
     86Like {{sxpath}}, only instead of a nodeset it returns the first node
     87found.  If no node was found, return '''an empty list'''.
     88
     89<procedure>(if-car-sxpath path)</procedure>
     90
     91Like {{car-sxpath}}, only returns {{#f}} instead of the empty list if
     92nothing matches.
     93
     94<procedure>(sxml:id-alist node . lpaths)</procedure>
     95
     96Builds an index as a list of {{(ID_value . element)}} pairs for given
     97{{node}}. {{lpaths}} are location paths for attributes of type ID (ie,
     98sxpath expressions that tell it how to find the ID attribute).
     99
     100Note: location paths ''must'' be of the form {{(expr '@ attrib-name)}}.
     101
     102See also {{sxml:lookup}} below, in {{sxpath-lolevel}}, which can use
     103this index.
     104
     105<examples>
     106<example>
     107<expr>
     108;; TODO: find out why location paths must be of the form (expr '@ symbol)
     109;;       or if this description is incorrect
     110(sxml:id-alist
     111 '(div (span (@ (id "hi")) "there")
     112       (div (@ (id "hello")) "dude")
     113       (a (@ (id "link")) "click here"))
     114 '(span @ id) '(a @ id))
     115</expr>
     116<result>
     117(("hi" . (span (@ (id "hi")) "there"))
     118 ("link" . (a (@ (id "link")) "click here")))
     119</result>
     120</example>
     121</examples>
     122
     123== sxpath-lolevel
     124
     125This section documents the low-level sxpath interface. It includes
     126mostly-generic list and SXML operators.
     127
     128It consists of the extensions defined in {{sxml-tools.scm}} plus
     129{{sxpathlib}} and {{sxpath-ext}}.  This is equivalent to the
     130"low-level sxpath interface" described at
     131[[http://www196.pair.com/lisovsky/query/sxpath/|the introduction to SXPath]].
    15132
    16133These utilities are useful when you want to query SXML document trees,
     
    19136But this also means they are very low-level, so you should use them
    20137only if you know what you're doing.
    21 
    22 Much documentation is available at
    23 [[http://www196.pair.com/lisovsky/xml/index.html|Lisovsky's XML page]]
    24 and the [[http://ssax.sf.net|SSAX homepage]].
    25 
    26 The initial documentation on this wiki page came straight from the
    27 comments in the extremely well-documented source code. It's
    28 recommended you read the code if you want to learn more.
    29 
    30 == sxpath-lolevel
    31 
    32 This section documents the low-level sxpath interface. It includes
    33 mostly-generic list and SXML operators.
    34 
    35 It consists of the extensions defined in {{sxml-tools.scm}} plus
    36 {{sxpathlib}} and {{sxpath-ext}}.  This is equivalent to the
    37 "low-level sxpath interface" described at
    38 [[http://www196.pair.com/lisovsky/query/sxpath/|the introduction to SXPath]].
    39138
    40139
Note: See TracChangeset for help on using the changeset viewer.