[WIP] 0.3.0

TODO.md

@@ -1,67 +1,101 @@
 New ideas and improvements for future releases
 ==============================================
 
-[0] Improvements for v0.2.x
------------------------------------------
+## Improvements for v0.3.x
 - Improve code allowing backward references and preventing forward ones inside a scope
 
-[1] New user-defined validators
------------------------------------------
-
+## New user-defined validators
+```yaml
 def:
   - $MY_VALIDATOR:                                       # name (part of the signature)
     - [myPath:path, num:integer|boolean, ...rest:string] # arguments (part of the signature)
     - isType: [{$var: path}, path]                       # body
 
   - $MY_VALIDATOR: [mypath, 3, hello, world]             # invocation
+```
 
-[2] R/W variables
+## R/W variables and operators
 -----------------------------------------
-SETTER:
-- opSet(var, val)
-- opAdd(var, val)
-- opSub(var, val)
-- opMul(var, val)
-- opDiv(var, val)
-- opAddMul(var, val, k)
-- opSubMul(var, val, k)
-- opConcat(var, val)
-- opNot(var, val)
-- opAnd(var, val)
-- opOr(var, val)
+- New operators to use in expressions for run-time calculation
+  - Arithmetic
+    - @add(val1, ..., valN)
+    - @sub(val1, ..., valN)
+    - @mul(val1, ..., valN)
+    - @div(val1, ..., valN)
+  - Logical
+    - @not(val)
+    - @and(val1, ..., valN)
+    - @or(val1, ..., valN)
+    - @xor(val1, ..., valN)
+  - String
+    - @concat(val1, ..., valN)
+    - @substring(str, start, end)
+  - Conversion
+    - @toBytes(val)
+    - @toMillis(val)
+- Non constant variables are prefixed by @ and defined as usual
+  ```yaml
+  def:
+    - @var1: hello
+      @var2: {@concat: [{$var: @var1}, ' world']}
+      ...
+      @varN: true
+    - child
+  ```
+- New validator assign allows you to set R/W variables already defined and reachable from the current scope
+  ```yaml
+  assign:
+    - @var1: {@add: [3, {@mul: [{$var: @var1.length}, 2]}]}
+      @var2: {@concat: [{$var: @var2}, '!!!']}
+      ...
+      @varN: {@not: [{$var: @varN}]}
+    - child
+  ```
 
+### Example 1:
+Consider the object below
+```json
 {
-  attachments: [
-    {content: "1234567890"},
-    {content: "qwerty"},
-    {content: "zxcvbnm"},
-    {content: "a b c d e f g h i"}
+  "attachments": [
+    {"content": "1234567890..."},
+    {"content": "qwerty..."},
+    {"content": "zxcvbnm..."},
+    {"content": "a b c d e f g h i..."}
   ]
 }   
-
+```
+You want to check if total content length exceeded a certain value 
+```yaml
 def:
-  - @len: 0
+  - @len: 0                           # accumulator
+  - maxLen: {@toBytes: [1 Kb]}        # constant
   - every:
     - attachments
-    - and
-      - add: [@len, {$path: value.content.length}]
-      - isNumber: [{$var: @len}, { min: 0, max: 100 }]
-
---------------------------
-
+    - assign:
+      - @len: {@add: [{$var: @len}, {$path: value.content.length}]}
+      - isNumberVar: [{$var: @len}, { min: 0, max: {$var: maxLen} }]
+```
+
+### Example 2:
+Consider the object below
+```json
 {
-  relatives: [
-    {parent: true},
-    {parent: false},
-    {parent: true},
+  "relatives": [
+    {"parent": true},
+    {"parent": false},
+    {"parent": true},
   ]
 }   
-
+```
+You want to check if there are at most two parents amongst relatives
+```yaml
 def:
-  - numParents: 0
+  - @numParents: 0
   - every:
     - relatives
-    - and:
+    - if:
       - equals: [value.parent, true] 
-      - add: [numParents, 1]
-      - isNumberVar: [{$var: numParents}, { min: 0, max: 2 }]
+      - assign:
+        - @numParents: {@add: [{$var: @numParents}, 1]
+        - isNumberVar: [{$var: @numParents}, { min: 0, max: 2 }]
+```

examples/data-driven.js

@@ -2,7 +2,7 @@
 const path = require("path");
 const fs = require("fs");
 const yaml = require("js-yaml");
-const ensureValidator = require("../lib/ensure-validator");
+const { Scope, compile } = require("../lib");
 
 let toBeValidated = {
     a: {
@@ -14,9 +14,9 @@ let toBeValidated = {
 
 // Load validator from file
 let vObj = yaml.safeLoad(fs.readFileSync(path.join(__dirname, "data-driven.yaml"), 'utf8'));
-let validator = ensureValidator(vObj);
+let validator = compile(vObj);
 
 // Validate
-let vError = validator(toBeValidated);
+let vError = validator(new Scope(toBeValidated));
 
 console.log(`${path.basename(__filename)}: Validation result --> ${vError? vError : "OK!"}`);

examples/data-driven.yaml

@@ -1,8 +1,8 @@
 and:
-  - isType: [a, object]
+  - isType$: [a, object]
   - xor:
-    - isSet: [a.b]
-    - isSet: [a.c]
-  - optIsType: [a.b, number]
-  - optIsType: [a.c, boolean]
-  - isArrayOf: [a.d, string]
+    - isSet$: [a.b]
+    - isSet$: [a.c]
+  - optIsType$: [a.b, number]
+  - optIsType$: [a.c, boolean]
+  - isArrayOf$: [a.d, string]

examples/dsl-validator.js

@@ -2,14 +2,14 @@
 const path = require("path");
 const fs = require("fs");
 const yaml = require("js-yaml");
-const ensureValidator = require("../lib/ensure-validator");
+const { V, Scope, compile } = require("../lib");
 
 // Load DSL validator from file
 let dslValidator = yaml.safeLoad(fs.readFileSync(path.join(__dirname, "dsl-validator.yaml"), 'utf8'));
-let validator = ensureValidator(dslValidator);
+let validator = compile(dslValidator);
 
 // Validate the DSL validator itself
 let toBeValidated = yaml.safeLoad(fs.readFileSync(path.join(__dirname, "dsl-validator.yaml"), 'utf8'));
-let vError = validator(toBeValidated);
+let vError = validator(new Scope(toBeValidated, {validatorNames: Object.keys(V)}));
 
 console.log(`${path.basename(__filename)}: Validation result --> ${vError? vError : "OK!"}`);