More $error() functionality (#353)

* Add more test cases for $error()

* Add documentation for $error() function.

* Respond to PR comments.

Author: jhorbulyk

docs/object-functions.md

@@ -13,7 +13,7 @@ Returns an array containing the keys in the object.  If the argument is an array
 __Signature:__ `$lookup(object, key)`
 
 Returns the value associated with `key` in `object`. If the first argument is an array of objects, then all of the objects in the array are searched, and the values associated with all occurrences of `key` are returned.
-  
+
 
 ## `$spread()`
 __Signature:__ `$spread(object)`
@@ -39,7 +39,7 @@ The `function` parameter will get invoked with two arguments:
 
 `function(value, name)`
 
-where the `value` parameter is the value of each name/value pair in the object and `name` is its name.  The `name` parameter is optional. 
+where the `value` parameter is the value of each name/value pair in the object and `name` is its name.  The `name` parameter is optional.
 
 __Examples__
 
@@ -51,4 +51,9 @@ __Examples__
       "Street: Hursley Park",
       "City: Winchester",
       "Postcode: SO21 2JN"
-    ]
+    ]
+
+ ## `$error()`
+__Signature:__`$error(message)`
+
+Deliberately throws an error with an optional `message`

src/jsonata.js

@@ -1810,7 +1810,8 @@ var jsonata = (function() {
         "D3133": "The 'name' modifier can only be applied to months and days in the date/time picture string, not {{value}}",
         "D3134": "The timezone integer format specifier cannot have more than four digits",
         "D3135": "No matching closing bracket ']' in date/time picture string",
-        "D3136": "The date/time picture string is missing specifiers required to parse the timestamp"
+        "D3136": "The date/time picture string is missing specifiers required to parse the timestamp",
+        "D3137": "{{{message}}}"
     };
 
     /**

test/test-suite/groups/function-error/case000.json

@@ -2,5 +2,8 @@
     "expr": "Account.Order[0].Product[0].Price > 35 ? Account.Order[0].Product[0].Price : $error('Too Expensive')",
     "dataset": "dataset5",
     "bindings": {},
-    "code": "D3137"
+    "error": {
+        "code": "D3137",
+        "message": "Too Expensive"
+    }    
 }

test/test-suite/groups/function-error/case003.json

@@ -2,5 +2,8 @@
     "expr": "Account.Order[0].Product[0].Price > 34 ? $error('Too Expensive') : Account.Order[0].Product[0].Price",
     "dataset": "dataset5",
     "bindings": {},
-    "code": "D3137"
+    "error": {
+        "code": "D3137",
+        "message": "Too Expensive"
+    }
 }

test/test-suite/groups/function-error/case005.json

@@ -2,5 +2,8 @@
     "expr": "$count(Account.Order[0].Product) < 3 ? $error('Not enough products in orders')",
     "dataset": "dataset5",
     "bindings": {},
-    "code": "D3137"
+    "error": {
+        "code": "D3137",
+        "message": "Not enough products in orders"
+    }
 }

test/test-suite/groups/function-error/case006.json

@@ -1,6 +1,9 @@
 {
-    "expr": "($msg='My Message'; $error($msg); true)",
+    "expr": "($msg:='My Message'; $error($msg); true)",
     "dataset": "dataset5",
     "bindings": {},
-    "code": "D3137"
+    "error": {
+        "code": "D3137",
+        "message": "My Message"
+    }
 }

test/test-suite/groups/function-error/case009.json

@@ -2,5 +2,8 @@
     "expr": "$error()",
     "dataset": "dataset5",
     "bindings": {},
-    "code": "D3137"
+    "error": {
+        "code": "D3137",
+        "message": "$error() function evaluated"
+    }
 }

test/test-suite/groups/function-error/case010.json

@@ -2,5 +2,8 @@
     "expr": "$error(foo)",
     "dataset": "dataset5",
     "bindings": {},
-    "code": "D3137"
+    "error": {
+        "code": "D3137",
+        "message": "$error() function evaluated"
+    }
 }