search

complyue / tour

2 stars 1 forks source link

readme

A Tour of Đ (Edh)

Greetings! TL;DR - Just click:

Open in Gitpod

What's Đ (Edh)

Đ Slogan

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:

Tours are Đ Documentation

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.

About this Tour

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).

Taking the Tour

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):

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 Open in Gitpod to begin the tour.

Seasoned and UX Rich Way - local IDE

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:

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.

Prerequisites

Operation System
UNIX Toolchain
You may already have all of them if you are a software developer - [bash](https://www.gnu.org/software/bash/) - You already have it It comes with a decent **Linux** or **macOS** box. - [git](https://git-scm.com/) - You get it From your **Linux** distribution's package manager, e.g. ```bash 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. ```bash xcode-select --install ```
Haskell Toolchain
That is, GHC plus X - [GHC](https://haskell.org/ghc) - [Cabal-install](https://www.haskell.org/cabal) You install'em all by any single **one**, or **all** of the following: - [ghcup](https://www.haskell.org/ghcup) - [Stack](https://haskellstack.org) - [Nix](https://nixos.org/download.html) > Confused? You are not alone, just continue the > [struggling](https://www.reddit.com/r/haskell/comments/a69ww2/struggling_to_get_started_with_developing_with) > and keep questioning that many (yet none perfect) competing options with > the [Haskell community](https://www.haskell.org/community)

Choose a Modern IDE

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.

Install Language Extensions

For HOWTOs see:

Easiest way is from the IDE's Extensions view, search for Edh and Haskell, install relevant ones as you'd like. Recommendations:

Optional: Use a more Đ/Haskell friendly Color Theme

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.

Install EPM

curl -o ~/.local/bin/epm -L https://github.com/e-wrks/epm/raw/latest/epm

chmod a+x ~/.local/bin/epm
Check it installed correctly ```console $ epm --help epm 0.3.9 >> Edh Package Manager << USAGE: epm [FLAGS] FLAGS: -v, --verbose Enable verbose output -h, --help Prints help information -V, --version Prints version information -B, --base 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 run | exec | x Run command with all effective EPM home's bin on $PATH rm Remove specified package(s) from nearest EPM home ```

Initialize a Workspace

mkdir ~/workspace
cd ~/workspace

epm init \
  -B https://github.com/e-wrks \
  edh \
  -B http://github.com/complyue \
  nedh els hasdim haskit 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

Clone and Open the Tour Repository

cd ~/workspace
git clone https://github.com/e-wrks/tour

# or perform the open from IDE's GUI
code tour

Optional: Open the Tour and All Library Packages

cd ~/workspace

# or perform the open from IDE's GUI
code tour edh-universe

Begin the Tour

Open tour/welcome.edh and start from there.

Contributing

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!

https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request