welcome.edh

# %% # If you see [ Run Cell | Run All ] above this line, you are good to take a sip of Đ now, just click [Run Cell] above, then press enter when a popup menu appears.

let ( do's, don'ts, ) = (
  [ 'feel it', 'experience it',
    'keep things up-to-date', ],
  [ "merely read it", 'literally remember it',
    'leave yourself outdated', ],
)

for ( todo, to'not'do ) from zip( do's, don'ts ) do {
  console.print$ 'Do ' ++ todo ++ ", don't " ++ to'not'do ++ '!'
}

# %#

{##
 # Welcome to A Tour of Đ (Edh)

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 `bookmark`s 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 on the contrary to the no-code / low-code approach, people can go code-fu with the Đ tooling, i.e. business languages (DSLs), being textual at heart while possibly supplemented with visuals, can be trivially developed and efficiently used in properly facilitated environments (IDEs).

  http://github.com/e-wrks/tour

 #}


{## Troubleshooting & Contributing
 # - Please use the issue tracker, and make PRs as you can

If you ever met any incident when walking through this tour, please consult
  http://github.com/e-wrks/tour/issues?q=is%3Aissue
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

 #} {; }


{## Pre-Flight Checks
 # - Verify your IDE / EPM Setup

Frictionless Developer Experience is a goal of Đ tooling

A Gitpod workspace (Eclipse Theia IDE on the cloud) can have the necessary IDE features & tools setup for you automatically, in case that's what you want, use this link:
  https://gitpod.io/#https://github.com/e-wrks/tour

Or you've decided to setup your own local IDE for better experience, make sure you have followed:
  https://github.com/e-wrks/tour#seasoned-and-ux-rich-way---local-ide

 #} {;

  {## Navigating a Single Module
   # - Use the Outline, Breadcrumbs, Folding for great good

For general IDE guidelines and HOWTOs, checkout:
  https://code.visualstudio.com/docs/editor/editingevolved

The tricks particularly helpful in browsing a single module (such as this file `welcome.edh`) is Outline, Breadcrumbs, and Folding.

* Outline
 > The outline is the live Table-of-Contents per opened module file, it updates as you modifying the file, and titles briefly shown there can be clicked, to take you to the location in the file.
 > It's essential to quick jump to the content you want to read.
 > Note by default, the outline view is located inside the left sidebar for VSCode, but is an expandable icon in the right bar for Gitpod/Theia.
 > And there are VSCode-only features such as [Follow Cursor], [Filter on Type], and various sorting options. Hope Theia support them as well one day.

* Breadcrumbs
 > The breadcrumbs bar is on top of the editor, it shows where current input cursor is located within the hierarchy of current module, and you can click any node to have a drop-down menu at that level, be aware that's an expandable tree, not just a static item list. It manifests the same document hierarchy as the outline view.

* Folding
 > Press *F1* to bring out the command palette, keyin `fold` to filter the options, (better see keyboard shortcuts shown for each interesting commands as well, and select:
  "Fold All"
 > Then only level 1 titles should be visible, isn't it much neater to read?
 > And hope you are not lost, figured out how to expand each section and finally made back here.

   #} {;
    {## Navigating a Single Module #}
    export edh'modu'navi = bookmark()
  }


  {## Đ Terminal Sessions of REPLs
   # - Good REPLs working nicely with Code Lens
   #} {;
    {## Đ Terminal Sessions of REPLs #}
    export edh'term'repls = bookmark()

    # You should see clickable labels in the following line:
    # %% # This line is a cell marker (prefixed with `# %%`)
    # Try click [Run Cell] above, then select [edh Run: epm x edh] from the popup list
    console.print( 'Hello, Đ world!' )

    # %% # This line starts another cell, separately runnable
    let ( do's, don'ts, ) = (
      [ 'feel it', 'experience it',
        'keep things up-to-date', ],
      [ "merely read it", 'literally remember it',
        'leave yourself outdated', ],
    )
    for ( todo, to'not'do ) from zip( do's, don'ts ) do {
      console.print$ 'Do ' ++ todo ++ ", don't " ++ to'not'do ++ '!'
    }
    # %# Note this line is an end-of-cell marker (prefixed with `# %#`)

    # A new Đ terminal session should have been starated, and code in a cell executed in the terminal, as you click [Run Cell] above it. Repeat clicking and it'll get executed more times.

    # Note that Gitpod/Theia's *Integrated Terminal* is less frictionless than VSCode's atm, it may not work well the first time you click [Run Cell], don't worry, repeat more times, it should eventually work correctly.

    # Also note you are free to interact with the REPL in the terminal, just like a traditional one you started from command line.

    {#
Also also note, you can run multiple Đ terminal sessions within an IDE, running same or different command lines, to start one more session, press *F1* to bring out the command palette, keyin `edh` then select the option:

  [Edh: New Đ Terminal]

For how to managing multiple terminal sessions, checkout:
  https://code.visualstudio.com/docs/editor/integrated-terminal#_managing-multiple-terminals
     #}
  }


  {## Navigating the World
   # - Wandering amongst interconnected places

"Go To Definition" is really versatile, also there's a trick to navigate back:
  https://code.visualstudio.com/docs/getstarted/tips-and-tricks#_go-to-definition
And you'd better find the keyboard shortcut (usually F12 and Ctrl^- or Ctrl^Alt^-) and use wisely.

Among usual references, an import in Đ can respond to "Go To Definition" requests too, so Cmd/Ctrl + Click can open its corresponding module file.

You can make good use of this feature, e.g. point your mouse cursor at the string 'lang' after `import * ` below, then hold down Cmd (on macOS) or Ctrl (on Linux), you should see it underlined, then click left-mouse-button, there you go!

Note you can also place your keyboard cursor into 'lang' below, by either arrow keys or mouse click, then press the shortcut key (usually F12), that works the same way.

   #} {; import * 'lang'

    # `bookmark` is a special type of artifact (a `Command` per se) that dedicated to anchor a particular location in some codebase, linkable from anywhere by code navigation.

    # Try hover on `what's'edh` below and see the tooltip, then "Go To Definition" of it
    what's'edh # <- this links to a location in the language tour

    # As well, we expose a bookmark linking to just here
    {## Navigating the World #}
    export edh'world'navi = bookmark()
  }


  {## Use a more Friendly Color Theme
   # - Đ (and Haskell) can be highlighted better

Standard color themes come with VSCode can NOT differentiate several types of syntactical elements in Đ (as well as Haskell) code, so the [Đ Syntax & Snippets](https://marketplace.visualstudio.com/items?itemName=ComplYue.edh-vscode-syntax) 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.

   #} {;
    {## Use a more Friendly Color Theme #}
    export edh'color'theme = bookmark()
  }

}


{## Ready to Takeoff
 # - Guide yourself

Assuming the [Pre-Flight Checks] are all good for you, it is important not only in taking this tour, as well it'll give you great power in software development workflows, with or without Đ.

The rest contents in this module contain many links that can teleport you to various places of interest.

 #} {;

  {## Tricks with the REPL/IDE
   # - Handful tools whenever you work with Đ stuff

   #} {;
    edh'utilities'details # <- follow this to details

    # TODO briefs & short examples here

  }

}


{## Đ the Language
 # - A Business Integration language, as well as a User Interface language
 #} {;

  {## Compared to Similar Languages
   # - Đ Compared to Similar Languages
   #} {; edh'lang'cmp # <- follow this to details

    # TODO briefs & short examples here

  }


  {## Grammar
   # - Syntax, Semantics, and Pragmatics
   #} {; edh'grammar # <- follow this to details

    # TODO briefs & short examples here

  }


  {## Advanced Topics
   # - Make the best out of Đ

   #} {; import * 'lang/advanced'
    {## Advanced Topics #}
    export edh'advanced = bookmark()


  }


  {## Becoming a Veteran
   # - Distinguished Đ developers doing sophisticated things

   #} {;import * 'lang/veteran'
    {## Becoming a Veteran #}
    export edh'veteran = bookmark()


  }


  {## Language Reference
   # - The boring list of all things
   #} {;
    edh'lang'refs'details # <- follow this bookmark to there
  }

}


{## Networked Đ
 # - Yet another abstraction of networking for IPC and RPC

An "Đ Terminal Session" running different interpreter (REPL) would be needed to run "Code Lens" there, "Go To Definition" of the following import to take the Tour there.

 #} {; import * 'swarm/tour' }


{## HasDim
 # - Do Object-Oriented Dimensional-Modeling

Vectorized High Performance Numeric Computing with NVM (e.g. disk) backed SIMD ready arrays should be the norm.

An "Đ Terminal Session" running different interpreter (REPL) would be needed to run "Code Lens" there, "Go To Definition" of the following import to take the Tour there.

 #} {; import * 'dim/tour' }


{## HaskIt
 # - Interactive workbench with easy yet powerful visualizations

Under the hood is BokehJS, for Data / Idea · Exploration / Exposition.

An "Đ Terminal Session" running different interpreter (REPL) would be needed to run "Code Lens" there, "Go To Definition" of the following import to take the Tour there.

 #} {; import * 'haskit/tour' }


{## Swarming Đ
 # - Run jobs with parallel computing power

Put up your own swarms of servers on premise, with possibily high-dimensional data efficiently shared as ND arrays.

It is capable of scheduling Pandas / Numpy / C/C++ based Python works, as well as HasDim / Haskell based Đ works, forming heterogeneous pipelines, where the same copies of NVM (e.g. disk) backed ND arrays are shared and pipelined amongst arbitrary components.

An "Đ Terminal Session" running different interpreter (REPL) would be needed to run "Code Lens" there, "Go To Definition" of the following import to take the Tour there.

 #} {; import * 'swarm/tour' }


{## How Đ Language Server Works
 # - Wonder why you can take this tour like it is?

That Tour is some different, I'd just send you there from here.

 #} {; import * 'els/tour' }