XQuery Functions and Accessors for URIs

There are a number of Accessors and Functions  for manipulating and outputting URIs as described in XPath and XQuery Data Model :

fn:base-uri The base URI of a node
fn:document-uri The URI of a document
fn:encode-for-uri Encodes reserved characters for use in the path of a URI
fn:escape-html-uri Escapes all characters except printable ASCII characters
fn:iri-to-uri Converts an IRI into a URI
fn:resolve-uri Resolves a relative URI to a base URI, returning an absolute URI
fn:static-base-uri The base URI from the static context

Fn:base-uri

Fn:base-uri returns the base URI for a specified node.  If the node is part of a document and its base-uri attribute is not explicitly set, fn:base-uri  defaults to the base URI of the document node.

Fn:base-uri  – Signature-

fn:base-uri() as xs:anyURI?

fn:base-uri($arg as node()?) as xs:anyURI?

The zero-argument version of the function returns the base URI of the context node and it is equivalent to calling fn:base-uri(.) The single-argument version of the function follows the below rules:

  • If $arg is the empty sequence, the function returns an empty sequence.
  • Otherwise, the function returns the value of the dm:base-uri accessor applied to the node $arg.

Fn:base-uri -Examples- 

Assume that $foo = ‘http://example.org/test/test.xml’

Input:  base-uri($foo)

Ouput: ‘http://example.org/test/test.xml’

Fn:document-uri

Fn:document-uri takes  a document node and returns the absolute URI associated with it. It is, in fact, the inverse of fn:doc, which returns a document node based on an absolute URI.

Fn:document-uri  – Signature –

Fn:document-uri($arg as node()?) as xs:anyURI?

If $arg is empty, it returns an empty sequence.

Fn:document-uri -Examples-

Assume that $foo=’doc(http://example.org/test/test.xml)’

Input:  document-uri($foo)

Output: ‘http://example.org/test/test.xml’

Fn:encode-for-uri

Fn:encode-for-uri encodes reserved characters for use in the path of a URI. URIs require some characters (ASCII and non-ASCII) to be escaped  with their hexadecimal Unicode code point preceded by the percentage sign (%). All characters can be escaped, exception made for the following:

  • letters a through z and A through Z
  • digits 0 through 9
  • hyphen (-), underscore (_), period (.), tilde (~)

Fn:encode-for-uri -Signature-

fn:encode-for-uri($uri-part as xs:string?) as xs:string

If $uri-part is an empty sequence, it returns a zero-length string.

Fn:encode-for-uri – Examples-

Input: concat("http://www.mypage.org/", 
encode-for-uri("~résumé"))

Output: "http://www.mypage.org/r%E9sum%C3%A9"

Fn:encode-html-uri 

Fn:escape-html-uri escapes all characters, except made for printable US-ASCII coded character set. The function enables HTML user agents to handle attribute values that expect URIs, by replacing each character with an escape sequence.

Fn:encode-html-uri -Signature-

The escape sequence takes the form of: %fn:escape-html-uri($uri as xs:string?) as xs:string

Fn:encode-html-uri -Examples-

Input:  escape-html-uri('http://www.mypage.org/résumé.html')

Output:  'http://www.mypage.org/r%E9sum%C3%A9.html'

Fn:iri-to-uri

Fn:iri-to-uri transforms a xs:string containing an IRI into a URI. This function replaces each special character with an escape sequence in the form %xx, where xx is two hexadecimal digits (in uppercase) representing the character in UTF-8.

Fn:iri-to-uri -Signature-

fn:iri-to-uri($iri as xs:string?) as xs:string

All characters except the following are escaped:

  • Letters a through z and A through Z
  • Digits 0 through 9
  • Hyphen (-), underscore (_), period (.), exclamation point (!), tilde (~), asterisk (*), apostrophe(‘), parentheses (‘(‘ and ‘)’) and hash mark (#)
  • Semicolon (;), forward slash (/), question mark (?), colon (:), at sign (@), ampersand (&), equals sign (=), plus sign (+), dollar sign ($), comma (,), square brackets (‘[‘ and ‘]’), and percent sign (%).

If only a specific part of a UR needs to escapedI (as opposed to an entire URI), it is recommended to use the function fn:encode-for-uri .

Fn:iri-to-uri – Examples-

Input:  fn:iri-to-uri ("http://www.example.com/00/Weather/CA/Los%20Angeles#ocean")

Output: http://www.example.com/00/Weather/CA/Los%20Angeles#ocean”

Fn:resolve-uri

Fn:resolve-uri  returns an absolute URI by taking a base URI ($base) and a relative($relative) URI as arguments. In case $base is not provided, then the  the base URI of the static context is used. The main difference between $base and $relative is detailed here

Fn:resolve-uri -Signature-

fn:resolve-uri($relative as xs:string?) as xs:anyURI?
fn:resolve-uri($relative as xs:string?$base as xs:string) as xs:anyURI?

Fn:resolve-uri -Examples-

Input: fn:resolve-uri('test', 'http://www.example.org/')

Output:http://www.example.org/test'

Fn:static-base-uri

Fn:static-base-uri returns the base URI of the static context.  The static context of an expression is the information that is available during static analysis of the expression, prior to its evaluation. If the base URI is undefined, an empty sequence is returned.

References:

  • XQuery 1.0 and XPath 2.0 Functions and Operators (Second Edition),  W3C Recommendation 14 December 2010. Available at: http://www.w3.org/TR/xpath-functions/
  • XQuery, Priscilla Walmsley,  O’Reilly Media, 2007
  • Michael Kay, XSLT 2.0 and XPath 2.0 Programmer’s Reference (Programmer to Programmer), Wrox; 4 edition, 2008IETF.
  • RFC 3987: Internationalized Resource Identifiers (IRIs). Available at: http://www.ietf.org/rfc/rfc3987.txtMozilla Developer Network XPath: https://developer.mozilla.org/en-US/docs/XPath
  • XQuery Library: http://www.xqueryfunctions.com/xq/

Posted on December 8, 2013, in Uncategorized. Bookmark the permalink. Leave a comment.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.