cts.walk

cts.walkctswalk Walks a node, evaluating a callback function for any text matching a query. It returns the empty-sequence(). This is similar to cts.highlight in how it evaluates its expression, but it is different in what it returns.

A node to walk. The node must be either a document node or an element node; it cannot be a text node.

node

Node

A query specifying the text on which to evaluate the expression. If a string is entered, the string is treated as a cts:word-query of the specified string.

query

cts.query

A function to call with matching text.

callback

function(xs.string, text(), cts.query*, xs.integer) as xs.string?

null

The arguments to the callback function provide context for the match.

text as xs:string

The matched text.

node as text()

The node containing the matched text.

queries as cts:query*

The matching queries.

start as xs:integer
The string-length position of the first character of text in node. Therefore, the following always returns true:
fn.substring(node, start,
             fn.stringLength(text)) eq text 

The return from the callback function is an action that specifies what happens next in the walk:

"continue": (default) Walk the next match. If there are no more matches, return.
"skip": Skip walking any more matches and return.
"break": Stop walking matches and return.
null: Continue with the previous action.

You cannot use cts.walk to walk results matching cts:similar-query and cts:element-attribute-*-query items.

The callback function can use variables in scope to accumulate results.

//
//   Return all text nodes containing matches to the query "the".
//
var doc = new NodeBuilder();
doc.startElement("p");
doc.addText("the quick brown fox ");
doc.startElement("b"); doc.addText("jumped"); doc.endElement();
doc.addText(" over the lazy dog's back");
doc.endElement();

var results = [];
function callback(text, node, queries, start) {
  results.push(node);
  return "continue";
};

cts.walk(doc.toNode(), "the", callback);
results;
=>
  ["the quick brown fox ", " over the lazy dog's back"]

//
//  Do not show any more matches that occur after
//  $threshold characters.
//
var doc = new NodeBuilder();
doc.startElement("p");
doc.addText("This is 1, this is 2, this is 3, this is 4, this is 5.");
doc.endElement();
var pos = 1;
var threshold = 20;
var results = [];

function callback(text, node, queries, start) {
  if (pos > threshold )
     return "break";
  else {
    results.push(text);
    pos = start;
    return "continue";
  }
}

cts.walk(doc.toNode(), "this is", callback);
results;

=>
["This is", "this is", "this is"]

//
//   Show the first two matches.
//
var doc = new NodeBuilder();
doc.startElement("p");
doc.addText("This is 1, this is 2, this is 3, this is 4, this is 5.");
doc.endElement();
var match = 0;
var threshold = 2;
var results = [];

function callback(text, node, queries, start) {
  if (match >= threshold )
     return "break";
  else {
    results.push(text);
    match = match + 1;
    return "continue";
  }
}

cts.walk(doc.toNode(), "this is", callback);
results;

=>
["This is", "this is"]

//
//  Similar to the example above but on JSON nodes.
//
var x = ["This is 1, this is 2, this is 3, this is 4, this is 5."];
var match = 0;
var threshold = 2;
var results = [];

function callback(text, node, queries, start) {
  if (match >= threshold )
     return "break";
  else {
    results.push(text);
    match = match + 1;
    return "continue";
  }
}

cts.walk(x, "this is", callback);
results;
=>
["This is", "this is"]

//
//  It works on JSON number, boolean and null nodes as well.
//
var x = { "p1" : "There are ", "p2" : 10,  "p3" : " books here."};
var results = [];
function callback (text, node, queries, start) {
  results.push(node);
  return "continue";
}
cts.walk(x, cts.jsonPropertyValueQuery("p2",10), callback);
results;
=>
[10]