[Exist-open] XQuery Pragmas

[Wolfgang M. <sb...@we...>]

Hi,

one of the new things available in today's snapshot is support for XQuery 
pragmas. A pragma is used to provide additional information to the XQuery 
engine. This is very handy to specify things like output properties. The 
syntax is

(::pragma QName contents ::)

A pragma can be specified anywhere that whitespace is allowed. It is basically 
handled like a comment. eXist understands the following pragmas:

(::pragma exist:timeout query-timeout ::)

Specifies the maximum amount of time (in ms) a query can take before it is 
cancelled by the XQuery engine.

(::pragma exist:output-size-limit size-hint ::)

Defines a limit for the max. size of a document fragment created within an 
XQuery. The limit is just an estimation, specified in terms of the 
accumulated number of nodes contained in all generated fragments. This can be 
used to prevent users from consuming too much memory if they are allowed to 
pass in their own XQueries.

(::pragma exist:serialize options-list ::)

exist:serialize can be used to set various output options dynamically. Options 
affect the way in which generated results are serialized to XML. For example, 
you can turn on/off XInclude expansion here. The options are the same that 
can be passed via XPathQueryService.setProperty() and 
XQueryService.setProperty() in Java. They are defined in 
javax.xml.transform.OutputKeys and org.exist.serializers.EXistOutputKeys. 
Valid options include:

indent=yes|no
omit-xml-declaration=yes|no
expand-xincludes=yes|no
highlight-matches=elements|attributes|both
process-xsl-pi=yes|no

For example, to disable XInclude expansion and indent the output you can use 
the pragma:

(::pragma exist:serialize expand-xincludes=no indent=yes ::)

Internally, the XQuery parser removes the pragma (like a comment) from the 
query during lexical analysis. However, the pragma is added to the 
XQueryContext class and can be retrieved from there. Unknown pragmas are 
simply ignored.

Wolfgang