macros; macro definitions for the short syntax of $exec and $call instructions

Author: epoberezkin

LANGUAGE.md

@@ -18,6 +18,14 @@ In the example above it is an object with the name `"router"` (the value of the
 
 When this simple script is evaluated its value will be the resolved value that the executor returns. See [Synchronous and asynchronous values](#synchronous-and-asynchronous-values).
 
+The full syntax above allows all properties to be evaluated - executor name and methods can be the result of some other scripts. For the majority of cases when these are constants the short syntax can be used:
+
+```json
+{ "$$router.get": { "path": "/resource/1" } }
+```
+
+This is achieved via [macros](#macros) support.
+
 JSONScript core includes other instructions that will be shown later and the interpreter may allow to define your own custom instructions.
 
 With JSONScript you can combine instructions in three ways:
@@ -50,11 +58,20 @@ JSONScript can include several instructions that will be executed sequentially:
   {
     "$exec": "router",
     "$method": "put",
-    "$args": { "path": "/resource/1", "body": { "test": "test" } }
+    "$args": { "path": "/resource/1", "body": "test" }
   }
 ]
 ```
 
+or with short syntax:
+
+```json
+[
+  { "$$router.get": { "path": "/resource/1" } },
+  { "$$router.put": { "path": "/resource/1", "body": "test" } }
+]
+```
+
 "Sequential" means that the next script begins evaluating only after the script in the previous item has evaluated (and if the result is an asynchronous value this value has resolved into synchronous).
 
 The example above will retrive the value of some resource and once it was retrieved it will update it. The sequential execution guarantees that it will be the value before the update.
@@ -76,7 +93,7 @@ For example, this script does the same as the script above for two resources:
     {
       "$exec": "router",
       "$method": "put",
-      "$args": { "path": "/resource/1", "body": { "test": "test" } }
+      "$args": { "path": "/resource/1", "body": "test" }
     }
   ],
   [
@@ -88,12 +105,28 @@ For example, this script does the same as the script above for two resources:
     {
       "$exec": "router",
       "$method": "put",
-      "$args": { "path": "/resource/2", "body": { "test": "test" } }
+      "$args": { "path": "/resource/2", "body": "test" }
     }
   ]
 ]
 ```
 
+or with short syntax:
+
+```json
+[
+  [
+    { "$$router.get": { "path": "/resource/1" } },
+    { "$$router.put": { "path": "/resource/1", "body": "test" } }
+  ],
+  [
+    { "$$router.get": { "path": "/resource/2" } },
+    { "$$router.put": { "path": "/resource/2", "body": "test" } }
+  ]
+]
+```
+
+
 The result of this script evaluation is the array of two arrays containing two items each, the items being the results of evaluation of individual instructions.
 
 
@@ -116,6 +149,15 @@ JSONScript can include several instructions that will be executed in parallel:
 }
 ```
 
+or with short syntax:
+
+```json
+{
+  "res1": { "$$router.get": { "path": "/resource/1" } },
+  "res2": { "$$router.get": { "path": "/resource/2" } }
+}
+```
+
 The meaning of "parallel" depends on the environment in which the script executes and on the interpreter implementation. The implementation should not guarantee any order in which evaluation of individual scripts will start, and instructions don't wait until another instruction evaluates (and resolves) to begin executing.
 
 The example above retrieves the values fo two resources. The result of the evaluation of the whole script above is a single asynchronous value (assuming that instructions return asynchronous values) that resolves into the object with the results of both instructions available in properties `"res1"` and `"res2"`.
@@ -137,7 +179,7 @@ For example, the script below is similar to the example in the previous section
     {
       "$exec": "router",
       "$method": "put",
-      "$args": { "path": "/resource/1", "body": { "test": "test" } }
+      "$args": { "path": "/resource/1", "body": "test" }
     }
   ],
   "res2": [
@@ -149,12 +191,27 @@ For example, the script below is similar to the example in the previous section
     {
       "$exec": "router",
       "$method": "put",
-      "$args": { "path": "/resource/2", "body": { "test": "test" } }
+      "$args": { "path": "/resource/2", "body": "test" }
     }
   ]
 }
 ```
 
+or with short syntax:
+
+```json
+{
+  "res1": [
+    { "$$router.get": { "path": "/resource/1" } },
+    { "$$router.put": { "path": "/resource/1", "body": "test" } }
+  ],
+  "res2": [
+    { "$$router.get": { "path": "/resource/2" } },
+    { "$$router.put": { "path": "/resource/2", "body": "test" } }
+  ]
+}
+```
+
 This example combines parallel and sequential evaluation. Each resource update only starts after the current value is retrieved, but the update of `"/resource/2"` does not need to wait until the `"/resource/1"` finished updating.
 
 The result of this script evaluation is the object with two properties `"res1"` and `"res2"` each containing two items with the results of individual instructions.
@@ -183,6 +240,15 @@ During the evaluation the script can use the data instance passed to the interpe
 ]
 ```
 
+or with short syntax:
+
+```json
+[
+  { "$$router.get: { "path": { "$data": "/path" } } },
+  { "$$router.put": { "$data": "" } }
+]
+```
+
 Data instance:
 
 ```json
@@ -264,6 +330,16 @@ JSONScript interpreters should both try to determine such situations as early as
 }
 ```
 
+or with short syntax:
+
+```json
+{
+  "$if": { "$$checkAvailability": "router1" },
+  "$then": { "$$router1.get": { "path": "/resource/1" } },
+  "$else": { "$$router2.get": { "path": "/resource/1" } }
+}
+```
+
 The result of the evaluation of the script in `$if` keyword should be a boolean value, otherwise the whole script will fail to evailuate (no type coercion is made).
 
 If the condition is `true` then the script in `$then` keyword will be evaluted and its result will be the result of `$if` instruction, otherwise the script in `$else` will be evaluated and `$if` evaluate to its result.
@@ -328,6 +404,18 @@ or using reference:
 }
 ```
 
+or with short syntax:
+
+```json
+{
+  "res1": { "$$router.get": { "path": "/resource/1" } },
+  "res2": {
+    "$delay": { "$$router.get": { "path": "/resource/2" } },
+    "$wait": 50
+  }
+}
+```
+
 The evaluation result will be the same as without `$delay` istruction, but the second "$exec" instruction will start executing at least 50 milliseconds later than the first.
 
 This instruction can also be used to create asynchronous value from synchronous value. For example if some executor expects an asynchronous value as an argument and you want to pass a constant, you can use `$delay`:
@@ -343,6 +431,17 @@ This instruction can also be used to create asynchronous value from synchronous
 }
 ```
 
+or with short syntax:
+
+```json
+{
+  "$$logger.resolve": {
+    "message": "Resolved",
+    "asyncValue": { "$delay": "test", "$wait": 1000 }
+  }
+}
+```
+
 In the example above a hypothetical logger logs message when asynchronous value is resolved. `$delay` instruction result is an asynchrnous value that resolves 1 second after its evaluation with the value `"test"`.
 
 `$wait` keyword is optional, the default is 0. It means that the interpreter should schedule the script evaluation as soon as possible but do not execute it immediately.
@@ -378,6 +477,27 @@ Anonymous or named function can be defined in the script to be passed to executo
 ]
 ```
 
+or with short syntax:
+
+```json
+[
+  {
+    "$func": { "$$router.get" { "path": { "$data": "/path" } } },
+    "$name": "getRes",
+    "$args": [ "path" ]
+  },
+  { "$#getRes": [ "/resource/1" ] },
+  {
+    "$call": { "$ref": "/0" },
+    "$args": { "path": "/resource/2" }
+  },
+  {
+    "$call": { "$ref": "1/0" },
+    "$args": "/resource/3"
+  }
+]
+```
+
 In the example above the same function `getRes` is used three times, being called by name and using $ref with absolute and relative JSON-pointers. Arguments can be passed to function as array, as an object (property names should match parameters declarations, otherwise an exception will be thrown) and as a scalar value if there is only one parameter.
 
 Functions can be used as parameters in the executors:
@@ -406,6 +526,26 @@ Functions can be used as parameters in the executors:
 }
 ```
 
+or with short syntax:
+
+```json
+{
+  "$$array.map": {
+    "data": [
+      "/resource/1",
+      "/resource/2",
+      "/resource/3"
+    ],
+    "iterator": {
+      "$func": {
+        "$$router1.get": { "path": { "$data": "/path" } }
+      },
+      "$args": ["path"]
+    }
+  }
+}
+```
+
 If the function was previously defined it can be passed either using `"$ref"` with an absolute or relative JSON-pointer or `{ "$func": "myfunc" }. The latter always evaluates as the reference to the existing function rather than the function that always returns string "myfunc", to define the function that always returns the same string you can use "$quote".
 
 
@@ -421,7 +561,7 @@ To insert an object that contains properties that start with `"$"` that normally
 }
 ```
 
-evaluates as: `{ "$exec": "myExec" }`.
+evaluates as: `{ "$exec": "myExec" }` and the executor is not called.
 
 `$quote` can also be used to define the function that always returns the same string:
 
@@ -431,4 +571,9 @@ evaluates as: `{ "$exec": "myExec" }`.
 }
 ```
 
-The anonymous function defined above always returns the string `"foo"`. Without `$quote` it would be the reference to the function with the name `foo`.
+The anonymous function defined above always returns the string `"foo"`. Without `$quote` it would have been the reference to the function with the name `foo`.
+
+
+## Macros
+
+JSONScript defines several core macros to support short syntax for executor and function calls and for calculations. The interpreter may allow to define your own custom macros.

README.md

@@ -12,9 +12,9 @@ JSONScript is created to manage scripted execution in remote systems to avoid th
 
 JSONScript:
 
-- uses JSON as its representaion format for both data and control structures, being similar to lisp (homoiconic)
+- uses JSON as its representaion format for both data and control structures, being similar to lisp (homoiconic).
 - defines simple control structures.
-- is asynchronous and concurrent without the need to use any special keywords
+- is asynchronous and concurrent without the need to use any special keywords.
 - actual processing in the remote system is done synchronously or asynchronously by the functions and objects supplied to JSONScript interpreter by the host environment.
 
 

SCHEMA.md

@@ -1,11 +1,15 @@
 # JSONScript Schema
 
-JSONScript uses JSON-Schema standard both for the validation schemas and for the schema that defines evaluation process.
+JSONScript uses JSON-Schema standard both for the validation schemas and for the schemas that define macro expansion and evaluation process.
 
-[JSONScript schema](http://www.json-script.com/schema/schema.json#) the schema that does not validate scalar keywords in instructions (keyword values can be scripts and have to be validated when the script is evaluated).
+[JSONScript schema](http://www.json-script.com/schema/schema.json#) - the schema for JSONScript that does not validate scalar keywords in instructions (keyword values can be scripts and have to be validated when the script is evaluated).
 
-[JSONScript strict schema](http://www.json-script.com/schema/schema_strict.json#) the schema that validates scalar keywords in instructions.
+[JSONScript strict schema](http://www.json-script.com/schema/schema_strict.json#) - the schema for JSONScript that validates scalar keywords in instructions.
 
-[JSONScript evaluation schema](http://www.json-script.com/schema/evaluate.json#) this schema defines evalution process. It can be used by implementations to evaluate scripts. It contains non-standard keywords.
+[Macro expansion schema](http://www.json-script.com/schema/expand_macros.json#) - this schema defines macro expansion process. It can be used by implementations to expand macros in the scripts before their evaluation. It contains non-standard keyword `expandJsMacro`.
 
-[Instruction definition schema](http://www.json-script.com/schema/instruction.json#) the schema for instruction defnitions. The definitions of both standard and user-defined instructions should be valid according to this schema.
+[Evaluation schema](http://www.json-script.com/schema/evaluate.json#) - this schema defines evalution process. It can be used by implementations to evaluate scripts. It contains non-standard keywords.
+
+[Instruction definition schema](http://www.json-script.com/schema/instruction.json#) - the schema for instruction defnitions. The definitions of both standard and user-defined instructions should be valid according to this schema.
+
+[Macro definition schema](http://www.json-script.com/schema/macro.json#) - the schema for macro definition. The definitions of both standard and user-defined macros should be valid according to this schema.

macros/call.json

@@ -0,0 +1,16 @@
+{
+  "name": "call",
+  "description": "function call",
+  "rules": [
+    {
+      "description": "call named function with arguments",
+      "rule": {
+        "^\\$\\#(.+)$": 1
+      },
+      "script": {
+        "$call": "$1",
+        "$args": 1
+      }
+    }
+  ]
+}

macros/exec.json

@@ -0,0 +1,27 @@
+{
+  "name": "exec",
+  "description": "executor call",
+  "rules": [
+    {
+      "description": "executor call without method",
+      "rule": {
+        "^\\$\\$([^\\.]+)$": 1
+      },
+      "script": {
+        "$exec": "$1",
+        "$args": 1
+      }
+    },
+    {
+      "description": "executor call with method",
+      "rule": {
+        "^\\$\\$([^\\.]+)\\.([^\\.]+)$": 1
+      },
+      "script": {
+        "$exec": "$1",
+        "$method": "$2",
+        "$args": 1
+      }
+    }
+  ]
+}

macros/index.js

@@ -0,0 +1,6 @@
+'use strict';
+
+module.exports = [
+  require('./exec.json'),
+  require('./call.json')
+];