| id |
|---|
morphir-elm-commands-processing |
The purpose of the document is to explain what happens when morphir-elm commands are run. This documents also describes each morphir-elm command, options and output/result of the command.
Note: This document is best suited for contributors or anyone interested in understanding how morphir-elm is glued together. You don't need all this information to use Morhpir-elm.
All morphir-elm commands are processed in NodeJS. This is because Elm is not built to
work outside a browser and has no way to interact with the terminal.
Morphir-elm uses the elm javascript-interop (i.e. ports) feature to foster communication between the
NodeJS environment and the Elm platform. Code validation and the generation of the IR happens
withing Elm.
Here's a list of the commands along with the supported options for each command and what they mean.
The following commands are described in this document:
1. morphir-elm make
2. morphir-elm gen
3. morphir-elm develop
4. morphir-elm test
###Command Description
This command reads elm sources, translates to Morphir IR and outputs the IR into JSON.
| Option | Requires | Description |
|---|---|---|
-o, --output |
<path> | Target file location where the Morphir IR will be saved. (default: "morphir-ir.json") |
-p, --project-dir |
<path> | Root directory of the project where morphir.json is located. (default: ".") |
-h, --help |
- | Output usage information. |
Here's a description of the processes involved with running the morphir-elm make command
The entry point for this command ie specified in morphir-elm-make.js.
Control is handed over to the make function defined in cli.js passing in the project directory (directory where the morphir.json lives) and cli arguments/options.
The cli.make function reads the morphir.json contents, reads the Elm source files (files ending with .elm),
and passes the source files, morphir.json and cli options to Elm using ports.
It is worth mentioning that only messages/data is sent between NodeJS and Elm and Elm notifies NodeJS when something goes wrong, or when the process is complete via commands and subscriptions.
The following ports are used:
- jsonDecodeError - this is used to receive possible jsonDecode error from Elm
- packageDefinitionFromSource - this is used to receive send the source files, morphir.json and cli options to Elm CLI.elm
- packageDefinitionFromSourceResult - this is used to receive the package definition results from elm.
The entry point responsible for the exposing ports to NodeJS can be found here.
The update function within elm is immediately triggered when a message comes in through a port.
Visit the docs on the elm architecture,
and checkout Commands and Subscriptions to get a better understanding on why the update function is called.
The update function identifies which port the message came through and carries out the next action based on that decision.
The Morphir IR is generated after validation and parsing, and a command is sent out to NodeJS to end the process with either a success (which creates the morphir-ir.json and write to it) or with a failure which outputs a failure and message showing where the error might have occurred.
This command reads the Morphir IR and generates the target sources in the specified language.
| Option | Requires | Description |
|---|---|---|
-i, --input |
<path> | Source location where the Morphir IR will be loaded from. (default: "morphir-ir.json") |
-o, --output |
<path> | Target location where the generate code will be saved (default: "./dist") |
-t, --target |
<type> | Language to Generate (Scala h SpringBoot cypher tri TypeScript) (default: "Scala") |
-e, --target-version |
<version> | Language version to generate. (default: "2.11") |
-c, --copy-deps |
<True or False> | Copy the dependencies used by the generated code to the output path (True False) (default: "False") |
-m, --modules-to-include |
<comma separated list of module names> | Limit the set of modules that will be included. |
Here's a description of the processes involved with running the morphir-elm gen command
The execution process begins with the reading of the Morphir IR from the specified input path. Next, the morphir ir is
stringified and passed into JSON. The resulting object is given to the generate function.
This generate function which does three things
- Subscribes to the jsonDecodeError port
- Subcribes to the generateResults port
- Sends the IR together with options to the Elm program (CLI.elm) via the generate port.
###Command Description
This command is used to test the test cases present in the morphir-ir.json.
| Option | Requires | Description |
|---|---|---|
-p, --projectDir |
<path> | Root directory of the project where morphir.json is located. (default: ".") |
|
Here's a description of the processes involved with running the morphir-elm make command
This command starts a web server and exposes the developer tools via a web UI
| Option | Requires | Description |
|---|---|---|
-p, --port |
<port> | Port to bind the server to. (default: "3000") |
-o, --host |
<host> | Host to bind the server to (default: "0.0.0.0") |
-i, --path |
<path> | Root directory of the project where the morphir.json is located (default: ".") |
Here's a description of the processes involved with running the morphir-elm develop command