Clyx (pronounced like _clicks_) is a concatenative, stack-oriented, interpreted programming language designed for simplicity, minimalism, and metaprogramming capabilities.
Clyx aims for maximum portability and can be implemented in any modern runtime environment that supports data structures defined in JSON (numbers, strings, lists and key-value dictionaries). Extra features varying in portability include filesystem support and TCP socket I/O.
Clone this repo, then run `sh dist-python.sh`. A `dist/clyx_py/clyx` directory will appear, which will contain all the files necessary to run `micropython clyx.py [prog.clx]` on the desktop or copy them to the target device.
Note: this section describes how to run the interpreter itself. For the language manual, refer to [Clyx Reference Manual](clyx_manual.md).
All core implementations must accept a `.clx` file to run (either via command line or via library call parameter). The REPL is implemented in Clyx itself and resides in the [clyx_repl.clx](clyx_repl.clx) file.
If Clyx is installed as a PyPi package, just use `clyx [prog.clx]` to run the REPL or a program.
Otherwise, to run the REPL, run `[micro]python clyx.py` command from the directory created by `./dist-python.sh`. Pass a `.clx` file additionally to run a Clyx program directly.
To run a Clyx source file directly, issue `clyx.clyx('path/to/file.clx')` instead.
Caveats:
1. The entire operation is rather slow (which is expected for an interpreted runtime on top of CircuitPython on this class of machines) and may sometimes overflow the allocated (native) Python stack. As such, it's not recommended to `src` files from the REPL if you can run them directly instead.
2. Don't forget to mount an SD card or run `unlock_rootfs()` if you want to use file writing capabilities inside T-DeckARD environment.
Similarly to [LVTL](https://codeberg.org/luxferre/lvtl-x) and [LTTB](https://codeberg.org/luxferre/lttb), the prototype of Clyx had been called LPLF (Luxferre's Pointer-Less Forth). However, as the finalized language began to differ from the Forth standard in too many ways, a decision was made to focus on the concatenative nature itself. Thus, the word ConCat had been chosen, which was quickly modded into ConLynx and then naturally shortened to Clyx.
Additionally, this name can be viewed as an acronym hinting at the order some binary operations pop their operands from the stack: "Compute by Loading Y, then X".
More of a high-level one (because you don't have any memory control), but in fact it can be both.
Clyx combines the conceptual simplicity of Forth (and concatenative/RPN programming in general) with list definition syntax, list manipulation and metaprogramming capabilities of Janet and Tcl, making it much more practical for everyday tasks. At the same time, you can build abstraction levels as high as you need to, making it a nice choice for creating custom DSLs (domain-specific languages), especially with the `next` word that pushes the next logical token onto the stack, allowing to change token processing order.
Forth is good if you are fine with only being able to push integers onto the stack and building all your abstractions using direct memory access. Clyx, on the other hand, does not have direct memory access because it was designed for the systems that might not even give you one, but you can do so much more with the data types that it allows you to push onto the stack without involving any trickery.
While diverging from some "purity" aspects, Clyx is a decent choice for newcomers that want to try out a totally new programming paradigm without investing too much time into fighting the language's quirks.
### What do I need to do to create my own Clyx implementation?
Just port the core interpreter along with the 48 primitive words, stubbing out the words that cannot be supported by the target platform if there are any, so that if a program that e.g. uses `nopen` runs on a non-networked host environment, or a program that uses `hseval` runs on a C-based interpreter, then the user would get a clear message that an unsupported core primitive word has been encountered and the program has been terminated because of that.
Apart from that, your implementation needs to be able to load `lib.clx` (standard library source) upon initialization, and `clyx_repl.clx` upon passing no parameters (if it is CLI-based).
### Doesn't `hseval` primitive make Clyx programs non-portable across different implementations?
Yes, it does, because it works differently across different host languages (and Clyx implementations are allowed to not support it at all), so it must only be used as a last resort when any other attempts to interact with the outside world are unsuccessful. Additionally, using `hseval` introduces extra security risks. Nevertheless, this primitive had been added in order to enable some host-specific interoperability that would otherwise be impossible or very cumbersome to implement, such as browser-based deployments.
In other words, `hseval` is sometimes very useful in very specific cases, but please avoid using it unless you have a really good reason to use it.
