@cnrs/hel 0.2.0 → 0.4.0

package/README.md

@@ -2,25 +2,34 @@
 
 <a href='https://datasphere.readthedocs.io/projects/hel/'><img src='https://gitlab.huma-num.fr/datasphere/doc/assets/-/raw/main/banners/HEL.png' width='100%'></a>
 
-![https://www.gnu.org/licenses/agpl-3.0.html](https://img.shields.io/badge/license-AGPL3.0-informational?logo=gnu&color=success)
-![https://www.repostatus.org/#wip](https://www.repostatus.org/badges/latest/wip.svg)
-![https://gitlab.huma-num.fr/datasphere/hel/js/pipelines/latest](https://gitlab.huma-num.fr/datasphere/hel/js/badges/main/pipeline.svg)
-![https://datasphere.gitpages.huma-num.fr/hel/js/coverage/](https://gitlab.huma-num.fr/datasphere/hel/js/badges/main/coverage.svg)
-![https://www.npmjs.com/package/@cnrs/hel](https://img.shields.io/npm/v/@cnrs/hel.svg)
-![https://datasphere.gitpages.huma-num.fr/hel/js/doc/](https://img.shields.io/badge/documentation-jsdoc-blue)
-![https://doi.org/10.5281/zenodo.18413436](https://zenodo.org/badge/DOI/10.5281/zenodo.18413436.svg)
+[![license](https://img.shields.io/badge/license-AGPL3.0-informational?logo=gnu&color=success)](https://www.gnu.org/licenses/agpl-3.0.html)
+[![repo status](https://www.repostatus.org/badges/latest/wip.svg)](https://www.repostatus.org/#wip)
+[![pipeline](https://gitlab.huma-num.fr/datasphere/hel/js/badges/main/pipeline.svg)](https://gitlab.huma-num.fr/datasphere/hel/js/pipelines/latest)
+[![coverage](https://gitlab.huma-num.fr/datasphere/hel/js/badges/main/coverage.svg)](https://datasphere.gitpages.huma-num.fr/hel/js/coverage/)
+[![npm version](https://img.shields.io/npm/v/@cnrs/hel.svg)](https://www.npmjs.com/package/@cnrs/hel)
+[![documentation](https://img.shields.io/badge/documentation-jsdoc-blue)](https://datasphere.gitpages.huma-num.fr/hel/js/doc/)
+[![doi](https://zenodo.org/badge/DOI/10.5281/zenodo.18413436.svg)](https://doi.org/10.5281/zenodo.18413436)
 
 
 
 ## What is this?
 
-**Hel** is a tool for ...
+**Hel** makes easier to query databases in a generic way.
+In practice, **Hel** is both the specification of a very simple query language, as long as a JavaScript module that allows you to:
+
+- convert a query string to the corresponding [AST (Abstract Syntax Tree)](https://en.wikipedia.org/wiki/Abstract_syntax_tree) ;
+- convert a query string to the corresponding filtering function, to then use it for example with [Heimdall](https://datasphere.readthedocs.io/projects/heimdall/) ;
+- convert an AST to the corresponding query string.
+
+For example, combined with [Heimdall.js](https://gitlab.huma-num.fr/datasphere/heimdall/js), **Hel.js** allows you to build web applications that query [Hera](https://datasphere.readthedocs.io/projects/hera/) databases by abstracting both the data retrieval and the data querying details.  
+… Which is what [Hecate](https://datasphere.readthedocs.io/projects/hera/) does, by the way.
 
 
 
 ## Why should I use it?
 
-TODO
+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. ¯\\_(ツ)_/¯
 
 
 
@@ -33,6 +42,16 @@ pnpm install @cnrs/hel
 ```
 You can add it as a dependency to your `package.json` file, as usual.
 
+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
+```
+
 
 
 ## 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.2.0",
+  "version": "0.4.0",
   "keywords": [
     "hera",
     "hecate",
@@ -144,4 +144,4 @@
     "lint": "exec eslint \"src/**/*.js\"",
     "doc:html": "./node_modules/jsdoc/jsdoc.js -c .jsdoc.conf.json"
   }
-}
+}

package/src/ast2str.js

@@ -0,0 +1,108 @@
+
+
+export const KEYS = {
+  'pid': property,
+  'eid': entity,
+  'aid': attribute,
+  'not': not,
+  'and': and,
+  'or': or,
+  'operator': relation,
+};
+
+function visit(ast, parentheses=false) {
+  for (const [key, visit_] of Object.entries(KEYS)) {
+    if (key in ast) {
+      return visit_(ast, parentheses);
+    }
+  }
+  throw new Error(`${JSON.stringify(ast)} is invalid`);
+}
+
+function property(ast) {
+  validate(ast, ['pid', ]);
+  return `pid ${ast.pid}`;
+}
+
+function entity(ast) {
+  validate(ast, ['eid', ]);
+  return `eid ${ast.eid}`;
+}
+
+function attribute(ast) {
+  validate(ast, ['aid', ]);
+  return `aid ${ast.aid}`;
+}
+
+function not(ast) {
+  validate(ast, ['not', ]);
+  return `!(${visit(ast.not)})`;
+}
+
+function and(ast) {
+  validate(ast, ['and', ]);
+  const operands = [];
+  for (const operand of ast.and) {
+    operands.push(visit(operand, true));
+  }
+  return `${operands.join(' & ')}`;
+}
+
+function or(ast, parentheses=false) {
+  validate(ast, ['or', ]);
+  const operands = [];
+  for (const operand of ast.or) {
+    operands.push(visit(operand));
+  }
+  const result = `${operands.join(' | ')}`;
+  return (parentheses && (result.length > 0)) ? `(${result})` : result;
+}
+
+function relation(ast) {
+  validate(ast, ['left', 'operator', 'right']);
+  const left = atom(ast.left);
+  const right = atom(ast.right);
+  return `${left} ${ast.operator} ${right}`
+}
+
+function atom(ast) {
+  if (typeof ast === 'object') {
+    return isPropertyOrAttribute(ast);
+  }
+  if (typeof ast === 'string') {
+    return `"${ast}"`;
+  }
+  return ast.toString();
+}
+
+function isPropertyOrAttribute(ast) {
+  if ('pid' in ast) {
+    return property(ast);
+  } else
+  if ('aid' in ast) {
+    return attribute(ast);
+  } else {
+    const dump = JSON.stringify(ast);
+    throw new Error(`${dump} is invalid (expected key: 'aid' or 'pid')`);
+  }
+}
+
+
+function validate(ast, keys) {
+  for (const key of keys) {
+    if (!(key in ast)) {
+      const dump = JSON.stringify(ast);
+      throw new Error(`Missing key in ${dump} (expected: '${key}')`);
+    }
+  }
+  if (Object.keys(ast).length > keys.length) {
+    const dump = JSON.stringify(ast);
+    const mine = keys.join(',')
+    throw new Error(`Unknown keys in ${dump} (expected only: ${mine})`);
+  }
+}
+
+
+export function toString(ast) {
+  return visit(ast);
+}

package/src/grammar.js

@@ -36,6 +36,7 @@ export class Parser extends CstParser {
             this.SUBRULE(this.statement);
             this.CONSUME(tokens.P_RIGHT);
         }},
+        { ALT: () => this.SUBRULE(this.entity) },
       ]);
     });
 
@@ -52,7 +53,8 @@ export class Parser extends CstParser {
       this.OR([
         { ALT: () => this.CONSUME(tokens.Integer) },
         { ALT: () => this.CONSUME(tokens.String) },
-        { ALT: () => this.CONSUME(tokens.Identifier) },
+        { ALT: () => this.SUBRULE(this.attribute) },
+        { ALT: () => this.SUBRULE(this.property) },
       ]);
     });
 
@@ -67,6 +69,22 @@ export class Parser extends CstParser {
       ]);
     });
 
+    this.RULE('entity', () => {
+      this.CONSUME(tokens.EID);
+      this.CONSUME(tokens.Identifier);
+    });
+
+    this.RULE('attribute', () => {
+      this.CONSUME(tokens.AID);
+      this.CONSUME(tokens.Identifier);
+    });
+
+    this.RULE('property', () => {
+      this.OPTION(() => { this.CONSUME(tokens.PID); });
+      this.CONSUME(tokens.Identifier);
+    });
+
+
     // very important to call this after all the rules have been defined.
     // otherwise the parser may not work correctly as it will lack information
     // derived during the self analysis phase.

package/src/index.js

@@ -0,0 +1,19 @@
+import { toString as ast2str } from './ast2str.js';
+import { toAst as str2ast } from './str2ast.js';
+import { toFunction as str2fun } from './str2fun.js';
+
+import { operators as ops } from './tokens.js';
+
+const operators = { };
+for (const [key, token] of Object.entries(ops)) {
+  // convert pattern to string and remove surrounding slashes '/'
+  const operator = token.PATTERN.toString();
+  operators[key] = operator.substring(1, operator.length-1);
+}
+
+export {
+  ast2str,
+  str2ast,
+  str2fun,
+  operators,
+};

package/src/str2ast.js

@@ -52,6 +52,9 @@ class StringToAstVisitor extends CstVisitor {
         not: this.visit(context.statement),
       };
     }  // else
+    if (context.entity) {
+      return this.visit(context.entity);
+    } // else
     return this.visit(context.statement);
   }
 
@@ -65,9 +68,10 @@ class StringToAstVisitor extends CstVisitor {
 
   atom(context) {
     // note: these visitor methods will return a string (xxx.image)
+    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);
-    if (context.String) return context.String[0].image;
-    return context.Identifier[0].image;
+    return context.String[0].image;
   }
 
   relationalOperator(context) {
@@ -79,6 +83,19 @@ class StringToAstVisitor extends CstVisitor {
     if (context.NotEqual) return context.NotEqual[0].image;
     return context.Equal[0].image;
   }
+
+  property(context) {
+    return { pid: context.Identifier[0].image };
+  }
+
+  attribute(context) {
+    return { aid: context.Identifier[0].image };
+  }
+
+  entity(context) {
+    return { eid: context.Identifier[0].image };
+  }
+
 }
 
 const visitor = new StringToAstVisitor();  // this is stateless, so Singleton

package/src/str2fun.js

@@ -5,9 +5,10 @@ import { Parser } from './grammar.js';
 const parser = new Parser();  // CST output is enabled by default
 const CstVisitor = parser.getBaseCstVisitorConstructor();
 
-function getMetadata(item, pid) {  // TODO use heimdall.getMetadata(item, ...)
+function getMetadata(item, aid, pid) {  // TODO? use heimdall.getMetadata(item, ...)
   for (const meta of item['metadata']) {
-    if (meta['pid'] == pid) return meta['value'];
+    if (aid != null && meta['aid'] == aid) return meta['value'];
+    if (pid != null && meta['pid'] == pid) return meta['value'];
   }
   return null;
 }
@@ -69,6 +70,9 @@ class StringToFunctionVisitor extends CstVisitor {
     if (context.Not) {
       return (item) => !this.visit(context.statement)(item);
     }  // else
+    if (context.entity) {
+      return this.visit(context.entity);
+    } // else
     return this.visit(context.statement);
   }
 
@@ -79,8 +83,9 @@ class StringToFunctionVisitor extends CstVisitor {
     const right = this.visit(context.right[0]);
     return function(item) {
       if (typeof left === 'object') {
-        const pid = left['pid'];
-        const value = getMetadata(item, pid);  // TODO what if null here ?
+        const aid = ('aid' in left ? left['aid'] : null);
+        const pid = ('pid' in left ? left['pid'] : null);
+        const value = getMetadata(item, aid, pid);  // TODO what if null here ?
         return filter(value, right);
       }
       return filter(left, right);
@@ -88,14 +93,14 @@ class StringToFunctionVisitor extends CstVisitor {
   }
 
   atom(context) {
-    // note: these visitor methods will return a string (xxx.image)
+    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);
-    if (context.String) return context.String[0].image;
-    return { pid: context.Identifier[0].image };
+    return context.String[0].image;
   }
 
   relationalOperator(context) {
-    // note: these visitor methods will return a function returnung a boolean
+    // note: these visitor methods will return a function returning a boolean
     if (context.Greater) return (x, y) => x > y;
     if (context.GreaterOrEqual) return (x, y) => x >= y;
     if (context.Lesser) return (x, y) => x < y;
@@ -103,6 +108,22 @@ class StringToFunctionVisitor extends CstVisitor {
     if (context.NotEqual) return (x, y) => x != y;
     return (x, y) => x == y;
   }
+
+  property(context) {
+    return { pid: context.Identifier[0].image };
+  }
+
+  attribute(context) {
+    return { aid: context.Identifier[0].image };
+  }
+
+  entity(context) {
+    return function(item) {
+      const eid = context.Identifier[0].image;
+      return item['eid'] == eid;
+    };
+  }
+
 }
 
 const visitor = new StringToFunctionVisitor();  // this is stateless, so Singleton

package/src/tokens.js

@@ -87,6 +87,21 @@ export const logic = {
 export const P_LEFT = createToken({ name: 'PLeft', pattern: /\(/ });
 export const P_RIGHT = createToken({ name: 'PRight', pattern: /\)/ });
 
+ // KEYWORDS
+//////////////
+export const PID = createToken({
+  name: 'PropertyID', pattern: /pid/,
+  longer_alt: Identifier,
+});
+export const EID = createToken({
+  name: 'EntityID', pattern: /eid/,
+  longer_alt: Identifier,
+});
+export const AID = createToken({
+  name: 'AttributeID', pattern: /aid/,
+  longer_alt: Identifier,
+});
+
  // WHITESPACE
 ////////////////
 export const WhiteSpace = createToken({
@@ -97,7 +112,7 @@ export const WhiteSpace = createToken({
 
 // /!\ order of tokens is important ! /!\
 // for example, keywords could never be matched if declared after Identifier,
-// or '!=' (NOT_EQUAL) could never be matched if declared after '!'I (NOT)
+// or '!=' (NOT_EQUAL) could never be matched if declared after '!' (NOT)
 export const TOKENS = [
   WhiteSpace,  // whitespace appears first to improve lexer performance
   // >>> START relational operators
@@ -110,6 +125,11 @@ export const TOKENS = [
   // <<< END relational operators
   P_LEFT,
   P_RIGHT,
+  // >>> START keywords
+  PID,
+  EID,
+  AID,
+  // <<< END keywords
   // >>> START boolean operators
   NOT,
   AND,