xquery version "3.0"; (: : Copyright 2006-2009 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 modules provides a set of functions to modify a collection and retrieve the nodes : contained in a particular collection. : : <p>Such collections are identified by a URI as defined in the XQuery specification. : However, please note that we do not advice users to use collections identified by URIs. : Instead, we refer to the <a href="../../html/data_lifecycle.html">data lifecycle : documentation</a>. It gives an overview over serveral ways to work with collections, : documents, and other data-structures.</p> : : @see <a href="../../html/data_lifecycle.html">Data Lifecycle</a> : @see http://www.zorba-xquery.com/modules/store/dynamic/collections/w3c/ddl : @see http://www.zorba-xquery.com/modules/store/dynamic/collections/ddl : @see http://www.zorba-xquery.com/modules/store/dynamic/collections/dml : @see <a href="www.zorba-xquery.com_errors.html">http://www.zorba-xquery.com/errors</a> : : @author Matthias Brantner, David Graf, Till Westmann, Markos Zaharioudakis : : @project store/collections/w3c :) module namespace dml = "http://www.zorba-xquery.com/modules/store/dynamic/collections/w3c/dml"; import module namespace ddl = "http://www.zorba-xquery.com/modules/store/dynamic/collections/w3c/ddl"; import module namespace qdml = "http://www.zorba-xquery.com/modules/store/dynamic/collections/dml"; declare namespace zerr = "http://www.zorba-xquery.com/errors"; declare namespace ann = "http://www.zorba-xquery.com/annotations"; declare namespace ver = "http://www.zorba-xquery.com/options/versioning"; declare option ver:module-version "2.0"; (:~ : The insert-nodes-first function is an updating function that inserts copies of the : given nodes at the beginning of the collection. : : @param $name The name of the collection to which the nodes should be added. : @param $content The sequences of nodes whose copies should be added to the collection. : : @return The result of the function is an empty XDM instance and a pending update list : which, once applied, inserts the nodes into the collection. : : @error zerr:ZDDY0003 if the collection identified by $name is not available. : :) declare updating function dml:insert-nodes-first( $name as xs:string, $content as node()*) { qdml:insert-nodes-first(ddl:to-qname($name), $content) }; (:~ : The insert-nodes-last function is an updating function that inserts copies of the : given nodes at the end of the collection. : : @param $name The name of the collection to which the nodes should be added. : @param $content The sequences of nodes whose copies should be added to the collection. : : @return The result of the function is an empty XDM instance and a pending update list : which, once applied, inserts the nodes into the collection. : : @error zerr:ZDDY0003 if the collection identified by $name is not available. : :) declare updating function dml:insert-nodes-last( $name as xs:string, $content as node()*) { qdml:insert-nodes-last(ddl:to-qname($name), $content) }; (:~ : The insert-nodes-before function is an updating function that inserts : copies of the given nodes into a collection at the position directly preceding the : given target node. : : @param $name The name of the collection to which the nodes should be added. : @param $target The node in the collection before which the $content : sequence should be inserted. : @param $content The sequences of nodes whose copies should be added to the collection. : : @return The result of the function is an empty XDM instance and a pending update list : which, once applied, inserts the nodes into the collection. : : @error zerr:ZDDY0003 if the collection identified by $name is not available. : @error zerr:ZDDY0011 if the target node is not contained in the collection. : :) declare updating function dml:insert-nodes-before($name as xs:string, $target as node(), $content as node()*) { qdml:insert-nodes-before(ddl:to-qname($name), $target, $content) }; (:~ : The insert-nodes-after function is an updating function that inserts : copies of the given nodes into a collection at the position directlry following the : given target node. : : @param $name The name of the collection to which the nodes should be added. : @param $target The node in the collection after which the $content : sequence should be inserted. : @param $content The sequences of nodes whose copies should be added to the collection. : : @return The result of the function is an empty XDM instance and a pending update list : which, once applied, inserts the nodes into the collection. : : @error zerr:ZDDY0003 if the collection identified by $name is not available. : @error zerr:ZDDY0011 if the target node is not contained in the collection. : :) declare updating function dml:insert-nodes-after($name as xs:string, $pos as node(), $content as node()*) { qdml:insert-nodes-after(ddl:to-qname($name), $pos, $content) }; (:~ : This function does the same as the insert-nodes function except : it immediately applies the resulting pending updates and returns the : nodes that have been inserted. : : @param $name The name of the collection to which the nodes should be added. : @param $content The sequences of nodes whose copies should be added to the collection. : : @return The result of the function is the sequence of nodes that have been : inserted into the collection. : : @error zerr:ZDDY0003 if the collection identified by $name is not available. : : @see dml:insert-nodes-first : :) declare %ann:sequential function dml:apply-insert-nodes-first( $name as xs:string, $content as node()*) as node()* { qdml:apply-insert-nodes-first(ddl:to-qname($name), $content) }; (:~ : This function does the same as the insert-nodes-last function except : it immediately applies the resulting pending updates and returns the : nodes that have been inserted. : : @param $name The name of the collection to which the nodes should be added. : @param $content The sequences of nodes whose copies should be added to the collection. : : @return The result of the function is the sequence of nodes that have been : inserted into the collection. : : @error zerr:ZDDY0003 if the collection identified by $name is not available. : : @see dml:insert-nodes-last : :) declare %ann:sequential function dml:apply-insert-nodes-last( $name as xs:string, $content as node()*) as node()* { qdml:apply-insert-nodes-last(ddl:to-qname($name), $content) }; (:~ : This function does the same as the insert-nodes-before function except : it immediately applies the resulting pending updates and returns the : nodes that have been inserted. : : @param $name The name of the collection to which the nodes should be added. : @param $target The node in the collection before which the $content : sequence should be inserted. : @param $content The sequences of nodes whose copies should be added to the collection. : : @return The result of the function is the sequence of nodes that have been : inserted into the collection. : : @error zerr:ZDDY0003 if the collection identified by $name is not available. : : @see dml:insert-nodes-before : :) declare %ann:sequential function dml:apply-insert-nodes-before( $name as xs:string, $target as node(), $content as node()*) as node()* { qdml:apply-insert-nodes-before(ddl:to-qname($name), $target, $content) }; (:~ : This function does the same as the insert-nodes-after function except : it immediately applies the resulting pending updates and returns the : nodes that have been inserted. : : @param $name The name of the collection to which the nodes should be added. : @param $target The node in the collection after which the $content : sequence should be inserted. : @param $content The sequences of nodes whose copies should be added to the collection. : : @return The result of the function is the sequence of nodes that have been : inserted into the collection. : : @error zerr:ZDDY0003 if the collection identified by $name is not available. : : @see dml:insert-nodes-after : :) declare %ann:sequential function dml:apply-insert-nodes-after( $name as xs:string, $pos as node(), $content as node()*) as node()* { qdml:apply-insert-nodes-after(ddl:to-qname($name), $pos, $content) }; (:~ : The delete-nodes function is an updating function that deletes zero of more : nodes from a collection. : : @param $target the nodes in the collection that should be deleted. : : @return The result of this function is an empty XDM instance and a pending update : list which, once applied, deletes the nodes from their collections. : : @error zerr:ZDDY0011 if any nodes in the $target sequence is not a member of a collection : or not all nodes of the $target sequence belong to the same collection. : the collection identified by the $name parameter. : :) declare updating function dml:delete-nodes($target as node()*) { qdml:delete-nodes($target) }; (:~ : The delete-node-first function is an updating function that deletes the : first node from a collection. : : @param $name The name of the collection from which the first node should be deleted. : : @return The result of this function is an empty XDM instance and a pending update : list which, once applied, deletes the first node from the collection. : : @error zerr:ZDDY0011 if the collection doesn't contain any node. : :) declare updating function dml:delete-node-first($name as xs:string) { qdml:delete-node-first(ddl:to-qname($name)) }; (:~ : The delete-nodes-first function is an updating function that deletes the : first n nodes from a collection. : : @param $name The name of the collection from which the first node should be deleted. : @param $number The number of nodes that should be removed from the beginning of : the collection. : : @return The result of this function is an empty XDM instance and a pending update : list which, once applied, deletes the nodes from the collection. : : @error zerr:ZDDY0011 if the collection doesn't contain the given number of nodes. :) declare updating function dml:delete-nodes-first( $name as xs:string, $number as xs:integer) { qdml:delete-nodes-first(ddl:to-qname($name), $number) }; (:~ : The delete-node-last function is an updating function that deletes the : last node from a collection. : : @param $name The name of the collection from which the first node should be deleted. : : @return The result of this function is an empty XDM instance and a pending update : list which, once applied, deletes the last node from the collection. : : @error zerr:ZDDY0009 If available collections does not provide a mapping : for the URI $name. : @error zerr:ZDDY0011 if the collection doesn't contain any node. :) declare updating function dml:delete-node-last($name as xs:string) { qdml:delete-node-last(ddl:to-qname($name)) }; (:~ : The delete-nodes-last function is an updating function that deletes the : last n nodes from an ordered collection. : : @param $name The name of the collection from which the first node should be deleted. : @param $number The number of nodes to delete. : : @return The result of this function is an empty XDM instance and a pending update : list which, once applied, deletes the last n nodes. : : @error zerr:ZDDY0009 If available collections does not provide a mapping : for the URI $name. : @error zerr:ZDDY0011 if the collection doesn't contain the given number of nodes. :) declare updating function dml:delete-nodes-last( $name as xs:string, $number as xs:integer) { qdml:delete-nodes-last(ddl:to-qname($name), $number) }; (:~ : The index-of function return the index of the given node in the collection. : : @param node The node to retrieve the index from. : : @return Returns the position as xs:integer of the given node in the collection. : : @error zerr:ZDDY0011 if node is not contained in any collection. : :) declare function dml:index-of($node as node()) as xs:integer { qdml:index-of($node) }; (:~ : The collection function returns the sequence of nodes of the collection : identified by the given name. : : @param $name The name of the collection. : : @return The sequence contained in the given collection. : : @error zerr:ZDDY0009 If available collections does not provide a mapping : for the URI $name. : :) declare function dml:collection($name as xs:string) as node()* { qdml:collection(ddl:to-qname($name)) }; (:~ : This function returns the name of the collection the given node belongs : to. : : @param $node The node for which to get the name of the collection : @return The result of this function is a URI which identifies the collection : to which the given node belongs to. : : @error zerr:ZDDY0011 if the given node does not belong to a collection. : :) declare function dml:collection-name($node as node()) as xs:string { ddl:from-qname(qdml:collection-name($node)) };