updated docs, schema

Author: epoberezkin

LANGUAGE.md

@@ -48,23 +48,6 @@ An asynchronous value is a value that is currently not available and will be ava
 
 JSONScript can include several instructions that will be executed sequentially:
 
-```json
-[
-  {
-    "$exec": "router",
-    "$method": "get",
-    "$args": { "path": "/resource/1" }
-  },
-  {
-    "$exec": "router",
-    "$method": "put",
-    "$args": { "path": "/resource/1", "body": "test" }
-  }
-]
-```
-
-or with short syntax:
-
 ```json
 [
   { "$$router.get": { "path": "/resource/1" } },
@@ -82,37 +65,6 @@ Sequential evaluation is not limited to executing individual instructions - any
 
 For example, this script does the same as the script above for two resources:
 
-```json
-[
-  [
-    {
-      "$exec": "router",
-      "$method": "get",
-      "$args": { "path": "/resource/1" }
-    },
-    {
-      "$exec": "router",
-      "$method": "put",
-      "$args": { "path": "/resource/1", "body": "test" }
-    }
-  ],
-  [
-    {
-      "$exec": "router",
-      "$method": "get",
-      "$args": { "path": "/resource/2" }
-    },
-    {
-      "$exec": "router",
-      "$method": "put",
-      "$args": { "path": "/resource/2", "body": "test" }
-    }
-  ]
-]
-```
-
-or with short syntax:
-
 ```json
 [
   [
@@ -134,23 +86,6 @@ The result of this script evaluation is the array of two arrays containing two i
 
 JSONScript can include several instructions that will be executed in parallel:
 
-```json
-{
-  "res1": {
-    "$exec": "router",
-    "$method": "get",
-    "$args": { "path": "/resource/1" }
-  },
-  "res2": {
-    "$exec": "router",
-    "$method": "get",
-    "$args": { "path": "/resource/2" }
-  }
-}
-```
-
-or with short syntax:
-
 ```json
 {
   "res1": { "$$router.get": { "path": "/resource/1" } },
@@ -168,37 +103,6 @@ Parallel evaluation is not limited to executing individual instructions - any sc
 
 For example, the script below is similar to the example in the previous section that updates two resources but it does it in parallel:
 
-```json
-{
-  "res1": [
-    {
-      "$exec": "router",
-      "$method": "get",
-      "$args": { "path": "/resource/1" }
-    },
-    {
-      "$exec": "router",
-      "$method": "put",
-      "$args": { "path": "/resource/1", "body": "test" }
-    }
-  ],
-  "res2": [
-    {
-      "$exec": "router",
-      "$method": "get",
-      "$args": { "path": "/resource/2" }
-    },
-    {
-      "$exec": "router",
-      "$method": "put",
-      "$args": { "path": "/resource/2", "body": "test" }
-    }
-  ]
-}
-```
-
-or with short syntax:
-
 ```json
 {
   "res1": [
@@ -225,23 +129,6 @@ Let's see what other instructions are defined in JSONScript core.
 
 During the evaluation the script can use the data instance passed to the interpeter in addition to the script:
 
-```json
-[
-  {
-    "$exec": "router",
-    "$method": "get",
-    "$args": { "path": { "$data": "/path" } }
-  },
-  {
-    "$exec": "router",
-    "$method": "put",
-    "$args": { "$data": "" }
-  }
-]
-```
-
-or with short syntax:
-
 ```json
 [
   { "$$router.get": { "path": { "$data": "/path" } } },
@@ -314,24 +201,6 @@ JSONScript interpreters should both try to determine such situations as early as
 
 `$if` instruction can be used to choose the strict that will be evaluated based on some condition:
 
-```json
-{
-  "$if": { "$exec": "checkAvailability", "$args": "router1" },
-  "$then": {
-    "$exec": "router1",
-    "$method": "get",
-    "$args": { "path": "/resource/1" }
-  },
-  "$else": {
-    "$exec": "router2",
-    "$method": "get",
-    "$args": { "path": "/resource/1" }
-  }
-}
-```
-
-or with short syntax:
-
 ```json
 {
   "$if": { "$$checkAvailability": "router1" },
@@ -353,7 +222,7 @@ Scalar values can be used in any place where the script is expected - they evalu
 ```json
 {
   "$exec": {
-    "$if": { "$exec": "checkAvailability", "$args": "router1" },
+    "$if": { "$$checkAvailability": "router1" },
     "$then": "router1",
     "$else": "router2"
   },
@@ -367,7 +236,7 @@ or using reference:
 ```json
 {
   "router": {
-    "$if": { "$exec": "checkAvailability", "$args": "router1" },
+    "$if": { "$$checkAvailability": "router1" },
     "$then": "router1",
     "$else": "router2"
   },
@@ -386,26 +255,6 @@ or using reference:
 
 `$delay` instruction can be used to delay the start of evaluation of any script. That can be useful, for example, if you need to ensure that one script starts evaluating after another script starts, but you don't need for it to wait for the completion (as in sequential processing):
 
-```json
-{
-  "res1": {
-    "$exec": "router",
-    "$method": "get",
-    "$args": { "path": "/resource/1" }
-  },
-  "res2": {
-    "$delay": {
-      "$exec": "router",
-      "$method": "get",
-      "$args": { "path": "/resource/2" }
-    },
-    "$wait": 50
-  }
-}
-```
-
-or with short syntax:
-
 ```json
 {
   "res1": { "$$router.get": { "path": "/resource/1" } },
@@ -420,19 +269,6 @@ The evaluation result will be the same as without `$delay` istruction, but the s
 
 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`:
 
-```json
-{
-  "$exec": "logger",
-  "$method": "resolve",
-  "$args": {
-    "message": "Resolved",
-    "asyncValue": { "$delay": "test", "$wait": 1000 }
-  }
-}
-```
-
-or with short syntax:
-
 ```json
 {
   "$$logger.resolve": {
@@ -451,34 +287,6 @@ In the example above a hypothetical logger logs message when asynchronous value
 
 Anonymous or named function can be defined in the script to be passed to executors (either predefined or supplied by user) or simply to be used multiple times.
 
-```json
-[
-  {
-    "$func": {
-      "$exec": "router",
-      "$method": "get",
-      "$args": { "path": { "$data": "/path" } }
-    },
-    "$name": "getRes",
-    "$args": [ "path" ]
-  },
-  {
-    "$call": "getRes",
-    "$args": [ "/resource/1" ]
-  },
-  {
-    "$call": { "$ref": "/0" },
-    "$args": { "path": "/resource/2" }
-  },
-  {
-    "$call": { "$ref": "1/0" },
-    "$args": "/resource/3"
-  }
-]
-```
-
-or with short syntax:
-
 ```json
 [
   {
@@ -502,32 +310,6 @@ In the example above the same function `getRes` is used three times, being calle
 
 Functions can be used as parameters in the executors:
 
-```json
-{
-  "$exec": "array",
-  "$method": "map",
-  "$args": {
-    "data": [
-      "/resource/1",
-      "/resource/2",
-      "/resource/3"
-    ],
-    "iterator": {
-      "$func": {
-        "$exec": "router1",
-        "$method": "get",
-        "$args": {
-          "path": { "$data": "/path" }
-        }
-      },
-      "$args": ["path"]
-    }
-  }
-}
-```
-
-or with short syntax:
-
 ```json
 {
   "$$array.map": {
@@ -546,6 +328,8 @@ or with short syntax:
 }
 ```
 
+See [Array iteration](#array-iteration).
+
 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".
 
 
@@ -566,9 +350,7 @@ 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:
 
 ```json
-{
-  "$func": { "$quote": "foo" }
-}
+{ "$func": { "$quote": "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`.

README.md

@@ -1,21 +1,50 @@
 # JSONScript
 
-Platform independent asynchronous and concurrent scripting language using JSON format.
-
-JSONScript is created to manage scripted execution in remote systems to avoid the latency between requests and unnecessary transfers of intermediary results.
+Language for scripted server-side processing of existing endpoints and services.
 
 [![Build Status](https://travis-ci.org/JSONScript/jsonscript.svg?branch=master)](https://travis-ci.org/JSONScript/jsonscript)
 [![npm version](https://badge.fury.io/js/jsonscript.svg)](https://www.npmjs.com/package/jsonscript)
 
 
-## Features
-
-JSONScript:
-
-- 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.
-- actual processing in the remote system is done synchronously or asynchronously by the functions and objects supplied to JSONScript interpreter by the host environment.
+## Script example
+
+```json
+{
+  "$$array.map": {
+    "data": [
+      { "path": "/resource/1", "body": { "test": 1 } },
+      { "path": "/resource/2", "body": { "test": 2 } },
+      { "path": "/resource/3", "body": { "test": 3 } },
+    ],
+    "iterator": {
+      "$func": [
+        { "$$router.get": { "path": { "$data": "/path" } } },
+        { "$$router.put": { "$data": "/" } },
+      ],
+      "$args": ["path", "body"]
+    }
+  }
+}
+```
+
+Using YAML for the same script makes it more readable:
+
+```yaml
+$$array.map:
+  data:
+    - { path: /resource/1, body: { test: 1 } }
+    - { path: /resource/2, body: { test: 2 } }
+    - { path: /resource/3, body: { test: 3 } }
+  iterator:
+    $func:
+      - $$router.get: { path: { $data: /path } }
+      - $$router.put: { $data: / }
+    $args: [ path, body ]
+```
+
+When executed on the server, the script above iterates array of requests, retrieves resource for each path and then updates it with a new value.
+
+See [Language](https://github.com/JSONScript/jsonscript/blob/master/LANGUAGE.md).
 
 
 ## Problem
@@ -45,17 +74,12 @@ At the same time JSONScript allows keeping the remote system completely secure a
 As the script executes, each instruction returns some data. By default this data replaces the script itself and all results will be available to the interpreter to pass back to the host system that requested execution. Host system usually sends results back to the client, but can do anything else with them, e.g. logging, storing to the database, etc.).
 
 
-## Language
-
-See [Language](https://github.com/JSONScript/jsonscript/blob/master/LANGUAGE.md)
-
-
 ## Schema
 
 See [Schema](https://github.com/JSONScript/jsonscript/blob/master/SCHEMA.md) for JSON-schemas for the script and for instruction definitions.
 
 
-## Implementation
+## Implementations
 
 JSONScript interpreter for node-js: [jsonscript-js](https://github.com/epoberezkin/jsonscript-js)
 

README_OLD.md

@@ -1,5 +1,7 @@
 # JSONScript syntax
 
+In progress - not complete, see [Language](https://github.com/JSONScript/jsonscript/blob/master/LANGUAGE.md).
+
 
 ## Script
 

SYNTAX.md

@@ -1,6 +1,6 @@
 {
   "name": "jsonscript",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Platform independent asynchronous and concurrent scripting language using JSON format",
   "main": "index.js",
   "scripts": {

package.json

@@ -200,65 +200,61 @@
       "id": "#macro_exec_0",
       "description": "short syntax for executor call",
       "type": "object",
-      "patternProperties": {
+      "patternGroups": {
         "^\\$\\$([^\\.]+)\\.([^\\.]+)$": {
-          "$ref": "#"
+          "schema": {
+            "$ref": "#"
+          },
+          "minimum": 1
         }
       },
       "maxProperties": 1,
-      "minProperties": 1,
-      "additionalProperties": false,
-      "patternRequired": [
-        "^\\$\\$([^\\.]+)\\.([^\\.]+)$"
-      ]
+      "additionalProperties": false
     },
     "_macro_exec_1": {
       "id": "#macro_exec_1",
       "description": "short syntax for executor call",
       "type": "object",
-      "patternProperties": {
+      "patternGroups": {
         "^\\$\\$([^\\.]+)$": {
-          "$ref": "#"
+          "schema": {
+            "$ref": "#"
+          },
+          "minimum": 1
         }
       },
       "maxProperties": 1,
-      "minProperties": 1,
-      "additionalProperties": false,
-      "patternRequired": [
-        "^\\$\\$([^\\.]+)$"
-      ]
+      "additionalProperties": false
     },
     "_macro_call_0": {
       "id": "#macro_call_0",
       "description": "short syntax for function call",
       "type": "object",
-      "patternProperties": {
+      "patternGroups": {
         "^\\$\\#(.+)$": {
-          "$ref": "#"
+          "schema": {
+            "$ref": "#"
+          },
+          "minimum": 1
         }
       },
       "maxProperties": 1,
-      "minProperties": 1,
-      "additionalProperties": false,
-      "patternRequired": [
-        "^\\$\\#(.+)$"
-      ]
+      "additionalProperties": false
     },
     "_macro_calc_0": {
       "id": "#macro_calc_0",
       "description": "short calculations syntax",
       "type": "object",
-      "patternProperties": {
+      "patternGroups": {
         "\\$([+\\-*/=!<>&\\|^]{1,2})": {
-          "$ref": "#"
+          "schema": {
+            "$ref": "#"
+          },
+          "minimum": 1
         }
       },
       "maxProperties": 1,
-      "minProperties": 1,
-      "additionalProperties": false,
-      "patternRequired": [
-        "\\$([+\\-*/=!<>&\\|^]{1,2})"
-      ]
+      "additionalProperties": false
     },
     "parallel": {
       "id": "#parallel",

schema/schema.json

@@ -59,13 +59,14 @@
           "id": "#macro_{{=macro.name}}_{{=i}}",
           "description": "{{=macro.description}}",
           "type": "object",
-          "patternProperties": {
-            "{{= patternKey }}": { "$ref": "#" }
+          "patternGroups": {
+            "{{= patternKey }}": {
+              "schema": { "$ref": "#" },
+              "minimum": 1
+            }
           },
           "maxProperties": 1,
-          "minProperties": 1,
-          "additionalProperties": false,
-          "patternRequired": [ "{{= patternKey }}" ]
+          "additionalProperties": false
         },
       {{~}}
     {{~}}

schema/schema.json.dot

@@ -346,65 +346,61 @@
       "id": "#macro_exec_0",
       "description": "short syntax for executor call",
       "type": "object",
-      "patternProperties": {
+      "patternGroups": {
         "^\\$\\$([^\\.]+)\\.([^\\.]+)$": {
-          "$ref": "#"
+          "schema": {
+            "$ref": "#"
+          },
+          "minimum": 1
         }
       },
       "maxProperties": 1,
-      "minProperties": 1,
-      "additionalProperties": false,
-      "patternRequired": [
-        "^\\$\\$([^\\.]+)\\.([^\\.]+)$"
-      ]
+      "additionalProperties": false
     },
     "_macro_exec_1": {
       "id": "#macro_exec_1",
       "description": "short syntax for executor call",
       "type": "object",
-      "patternProperties": {
+      "patternGroups": {
         "^\\$\\$([^\\.]+)$": {
-          "$ref": "#"
+          "schema": {
+            "$ref": "#"
+          },
+          "minimum": 1
         }
       },
       "maxProperties": 1,
-      "minProperties": 1,
-      "additionalProperties": false,
-      "patternRequired": [
-        "^\\$\\$([^\\.]+)$"
-      ]
+      "additionalProperties": false
     },
     "_macro_call_0": {
       "id": "#macro_call_0",
       "description": "short syntax for function call",
       "type": "object",
-      "patternProperties": {
+      "patternGroups": {
         "^\\$\\#(.+)$": {
-          "$ref": "#"
+          "schema": {
+            "$ref": "#"
+          },
+          "minimum": 1
         }
       },
       "maxProperties": 1,
-      "minProperties": 1,
-      "additionalProperties": false,
-      "patternRequired": [
-        "^\\$\\#(.+)$"
-      ]
+      "additionalProperties": false
     },
     "_macro_calc_0": {
       "id": "#macro_calc_0",
       "description": "short calculations syntax",
       "type": "object",
-      "patternProperties": {
+      "patternGroups": {
         "\\$([+\\-*/=!<>&\\|^]{1,2})": {
-          "$ref": "#"
+          "schema": {
+            "$ref": "#"
+          },
+          "minimum": 1
         }
       },
       "maxProperties": 1,
-      "minProperties": 1,
-      "additionalProperties": false,
-      "patternRequired": [
-        "\\$([+\\-*/=!<>&\\|^]{1,2})"
-      ]
+      "additionalProperties": false
     },
     "parallel": {
       "id": "#parallel",