From 28e73a2817e46cf52d5377f687da4e8d12238dd9 Mon Sep 17 00:00:00 2001
From: Raymond Nicholson
Date: Sun, 1 May 2016 21:02:09 +0100
Subject: [PATCH] * doc/ref/sxml.texi: Added documentation for SXML based on
the comments in the source code.
---
doc/ref/sxml.texi | 263 ++++++++++++++++++++++++++++++++++++++++++++++++++----
1 file changed, 246 insertions(+), 17 deletions(-)
diff --git a/doc/ref/sxml.texi b/doc/ref/sxml.texi
index 75867f3..7d8dc45 100644
--- a/doc/ref/sxml.texi
+++ b/doc/ref/sxml.texi
@@ -733,21 +733,103 @@ literally from the XPath specification, while the others are adjusted
for our running example, tree1.
@subsubsection Usage
address@hidden {Scheme Procedure} nodeset? x
address@hidden deffn
address@hidden Basic converters and applicators
+
+A converter is a function
+
address@hidden
+ type Converter = Node|Nodeset -> Nodeset
address@hidden example
+
+A converter can also play a role of a predicate: in that case, if a
+converter, applied to a node or a nodeset, yields a non-empty
+nodeset, the converter-predicate is deemed satisfied. Throughout
+this file a nil nodeset is equivalent to #f in denoting a failure.
+
+The following function implements a 'Node test' as defined in
+Sec. 2.3 of XPath document. A node test is one of the components of a
+location step. It is also a converter-predicate in SXPath.
@deffn {Scheme Procedure} node-typeof? crit
@end deffn
+The function node-typeof? takes a type criterion and returns a function,
+which, when applied to a node, will tell if the node satisfies
+the test.
+
address@hidden
+ node-typeof? :: Crit -> Node -> Boolean
address@hidden example
+
+The criterion 'crit' is a symbol, one of the following:
address@hidden
+ id - tests if the Node has the right name (id)
+ @ - tests if the Node is an
+ * - tests if the Node is an
+ *text* - tests if the Node is a text node
+ *PI* - tests if the Node is a PI node
+ *any* - #t for any type of Node
address@hidden verbatim
+
address@hidden {Scheme Procedure} nodeset? x
+Tests whether a scheme object is a nodeset or not.
address@hidden deffn
+
address@hidden Curried equivalence converter-predicates
+
@deffn {Scheme Procedure} node-eq? other
+
address@hidden
+(define (node-eq? other)
+ (lambda (node)
+ (eq? other node)))
address@hidden verbatim
@end deffn
@deffn {Scheme Procedure} node-equal? other
+
address@hidden
+(define (node-equal? other)
+ (lambda (node)
+ (equal? other node)))
address@hidden verbatim
@end deffn
@deffn {Scheme Procedure} node-pos n
+
address@hidden
+node-pos:: N -> Nodeset -> Nodeset, or
+node-pos:: N -> Converter
address@hidden example
+
+Select the N'th element of a Nodeset and return as a singular Nodeset;
+Return an empty nodeset if the Nth element does not exist.
+
address@hidden
+((node-pos 1) Nodeset)
address@hidden example
+selects the node at the head of the Nodeset, if exists
+
address@hidden
+((node-pos 2) Nodeset)
address@hidden example
+selects the Node after that, if exists.
+
+N can also be a negative number: in that case the node is picked from
+the tail of the list.
+
address@hidden
+((node-pos -1) Nodeset)
address@hidden example
+selects the last node of a non-empty nodeset;
+
address@hidden
+((node-pos -2) Nodeset)
address@hidden example
+selects the last but one node, if exists.
@end deffn
+
@deffn {Scheme Procedure} filter pred?
@verbatim
-- Scheme Procedure: filter pred list
@@ -758,64 +840,211 @@ for our running example, tree1.
list. The dynamic order in which the various applications of pred
are made is not specified.
- (filter even? '(0 7 8 8 43 -4)) => (0 8 8 -4)
-
-
+ (filter even? '(0 7 8 8 43 -4)) => (0 8 8 -4)
@end verbatim
@end deffn
@deffn {Scheme Procedure} take-until pred?
address@hidden
+take-until:: Converter -> Converter, or
+take-until:: Pred -> Node|Nodeset -> Nodeset
address@hidden example
+
+Given a converter-predicate and a nodeset, apply the predicate to
+each element of the nodeset, until the predicate yields anything but #f or
+nil. Return the elements of the input nodeset that have been processed
+till that moment (that is, which fail the predicate).
+
+take-until is a variation of the filter above: take-until passes
+elements of an ordered input set till (but not including) the first
+element that satisfies the predicate.
+
+The nodeset returned by ((take-until (not pred)) nset) is a subset --
+to be more precise, a prefix -- of the nodeset returned by
+((filter pred) nset)
@end deffn
@deffn {Scheme Procedure} take-after pred?
+
address@hidden
+take-after:: Converter -> Converter, or
+take-after:: Pred -> Node|Nodeset -> Nodeset
address@hidden example
+
+Given a converter-predicate and a nodeset, apply the predicate to
+each element of the nodeset, until the predicate yields anything but #f or
+nil. Return the elements of the input nodeset that have not been processed:
+that is, return the elements of the input nodeset that follow the first
+element that satisfied the predicate.
+take-after along with take-until partition an input nodeset into three
+parts: the first element that satisfies a predicate, all preceding
+elements and all following elements.
@end deffn
@deffn {Scheme Procedure} map-union proc lst
+Apply proc to each element of lst and return the list of results.
+if proc returns a nodeset, splice it into the result
+
+From another point of view, map-union is a function Converter->Converter,
+which places an argument-converter in a joining context.
@end deffn
@deffn {Scheme Procedure} node-reverse node-or-nodeset
address@hidden
+node-reverse :: Converter, or
+node-reverse:: Node|Nodeset -> Nodeset
address@hidden example
+
+Reverses the order of nodes in the nodeset
+This basic converter is needed to implement a reverse document order
+(see the XPath Recommendation).
@end deffn
@deffn {Scheme Procedure} node-trace title
address@hidden
+node-trace:: String -> Converter
address@hidden example
+
+(node-trace title) is an identity converter. In addition it prints out
+a node or nodeset it is applied to, prefixed with the 'title'.
+This converter is very useful for debugging.
@end deffn
+
address@hidden Converter combinators
+
@deffn {Scheme Procedure} select-kids test-pred?
+
address@hidden
+select-kids:: Pred -> Node -> Nodeset
address@hidden example
+
+Given a Node, return an (ordered) subset its children that satisfy
+the Pred (a converter, actually)
+
address@hidden
+select-kids:: Pred -> Nodeset -> Nodeset
address@hidden example
+
+The same as above, but select among children of all the nodes in
+the Nodeset
@end deffn
@deffn {Scheme Procedure} node-self pred?
address@hidden
- -- Scheme Procedure: filter pred list
- Return all the elements of 2nd arg LIST that satisfy predicate
- PRED. The list is not disordered - elements that appear in the
- result list occur in the same order as they occur in the argument
- list. The returned list may share a common tail with the argument
- list. The dynamic order in which the various applications of pred
- are made is not specified.
-
- (filter even? '(0 7 8 8 43 -4)) => (0 8 8 -4)
address@hidden
+node-self:: Pred -> Node -> Nodeset, or
+node-self:: Converter -> Converter
address@hidden example
-
address@hidden verbatim
+Similar to select-kids but apply to the Node itself rather
+than to its children. The resulting Nodeset will contain either one
+component, or will be empty (if the Node failed the Pred).
@end deffn
@deffn {Scheme Procedure} node-join . selectors
address@hidden
+node-join:: [LocPath] -> Node|Nodeset -> Nodeset, or
+node-join:: [Converter] -> Converter
address@hidden example
+
+join the sequence of location steps or paths as described
+in the title comments above.
@end deffn
@deffn {Scheme Procedure} node-reduce . converters
address@hidden
+node-reduce:: [LocPath] -> Node|Nodeset -> Nodeset, or
+node-reduce:: [Converter] -> Converter
address@hidden example
+
+A regular functional composition of converters.
+From a different point of view,
address@hidden
+((apply node-reduce converters) nodeset)
address@hidden example
+is equivalent to
address@hidden
+(foldl apply nodeset converters)
address@hidden example
+i.e., folding, or reducing, a list of converters with the nodeset
+as a seed.
@end deffn
@deffn {Scheme Procedure} node-or . converters
address@hidden
+node-or:: [Converter] -> Converter
address@hidden example
+
+This combinator applies all converters to a given node and
+produces the union of their results.
+This combinator corresponds to a union, '|' operation for XPath
+location paths.
@end deffn
@deffn {Scheme Procedure} node-closure test-pred?
address@hidden
+node-closure:: Converter -> Converter
address@hidden example
+
+Select all _descendants_ of a node that satisfy a converter-predicate.
+This combinator is similar to select-kids but applies to
+grand... children as well.
+This combinator implements the "descendant::" XPath axis
@end deffn
@deffn {Scheme Procedure} node-parent rootnode
address@hidden
+node-parent:: RootNode -> Converter
address@hidden example
+
+(node-parent rootnode) yields a converter that returns a parent of a
+node it is applied to. If applied to a nodeset, it returns the list
+of parents of nodes in the nodeset. The rootnode does not have
+to be the root node of the whole SXML tree -- it may be a root node
+of a branch of interest.
+
+Given the notation of Philip Wadler's paper on semantics of XSLT,
address@hidden
+parent(x) = { y | y=subnode*(root), x=subnode(y) }
address@hidden verbatim
+Therefore, node-parent is not the fundamental converter: it can be
+expressed through the existing ones. Yet node-parent is a rather
+convenient converter. It corresponds to a parent:: axis of SXPath.
+Note that the parent:: axis can be used with an attribute node as well!
@end deffn
+
address@hidden Evaluate an abbreviated SXPath
+
@deffn {Scheme Procedure} sxpath path
@end deffn
address@hidden
+ sxpath:: AbbrPath -> Converter, or
+ sxpath:: AbbrPath -> Node|Nodeset -> Nodeset
address@hidden example
+
+AbbrPath is a list. It is translated to the full SXPath according
+ to the following rewriting rules
+
address@hidden
+ (sxpath '()) -> (node-join)
+ (sxpath '(path-component ...)) ->
+ (node-join (sxpath1 path-component) (sxpath '(...)))
+ (sxpath1 '//) -> (node-or
+ (node-self (node-typeof? '*any*))
+ (node-closure (node-typeof? '*any*)))
+ (sxpath1 '(equal? x)) -> (select-kids (node-equal? x))
+ (sxpath1 '(eq? x)) -> (select-kids (node-eq? x))
+ (sxpath1 ?symbol) -> (select-kids (node-typeof? ?symbol)
+ (sxpath1 procedure) -> procedure
+ (sxpath1 '(?symbol ...)) -> (sxpath1 '((?symbol) ...))
+ (sxpath1 '(path reducer ...)) ->
+ (node-reduce (sxpath path) (sxpathr reducer) ...)
+ (sxpathr number) -> (node-pos number)
+ (sxpathr path-filter) -> (filter (sxpath path-filter))
address@hidden verbatim
+
@node sxml ssax input-parse
@subsection (sxml ssax input-parse)
@subsubsection Overview
--
2.7.4