@cnrs/hel 0.4.0 → 0.5.1

package/README.md

@@ -28,8 +28,8 @@ For example, combined with [Heimdall.js](https://gitlab.huma-num.fr/datasphere/h
 
 ## Why should I use it?
 
-Well really your shouldn't, or Hel may drain your soul and take it along the twelve rivers all the way to the Halls of the Dead for an eternity of suffering.  
-Anyways, it's up to you. ¯\\_(ツ)_/¯
+Well really y̴̖̿̓ö̶͕͕͝ǘ̶͖͍ ̵̺̫́s̵̼͝h̷͓͂ò̸̠ü̸͍̈́ḽ̷̋͊ḏ̷̽ṅ̷̘'̷̺́̈́ṭ̶̬́͋,̸͔̥̾ ̴̪̌ô̶̤̇r̴̳̅̀ ̶͚̫͒̕H̶̹̿͜e̵̛̞̒l̵̖͗ ̵̪͓͘m̷̰̦̾a̵̠̱̽y̴͙̝͑ ̷͈̙͌d̵̯͝ř̷̟̓ͅa̷̟͖͗i̸͔̮̎n̶̗̠͂͋ ̶̢̦̿̕y̶̖̼̎o̵̖͉͐̎ú̴̧̕r̶͙̳͆ ̸̟͈͋s̶̰̫̿̀o̵̲͕̐ṳ̸̠̋͠l̷͔̫͘ ̴̦̇̐ ̶̧̤̑̂̃͐ä̵̡̙́̀n̵̞͓̬̅d̷̛͕̞̈̂͘ ̸̧͖̘̘̀t̵͖̓̿̆͂ą̵̳̘͉̿͂̈̎k̴̳̘̖̉͆͠ě̴̠̫ ̴̛̞̏̈́̕i̷̬̜̻͗́͒̽͜t̸̘̻̓ ̴̮̎̇̓a̶̦̪̰͈̍̍͝l̶͕̣̙̆̓ő̴̭͊͌͑ǹ̵̡͖̼̗̚g̷͖̙̤̐̂ ̷̝̞̣͑͜ẗ̸̯́h̶̙̒̊e̶̟͓̖͆̄ͅ ̴̣̰͋t̸̙̭́ẅ̷̨̹́ͅẻ̵̗͍̑l̶̪̏͊͌v̴̼̣̾͑͜͠é̷͇͈̥̣́̇ ̸͈̤̱̗͌̃́r̶̬̼͓̕͝ͅi̷̪̎v̵͍͎̦͂͊̓e̴̗̠͖̍̅͝r̸̡̩̘͝s̷̢̝̞͆ ̸̮̒̎̏̕a̴̳̖̔́̕ḷ̷̨͇͙͌͂̓l̴͖̺̤͓͌̓ ̶̢̩̑̃̅t̷̤͙̙̅̓h̸̢̙̰̋ḙ̶͎̰̀ ̵̢̪̿̍w̶͈͚̺̋̃á̵͈̑̅y̷͇̍ ̷̧̠͍̈́̾͑͝t̴̨̨͕̪̎͋̂ȏ̸̳ͅ ̴̡͓̀̔̓̐t̵͖̖̤̽h̴̞͑́ȇ̵̹̰̫̞ ̸̧̻̻̻̌͗H̷̪̜̐́a̴͎̜͖̞͒̋̉̃l̵͖̀̿́͂ḽ̸͛͌ş̶̜̤͐͌ ̴̧̜̞̊̂o̴̥͚̩̐͜f̶̤̦́̔ ̵̳̰̈́͌ṫ̶̡̩͈h̸̳̳̯̏̈́́͒ḙ̶̣̈͊̎̕ ̴̢͓͇̬̍̽D̷̩̋̈́͝͝e̶̲̥̲̐̀͠a̶̪̐d̷͙̉͑ ̸̣̪̥͠f̷̨͈̰̎̿̓ͅỏ̶͓̬͉̘̀͝r̸̫͍̘̪̍͑̋̕ ̸̱̤̎a̵̺̻̿́ṅ̸̢̡̮̹͘̕ ̴̳̻̮̣̊̍̔e̷͚̠̜̠̽t̵̮͚͈̙̋ę̶̭͔͕͛r̶̼̿̋̕n̷̞̼͈̻̒ḭ̴͚̔͛͊͊ͅṱ̴̣͆͘y̸̤̝̘̲͝ ̴̧͓̩̈́̍͐̀ö̵́́̽͠ͅf̴̼͎̣̂̔̔ ̷̨̝͋̕s̸̫͐͝u̴̦͇̙̤̓f̷̥̙̆f̴̡̲̠̽́̎ě̶̡͍̀r̸̛̹͎̭͔̽i̷̖͕͋̚n̴͓̊́͜ģ̶͉̭̈́̅̌̇.̶̝̓̕ ̵̝̣̞͋̋̽̚  
+Anyways, what was I saying? Oh well, it's up to you I guess. ¯\\_(ツ)_/¯
 
 
 
@@ -47,12 +47,28 @@ Once installed, you can start using it with a few simple calls:
 import { * as hel } from '@cnrs/hel';
 
 const query = '!(type != "cat") & (subtype == "bobcat" | danger > "high")';
-const filter = hel.str2fun(query);  // filter function
-const tree = hel.str2ast(query);   // Abstract Syntax Tree (AST)
-const equivalent_query = hel.ast2str(tree);  // equivalent to query
+const filter = hel.fromStringToFilter(query);  // filter function
+const tree = hel.fromStringToTree(query);   // Abstract Syntax Tree (AST)
+const equivalent_query = hel.fromTreeToString(tree);  // equivalent to query
 ```
 
 
+The equivalences between the HEL query language syntax and the corresponding [AST (Abstract Syntax Tree)](https://en.wikipedia.org/wiki/Abstract_syntax_tree) JavaScript nodes :
+
+| Name      | Syntax        | AST node             | Atom? | Notes                                      |
+| --------- | ------------- | -------------------- | ----- | ------------------------------------------ |
+| Entity    |`eid VALUE`    |`{ eid: 'VALUE'}`     |  No   | An item of entity ID `VALUE`:String.       |
+| Attribute |`aid VALUE`    |`{ aid: 'VALUE'}`     |  Yes  | A metadata of attribute ID `VALUE`:String. |
+| Property  |`pid VALUE`    |`{ pid: 'VALUE'}`     |  Yes  | A metadata of property  ID `VALUE`:String. |
+| Number    |`VALUE`        |`VALUE`               |  Yes  | A litteral numeric equals to `VALUE`.      |
+| String    |`"VALUE"`      |`"VALUE"`             |  Yes  | A litteral string equals to `VALUE`.       |
+| Relation  |`ATOM OP ATOM` |`{ left: ATOM, operator: OP, right: ATOM}`|  No   | A relation between a left and a right `ATOM`, using a binary relationnal operator `OP`. |
+| And       |`N¹ & N² & …`  |`{ and: [ N¹, N², …]}`|  No   | True if all nodes `N¹`,`N²`,… are true.    |
+| Or        |`N¹ \| N² \| …`|`{ or: [ N¹, N², …]}` |  No   | True if any node `N¹`,`N²`,… is true.      |
+| Not       |`!( N )`       |`{ not: N }`          |  No   | The negated value of node `N`.             |
+| Parentheses |`( N )`      |`N`                   |  No   | Used for priority between And and Or.      |
+
+
 
 ## Is it documented?
 

package/package.json

@@ -28,7 +28,7 @@
     "https://medium.com/sapioit/why-having-3-numbers-in-the-version-name-is-bad-92fc1f6bc73c",
     "https://gist.github.com/jashkenas/cbd2b088e20279ae2c8e"
   ],
-  "version": "0.4.0",
+  "version": "0.5.1",
   "keywords": [
     "hera",
     "hecate",

package/src/ast2str.js

@@ -104,5 +104,6 @@ function validate(ast, keys) {
 
 
 export function toString(ast) {
+  if (Object.keys(ast).length < 1)  return "";  // accepts {}
   return visit(ast);
 }

package/src/index.js

@@ -1,6 +1,6 @@
-import { toString as ast2str } from './ast2str.js';
-import { toAst as str2ast } from './str2ast.js';
-import { toFunction as str2fun } from './str2fun.js';
+import { toString as fromTreeToString } from './ast2str.js';
+import { toAst as fromStringToTree } from './str2ast.js';
+import { toFunction as fromStringToFilter } from './str2fun.js';
 
 import { operators as ops } from './tokens.js';
 
@@ -12,8 +12,8 @@ for (const [key, token] of Object.entries(ops)) {
 }
 
 export {
-  ast2str,
-  str2ast,
-  str2fun,
+  fromTreeToString,
+  fromStringToTree,
+  fromStringToFilter,
   operators,
 };

package/src/str2ast.js

@@ -71,7 +71,8 @@ class StringToAstVisitor extends CstVisitor {
     if (context.attribute) return this.visit(context.attribute);
     if (context.property) return this.visit(context.property);
     if (context.Integer) return parseInt(context.Integer[0].image);
-    return context.String[0].image;
+    const value = context.String[0].image;
+    return value.substring(1, value.length-1);
   }
 
   relationalOperator(context) {
@@ -101,6 +102,7 @@ class StringToAstVisitor extends CstVisitor {
 const visitor = new StringToAstVisitor();  // this is stateless, so Singleton
 
 export function toAst(input) {
+  if (!input) return {};  // accepts ""
   const result = tokenize(input);
   parser.input = result.tokens;  // resets the parser's internal state
   const cst = parser.statement();  // semantics actions are now defined

package/src/str2fun.js

@@ -129,6 +129,7 @@ class StringToFunctionVisitor extends CstVisitor {
 const visitor = new StringToFunctionVisitor();  // this is stateless, so Singleton
 
 export function toFunction(input) {
+  if (!input) return (item) => true;  // accepts ""
   const result = tokenize(input);
   parser.input = result.tokens;  // resets the parser's internal state
   const cst = parser.statement();  // semantics actions are now defined