Changeset 13415 in project


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

Document more of the high-level interface that txpath offers

File:
1 edited

Legend:

Unmodified
Added
Removed
  • wiki/eggref/4/sxpath

    r13373 r13415  
    137137queries.
    138138
     139=== High-level interface
     140
     141The following procedures are the main interface one would use in
     142practice. There are also more low-level procedures (see next section),
     143which one could use to build txpath extensions.
     144
     145<procedure>(sxml:xpath string . ns-binding)</procedure>
    139146<procedure>(txpath string . ns-binding)</procedure>
     147<procedure>(sxml:xpath+root string . ns-binding)</procedure>
     148<procedure>(sxml:xpath+root+vars string . ns-binding)</procedure>
    140149
    141150Returns a procedure that accepts an SXML document tree and returns a
    142 nodeset (list of nodes) that match the {{path}} expression.
     151nodeset (list of nodes) that match the XPath expression {{string}}.
    143152
    144153The optional {{ns-binding}} argument is an alist of namespace
     
    147156
    148157{{(txpath x)}} is equivalent to {{(sxpath x)}} whenever {{x}} is a
    149 string.
     158string.  The {{txpath}}, {{sxml:xpath+root}} and
     159{{sxml:xpath+root+vars}} procedures are currently all aliases for
     160{{sxml:xpath}}, which exist for backwards compatibility reasons.
    150161
    151162It's useful to compare the following examples to the above examples
     
    166177<example>
    167178<expr>
     179;; Same example as above, but now with a namespace prefix of 'x',
     180;; which is bound to the namespace "bar" in the ns-binding parameter.
     181((txpath "//x:olist/item" '((x . "bar")))
     182 '(doc (bar:olist (item "1")) (item "2") (nested (olist (item "3")))))
     183</expr>
     184<result>
     185((item "1"))
     186</result>
     187<example>
     188<expr>
    168189;; selects the 'chapter' children of the context node that have one or
    169190;; more 'title' children with string-value equal to 'Introduction'
     
    176197</example>
    177198</examples>
     199
     200<procedure>(sxml:xpath+index string . ns-binding)</procedure>
     201
     202This procedure returns the result of {{sxml:xpath}} consed onto
     203{{#t}}.  If the {{sxml:xpath}} would return {{#f}}, this returns
     204{{#f}} instead.
     205
     206It is provided solely for backwards compatibility.
     207
     208
     209<procedure>(sxml:xpointer string . ns-binding)</procedure>
     210<procedure>(sxml:xpointer+root+vars string . ns-binding)</procedure>
     211
     212Returns a procedure that accepts an SXML document tree and returns a
     213nodeset (list of nodes) that match the XPointer expression {{string}}.
     214
     215The optional {{ns-binding}} argument is an alist of namespace
     216bindings.  It is used to map abbreviated namespace prefixes to full
     217URI strings.
     218
     219Currently, only the XPointer {{xmlns()}} and {{xpointer()}} schemes
     220are implemented, the {{element()}} scheme is not.
     221
     222<examples>
     223<example>
     224<expr>
     225;; selects all the 'item' elements that have an 'olist' parent
     226;; (which is not root) and that are in the same document as the context node.
     227;; Equivalent to (txpath "//olist/item").
     228((sxml:xpointer "xpointer(//olist/item)")
     229 '(doc (olist (item "1")) (item "2") (nested (olist (item "3")))))
     230</expr>
     231<result>
     232((item "1") (item "3"))
     233</result>
     234</example>
     235<example>
     236<expr>
     237;; An example with a namespace prefix, now using the XPointer xmlns()
     238;; function instead of the ns-binding parameter. xmlns always have full
     239;; namespace names on their right-hand side, never bound shortcuts.
     240((sxml:xpointer "xmlns(x=bar)xpointer(//x:olist/item)")
     241 '(doc (bar:olist (item "1")) (item "2") (nested (olist (item "3")))))
     242</expr>
     243<result>
     244((item "1"))
     245</result>
     246</example>
     247</examples>
     248
     249<procedure>(sxml:xpointer+index string . ns-binding)</procedure>
     250
     251This procedure returns the result of {{sxml:xpointer}} consed onto
     252{{#t}}.  If the {{sxml:xpointer}} would return {{#f}}, this returns
     253{{#f}} instead.
     254
     255It is provided solely for backwards compatibility.
     256
     257
     258<procedure>(sxml:xpath-expr string . ns-binding)</procedure>
     259
     260Returns a procedure that accepts an SXML node and returns {{#t}} if
     261the node matches the {{string}} expression.  This is an expression of
     262type {{Expr}}, which is whatever you can put in a predicate (between
     263square brackets after a node name).
     264
     265The optional {{ns-binding}} argument is an alist of namespace
     266bindings.  It is used to map abbreviated namespace prefixes to full
     267URI strings.
     268
     269<examples>
     270<example>
     271<expr>
     272;; Does the node have a class attribute with "content" as value?
     273((sxml:xpath-expr "@class=\"content\"")
     274 '(div (@ (class "content")) (p "Lorem ipsum")))
     275</expr>
     276<result>
     277#t
     278</result>
     279</example>
     280<example>
     281<expr>
     282;; Does the node have a paragraph with string value of "Lorem ipsum"?
     283((sxml:xpath-expr "p=\"Lorem ipsum\"")
     284 '(div (@ (class "content")) (p "Lorem ipsum")))
     285</expr>
     286<result>
     287#t
     288</result>
     289</example>
     290<example>
     291<expr>
     292;; Does the node have a "p" child node with string value of "Blah"?
     293((sxml:xpath-expr "p=\"Blah\"")
     294 '(div (@ (class "content")) (p "Lorem ipsum")))
     295</expr>
     296<result>
     297#f
     298</result>
     299</example>
     300</examples>
     301
     302
     303=== Low-level procedures
     304
     305These procedures can be used to create custom xpath parsers.
     306
     307TODO: document these
     308
     309   txp:parameterize-parser
     310   sxml:whitespace
     311   txp:signal-semantic-error
     312   txp:error?
     313
     314   sxml:core-last
     315   sxml:core-position
     316   sxml:core-count
     317   sxml:core-id
     318   sxml:core-local-name
     319   sxml:core-namespace-uri
     320   sxml:core-name
     321   sxml:core-string
     322   sxml:core-concat
     323   sxml:core-starts-with
     324   sxml:core-contains
     325   sxml:core-substring-before sxml:core-substring-after
     326   sxml:core-substring
     327   sxml:core-string-length
     328   sxml:core-normalize-space
     329   sxml:core-translate
     330   sxml:core-boolean
     331   sxml:core-not
     332   sxml:core-true
     333   sxml:core-false
     334   sxml:core-lang
     335   sxml:core-number
     336   sxml:core-sum
     337   sxml:core-floor
     338   sxml:core-ceiling
     339   sxml:core-round
     340   sxml:classic-params
     341
    178342
    179343== sxpath-lolevel
Note: See TracChangeset for help on using the changeset viewer.