The "Zorba util" functions

1 Introduction

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

1.1 Namespace

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 is 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 generate 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()

2.3 Function for parsing XML

  declare function parse($doc xs:string) as document-node()?

Summary: Loads the document given as string into the store

Error scenarios:

If the passed string does not have a valid XML structure, the STR0008
error is raised

In the following, we demonstrate the use of the parse function.

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

let $message := util:parse("<?xml version='1.0'?><a><b/></a>")
return $message

The following query:

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

let $message := util:parse("<?xml version='1.0'?>
<soap:Envelope xmlns:soap='http://www.w3.org/2003/05/soap-envelope'>
  <soap:Header>
    <so:transaction xmlns:so='http://www.28msec.com/templates/soap/stockorder'
                    soap:mustUnderstand='1'
                    soap:actor='http://www.28msec.com/ordersystem'
                    soap:encodingStyle='http://www.w3.org/2001/12/soap-encoding'>
      75548
    </so:transaction>
  </soap:Header>
  <soap:Body>
    <system:order xmlns:o='http://www.28msec.com/ordersystem'
                  soap:encodingStyle='http://www.w3.org/2001/12/soap-encoding'>
      <system:isin>CH0010570767</system:isin>
      <system:qty>1000</system:qty>
    </system:order>
  </soap:Body>
</soap:Envelope>")
return $message

will raise [STR0008] Loader parsing error: Namespace prefix system on order is not defined

2.4 Function for serialization

  declare function serialize-to-string($doc as item()*) as xs:string

Summary: This functions takes a sequence of nodes, serializes them into strings and returns the concatenation of all strings.
The serialization is done with "omit-xml-declaration" parameter set to true

In the following, we demonstrate the use of the serialize-to-string function.

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

let $message := zu:parse("<?xml version='1.0'?><a><b>textnode</b></a>")

return ser:serialize($message)

2.5 Functions to encode/decode base64

2.5.1 zorba-util:base64Encode

  declare function base64Encode($value as xs:string) as xs:base64Binary

This function takes a string and encodes it to a base64 value.

2.5.2 zorba-util:base64Decode

  declare function base64Decode($value as xs:base64Binary) as xs:string

This function takes a base64 value and decodes it to string.

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.

 All Files