xquery version "3.0"; (: : Copyright 2006-2012 The FLWOR Foundation. : : Licensed under the Apache License, Version 2.0 (the "License"); : you may not use this file except in compliance with the License. : You may obtain a copy of the License at : : http://www.apache.org/licenses/LICENSE-2.0 : : Unless required by applicable law or agreed to in writing, software : distributed under the License is distributed on an "AS IS" BASIS, : WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. : See the License for the specific language governing permissions and : limitations under the License. :) (:~ : This module provides functions for processing URIs and URLs. : : @author Matthias Brantner, Luis Rodriguez Gonzalez : @project XDM/atomic : :) module namespace uri = "http://www.zorba-xquery.com/modules/uri"; declare namespace zerr = "http://www.zorba-xquery.com/errors"; declare namespace ver = "http://www.zorba-xquery.com/options/versioning"; declare option ver:module-version "1.0"; (:~ : Constant for the "scheme" part of a URI object. :) declare variable $uri:SCHEME as xs:string := "scheme"; (:~ : Constant for the "authority" part of a URI object. :) declare variable $uri:AUTHORITY as xs:string := "authority"; (:~ : Constant for the "user-info" part of a URI object. :) declare variable $uri:USER-INFO as xs:string := "user-info"; (:~ : Constant for the "host" part of a URI object. :) declare variable $uri:HOST as xs:string := "host"; (:~ : Constant for the "port" part of a URI object. :) declare variable $uri:PORT as xs:string := "port"; (:~ : Constant for the "path" part of a URI object. :) declare variable $uri:PATH as xs:string := "path"; (:~ : Constant for the "query" part of a URI object. :) declare variable $uri:QUERY as xs:string := "query"; (:~ : Constant for the "fragment" part of a URI object. :) declare variable $uri:FRAGMENT as xs:string := "fragment"; (:~ : Constant for the "opaque-part" part of a URI object. : : If this is set in a URI object, then none of $uri:PATH, $uri:HOST, : $uri:PORT, $uri:USER-INFO, or : $uri:QUERY may be specified. : : If this is set in a URI object, $uri:SCHEME must also be specified : (ie, it must be an absolute URI). :) declare variable $uri:OPAQUE-PART as xs:string := "opaque-part"; (:~ : Percent-decodes (aka URL decoding) the given string. : : All percent encoded octets will be translated into their : decoded UTF-8 representation. : : Please note that the percent encoding guarantees that a string : consists of ASCII characters only. Passing a string that contains : non-ASCII characters results in undefined behavior. : : @param $s the string to decode : : @return the percent decoded string :) declare function uri:decode($u as xs:string) as xs:string { uri:decode($u, fn:false()) }; (:~ : Percent-decodes (aka URL decoding) the given string. : : All percent encoded octets will be translated into their : decoded UTF-8 representation. : : If $decode-plus is specified all occurrences of the char '+' : will be replaced with a space ' ' before the percent decoding : happens. : : Please note that the percent encoding guarantees that a string : consists of ASCII characters only. Passing a string that contains : non-ASCII characters results in undefined behavior. : : @param $s the string to decode : @param $decode-plus whether '+' chars will be replaced with spaces : : @return the percent decoded string :) declare function uri:decode( $u as xs:string, $decode-plus as xs:boolean) as xs:string { uri:decode($u, $decode-plus, "UTF-8") }; (:~ : Percent-decodes (aka URL decoding) the given string. : : All percent encoded octets will be translated into their : decoded UTF-8 representation. : : If $decode-plus is specified all occurrences of the char '+' : will be replaced with a space ' ' before the percent decoding : happens. : : The $charset parameter specifies the source charset after precent : decoding. It is used to convert the decoded string into UTF-8. : : Please note that the percent encoding guarantees that a string : consists of ASCII characters only. Passing a string that contains : non-ASCII characters results in undefined behavior. : : @param $s the string to decode : @param $decode-plus whether '+' chars will be replaced with spaces : @param $charset the source charset of the string after percent decoding : : @return the percent decoded string : : @error zerr:ZXQP0006 if the given charset is unknown or not supported : : @error zerr:ZOSE0006 if there is an error transcoding the string :) declare function uri:decode( $s as xs:string, $decode-plus as xs:boolean, $charset as xs:string) as xs:string external; (:~ : Parses the URI passed as string. The returned object : contains only members with field names declared as constants in : this module. : : For example, : <code> : let my-uri := "http://www.my.project.com/a/b/c?user=john;pass=1234#profile" : return uri:parse(my-uri) : </code> : : returns : <code> : { "squeme" : "http", "host" : "www.my.project.com", "path" : "/a/b/c", : "query" : "user=john;pass=123", "fragment" : "profile" } : </code> : : @param $uri the URI to parse : : @return the JSON object : : @error err:XQST0046 if the URI is textually invalid :) declare function uri:parse( $uri as xs:string) as object() external; (:~ : Serialize the URI passed as object into a string. : : @param $uri the object representing the URI : : @return the URI as string : : @error zerr:ZURI0001 if opaque part is specified in conjunction with : host/port/path/user-info/query. : : @error zerr:ZURI0002 if opaque part is present but no scheme is present. : : @error zerr:ZURI0003 if a path component for an absolute URI : doesn't start with "/". :) declare function uri:serialize( $uri as object()) as xs:string external;