Merge pull request #1 from LeopoldWichtel/testsuite

Testsuite

.github/workflows/test.yml

@@ -0,0 +1,30 @@
+name: Test
+
+on:
+  push:
+    branches: [ testsuite ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test_js:
+    name: test logics-js
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v3
+      - run: cd logics-js && npm install --save-dev && npm test
+  test_py:
+    name: test logics-py
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.11'
+      - name: Install pipenv
+        run: pip install pipenv
+      - name: Run Testsuite
+        run: cd logics-py && pipenv install --dev && pipenv run pytest -vvv
+

.gitignore

@@ -1,4 +1,6 @@
 *.pyc
 .idea
+.vscode
 logics-py/dist
 logics-py/.venv
+logics-js/node_modules

README.md

@@ -10,18 +10,59 @@
     <a href="https://github.com/viur-framework/logics/LICENSE">
         <img src="https://img.shields.io/github/license/viur-framework/logics" alt="Badge displaying the license" title="License badge">
     </a>
+    <a href="https://github.com/LeopoldWichtel/logics/actions/workflows/test.yml">
+        <img src="https://github.com/LeopoldWichtel/logics/actions/workflows/test.yml/badge.svg" alt="Badge displaying the test status" title="Test badge">
+    </a>
+
     <br>
     A tiny, sandboxed, secure and extendable formula language with a flavor of Python.
 </div>
 
 ## About
 
-Logics is a simple expression language with the goal to provide equal syntax and semantics for different runtime contexts and host languages.
+Logics is a formula language with the aim of flexibly implementing programmable logics such as conditions, calculations or validations, so that developers as well as administrators and experienced users can use such expressions within a framework specified by the system to influence, calculate or otherwise dynamically adapt certain processes of a system.
+
+The language can be compared to [Excel's formula language](https://github.com/microsoft/power-fx), where expressions can be defined based on variables and calculated dynamically. But Logics has a Python-like syntax at this point, but provides its own semantics, so that numbers and strings, for example, can be directly linked, None-values are assumed as 0, and Exceptions are generally not raised.
+
+In addition, Logics provides a sandbox environment, which does not allow potential attackers to break out of the provided environment or slow down the system. There are appropriate security mechanisms integrated into the language for this purpose.
+
+Logics has been developed at [Mausbrand Informationssysteme GmbH](https://www.mausbrand.de/en) as part of the [ViUR ecosystem](https://www.viur.dev/), but it is a standalone project that can also be used outside the ViUR context.
+
+Previous uses of Logics included
+
+- event-based state evaluation
+- dynamic rule systems
+- programmable conditions for filters
+- template engine generating text modules
+- questionnaires with queries that depend on previous answers
+
+## Usage
+
+Since Logics is used on both the client and server side, the language has been implemented in two separate implementations:
+
+- [logics-js](https://www.npmjs.com/package/logics-js) is a pure (vanilla) JavaScript implementation of Logics provided as npm-package.
+- [logics-py](https://pypi.org/project/logics-py/) is a pure Python 3.10 implementation of Logics provided as PyPI-package, with no other dependencies.
+
+Both packages are under recent development and not stable right now. They are maintained in separate version numbers, which is planned to be changed soon, when they become almost feature-complete.
 
-- [logics-js](https://www.npmjs.com/package/logics-js) is a pure JavaScript implementation of Logics provided as npm-package.
-- [logics-py](https://pypi.org/project/logics-py/) is a pure Python implementation of Logics provided as PyPI-package.
+Using Logics in JavaScript:
 
-Both packages are under recent development and not stable right now. They are maintained in separate version numbers.
+```javascript
+// npm install logics-js
+import Logics from "logics-js";
+
+let logics = new Logics("a + 2 * 3 + b");
+console.log(logics.run({a: 1, b: "-Logics"}).toString()); // "7-Logics"
+```
+
+Using Logics in Python:
+```python
+# pip install logics-py
+from logics import Logics
+
+logics = Logics("a + 2 * 3 + b")
+print(logics.run({"a": 1, b: "-Logics"}))  # "7-Logics"
+```
 
 ## Features
 
@@ -41,12 +82,14 @@ Both packages are under recent development and not stable right now. They are ma
   - Attribute access `x[y]`
   - `# comments` in separate lines
   - Dedicated Value object abstraction of native types for
-    - `True`, `False`, `None`
+    - `None`
+    - `True`, `False`
     - `int`, `float`, `str`
-    - `list` for arrays
-    - `dict` for structured objects
+    - `list` for lists (similar to arrays)
+    - `dict` for dicts (similar to structured objects)
 - Provides a set of functions that can be used in expressions
 - Extendable to custom functions
+- Embeddable into other languages
 
 ## `Logics` vs. `Python`
 
@@ -61,6 +104,31 @@ Logics does look like Python, but it isn't Python!
   - e.g. the content of strings is automatically converted when used in calculations,
     so `"42" ** 3` produces 74088, and not a TypeError.
 
+## Building & Packaging
+
+Logics is built using the [UniCC LALR(1) Parser Generator](https://github.com/phorward/unicc), which supports generating parsers in multiple target languages.<br>
+UniCC should be compiled from source, as the latest version 1.8 is required.
+
+Whenever something is changed on the syntax, ensure `unicc` is installed properly and run `make`, which regenerates the parser modules.
+
+### Packaging logics-js
+
+```bash
+cd logics-js
+npm publish
+```
+
+### Packaging logics-py
+
+```bash
+cd logics-py
+pipenv install --dev
+pipenv run build
+pipenv run publish
+pipenv run clean
+pipenv --rm
+```
+
 ## License
 
 Copyright © 2023 by Mausbrand Informationssysteme GmbH.<br>

logics-js/logics.html

@@ -43,7 +43,7 @@
                 console.debug("values = ", values);
 
                 try {
-                    calc = new Logics(e.target.value);
+                    calc = new logics.Logics(e.target.value);
 
                     let result = calc.run(values);
                     console.debug("result = ", result);

logics-js/logics.js

@@ -343,6 +343,10 @@ export default class Logics {
 }
 
 // Register Logics in the browser
-if (window !== undefined) {
-    window.Logics = Logics;
+if (typeof window !== "undefined") {
+    window.logics = {
+        "Logics": Logics,
+        "Value": Value 
+    };
 }
+