Greetings! TL;DR - Just click:
- What's Đ (Edh)
- About this Tour
- Taking the Tour
- Contributing
Reactive Events Integration with Dynamic Effect Tracking
Đ (Edh) is an Object-Oriented, Dynamic Typing, Scripting programming language, meant to serve as a user interface language for human-machine interactions, as well as the surface langauge for interoperations between distributed processes. Interoperations between software components within a local process are better supported as well.
Source code in Đ (Edh) - the surface language, run interpreted atop certain runtime environment programmed in another, more versatile programming language, i.e. the host langauge, currently being GHC/Haskell. Julia, Go, Python, and JavaScript are hopefully to be supported in the future.
Ergonomics (i.e. Human Performance) comes 1st in Đ (Edh)'s language design, raw machine performance as well as a prosperous ecosystem and etc. are less a goal, they are offloaded to efforts around the host programming language and/or runtime.
Free of side-effects is not strictly enforced, but you can start effect tracking with Dynamic Scoped Effects in Đ (Edh), to gradually improve modularity & maintainability of the software components (libraries, frameworks, applications) at large scale.
Đ seeks to be a Business Integration language, as well as a User Interface language, it is born for two main goals:
-
To upscale business-oriented integration of distributed, heterogeneous software components
State of art architecture requires design of various (restful as you've likely heard of) communication specs, after expensive modeling of the business, then infrastructure and software deployments continuously refactored into distributed spaghetti code.
Đ (Edh) stands for Event Distributing & Hosting, an event is a consistent (but not necessarily atomic) piece of data, encapsulating the information of something just happend in one place, and sent to another place for its consequences to be realized there. Event is conceptually coherent to Algebraic Data Type in type theory as well as a functional programming language, but it's not practical to be a mechanical utility in a procedural langauge like Đ. So event stays conceptual in Đ the language.
The event abstraction should decouple much of the complexity, and degrade much part of the problem, to be solvable by Citizen Developers, especially with the aid of modern software engineering toolings.
-
To be directly usable by users of all roles in the organization, especially stake-holders of the business
Most people have been accustomed to GUI (Graphical User Interface) for interaction with a computer system, while visual languages still lack sufficient expressiveness in many tasks for global efficiency. Text based communication, governed by grammar (syntax, semantics, pragmatics), can be way more productive and constructive in such cases, and fortunately modern IDEs have filled much of the gap between GUI and TUI (Terminal User Interface), especially when we put Code Lens into good use:
https://code.visualstudio.com/blogs/2017/02/12/code-lens-roundup
Inspired by Jupyter code cells:
Each Đ code cell (a piece of code) is individually executable by a single mouse click, on a Code Lens above it reads [Run Cell] (note the click/execution can be repeated).
This is much closer to a GUI, yet with more flexible variance & context. The greatest advantage of this tactic is, a user can make slight changes to the code in a template cell, then execute it to achieve tasks in need of a complex phrasing of scription. Traditional TUI requires the user to type out a complete sentence for the job, which needs greatly internalized knowledge about what/how he/she is doing, as well as mental effort nevertheless; while traditional GUI might be just inable to provide the flexibility needed due to level of complexity of the task.
So with Đ and its tooling, we can obtain more advantages at the same time, from both worlds: expressiveness from textual languages as well as intuition from visual languages. And Đ is even more dynamic and interactive than Python, also it facilitates effectful functionality composition in a novel way (i.e. Dynamic Scoped Effects). From REPLs atop stdio, to WebREPLs, to the extensive IDE features, it's fine-tuned for frictionless developer experience, where anyone could be the developer, and i.e. Citizen Developer.
Instead of traditional medium forms of documentation (paperback books/manuals, digital twins of them like PDFs and other eBook formats, or online HTML pages, etc.), Đ software tends to be documented by interactive snippets, usually hierarchical blocks of them, all well commented, but essentially in Đ the language itself. Such materials are organized into Tours so we call them, they can only be properly browsed by a developer IDE such as VSCode, with IntelliSense enabled. And community fixups by any reader are highly encouraged, by submitting pull requests to the maintained repositories.
That said but it's not the same thing someone would call "Code as Documentation", implementation details with elaborate comments about design choices, guidance/caveat to further develop them, are of course the code of conduct in authoring Đ packages, but Tours should be user/consumer facing Đ snippets demonstrating the usage of the implemented functionalities, aimmed to helping beginners to internalize sensible skills with hands-on experience of the package, as quick as possible.
It's ill-minded for a package author to expect his/her users to go over his/her struggle and even pains in making the final piece possible. They who find your piece useful to them should be thankful and admiring you in return, but any hardness in finding that fact themselves, may prevent such result from happening at all, by frightening them off earlier. So get your mind straight, write enlightening Tours even that means more/harder effort than making the core implementation of your packages, helping your potentional users is helping yourself.
This tour is an entry point (with briefs) to various standalone tours provided by many Đ packages of respective purpose, here is more like an explorative playground, or a self-guided walkthrough, rather than a typical tutorial with a linear narrative. You are not supposed to follow the text run in any particular order. Materials are organized in cyclic hierarchies, with the principle that shallower (wrt discoverability) contents should be more brief, and deeper contents to provide more elaborate explainations and examples of greater verbosity.
It is designed for reading efficiency & pleasure. We try not bore experienced readers with unnecessary details, while for readers unfamiliar with certain programming concepts, in elsewhere we craft elaborate explaination and more live examples of greater verbosity, then make those artifacts linked to briefs. The reader can use standard code navigation capability of the IDE to follow those links into greater details. Note ultimately all of these become hierarchies of materials with plenty interconnections.
Clever readers, even noob to some concept, can merely run relevant Code Lens and try comprehend the output result, good intuition is already enough at times. After all, code navigation is your freedom, go back and forth, any time, any where, for whatever reason, just remember you can right-mouse-click most highlighted code elements in any Đ file (with bookmarks even dedicated for this purpose), then select [Go To Definition] to navigate to elaborate definition (explaination) of it. The tooltip shown up when you hover the mouse cursor over it may already give some useful information.
Experiences in other programming languages, Python, JavaScript, Go, Haskell and etc. are good source of intuition to complete this tour faster, but never a necessarity.
And it is very expected for sophisticated developers to come back at times, in seeking inspirations from discussions regarding various topics reachable from here, we just have brief & links to many tours by various standalone packages maintained here, this is an open, public Github repository welcoming contributions.
The big mission be it evolves to a general learning resource as well as a framework, for advanced computer application practices, enabling massive open Citizen Development, but not without code, instead business languages (DSLs), textual and better supplemented with visuals, can be trivially developed and efficiently used in properly facilitated environments (IDEs).
You need a development environment capable of building source packages in the host language, i.e. GHC based Haskell development.
You have 2 ways to take this tour of Đ (Edh) (as well as to start your own Đ (Edh) based software development):
- Cloud based - the fast and easy way
- Local setup - the seasoned and UX rich way
Fast and Easy Way - Gitpod workspace
Thanks to Gitpod, you can get a fully working dev
environment in your browser with just one-click, the
Free Plan would work perfectly well,
after sign up, you can just click
TODO ... screenshots to showcase the steps
Note:
Being soly Eclipse Theia based, Gitpod workspace is currently less featureful / UX-rich compared to VSCode / VSCodium, while the good news are upcoming Github Codespaces and Gitpod's push of VSCode support in response, esp. Gitpod's big vision.
The Đ tooling struggles for ergonomics in software development, it achieves so on the shoulders of modern IDEs, with optimized workflows to build, test, demonstrate, and run relevant software components.
The most preferable/testified IDE is VSCode
/ VSCodium, and 2nd best is Gitpod (which is Eclipse Theia based). Other IDEs such as SublimeText, Emacs, Vim, are not supported by far, merely lacking a LSP client component to communicate with els, they are hopefully to be supported in the future.
EPM is always under the hood, used to initialize (possibly cascaded for localized dependencies) EPM homes, Đ packages from public or private Git repositories, are installed into each EPM home, and updated as a whole.
An Đ package consists of multiple Đ script files under edh_modules subdir, and optionally:
- A tour for the package on its own right, typicaly under
edh_modules/<pkg-name>/toursubdir - A Haskell package, typically under
host.hssubdir - Some Python modules under
host.pysubdir - Some JavaScript modules under
host.jssubdir - More artifacts to support running Đ in different hosting environments
epm cli utility will organize all Haskell packages in an EPM home as both a stack project and a cabal project, under the edh-universe subdir, so it is suffice to build and install Haskell based Đ interpreters by simply running stack install or cabal install there, then the built interpreter programs can be used to run Đ modules and files.
Use epm exec <prog> or the shorthand epm x <prog> is a portable way to run Đ programs without installing them into system locations, it locates the nearest EPM home from the directory you run epm, and takes care of localized dependencies automatically.
The Đ Language Server els is such an Đ package per se, and needs to be built and installed such way for proper support of Đ software development from the IDE, including code navigation, which is crucial for the UX you'd take this tour.
-
Linux or macOS
On WindowsTM ?
Consider run a Linux guest VM through VMWare or VirtualBox.
Another good option, if you have some Linux box (either a VPC on the cloud or another machine sitting besides you) up, and prefer to run a VSCode / VSCodium IDE native to Windows, check out VSCode Remote Development using SSH after following the steps on that Linux box.
You may already have all of them if you are a software developer
-
bash - You already have it
It comes with a decent Linux or macOS box.
-
git - You get it
From your Linux distribution's package manager, e.g.
sudo apt install git
Or for your macOS, run following command and follow its prompts
Note: It installs a full fledged compiler toolchain, maybe bloating to you, yet better to have.
xcode-select --install
That is, GHC plus X
-
You install'em all by any single one, or all of the following:
-
Confused? You are not alone, just continue the struggling and keep questioning that many (yet none perfect) competing options with the Haskell community
Choose VSCode or VSCodium, install it.
Note:
SublimeText, Emacs, Vim and etc. should work equaly well after a LSP client component is created, contribution anticipated.
For HOWTOs see:
- Managing Extensions in Visual Studio Code
- Eclipse Open VSX project
- VSCodium - Extensions + Marketplace
Easiest way is from the IDE's Extensions view, search for Edh and Haskell, install relevant ones as you'd like. Recommendations:
-
For Đ language support, install the extension pack:
-
Or each extension individually (necessary for Eclipse Theia etc.):
-
For interactive Đ Code Lens:
-
For Haskell language support:
Standard color themes come with VSCode can NOT differentiate several types of syntactical elements in Đ (as well as Haskell) code, so the Đ Syntax & Snippets extension bundles a few color themes optimized.
Press F1 to bring out Command Palette, keyin theme and choose [Preferences: Color Theme], then select [Đ (Edh) - Calm Warm] or any other you'd like.
curl -o ~/.local/bin/epm -L https://github.com/e-wrks/epm/raw/latest/epm
chmod a+x ~/.local/bin/epmCheck it installed correctly
$ epm --help
epm 0.2.7 >> Edh Package Manager <<
USAGE:
epm [FLAGS] <SUBCOMMAND>
FLAGS:
-v, --verbose Enable verbose output
-h, --help Prints help information
-V, --version Prints version information
-B, --base <URL> URL prefix for upstream package repositories
default: https://github.com/e-wrks
environment variable EPM_REPO_BASE overrides above
SUBCOMMANDS:
init Initialize current working directory as an EPM home
install | i Install new, or change branches of existing packages
list | l List homes and packages
update | up | u Pull upstream changes of packages from tracked branches
with | w Run command within the directory of a package
run | exec | x Run command with all effective EPM home's bin on $PATH
rm Remove specified package(s) from nearest EPM homemkdir ~/workspace
cd ~/workspace
epm init \
-B https://github.com/e-wrks \
edh nedh els hasdim haskit \
-B http://github.com/complyue \
sedh
cd ~/workspace/edh-universe
# build & install all Đ (Edh) interpreters from those packages, including the
# essential *Edh Language Server* (els) for IntelliSense
stack update
stack install
# do HLS a favor
stack install implicit-hie
epm x gen-hie > hie.yaml
cd ~/workspace
git clone https://github.com/e-wrks/tour
# or perform the open from IDE's GUI
code tour
cd ~/workspace
# or perform the open from IDE's GUI
code tour edh-universe/e-wrks/* edh-universe/complyue/*
Open tour/welcome.edh and start from there.
There are rough edges within both this Tour and the IntelliSense provided by the Edh Language Server
If you ever met any incident when walking through this tour, please consult the issue tracker to see whether it is a known issue and has solutions or workarounds.
In case no existing one solves your problem, please file a new issue, that'll help later comers from meeting the same trouble.
Even difficulties in understanding count, let's figure out how to improve the experience for people from a similar background of you.
Consider opening a PR if you can, to add more information or details, correct conceptions or backgrounds, improve the wording / phrasing, link to your package's tour, or merely correct some typos, contributions are more than welcome!