The "Zorba util" functions

1 Introduction

This document defines a general set of functions grouped together under "zorba-util" namespace.

1.2 Namespaces

In order to use Zorba util functions, the module "http://www.zorba-xquery.com/zorba/util-functions" has to be included at the beginning of a query. For example

  import module namespace zorba-util = "http://www.zorba-xquery.com/zorba/util-functions";

2 Function Signatures and Descriptions

2.1 Functions using Tidy library

In order to use the functions that require Tidy you have to:

2.1.1 zorba-util:tidy

  declare function tidy($str          as xs:string) as item()
  declare function tidy($str          as xs:string,
                        $tidyOptions  as xs:string?) as item()

Summary: Assuming $str contains a "dirty" HTML the function will return an item containing a valid XHTML version of the $str.

A complete set of options that can be set for a Tidy call can be found at HTML Tidy Configuration Options

By default Zorba sets these values for the following options:

These options can be overwritten by passing different $tidyOptions

Example:

  import module namespace
  fn-zorba-util="http://www.zorba-xquery.com/zorba/util-functions";
  fn:string(fn-zorba-util:tidy('<title>Foo</title><p>Foo!','"newline=CRLF","doctype=omit","force-output","bare=yes"'))

As a result:

Note: you can set a boolean parameter to true by either of the following methods:

Error conditions:
If Tidy lib is not able to transform the given string into a valid XHTML, an error is raised XQP0029_TIDY_ERROR (see Appendix A: Error codes).

2.1.2 zorba-util:tdoc

  declare function tdoc($uri         as xs:string?) as document-node()?
  declare function tdoc($uri         as xs:string
                        $tidyOptions as xs:string?) as document-node()?

Summary: This function if very similar to the 15.5.4 fn:doc from XQuery 1.0 and XPath 2.0 Functions and Operators function. The only difference is that prior to parsing and inserting the document identified by $uri in the store, tdoc function transforms the document into a valid XHTML document with the help of Tidy lib.

A complete set of options that can be set for a Tidy call can be found at HTML Tidy Configuration Options

By default Zorba sets these values for the following options:

These options can be overwritten by passing different $tidyOptions

Example:

  import module namespace
  fn-zorba-util="http://www.zorba-xquery.com/zorba/util-functions";
  fn-zorba-util:tdoc('http://tidy.sourceforge.net/libintro.html','"newline=CRLF","doctype=omit","force-output","bare=yes"')

As a result:

Note: you can set a boolean parameter to true by either of the following methods:

Error conditions:
If Tidy lib is not able to transform the given string into a valid XHTML, an error is raised XQP0029_TIDY_ERROR (see Appendix A: Error codes).

2.2 Functions for generating UUID's, random integers

2.2.1 zorba-util:uuid

  declare function uuid() as xs:string

Summary: This function does not generates a DCE 1.1 variant UUIDs.
However please take into account that the UUID contains the time (as the number of 100-nanosecond intervals since the adoption of the Gregorian calendar in the West) at which the UUID was generated (like DCE version 1 states).
The UUID does not contain the MAC address of the machine used to generate it, and that is why the generated UUID's are not conformant to DCE version 1.

2.2.2 zorba-util:random

  declare function random() as xs:integer
  declare function random($seed as xs:integer) as xs:integer

Summary: Function for generating a random integer.
$seed can be used to set the starting point of the std::rand sequence. If random is called whithin a loop but diffrent numbers are expected as a result this parameter should be set. Please see the example below.

  import module namespace zu = "http://www.zorba-xquery.com/zorba/util-functions";
  for $i in (1 to 10)
    return zu:random($i)

If the seed is not passed as an argument the same number will be generated every time:

  import module namespace zu = "http://www.zorba-xquery.com/zorba/util-functions";
  for $i in (1 to 10)
    return zu:random()

Appendix A: Error codes

XQP0029_TIDY_ERROR - Error in Tidy library - is returned in case Tidy lib is not able to transform the given string into a valid XHTML.