mirror of
https://codeberg.org/setop/elm-scripting
synced 2025-11-08 21:49:57 +00:00
124 lines
3.2 KiB
Markdown
124 lines
3.2 KiB
Markdown
A tool to generate HTML code from Elm source in the terminal using [QuickJS](https://bellard.org/quickjs/).
|
|
|
|
# Requirements
|
|
|
|
* depends only on elm compiler, quickjs cli and a posix shell
|
|
* do not alter elm compiler
|
|
* do not alter quickjs cli
|
|
* do not patch elm compiler output
|
|
* provide acceptable performances (500ms for a big script)
|
|
|
|
|
|
# Design
|
|
|
|
QuickJS (Qjs) is a [JavaScript runtime](https://en.wikipedia.org/wiki/List_of_JavaScript_engines), similar to V8 or SpiderMonkey, but lighter and faster.
|
|
|
|
As any runtime, Qjs can interpret JavaScript code, but it is not a web browser. It has no concept of an HTML document.
|
|
|
|
To bridge this gap, we add a minimal [DOM](https://dom.spec.whatwg.org/) implementation.
|
|
|
|
Next, we concatenate this with the Elm JavaScript output and an app launcher snippet, then ask Qjs to interpret all of it.
|
|
|
|
## Limitations
|
|
|
|
* No event loop
|
|
* Hence, no [TEA](https://guide.elm-lang.org/architecture/); no `update` can be triggered
|
|
* Hence, no Time, no Random, no Http
|
|
* Nodes can only have one parent (this should always be the case)
|
|
* Does not scale well : creating thousands of Nodes consumes a [lot of RAM](#Performances)
|
|
|
|
|
|
# Usage
|
|
|
|
1. Clone this repository and navigate into your local copy
|
|
2. Run `elm init`.
|
|
3. Create `src/Hello.elm` with the following content:
|
|
|
|
```elm
|
|
module Hello exposing(main)
|
|
|
|
import Html exposing (text)
|
|
|
|
main = text "Hello World!"
|
|
```
|
|
|
|
4. Run `./elmscript.sh src/Hello.elm`
|
|
|
|
This produces the expected output:
|
|
|
|
```text
|
|
Hello World!
|
|
```
|
|
|
|
## passing input
|
|
|
|
Input content can be passed to the script via the standard input. The content is then passed to the Elm script as "flags". The script must then use `Browser.element` and implement `init flags` function.
|
|
|
|
|
|
Create `src/Greet.elm` with the following content:
|
|
|
|
```elm
|
|
module Greet exposing (main)
|
|
|
|
import Browser
|
|
import Html exposing (text)
|
|
|
|
|
|
main =
|
|
Browser.element
|
|
{ init = \f -> (f, Cmd.none)
|
|
, update = \m _ -> (m, Cmd.none)
|
|
, view = \m -> text ("hello " ++ m)
|
|
, subscriptions = always Sub.none
|
|
}
|
|
```
|
|
|
|
Run `./elmscript.sh src/Greet.elm <<< 'Elm'`
|
|
|
|
This produces the expected output: `hello Elm`.
|
|
|
|
|
|
I's even more natural when passing file :
|
|
|
|
* run `elm install elm-explorations/markdown`
|
|
* create `src/MdRender.elm` with the following content:
|
|
|
|
```elm
|
|
module MdRender exposing (main)
|
|
|
|
import Browser
|
|
import Html.Attributes exposing (class)
|
|
import Markdown
|
|
|
|
main =
|
|
Browser.element
|
|
{ init = \s -> (s, Cmd.none)
|
|
, update = \m c -> (m, Cmd.none)
|
|
, view = \m -> Markdown.toHtml [class "content"] m
|
|
, subscriptions = always Sub.none
|
|
}
|
|
|
|
```
|
|
|
|
* run `./elmscript.sh src/MdRender.elm < README.md > README.html`
|
|
|
|
|
|
|
|
## Performances
|
|
|
|
Acceptable for small scripts : 250ms on a modest x86_64 CPU and 64MB RAM for a 500 records into a table ; but is does not scale well as everything is loaded before processing ; no streaming contrary to the usual Unix way.
|
|
|
|
Generate 500k "li" loop took 17s and 900MB RAM.
|
|
|
|
|
|
# Prior Work
|
|
|
|
There are more complete tools for generating static sites with Elm:
|
|
|
|
* [elm-pages](https://elm-pages.com/)
|
|
* [elmstatic](https://korban.net/elm/elmstatic)
|
|
* [elm-starter](https://github.com/lucamug/elm-starter)
|
|
* [siteelm](https://github.com/nikueater/siteelm)
|
|
|
|
You should probably consider using one of them instead of this one. :)
|