[Guile-commits] 22/47: doc: Add SXPath documentation from sources

[Andy Wingo]

wingo pushed a commit to branch master
in repository guile.

commit b6c1018d9696b8b9e0117932a15d9bd07c8a8351
Author: Ricardo Wurmus <address@hidden>
Date:   Sun Aug 30 10:58:42 2015 +0200

    doc: Add SXPath documentation from sources
    
    Fixes <http://bugs.gnu.org/19478>.
    
    * doc/ref/sxml.texi (SXPath): Add procedure documentation from sources.
    
    Signed-off-by: Ludovic Courtès <address@hidden>
---
 doc/ref/sxml.texi |  302 ++++++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 267 insertions(+), 35 deletions(-)

diff --git a/doc/ref/sxml.texi b/doc/ref/sxml.texi
index 75867f3..03f0324 100644
--- a/doc/ref/sxml.texi
+++ b/doc/ref/sxml.texi
@@ -3,6 +3,10 @@
 @c Copyright (C) 2013 Free Software Foundation, Inc.
 @c See the file guile.texi for copying conditions.
 
address@hidden SXPath documentation based on SXPath.scm by Oleg Kiselyov,
address@hidden which is in the public domain according to 
<http://okmij.org/ftp/>
address@hidden and <http://ssax.sourceforge.net/>.
+
 @node SXML
 @section SXML
 
@@ -250,8 +254,8 @@ internal and external parsed entities, user-controlled 
handling of
 whitespace, and validation.  This module therefore is intended to be a
 framework, a set of ``Lego blocks'' you can use to build a parser
 following any discipline and performing validation to any degree.  As an
-example of the parser construction, this file includes a semi-validating
-SXML parser.
+example of the parser construction, the source file includes a
+semi-validating SXML parser.
 
 SSAX has a ``sequential'' feel of SAX yet a ``functional style'' of DOM.
 Like a SAX parser, the framework scans the document only once and
@@ -725,95 +729,323 @@ location path is a relative path applied to the root 
node.
 Similarly to XPath, SXPath defines full and abbreviated notations for
 location paths.  In both cases, the abbreviated notation can be
 mechanically expanded into the full form by simple rewriting rules.  In
-case of SXPath the corresponding rules are given as comments to a sxpath
-function, below.  The regression test suite at the end of this file shows
-a representative sample of SXPaths in both notations, juxtaposed with
-the corresponding XPath expressions.  Most of the samples are borrowed
-literally from the XPath specification, while the others are adjusted
-for our running example, tree1.
+the case of SXPath the corresponding rules are given in the
+documentation of the @code{sxpath} procedure.
address@hidden,,SXPath procedure documentation}.
+
+The regression test suite at the end of the file @file{SXPATH-old.scm}
+shows a representative sample of SXPaths in both notations, juxtaposed
+with the corresponding XPath expressions.  Most of the samples are
+borrowed literally from the XPath specification.
+
+Much of the following material is taken from the SXPath sources by Oleg
+Kiselyov et al.
+
address@hidden Basic Converters and Applicators
+
+A converter is a function mapping a nodeset (or a single node) to another
+nodeset.  Its type can be represented like this:
+
address@hidden
+type Converter = Node|Nodeset -> Nodeset
address@hidden example
+
+A converter can also play the 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.  Likewise, an empty nodeset
+is equivalent to @code{#f} in denoting failure.
 
address@hidden Usage
 @deffn {Scheme Procedure} nodeset? x
+Return @code{#t} if @var{x} is a nodeset.
 @end deffn
 
 @deffn {Scheme Procedure} node-typeof? crit
+This function implements a 'Node test' as defined in Sec. 2.3 of the
+XPath document.  A node test is one of the components of a location
+step.  It is also a converter-predicate in SXPath.
+
+The function @code{node-typeof?} takes a type criterion and returns a
+function, which, when applied to a node, will tell if the node satisfies
+the test.
+
+The criterion @var{crit} is a symbol, one of the following:
+
address@hidden @code
address@hidden id
+tests if the node has the right name (id)
+
address@hidden @@
+tests if the node is an <attributes-coll>
+
address@hidden *
+tests if the node is an <Element>
+
address@hidden *text*
+tests if the node is a text node
+
address@hidden *PI*
+tests if the node is a PI (processing instruction) node
+
address@hidden *any*
address@hidden for any type of node
address@hidden table
 @end deffn
 
 @deffn {Scheme Procedure} node-eq? other
+A curried equivalence converter predicate that takes a node @var{other}
+and returns a function that takes another node.  The two nodes are
+compared using @code{eq?}.
 @end deffn
 
 @deffn {Scheme Procedure} node-equal? other
+A curried equivalence converter predicate that takes a node @var{other}
+and returns a function that takes another node.  The two nodes are
+compared using @code{equal?}.
 @end deffn
 
 @deffn {Scheme Procedure} node-pos n
+Select the @var{n}'th element of a nodeset and return as a singular
+nodeset.  If the @var{n}'th element does not exist, return an empty
+nodeset.  If @var{n} is a negative number the node is picked from the
+tail of the list.
+
address@hidden
+((node-pos 1) nodeset)  ; return the the head of the nodeset (if exists)
+((node-pos 2) nodeset)  ; return the node after that (if exists)
+((node-pos -1) nodeset) ; selects the last node of a non-empty nodeset
+((node-pos -2) nodeset) ; selects the last but one node, if exists.
address@hidden example
 @end deffn
 
 @deffn {Scheme Procedure} filter 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 verbatim
+A filter applicator, which introduces a filtering context.  The argument
+converter @var{pred?} is considered a predicate, with either @code{#f}
+or @code{nil} meaning failure.
 @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 @var{pred?} and a nodeset, apply the
+predicate to each element of the nodeset, until the predicate yields
+anything but @code{#f} or @code{nil}.  Return the elements of the input
+nodeset that have been processed until that moment (that is, which fail
+the predicate).
+
address@hidden is a variation of the @code{filter} above:
address@hidden passes elements of an ordered input set up to (but not
+including) the first element that satisfies the predicate.  The nodeset
+returned by @code{((take-until (not pred)) nset)} is a subset -- to be
+more precise, a prefix -- of the nodeset returned by @code{((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 @var{pred?} and a nodeset, apply the
+predicate to each element of the nodeset, until the predicate yields
+anything but @code{#f} or @code{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.
+
address@hidden along with @code{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 @var{proc} to each element of @var{lst} and return the list of results.
+If @var{proc} returns a nodeset, splice it into the result
+
+From another point of view, @code{map-union} is a function
address@hidden>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
+
address@hidden(node-trace title)} is an identity converter.  In addition it
+prints out the node or nodeset it is applied to, prefixed with the
address@hidden  This converter is very useful for debugging.
 @end deffn
 
address@hidden Converter Combinators
+
+Combinators are higher-order functions that transmogrify a converter or
+glue a sequence of converters into a single, non-trivial converter.  The
+goal is to arrive at converters that correspond to XPath location paths.
+
+From a different point of view, a combinator is a fixed, named
address@hidden of applying converters.  Given below is a complete set of
+such patterns that together implement XPath location path specification.
+As it turns out, all these combinators can be built from a small number
+of basic blocks: regular functional composition, @code{map-union} and
address@hidden applicators, and the nodeset union.
+
 @deffn {Scheme Procedure} select-kids test-pred?
address@hidden takes a converter (or a predicate) as an argument and
+returns another converter.  The resulting converter applied to a nodeset
+returns an ordered subset of its children that satisfy the predicate
address@hidden
 @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 verbatim
+Similar to @code{select-kids} except that the predicate @var{pred?} is
+applied 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 predicate.
 @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 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, @code{((apply node-reduce converters) nodeset)} is equivalent
+to @code{(foldl apply nodeset converters)}, 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
+(@code{|} 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 @emph{descendants} of a node that satisfy a
+converter-predicate @var{test-pred?}.  This combinator is similar to
address@hidden but applies to grand... children as well.  This
+combinator implements the @code{descendant::} XPath axis.  Conceptually,
+this combinator can be expressed as
+
address@hidden
+(define (node-closure f)
+  (node-or
+    (select-kids f)
+    (node-reduce (select-kids (node-typeof? '*)) (node-closure f))))
address@hidden example
+
+This definition, as written, looks somewhat like a fixpoint, and it will
+run forever.  It is obvious however that sooner or later
address@hidden(select-kids (node-typeof? '*))} will return an empty nodeset.  At
+this point further iterations will no longer affect the result and can
+be stopped.
 @end deffn
 
 @deffn {Scheme Procedure} node-parent rootnode
address@hidden
+node-parent:: RootNode -> Converter
address@hidden example
+
address@hidden(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 @var{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, @code{node-parent} is not the fundamental converter: it can
+be expressed through the existing ones.  Yet @code{node-parent} is a
+rather convenient converter.  It corresponds to a @code{parent::} axis
+of SXPath.  Note that the @code{parent::} axis can be used with an
+attribute node as well.
 @end deffn
 
address@hidden
 @deffn {Scheme Procedure} sxpath path
+Evaluate an abbreviated SXPath.
+
address@hidden
+sxpath:: AbbrPath -> Converter, or
+sxpath:: AbbrPath -> Node|Nodeset -> Nodeset
address@hidden example
+
address@hidden is a list.  It is translated to the full SXPath according to
+the following rewriting rules:
+
address@hidden
+(sxpath '())
address@hidden (node-join)
+
+(sxpath '(path-component ...))
address@hidden (node-join (sxpath1 path-component) (sxpath '(...)))
+
+(sxpath1 '//)
address@hidden (node-or
+   (node-self (node-typeof? '*any*))
+   (node-closure (node-typeof? '*any*)))
+
+(sxpath1 '(equal? x))
address@hidden (select-kids (node-equal? x))
+
+(sxpath1 '(eq? x))
address@hidden (select-kids (node-eq? x))
+
+(sxpath1 ?symbol)
address@hidden (select-kids (node-typeof? ?symbol)
+
+(sxpath1 procedure)
address@hidden procedure
+
+(sxpath1 '(?symbol ...))
address@hidden (sxpath1 '((?symbol) ...))
+
+(sxpath1 '(path reducer ...))
address@hidden (node-reduce (sxpath path) (sxpathr reducer) ...)
+
+(sxpathr number)
address@hidden (node-pos number)
+
+(sxpathr path-filter)
address@hidden (filter (sxpath path-filter))
address@hidden example
 @end deffn
 
 @node sxml ssax input-parse