issue #736: AQL function to parse collection and key from document handle

CHANGELOG

@@ -3,6 +3,8 @@ v1.5.0 (XXXX-XX-XX)
 
 * issue #738: added __dirname, __filename pseudo-globals. Fixes #733. (@by pluma)
 
+* issue #736: AQL function to parse collection and key from document handle
+
 * allow `\n` (as well as `\r\n`) as line terminator in batch requests sent to 
   `/_api/batch` HTTP API.
 

Documentation/UserManual/Aql.md

@@ -1259,6 +1259,19 @@ AQL supports the following functions to operate on document values:
 
     RETURN KEEP(doc, 'firstname', 'name', 'likes')
 
+- @FN{PARSE_IDENTIFIER(@FA{document-handle})}: parses the document handle specified in 
+  @FA{document-handle} and returns a the handle's individual parts a separate attributes.
+  This function can be used to easily determine the collection name and key from a given document.
+  The @FA{document-handle} can either be a regular document from a collection, or a document
+  identifier string (e.g. `_users/1234`). Passing either a non-string or a non-document or a
+  document without an `_id` attribute will result in an error.
+
+    RETURN PARSE_IDENTIFIER('_users/my-user')
+    [ { "collection" : "_users", "key" : "my-user" } ]
+
+    RETURN PARSE_IDENTIFIER({ "_id" : "mycollection/mykey", "value" : "some value" })
+    [ { "collection" : "mycollection", "key" : "mykey" } ]
+
 @subsubsection AqlFunctionsGeo Geo functions
 
 AQL offers the following functions to filter data based on geo indexes:

arangod/Ahuacatl/ahuacatl-functions.c

@@ -714,6 +714,7 @@ TRI_associative_pointer_t* TRI_CreateFunctionsAql (void) {
   REGISTER_FUNCTION("NOT_NULL", "NOT_NULL", true, false, ".|+", NULL);
   REGISTER_FUNCTION("FIRST_LIST", "FIRST_LIST", true, false, ".|+", NULL);
   REGISTER_FUNCTION("FIRST_DOCUMENT", "FIRST_DOCUMENT", true, false, ".|+", NULL);
+  REGISTER_FUNCTION("PARSE_IDENTIFIER", "PARSE_IDENTIFIER", true, false, ".", NULL);
 
   if (! result) {
     TRI_FreeFunctionsAql(functions);

js/server/modules/org/arangodb/ahuacatl.js

@@ -3254,6 +3254,36 @@ function FIRST_DOCUMENT () {
   return null;
 }
 
+////////////////////////////////////////////////////////////////////////////////
+/// @brief return the parts of a document identifier separately
+///
+/// returns a document with the attributes `collection` and `key` or fails if
+/// the individual parts cannot be determined.
+////////////////////////////////////////////////////////////////////////////////
+
+function PARSE_IDENTIFIER (value) {
+  "use strict";
+
+  if (TYPEWEIGHT(value) === TYPEWEIGHT_STRING) {
+    var parts = value.split('/');
+    if (parts.length === 2) {
+      return { 
+        collection: parts[0],
+        key: parts[1]
+      };
+    }
+    // fall through intentional
+  }
+  else if (TYPEWEIGHT(value) === TYPEWEIGHT_DOCUMENT) {
+    if (value.hasOwnProperty('_id')) {
+      return PARSE_IDENTIFIER(value._id);
+    }
+    // fall through intentional
+  }
+  
+  THROW(INTERNAL.errors.ERROR_QUERY_FUNCTION_ARGUMENT_TYPE_MISMATCH, "PARSE_IDENTIFIER");
+}
+
 ////////////////////////////////////////////////////////////////////////////////
 /// @brief check whether a document has a specific attribute
 ////////////////////////////////////////////////////////////////////////////////
@@ -4048,6 +4078,7 @@ exports.GRAPH_NEIGHBORS = GRAPH_NEIGHBORS;
 exports.NOT_NULL = NOT_NULL;
 exports.FIRST_LIST = FIRST_LIST;
 exports.FIRST_DOCUMENT = FIRST_DOCUMENT;
+exports.PARSE_IDENTIFIER = PARSE_IDENTIFIER;
 exports.HAS = HAS;
 exports.ATTRIBUTES = ATTRIBUTES;
 exports.UNSET = UNSET;

js/server/tests/ahuacatl-functions.js

@@ -1869,6 +1869,90 @@ function ahuacatlFunctionsTestSuite () {
       assertEqual(expected, actual);
     },
 
+////////////////////////////////////////////////////////////////////////////////
+/// @brief test parse identifier function
+////////////////////////////////////////////////////////////////////////////////
+    
+    testParseIdentifier : function () {
+      var actual;
+
+      actual = getQueryResults("RETURN PARSE_IDENTIFIER('foo/bar')");
+      assertEqual([ { collection: 'foo', key: 'bar' } ], actual);
+      
+      actual = getQueryResults("RETURN PARSE_IDENTIFIER('this-is-a-collection-name/and-this-is-an-id')");
+      assertEqual([ { collection: 'this-is-a-collection-name', key: 'and-this-is-an-id' } ], actual);
+      
+      actual = getQueryResults("RETURN PARSE_IDENTIFIER('MY_COLLECTION/MY_DOC')");
+      assertEqual([ { collection: 'MY_COLLECTION', key: 'MY_DOC' } ], actual);
+
+      actual = getQueryResults("RETURN PARSE_IDENTIFIER('_users/AbC')");
+      assertEqual([ { collection: '_users', key: 'AbC' } ], actual);
+      
+      actual = getQueryResults("RETURN PARSE_IDENTIFIER({ _id: 'foo/bar', value: 'baz' })");
+      assertEqual([ { collection: 'foo', key: 'bar' } ], actual);
+
+      actual = getQueryResults("RETURN PARSE_IDENTIFIER({ ignore: true, _id: '_system/VALUE', value: 'baz' })");
+      assertEqual([ { collection: '_system', key: 'VALUE' } ], actual);
+
+      actual = getQueryResults("RETURN PARSE_IDENTIFIER({ value: 123, _id: 'Some-Odd-Collection/THIS_IS_THE_KEY' })");
+      assertEqual([ { collection: 'Some-Odd-Collection', key: 'THIS_IS_THE_KEY' } ], actual);
+    },
+
+////////////////////////////////////////////////////////////////////////////////
+/// @brief test parse identifier function
+////////////////////////////////////////////////////////////////////////////////
+    
+    testParseIdentifierCollection : function () {
+      var cn = "UnitTestsAhuacatlFunctions";
+
+      internal.db._drop(cn);
+      var cx = internal.db._create(cn);
+      cx.save({ "title" : "123", "value" : 456, "_key" : "foobar" });
+      cx.save({ "_key" : "so-this-is-it", "title" : "nada", "value" : 123 });
+
+      var expected, actual;
+      
+      expected = [ { collection: cn, key: "foobar" } ];
+      actual = getQueryResults("RETURN PARSE_IDENTIFIER(DOCUMENT(CONCAT(@cn, '/', @key)))", { cn: cn, key: "foobar" });
+      assertEqual(expected, actual);
+
+      expected = [ { collection: cn, key: "foobar" } ];
+      actual = getQueryResults("RETURN PARSE_IDENTIFIER(DOCUMENT(CONCAT(@cn, '/', @key)))", { cn: cn, key: "foobar" });
+      assertEqual(expected, actual);
+
+      expected = [ { collection: cn, key: "foobar" } ];
+      actual = getQueryResults("RETURN PARSE_IDENTIFIER(DOCUMENT(CONCAT(@cn, '/', 'foobar')))", { cn: cn });
+      assertEqual(expected, actual);
+
+      expected = [ { collection: cn, key: "foobar" } ];
+      actual = getQueryResults("RETURN PARSE_IDENTIFIER(DOCUMENT([ @key ])[0])", { key: "UnitTestsAhuacatlFunctions/foobar" });
+      assertEqual(expected, actual);
+
+      expected = [ { collection: cn, key: "so-this-is-it" } ];
+      actual = getQueryResults("RETURN PARSE_IDENTIFIER(DOCUMENT([ 'UnitTestsAhuacatlFunctions/so-this-is-it' ])[0])");
+      assertEqual(expected, actual);
+
+      internal.db._drop(cn);
+    },
+
+////////////////////////////////////////////////////////////////////////////////
+/// @brief test parse identifier function
+////////////////////////////////////////////////////////////////////////////////
+
+    testParseIdentifier : function () {
+      assertQueryError(errors.ERROR_QUERY_FUNCTION_ARGUMENT_NUMBER_MISMATCH.code, "RETURN PARSE_IDENTIFIER()"); 
+      assertQueryError(errors.ERROR_QUERY_FUNCTION_ARGUMENT_NUMBER_MISMATCH.code, "RETURN PARSE_IDENTIFIER('foo', 'bar')");
+      assertQueryError(errors.ERROR_QUERY_FUNCTION_ARGUMENT_TYPE_MISMATCH.code, "RETURN PARSE_IDENTIFIER(null)"); 
+      assertQueryError(errors.ERROR_QUERY_FUNCTION_ARGUMENT_TYPE_MISMATCH.code, "RETURN PARSE_IDENTIFIER(false)"); 
+      assertQueryError(errors.ERROR_QUERY_FUNCTION_ARGUMENT_TYPE_MISMATCH.code, "RETURN PARSE_IDENTIFIER(3)"); 
+      assertQueryError(errors.ERROR_QUERY_FUNCTION_ARGUMENT_TYPE_MISMATCH.code, "RETURN PARSE_IDENTIFIER(\"foo\")"); 
+      assertQueryError(errors.ERROR_QUERY_FUNCTION_ARGUMENT_TYPE_MISMATCH.code, "RETURN PARSE_IDENTIFIER('foo bar')"); 
+      assertQueryError(errors.ERROR_QUERY_FUNCTION_ARGUMENT_TYPE_MISMATCH.code, "RETURN PARSE_IDENTIFIER('foo/bar/baz')"); 
+      assertQueryError(errors.ERROR_QUERY_FUNCTION_ARGUMENT_TYPE_MISMATCH.code, "RETURN PARSE_IDENTIFIER([ ])"); 
+      assertQueryError(errors.ERROR_QUERY_FUNCTION_ARGUMENT_TYPE_MISMATCH.code, "RETURN PARSE_IDENTIFIER({ })"); 
+      assertQueryError(errors.ERROR_QUERY_FUNCTION_ARGUMENT_TYPE_MISMATCH.code, "RETURN PARSE_IDENTIFIER({ foo: 'bar' })"); 
+    },
+
 ////////////////////////////////////////////////////////////////////////////////
 /// @brief test document function
 ////////////////////////////////////////////////////////////////////////////////