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 items : contained in a particular collection. : : <p>Please refer to our documentation for <a href="../../html/data_lifecycle.html"> : more information</a> about the lifecycle management and the manipulation of such : collections.</p> : : @see <a href="../../html/data_lifecycle.html">Data Lifecycle</a> : @see http://www.zorba-xquery.com/modules/store/dynamic/collections/ddl : @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/dynamic :) module namespace dml = "http://www.zorba-xquery.com/modules/store/dynamic/collections/dml"; declare namespace zerr = "http://www.zorba-xquery.com/errors"; declare namespace an = "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. : : @deprecated please use the cdml:insert-first#2 function : :) declare updating function dml:insert-nodes-first($name as xs:QName, $content as node()*) external; (:~ : The insert-first function is an updating function that inserts copies of the : given items (nodes or json items) at the beginning of the collection. : : @param $name The name of the collection to which the items should be added. : @param $content The sequences of items 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 items into the collection. : : @error zerr:ZDDY0003 if the collection identified by $name is not available. : :) declare updating function dml:insert-first($name as xs:QName, $content as item()*) external; (:~ : 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. : : @deprecated please use the cdml:insert-last#2 function : :) declare updating function dml:insert-nodes-last($name as xs:QName, $content as node()*) external; (:~ : The insert-last function is an updating function that inserts copies of the : given items (nodes or json items) at the end of the collection. : : @param $name The name of the collection to which the items should be added. : @param $content The sequences of items 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 items into the collection. : : @error zerr:ZDDY0003 if the collection identified by $name is not available. : :) declare updating function dml:insert-last($name as xs:QName, $content as item()*) external; (:~ : 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. : : @deprecated please use the cdml:insert-before#3 function : :) declare updating function dml:insert-nodes-before( $name as xs:QName, $target as node(), $content as node()*) external; (:~ : The insert-before function is an updating function that inserts copies of : the given items (nodes or json items) into a collection at the position : directly preceding the given target item. : : @param $name The name of the collection to which the items should be added. : @param $target The item in the collection before which the $content : sequence should be inserted. : @param $content The sequences of items 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 items into the collection. : : @error zerr:ZDDY0003 if the collection identified by $name is not available. : @error zerr:ZDDY0011 if the target item is not contained in the collection. : :) declare updating function dml:insert-before($name as xs:QName, $target as item(), $content as item()*) external; (:~ : The insert-nodes-after function is an updating function that inserts : copies of the given nodes into a collection at the position directly 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. : : @deprecated please use the cdml:insert-after#3 function : :) declare updating function dml:insert-nodes-after( $name as xs:QName, $pos as node(), $content as node()*) external; (:~ : The insert-after function is an updating function that inserts copies of : the given items (nodes and/or json items) into a collection at the position : directly following the given target item. : : @param $name The name of the collection to which the items should be added. : @param $target The item in the collection after which the $content : sequence should be inserted. : @param $content The sequences of items 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 items 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-after($name as xs:QName, $pos as item(), $content as item()*) external; (:~ : This function does the same as the insert-nodes-first 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 : : @deprecated please use the cdml:apply-insert-first#2 function : :) declare %an:sequential function dml:apply-insert-nodes-first( $name as xs:QName, $content as node()*) as node()* external; (:~ : This function does the same as the insert-first function except it immediately : applies the resulting pending updates and returns the items that have been inserted. : : @param $name The name of the collection to which the items should be added. : @param $content The sequences of items whose copies should be added to the collection. : : @return The result of the function is the sequence of items that have been : inserted into the collection. : : @error zerr:ZDDY0003 if the collection identified by $name is not available. : : @see dml:insert-first : :) declare %an:sequential function dml:apply-insert-first($name as xs:QName, $content as item()*) as item()* external; (:~ : 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 : : @deprecated please use the cdml:apply-insert-last#2 function : :) declare %an:sequential function dml:apply-insert-nodes-last( $name as xs:QName, $content as node()*) as node()* external; (:~ : This function does the same as the insert-last function except it immediately : applies the resulting pending updates and returns the items that have been : inserted. : : @param $name The name of the collection to which the items should be added. : @param $content The sequences of items whose copies should be added to the collection. : : @return The result of the function is the sequence of items that have been : inserted into the collection. : : @error zerr:ZDDY0003 if the collection identified by $name is not available. : : @see dml:insert-last : :) declare %an:sequential function dml:apply-insert-last( $name as xs:QName, $content as item()*) as item()* external; (:~ : 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 : : @deprecated please use the cdml:apply-insert-before#3 function : :) declare %an:sequential function dml:apply-insert-nodes-before( $name as xs:QName, $target as node(), $content as node()*) as node()* external; (:~ : This function does the same as the insert-before function except it immediately : applies the resulting pending updates and returns the items that have been : inserted. : : @param $name The name of the collection to which the items should be added. : @param $target The item in the collection before which the $content : sequence should be inserted. : @param $content The sequences of items whose copies should be added to the collection. : : @return The result of the function is the sequence of items that have been : inserted into the collection. : : @error zerr:ZDDY0003 if the collection identified by $name is not available. : : @see dml:insert-before : :) declare %an:sequential function dml:apply-insert-before( $name as xs:QName, $target as item(), $content as item()*) as item()* external; (:~ : 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 : : @deprecated please use the cdml:apply-insert-after#3 function : :) declare %an:sequential function dml:apply-insert-nodes-after( $name as xs:QName, $pos as node(), $content as node()*) as node()* external; (:~ : This function does the same as the insert-after function except it immediately : applies the resulting pending updates and returns the items that have been : inserted. : : @param $name The name of the collection to which the items should be added. : @param $target The item in the collection after which the $content : sequence should be inserted. : @param $content The sequences of items whose copies should be added to the collection. : : @return The result of the function is the sequence of items that have been : inserted into the collection. : : @error zerr:ZDDY0003 if the collection identified by $name is not available. : : @see dml:insert-after : :) declare %an:sequential function dml:apply-insert-after( $name as xs:QName, $pos as item(), $content as item()*) as item()* external; (:~ : 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. : : @deprecated please use the cdml:delete#1 function : :) declare updating function dml:delete-nodes($target as node()*) external; (:~ : The delete function is an updating function that deletes zero of more items : (nodes and/or json items) from a collection. : : @param $target the items 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 items from their collections. : : @error zerr:ZDDY0011 if any item in the $target sequence is not a member of : a collection or not all items of the $target sequence belong to the : same collection. : :) declare updating function dml:delete($target as item()*) external; (:~ : 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. : : @deprecated please use the cdml:delete-first#1 function : :) declare updating function dml:delete-node-first($name as xs:QName) external; (:~ : The delete-first function is an updating function that deletes the first item : from a collection. : : @param $name The name of the collection from which the first item 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 item from the collection. : : @error zerr:ZDDY0011 if the collection doesn't contain any item. : :) declare updating function dml:delete-first($name as xs:QName) external; (:~ : 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. : : @deprecated please use the cdml:delete-first#2 function : :) declare updating function dml:delete-nodes-first($name as xs:QName, $number as xs:integer) external; (:~ : The delete-first function is an updating function that deletes the first N : items from a collection. : : @param $name The name of the collection from which the first N items should be deleted. : @param $number The number N of items 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 items from the collection. : : @error zerr:ZDDY0011 if the collection doesn't contain the given number of items. : :) declare updating function dml:delete-first($name as xs:QName, $number as xs:integer) external; (:~ : 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 last 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:ZDDY0003 If available collections does not provide a mapping : for the expanded QName $name. : @error zerr:ZDDY0011 if the collection doesn't contain any node. : : @deprecated please use the cdml:delete-last#1 function : :) declare updating function dml:delete-node-last($name as xs:QName) external; (:~ : The delete-last function is an updating function that deletes the last item : from a collection. : : @param $name The name of the collection from which the last item 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 item from the collection. : : @error zerr:ZDDY0003 If available collections does not provide a mapping : for the expanded QName $name. : @error zerr:ZDDY0011 if the collection doesn't contain any item. : :) declare updating function dml:delete-last($name as xs:QName) external; (:~ : 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:ZDDY0003 If available collections does not provide a mapping : for the expanded QName $name. : @error zerr:ZDDY0011 if the collection doesn't contain the given number of nodes. : : @deprecated please use the cdml:delete-last#2 function : :) declare updating function dml:delete-nodes-last($name as xs:QName, $number as xs:integer) external; (:~ : The delete-last function is an updating function that deletes the last N : items from an ordered collection. : : @param $name The name of the collection from which the lsat N items should be deleted. : @param $number The number N of items 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 items. : : @error zerr:ZDDY0003 If available collections does not provide a mapping : for the expanded QName $name. : @error zerr:ZDDY0011 if the collection doesn't contain the given number of items. : :) declare updating function dml:delete-last($name as xs:QName, $number as xs:integer) external; (:~ : The edit function is an updating function that edits the first supplied : item so as to make it look exactly like a copy of the second supplied item, : while retaining its original identity. : : @param $target The target item ,that must be edited. : @param $content The content item, that serves as an edit goal. : : @return The result of the function is an empty XDM instance and a pending update list : which, once applied, performs the replacement. : : @error zerr:ZDDY0003 if the collection to which $target belongs is not available. : @error zerr:ZDDY0006 if the modifier property of the collection to which $target : belongs is append-only, const, or queue. : @error zerr:ZDDY0017 if the $target item is not a member of a collection. : @error zerr:ZDDY0037 if the collection is append-only. : @error zerr:ZDDY0038 if the collection is a queue. : @error zerr:ZDDY0039 if the $target item is not a root. : @error zerr:ZDDY0040 if the target cannot be updated to match the content (for : example because the target is a node and the content is an object). : :) declare updating function dml:edit($target as item(), $content as item()) external; (:~ : The truncate function is an updating function that deletes the : entire contents of collection. : : @param $name The name of the collection whose content to delete : : @return The result of this function is an empty XDM instance and a pending update : list which, once applied, deletes the nodes. : : @error zerr:ZDDY0003 if the collection identified by $name is not available. :) declare updating function dml:truncate($name as xs:QName) external; (:~ : The collection function returns the sequence of nodes and/or json items : that belong to the collection identified by the given name. : : @param $name The name of the collection. : : @return The sequence contained in the given collection. : : @error zerr:ZDDY0003 If available collections does not provide a mapping : for the expanded QName $name. : :) declare function dml:collection($name as xs:QName) as item()* external; (:~ : The collection function returns the sequence of nodes and/or json items : that belong to the collection identified by the given name. : : @param $name The name of the collection. : @param $skip The number of collection items to skip. : : @return The sequence contained in the given collection. : : @error zerr:ZDDY0003 If available collections does not provide a mapping : for the expanded QName $name. : :) declare function dml:collection($name as xs:QName, $skip as xs:integer) as item()* external; (:~ : The collection function returns the sequence of nodes and/or json items : that belong to the collection identified by the given name. : The parameters $start and $skip can be used to skip over some items at : the beginning of the collection. If both are given, both are applied: : first $start to skip to the referenced item and then $skip to skip an : additional number of items. : : @param $name The name of the collection. : @param $start A reference to the first item to return. All items before are skipped. : @param $skip The number of collection items to skip. : : @return The sequence contained in the given collection. : : @error zerr:ZAPI0028 If the given URI is not a valid node : position computed by the <tt>np:node-position</tt> function. : @error zerr:ZDDY0003 If available collections does not provide a mapping : for the expanded QName $name. : @error zerr:ZSTR0066 If the passed reference $start does not reference : a node from the collection identified by $name. : :) declare function dml:collection($name as xs:QName, $start as xs:anyURI, $skip as xs:integer) as item()* external; (:~ : The collection-name function returns the name of the collection the given : item (node or json item) belongs to. : : @param $item The item for which to get the name of the collection : @return The result of this function is a QName which identifies the collection : to which the given item belongs to. : : @error zerr:ZDDY0011 if the given item does not belong to a collection. : :) declare function dml:collection-name($item as item()) as xs:QName external; (:~ : The index-of function returns the position of the given item (node or : json item) within its containing the collection. : : @param $item The item to retrieve the index from. : : @return Returns the position as xs:integer of the given item in the collection. : : @error zerr:ZDDY0011 if the item is not contained in any collection. : :) declare function dml:index-of($item as item()) as xs:integer external;