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