Skip to content

Commit 3a2df52

Browse files
rjoserjose
authored
V4 (#14)
== Create primary forthic-py variant * Copied v3 into forthic-py * Copy v3 docs to forthic-py * Build a forthic package with flit * Got unit tests running * Reorganize files to support building forthic package * Move tox.ini to forthic-py and tighten up * Add forthic-py Makefile * Update Forthix examples server to use code in forthic-py == General cleanup * Remove deprecated namespace_packages * Clean up makefile targets * Clean up qa warnings * Move tests to their respective source directories * Fix: Escape '.' correctly in regex * Address dependabot vulnerability alerts * Revise Makefiles to support testing all interpreter variants * Commented out date tests (for now) in forthic-js and forthic-react because the months don't match what you get in the browser * Update README files == Move LinkedIn code to forthic-in directory * Move old Forthic docs to forthic-in/docs dir == Add experimental interpreters * Move experimental languages to experimental dir
1 parent 50962c9 commit 3a2df52

File tree

542 files changed

+43565
-1873
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

542 files changed

+43565
-1873
lines changed

‎Makefile‎

Lines changed: 22 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -1,56 +1,47 @@
11
SHELL := /bin/bash
2+
TOX_INI = -c ./forthic-py/tox.ini
23

3-
.PHONY: install-forthic test test-js credentials-server examples docs
4+
.PHONY: install-forthic test credentials-server
45

6+
# ----- Example server --------------------------------------------------------
57
example-server: install-forthic
68
source myenv/bin/activate && cd server && FLASK_APP=run.py FLASK_DEBUG=true flask run --port=8000
79

810
myenv:
911
python3 -m venv myenv
1012

1113
install-forthic: myenv
12-
source myenv/bin/activate && python -m pip install -U pip && pip install .
14+
source myenv/bin/activate && python -m pip install -U pip && cd ./forthic-py && pip install . && pip install Flask
15+
16+
delete-secrets:
17+
rm server/.key
18+
rm server/.secrets
19+
20+
credentials-server:
21+
FLASK_APP=apps/setup/run.py flask run --port=8000
1322

1423
build-forthic-react:
1524
cd forthic-react/v1 && make build
1625

17-
docs: myenv
18-
source myenv/bin/activate && pip install tox && tox -edocs
1926

20-
test: myenv
21-
source myenv/bin/activate && pip install tox && tox
22-
23-
qa: myenv
24-
source myenv/bin/activate && pip install tox && tox -eqa
27+
# ----- Tests ------------------------------------------------------------------
2528

2629
test-py:
27-
source myenv/bin/activate && python -m pytest tests/tests_py
30+
cd forthic-py && make test
2831

29-
delete-secrets:
30-
rm server/.key
31-
rm server/.secrets
32-
33-
# NOTE: The Forthic JS code has been deprecated. Please use Forthic React for client side work
3432
test-js:
35-
@echo
36-
@echo "Forthic JS tests"
37-
@echo "============"
38-
node --experimental-modules ./tests/tests_js/test_all.mjs
33+
cd forthic-js && make test
3934

4035
test-react:
41-
@echo
42-
@echo "Forthic React tests"
43-
@echo "============"
44-
cd forthic-react/v1 && npm install && CI=1 npm run test
36+
cd forthic-react/v1 && make test
4537

46-
test-rs:
47-
@echo
48-
@echo "Forthic Rust tests"
49-
@echo "============"
50-
cargo test --manifest-path tests/tests_rs/Cargo.toml
38+
test: test-py test-react
5139

5240

53-
test-all: test-py test-react test-js
41+
test-rs:
42+
cd experimental/forthic-rs && make test
5443

55-
credentials-server:
56-
FLASK_APP=apps/setup/run.py flask run --port=8000
44+
test-zig:
45+
cd experimental/forthic-zig && make test
46+
47+
test-experimental: test-rs test-zig

‎README.md‎

Lines changed: 72 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,42 @@
11
# Forthic
22

3-
Forthic is a stack-based language for writing tweakable applications by coordinating code written in a host language.
3+
Forthic is a stack-based language for making apps tweakable.
4+
5+
By embedding a Forthic interpreter in your application, you can make apps tweakable at runtime, even by end users.
6+
LinkedIn has used this approach to build hundreds of internal Jira-based program management tools.
7+
8+
This repository contains two primary Forthic interpreters: a Python-based based one that can run within a Flask app in order to create
9+
APIs that can be revised at runtime and a React-based one that can create user interfaces on-the-fly.
410

511
## Documentation
6-
For a brief overview of Forthic, see [OVERVIEW.md](docs/OVERVIEW.md). The [ARCHITECTURE.md](docs/ARCHITECTURE.md) provides more technical detail about Forthic, including a brief overview of some of the standard global Forthic words. The [IDIOMS.md](docs/IDIOMS.md) file gives pointers on how to use Forthic the way it was designed to be used. Also see the [THREAT_MODEL.md](docs/THREAT_MODEL.md) file for guidance on running Forthic securely.
12+
13+
For a brief overview of Forthic, see [OVERVIEW.md](docs/OVERVIEW.md).
14+
The [SYNTAX.md](docs/SYNTAX.md) file shows what the language looks like, including a brief overview of some of the standard global Forthic words.
15+
The [IDIOMS.md](docs/IDIOMS.md) file gives pointers on how to use Forthic the way it was designed to be used.
16+
The [ARCHITECTURE.md](docs/ARCHITECTURE.md) file shows how Forthic interpreters can work within apps.
17+
18+
Forthic modules are documented in the [modules](./forthic-py/docs/)
19+
20+
### YouTube
21+
22+
There are several YouTube videos for learning Forthic
23+
24+
- [Coding Forthic with Rino](https://www.youtube.com/@codingforthic) goes over some of the example applications
25+
- [Learning Forthic](https://www.youtube.com/playlist?list=PLSnCkfp4FIBQJEM9SNeGLjt_VrPrHMzQF) teaches Forthic using [Forthix Jira Plugins](https://marketplace.atlassian.com/vendors/1225195/forthix-llc) and Jupyter notebooks.
26+
27+
### Articles
28+
29+
- [Forthic How To](https://forthix.com/category/how-to/)
30+
- [LinkedIn Article on how to use the Jira module](https://www.linkedin.com/pulse/hello-forthic-abdul-sheik)
31+
- [Categorical Coding](https://forthix.com/category/categorical-coding/)
732

833
## Getting started
34+
35+
To get started, you can run an example Flask server with an embedded Forthic interpreter that
36+
also serves React apps with embedded Forthic interpreters.
37+
38+
### Starting the example server
39+
940
```
1041
# On Mac and Linux
1142
make
@@ -15,30 +46,15 @@ make
1546
.\make-server.ps1
1647
```
1748

18-
This will create a Python virtual environment, install Forthic into it, and run a
19-
web server on port 8000 that can run some sample applications.
20-
21-
## Examples
22-
The Forthic examples run as web apps. To see a list of the examples run the server using `make` and then go here: [http://localhost:8000](http://localhost:8000)
49+
This creates a Python virtual environment, installs Forthic into it, and runs a
50+
web server on [http://localhost:8000](http://localhost:8000)
2351

24-
See [EXAMPLES.md](docs/EXAMPLES.md) for more info.
52+
See [EXAMPLES.md](docs/EXAMPLES.md) for more information.
2553

54+
### Deleting secrets
2655

27-
## Tests
28-
```
29-
# Tests the Python Forthic interpreter
30-
make test
31-
32-
# Tests the JavaScript Forthic interpreter
33-
make test-js
34-
35-
# Tests both
36-
make test-all
37-
```
38-
39-
## Deleting secrets
40-
All credentials are stored encrypted in a JSON object in the `server/.secrets` file. To delete a particular secret, just remove it from the JSON record
41-
and save the file. To delete all secrets along with the encryption key, delete `server/.secrets` and `server/.key` or
56+
Some examples require credentials in order to work (e.g., Jira username and password/api-token).
57+
The example server stores these on your computer as an encrypted in a JSON object in the `server/.secrets` file. To delete a particular secret, just remove it from this file and save. To delete all secrets along with the encryption key, delete `server/.secrets` and `server/.key` or
4258

4359
```
4460
# On Mac and Linux
@@ -48,10 +64,37 @@ make delete-secrets
4864
make-delete-secrets.ps1
4965
```
5066

51-
## YouTube
52-
- [Coding Forthic with Rino](https://www.youtube.com/@codingforthic)
67+
## Tests
68+
69+
Each Forthic interpreter variant has its own test suite. To run the primary tests for `forthic-py` and `forthic-react` just run
70+
71+
```
72+
make test
73+
```
5374

54-
## Articles
55-
- [Categorical Coding](https://forthix.com/category/categorical-coding/)
56-
- [Forthic How To](https://forthix.com/category/how-to/)
57-
- LinkedIn Article on how to use the Jira module https://www.linkedin.com/pulse/hello-forthic-abdul-sheik
75+
## Experimental Interpreters
76+
77+
In addition to the primary interpreters for Python and React, there are a number of experimental interpreters that
78+
show how Forthic can be implemented in other languages.
79+
Those who like learning different programming languages might find it interesting to compare the different implementations.
80+
These proto-implementations can also serve as starting points for complete Forthic interpreters.
81+
82+
| Host Language | Comments |
83+
| ------------------------------------- | ------------------------------------------------------------------------------------------ |
84+
| [C++](./experimental/forthic-cpp/) | Proof of concept using C++ in .NET |
85+
| [Haskell](./experimental/forthic-hs) | An experiment to see if a Forthic interpreter could be built in a pure functional language |
86+
| [Julia](./experimental/forthic-jl) | Proof of concept in Julia |
87+
| [nvcc](./experimental/forthic-nvcc) | Proof of concept for building a interpreter that could run on GPUs via CUDA |
88+
| [swift](./experimental/forthic-swift) | An attempt to build macOS apps that could be tweaked at runtime |
89+
| [Rust](./experimental/forthic-rs) | A Forthic tokenizer in Rust |
90+
| [zig](./experimental/forthic-zig) | WIP Forthic implmentation using zig |
91+
92+
### Pre-forthic Implementations
93+
94+
Prior to Forthic, there were several experiments at building FORTH-like interpreters in a variety of languages
95+
| Host Language | Comments |
96+
| ------------- | -------- |
97+
| [asm](./experimental/pre-forthic/forrth-asm/) | Proof of concept in assembly language |
98+
| [C#](./experimental/pre-forthic/forrth-cs/) | Proof of concept in C# |
99+
| [Erlang](./experimental/pre-forthic/forrth-erl/) | Proof of concept in Erlang, which was one of the easiest Forth-like implementations |
100+
| [Fortran](./experimental/pre-forthic/forrth-f90/) | Proof of concept in Fortran, which was the hardest Forth-like implementation |

0 commit comments

Comments
 (0)