frontend

Frontend

This is the frontend of the tool.
Implemented as a VS Code extension in Elm.

Architecture

This is an approximate illustration of the setup of the extension.

1. VS Code interface is connected to a thin JS-based client.
2. This JS client connects itself to the background Elm workers.
3. The Elm workers manage the incoming calls to perform the shorthndr tasks.
   1. Since interacting with child processes from Elm is quite tricky, the shorthndr CLI tool is also wrapped into a small JS client used as a "side-car" for the Elm workers.

The illustration below might be out of date, but should give a basic idea.

| ======= |
| VS Code |
| ======= |
     A
     |
     V
| ============== |                                   | ================== |                                   | ================= |
| EXTENSION [Js] |                                   | ExpandWorker [Elm] |                                   | ShortHndrCli [Js] |
| ~~~~~~~~~~~~~~ |                                   | ~~~~~~~~~~~~~~~~~~ |                                   | ~~~~~~~~~~~~~~~~~ |
| commands       |                                   | ports              |                                   | child_process     |
|                | -[listen]-> (toExtensionSuccess)= |                    |                                   |                   |
|                | -[listen]---> (toExtensionError)= |                    | =(toShortHndr) <--------[listen]- |                   |
|                | -[listen]----> (toExtensionInfo)= |                    | =(fromShortHndrSuccess) <-[send]- |                   |
|                | -[send]--------> (fromExtension)= |                    | =(fromShortHndrError) <---[send]- |                   |
|                | -[send]--> (fromExtensionExpand)= |                    |                                   | ================= |
| ============== |                                   | ================== | 

Directory setup

• src/ - contains all the Elm components
• wiring/ - defines the JS wrappers and utilities for the Elm workers (and shorthndr CLI)
• extension.js - entrypoint of the VS Code extension
• debug.js - a tool for manual debugging/sandboxing/integration of the Elm interfaces with node
• .vscode/launch.json - defines a debugging entrypoint for a VS Code extension
• package.json - defines VS Code extension dependencies and development scripts
• elm.json - defines configuration and dependencies of the Elm components.

Usage demo

1. Running the expand command

   

2. Running the replace command

   

Development steps

NB: currently we only support the extension with shorthndr running on Unix systems.

Configure project

Run npm install to set up all the project dependencies (internal and external).
This will automatically (using the preinstall and postinstall scripts):

1. Run npm run setup:shorthndr to install the shorthndr CLI from the ../backend/team-proj-abbr directory to make sure that the shorthndr CLI is available to use. It uses the stack install under the hood and installs the project to $HOME/.local/bin directory.
2. Run npm install resolving all the NPM (JavaScript/Node.js) dependencies for the project
3. Run npm run make:elm to compile the Elm components into JavaScript using elm make under the hood. The compilation results are placed in the ./dist directory.

How to use the extension on VS Code

If developing with VS Code, start a debugging session with F5, located also in the "Run" menu -> "Start Debugging" (or for the successive runs, also via "Run and Debug" panel -> "Run Extension").

The command will open a new VS Code debug window, with the extension enabled.

Then, you can use the command palette Cmd/Ctrl + P, write >ShortHndr in the text field, and you will see all our Replace and Expand commands!

Building Elm stuff

Getting started

Install Elm following the oficial docs.

Useful Elm commands

• elm init - initialize a new elm project
• elm reactor - start a reactive local server for your project
• elm make - build a given elm file
• elm install <package name> - install an external package