SXML/xpath documentation

SXML/xpath documentation

[rain1]

[-- Attachment #1: Type: text/plain, Size: 178 bytes --]

Hello!

Here is a patch that adds documentation for the functions in 
https://www.gnu.org/software/guile/manual/html_node/SXPath.html based on 
the comments in the source code.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-doc-ref-sxml.texi-Added-documentation-for-SXML-based.patch --]
[-- Type: text/x-diff; name=0001-doc-ref-sxml.texi-Added-documentation-for-SXML-based.patch, Size: 10707 bytes --]

From 28e73a2817e46cf52d5377f687da4e8d12238dd9 Mon Sep 17 00:00:00 2001
From: Raymond Nicholson <rain1@openmailbox.org>
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
-@deffn {Scheme Procedure} nodeset? x
-@end deffn
+@heading Basic converters and applicators
+
+A converter is a function
+
+@example
+        type Converter = Node|Nodeset -> Nodeset
+@end 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.
+
+@example
+        node-typeof? :: Crit -> Node -> Boolean
+@end example
+
+The criterion 'crit' is a symbol, one of the following:
+@verbatim
+	id		- tests if the Node has the right name (id)
+	@		- tests if the Node is an <attributes-coll>
+	*		- tests if the Node is an <Element>
+	*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
+@end verbatim
+
+@deffn {Scheme Procedure} nodeset? x
+Tests whether a scheme object is a nodeset or not.
+@end deffn
+
+@heading Curried equivalence converter-predicates
+
 @deffn {Scheme Procedure} node-eq? other
+
+@verbatim
+(define (node-eq? other)
+  (lambda (node)
+    (eq? other node)))
+@end verbatim
 @end deffn
 
 @deffn {Scheme Procedure} node-equal? other
+
+@verbatim
+(define (node-equal? other)
+  (lambda (node)
+    (equal? other node)))
+@end verbatim
 @end deffn
 
 @deffn {Scheme Procedure} node-pos n
+
+@example
+node-pos:: N -> Nodeset -> Nodeset, or
+node-pos:: N -> Converter
+@end 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.
+
+@example
+((node-pos 1) Nodeset)
+@end example
+selects the node at the head of the Nodeset, if exists
+
+@example
+((node-pos 2) Nodeset)
+@end 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.
+
+@example
+((node-pos -1) Nodeset)
+@end example
+selects the last node of a non-empty nodeset;
+
+@example
+((node-pos -2) Nodeset)
+@end 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?
+@example
+take-until:: Converter -> Converter, or
+take-until:: Pred -> Node|Nodeset -> Nodeset
+@end 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?
+
+@example
+take-after:: Converter -> Converter, or
+take-after:: Pred -> Node|Nodeset -> Nodeset
+@end 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
+@example
+node-reverse :: Converter, or
+node-reverse:: Node|Nodeset -> Nodeset
+@end 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
+@example
+node-trace:: String -> Converter
+@end 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
 
+
+@heading Converter combinators
+
 @deffn {Scheme Procedure} select-kids test-pred?
+
+@example
+select-kids:: Pred -> Node -> Nodeset
+@end example
+
+Given a Node, return an (ordered) subset its children that satisfy
+the Pred (a converter, actually)
+
+@example
+select-kids:: Pred -> Nodeset -> Nodeset
+@end example
+
+The same as above, but select among children of all the nodes in
+the Nodeset
 @end deffn
 
 @deffn {Scheme Procedure} node-self pred?
-@verbatim 
- -- 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)
+@example
+node-self:: Pred -> Node -> Nodeset, or
+node-self:: Converter -> Converter
+@end example
 
- 
-@end 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
+@example
+node-join:: [LocPath] -> Node|Nodeset -> Nodeset, or
+node-join:: [Converter] -> Converter
+@end example
+
+join the sequence of location steps or paths as described
+in the title comments above.
 @end deffn
 
 @deffn {Scheme Procedure} node-reduce . converters
+@example
+node-reduce:: [LocPath] -> Node|Nodeset -> Nodeset, or
+node-reduce:: [Converter] -> Converter
+@end example
+
+A regular functional composition of converters.
+From a different point of view,
+@example
+((apply node-reduce converters) nodeset)
+@end example
+is equivalent to
+@example
+(foldl apply nodeset converters)
+@end example
+i.e., folding, or reducing, a list of converters with the nodeset
+as a seed.
 @end deffn
 
 @deffn {Scheme Procedure} node-or . converters
+@example
+node-or:: [Converter] -> Converter
+@end 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?
+@example
+node-closure:: Converter -> Converter
+@end 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
+@example
+node-parent:: RootNode -> Converter
+@end 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,
+@verbatim
+parent(x) = { y | y=subnode*(root), x=subnode(y) }
+@end 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
 
+
+@heading Evaluate an abbreviated SXPath
+
 @deffn {Scheme Procedure} sxpath path
 @end deffn
 
+@example 
+	sxpath:: AbbrPath -> Converter, or
+        sxpath:: AbbrPath -> Node|Nodeset -> Nodeset
+@end example
+
+AbbrPath is a list. It is translated to the full SXPath according
+ to the following rewriting rules
+
+@verbatim 
+ (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))
+@end verbatim
+
 @node sxml ssax input-parse
 @subsection (sxml ssax input-parse)
 @subsubsection Overview
-- 
2.7.4

Re: SXML/xpath documentation

[Ricardo Wurmus]

Hi,

> Here is a patch that adds documentation for the functions in 
> https://www.gnu.org/software/guile/manual/html_node/SXPath.html based on 
> the comments in the source code.

I remember that I once submitted a similar patch to this list, and I
think it has already been merged to the “stable-2.0” branch.  It’s
probably this one:

~~~~~~~~~~
commit fbe95dc6e6a83497b9074bd368b7050f536bc234
Author: Ricardo Wurmus <rekado@elephly.net>
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 <ludo@gnu.org>
~~~~~~~~~~

Maybe this should also be in master to avoid confusion.

~~ Ricardo