@cnrs/hel 0.3.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.3.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

@@ -16,7 +16,7 @@ function visit(ast, parentheses=false) {
       return visit_(ast, parentheses);
     }
   }
-  throw new Error(`${dump} is invalid`);
+  throw new Error(`${JSON.stringify(ast)} is invalid`);
 }
 
 function property(ast) {
@@ -76,12 +76,15 @@ function atom(ast) {
 }
 
 function isPropertyOrAttribute(ast) {
-  try { return property(ast); }
-  catch (error) { /* it's probably an attribute ... */ }
-  try { return attribute(ast); }
-  catch (error) { /* now we have a problem ! */ }
-  const dump = JSON.stringify(ast);
-  throw new Error(`${dump} is invalid (expected key: 'aid' or 'pid')`);
+  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')`);
+  }
 }
 
 
@@ -101,5 +104,5 @@ function validate(ast, keys) {
 
 
 export function toString(ast) {
-  return visit(input);
+  return visit(ast);
 }

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,
+};