XQuery Function Documentation

Search and Browse

http://exist-db.org/xquery/kwic

KWIC module: formats query results to display <em>keywords in context</em> (KWIC). A configurable amount of text is displayed to the left and right of a matching keyword (or phrase). The module works with all indexes that support match highlighting (matches are tagged with an &lt;exist:match&gt; element). This includes the old full text index, the new Lucene-based full text index, as well as the NGram index. The <b>kwic:summarize()</b> function represents the main entry point into the module. To have more control over the text extraction context, you can also call <b>kwic:get-summary()</b> instead. For example, the following snippet will only print the first match within a given set of context nodes ($ancestor): <pre> let $matches := kwic:get-matches($hit)<br/> for $ancestor in $matches/ancestor::para | $matches/ancestor::title | $matches/ancestor::td<br/> return<br/> kwic:get-summary($ancestor, ($ancestor//exist:match)[1], $config) </pre>

kwic:callback

kwic:callback($callback as function?, $node as node(), $mode as xs:string) as xs:string?

Parameters:
$callback? $callback?
$node $node
$mode $mode
Returns:
xs:string?

kwic:display-text

kwic:display-text($text as text()?) as node()?

Parameters:
$text? $text?
Returns:
node()?

kwic:expand

kwic:expand($hit as element()) as element()

Expand the element in $hit. Creates an in-memory copy of the element and marks all matches with an exist:match tag, which will be used by all other functions in this module. You need to call kwic:expand before kwic:get-summary. kwic:summarize will call it automatically.

Parameters:
$hit $hit
Returns:
element()

kwic:get-matches

kwic:get-matches($hit as element()) as element()*

Return all matches within the specified element, $hit. Matches are returned as exist:match elements. The returned nodes are part of a new document whose root element is a copy of the specified $hit element.

Parameters:
$hit an arbitrary XML element which has been selected by one of the full text operations or an ngram search.
Returns:
element()*

kwic:get-summary

kwic:get-summary($root as node(), $node as element(), $config as element()?) as element()

Parameters:
$root $root
$node $node
$config? $config?
Returns:
element()

kwic:get-summary

kwic:get-summary($root as node(), $node as element(), $config as element()?, $callback as function?) as element()

Print a summary of the match in $node. Output a predefined amount of text to the left and the right of the match.

Parameters:
$root root element which should be used as context for the match. It defines the boundaries for the text extraction. Text will be taken from this context.
$node the exist:match element to process.
$config? configuration element which determines the behaviour of the function
$callback? (optional) reference to a callback function which will be called once for every text node before it is appended to the displayed text. The function should accept 2 parameters: 1) a single text node, 2) a string indicating the current direction in which text is appended, i.e. "before" or "after". The function may return the empty sequence if the current node should be ignore (e.g. if it belongs to a "footnote" which should not be displayed). Otherwise it should return a single string.
Returns:
element()

kwic:string-length

kwic:string-length($nodes as item()*) as xs:integer

Computes the total string length of the nodes in the argument sequence

Parameters:
$nodes* $nodes*
Returns:
xs:integer

kwic:substring

kwic:substring($node as item(), $start as xs:int, $count as xs:int) as item()?

Like fn:substring, but takes a node argument. If the node is an element, a new element is created with the same node-name as the old one and the shortened text content.

Parameters:
$node $node
$start $start
$count $count
Returns:
item()?

kwic:summarize

kwic:summarize($hit as element(), $config as element()?) as element()*

Parameters:
$hit $hit
$config? $config?
Returns:
element()*

kwic:summarize

kwic:summarize($hit as element(), $config as element()?, $callback as function?) as element()*

Main function of the KWIC module: takes the passed element and returns an XHTML fragment containing a chunk of text before and after the first full text match in the node. The optional config parameter is used to configure the behaviour of the function: &lt;config width="character width" table="yes|no" link="URL to which the match is linked"/&gt; By default, kwic:summarize returns an XHTML fragment with the following structure: &lt;p xmlns="http://www.w3.org/1999/xhtml"&gt; &lt;span class="previous"&gt;Text before match&lt;/span&gt; &lt;a href="passed URL if any" class="hi"&gt;The highlighted term&lt;/a&gt; &lt;span class="following"&gt;Text after match&lt;/span&gt; &lt;/p&gt; If table=yes is passed with the config element, a tr table row will be returned instead of a span (using the same class names).

Parameters:
$hit an arbitrary XML element which has been selected by one of the full text operations or an ngram search.
$config? configuration element to configure the behaviour of the function
$callback? $callback?
Returns:
element()*

kwic:truncate-following

kwic:truncate-following($root as node(), $node as node()?, $truncated as item()*, $max as xs:int, $chars as xs:int, $callback as function?) as item()*

Generate the right-hand context of the match. Returns a sequence of nodes and strings, whose total string length is less than or equal to $max characters.
Note: this function calls itself recursively until $nodes is empty or the returned sequence has the desired total string length.

Parameters:
$root $root
$node? $node?
$truncated* $truncated*
$max $max
$chars $chars
$callback? $callback?
Returns:
item()*

kwic:truncate-previous

kwic:truncate-previous($root as node(), $node as node()?, $truncated as item()*, $max as xs:int, $chars as xs:int, $callback as function?) as item()*

Generate the left-hand context of the match. Returns a sequence of nodes and strings, whose total string length is less than or equal to $max characters.
Note: this function calls itself recursively until $nodes is empty or the returned sequence has the desired total string length.

Parameters:
$root $root
$node? $node?
$truncated* $truncated*
$max $max
$chars $chars
$callback? $callback?
Returns:
item()*