firefly-compiler 0.4.80 → 0.4.81

package/core/Task.ff

@@ -85,6 +85,14 @@ extend self: Task {
             readOr(self.channel()) {_ => }.
             timeout(duration) {}
     }
+    
+    mapList[T, R](list: List[T], body: T => R): List[R] {
+        self.all(list.map {x => {body(x)}})
+    }
+    
+    raceList[T, R](list: List[T], body: T => R): R {
+        self.race(list.map {x => {body(x)}})
+    }
 
     all[T](tasks: List[() => T]): List[T] {
         let successChannel = self.channel()

package/fireflysite/Guide.ff

@@ -92,12 +92,11 @@ data GuideDocument(
     document: Document
 )
 
-render(lux: Lux, browser: BrowserSystem, prefix: String, kebab: String, guides: List[Guide], demos: List[Demo]) {
+render(lux: Lux, httpClient: HttpClient, prefix: String, kebab: String, guides: List[Guide], demos: List[Demo]) {
     let guide = guides.find {_.prefix == prefix}.else {guides.grabFirst()}
     let document = guide.documents.find {d => 
         kebabCase(d.heading()) == kebab
     }.else {guide.documents.grabFirst()}
-    browser.js().global().get("document").set("title", document.title(guide))
     let guideDocuments = guides.flatMap {guide => guide.documents.map {document => 
         GuideDocument(guide, document)
     }}
@@ -111,7 +110,7 @@ render(lux: Lux, browser: BrowserSystem, prefix: String, kebab: String, guides:
             lux.cssClass(Styles.guideCss)
             lux.add("main") {
                 lux.cssClass(Styles.guideMainCss)
-                renderDocument(lux, browser.httpClient(), prefix, document, demos, nextDocument)
+                renderDocument(lux, httpClient, prefix, document, demos, nextDocument)
             }
             renderTopbar(lux, menu, setMenu)
             lux.add("div") {

package/fireflysite/Main.ff

@@ -1,5 +1,6 @@
 import WebServer from ff:webserver
 import Lux from ff:lux
+import Css from ff:lux
 import Guide
 import GettingStarted
 import ReferenceAll
@@ -18,18 +19,6 @@ nodeMain(system: NodeSystem): Unit {
         let path = request.readPath()
         let segments = path.split('/').filter {s => s != "" && s != "." && s != ".."}
         segments.{
-            | ["reference", ...] => 
-                serveGuideHtml("Firefly Reference", request)
-            | ["getting-started", ...] => 
-                serveGuideHtml("Firefly Getting Started", request)
-            | ["examples", ...] => 
-                serveGuideHtml("Firefly Examples", request)
-            | ["packages", ...] => 
-                serveGuideHtml("Firefly Packages", request)
-            | ["community", ...] => 
-                serveGuideHtml("Firefly Community", request)
-            | ["front", ...] => 
-                serveGuideHtml("Firefly", request)
             | ["js", ...] => 
                 let asset = if(path == "/js/ff/fireflysite/Main.mjs" && system.assets().exists("/js/Main.bundle.js")) {
                     "/js/Main.bundle.js"
@@ -44,6 +33,7 @@ nodeMain(system: NodeSystem): Unit {
             | ["assets", "font", "FireflySans.ttf"] => 
                 serveAsset(system, cacheSalt, request, "font/ttf", "/assets/font/NunitoSans-VariableFont_YTLC,opsz,wdth,wght.ttf")
             | ["assets", ...rest] => serveAssets(system, cacheSalt, request, rest)
+            | _ {serveGuide(system, request)} => 
             | _ =>
                 let parameters = if(request.readRawQueryString().size() == 0) {""} else {
                     "?" + request.readRawQueryString()
@@ -54,21 +44,40 @@ nodeMain(system: NodeSystem): Unit {
     }    
 }
 
+guides = [
+    Guide("/front/", [FrontPage.new()])
+    Guide("/getting-started/", [GettingStarted.new()])
+    Guide("/examples/", ExamplesOverview.mock())
+    Guide("/reference/", ReferenceAll.mock())
+    Guide("/packages/", [PackagesOverview.new()])
+    Guide("/community/", [CommunityOverview.new()])
+]
+
+serveGuide(system: NodeSystem, request: WebRequest[WebResponse]): Bool {
+    let demos = ExamplesOverview.demos()
+    mutable served = False
+    guides.each {guide => 
+        if(request.readPath().startsWith(guide.prefix)):
+        let kebab = request.readPath().dropFirst(guide.prefix.size())
+        let htmlAndCss = Lux.renderToString(system) {lux =>
+            Guide.render(lux, system.httpClient(), guide.prefix, kebab, guides, demos)
+        }
+        let title = guide.documents.find {d => 
+            Guide.kebabCase(d.heading()) == kebab
+        }.map {_.title(guide)}.else {guide.title()}
+        serveGuideHtml(title, htmlAndCss.first, htmlAndCss.second, request)
+        served = True
+    }
+    served
+}
+
 browserMain(system: BrowserSystem): Unit {
     let demos = ExamplesOverview.demos()
-    let guides = [
-        Guide("/front/", [FrontPage.new()])
-        Guide("/getting-started/", [GettingStarted.new()])
-        Guide("/examples/", ExamplesOverview.mock())
-        Guide("/reference/", ReferenceAll.mock())
-        Guide("/packages/", [PackagesOverview.new()])
-        Guide("/community/", [CommunityOverview.new()])
-    ]
     guides.collect {guide => 
         if(system.urlPath().startsWith(guide.prefix)):
         Lux.renderById(system, "main") {lux => 
             let kebab = system.urlPath().dropFirst(guide.prefix.size())
-            Guide.render(lux, system, guide.prefix, kebab, guides, demos)
+            Guide.render(lux, system.httpClient(), guide.prefix, kebab, guides, demos)
         }
     }
 }
@@ -119,10 +128,11 @@ serveAsset(system: NodeSystem, salt: Buffer, request: WebRequest[WebResponse], c
     }
 }
 
-serveGuideHtml(title: String, request: WebRequest[WebResponse]): Unit {
+serveGuideHtml(title: String, contentHtml: String, styleTags: String, request: WebRequest[WebResponse]): Unit {
     request.writeHeader("Content-Type", "text/html; charset=UTF-8")
     request.writeText("<!doctype html>")
     request.writeText("<html lang='en' style='background-color: #ffffff; color: #333333; width: 100%; height: 100%; color-scheme: light;'>")
+    request.writeText("<script type='module' src='/js/ff/fireflysite/Main.mjs'></script>")
     request.writeText("<head>")
     request.writeText("<title>" + title + "</title>")
     request.writeText("<meta name='viewport' content='width=device-width, initial-scale=1.0'>")
@@ -132,10 +142,10 @@ serveGuideHtml(title: String, request: WebRequest[WebResponse]): Unit {
     request.writeText("<link rel='preload' href='/assets/image/firefly-logo-yellow.png' as='image'>")
     request.writeText("<style>@font-face { font-family: 'Firefly Mono'; font-display: fallback; src: url('/assets/font/FireflyMono.ttf'); unicode-range: U+000-5FF; }</style>")
     request.writeText("<style>@font-face { font-family: 'Firefly Sans'; font-display: fallback; src: url('/assets/font/FireflySans.ttf'); unicode-range: U+000-5FF; }</style>")
+    request.writeText(styleTags)
     request.writeText("</head>")
     request.writeText("<body style='margin: 0; padding: 0; width: 100%; height: 100%; touch-action: manipulation;'>")
-    request.writeText("<div id='main'></div>")
-    request.writeText("<script type='module' src='/js/ff/fireflysite/Main.mjs'></script>")
+    request.writeText("<div id='main'>" + contentHtml + "</div>")
     request.writeText("</body>")
     request.writeText("</html>")
 }

package/fireflysite/ReferenceAll.ff

@@ -12,8 +12,7 @@ mock(): List[Document] {
         UnfetchedDocument("Pattern matching")
         UnfetchedDocument("Traits and instances")
         UnfetchedDocument("Exceptions")
-        UnfetchedDocument("JavaScript interop")
-        UnfetchedDocument("Async I/O")
         UnfetchedDocument("Structured concurrency")
+        UnfetchedDocument("JavaScript interop")
     ]
 }

package/fireflysite/Test.ff

@@ -19,6 +19,14 @@ nodeMain(system: NodeSystem) {
         
     Log.show([1, 2].map(increment))
     
+    Log.show(p(42))
+    let f2 = {42}
+    Log.show(f2())
+    let pairs = {Pair(_, {_})}
+    let pp = pairs(42)
+    let foo = {{_ + 1}(_)}
+    Log.show(foo(1))
+    
 }
 
 factorial(n: Int): Int {

package/fireflysite/assets/markdown/reference/EmittedJavascript.md

@@ -0,0 +1,66 @@
+# Emitted JavaScript
+
+While most Firefly code maps directly to the JavaScript equivalent, there are two notable exceptions:
+
+ * I/O appears to be blocking, but compiles down to JavaScript `async`/`await`.
+ * Methods are resolved statically in Firefly and become top level functions in JavaScript.
+
+In addition, pattern matching doesn't have a direct equivalent in JavaScript, and neither does traits.
+
+
+# Example
+
+Consider the following main function:
+
+```firefly
+nodeMain(system: NodeSystem) {
+    
+    let files = ["a.txt", "b.txt"]
+    
+    let contents = files.map {file =>
+        system.path(file).readText()
+    }
+    
+    let upper = contents.map {content =>
+        content.upper()
+    }
+    
+    system.writeLine("Result: " + upper.join(""))
+    
+}
+```
+
+The JavaScript that's emitted looks roughly like this:
+
+```js
+export async function nodeMain$(system) {
+    
+    const files = ["a.txt", "b.txt"]
+    
+    const contents = await List_map$(files, async file => {
+        return await Path_readText$(await NodeSystem_path$(system, file))
+    })
+    
+    const upper = List_map(contents, content => {
+        return String_upper(content)
+    })
+    
+    NodeSystem_writeLine$("Result: " + String_join(upper, ""))
+    
+}
+```
+
+In JavaScript, `nodeMain` becomes an `async` function and gets the `$` suffix to distinguish it from a synchronous function.
+
+The `let` keyword in Firefly corresponds to the `const` keyword in JavaScript, and Firefly list literals become JavaScript array literals.
+
+The `map` method becomes a top level function, or rather, one `async` top level function named `List_map$` and another synchronous function named `List_map`.
+A static analysis is performed to decide which version to call.
+
+Because the first call to `map` is passed an anonymous function that calls a method on `system`, which is a capability, and the current top level function is asynchronous,
+the analysis picks the asynchronous version `List_map$` and uses the `await` keyword.
+
+The second call to `map` is passed an anonymous function that doesn't involve any other capabilities, the analysis picks the synchronous version `List_map`.
+
+This static analysis is necessarily conservative, and may occasionally call the asynchronous version of a function where the synchrhonous version would suffice.
+When using the VSCode extension, the hover information for a call will note if the call is asynchronous.

package/fireflysite/assets/markdown/reference/Exceptions.md

@@ -0,0 +1,101 @@
+# Exceptions
+
+Exceptions allow a program to transfer control from the point of error to a designated exception handler, separating error-handling logic from regular program flow.
+
+
+# Throwing exceptions
+
+Exceptions are thrown using the `throw` function. Example:
+
+```firefly
+grabOption[T](option: Option[T]): T {
+    | Some(v) => v
+    | None => throw(GrabException())
+}
+```
+
+In this example, if the argument is `Some(v)`, then `v` is returned. Otherwise, a `GrabException` is thrown.
+
+Any type declared with the `data` or `newtype` keyword can be thrown as an exception, since the type will have an instance for the `HasAnyTag` trait.
+
+
+# Catching exceptions
+
+When an exception is thrown, it propagates up the call chain to the nearest `try`, where it can be caught:
+
+```firefly
+try {
+    grabOption(None)
+} catch {| GrabException, error =>
+    Log.trace("A GrabException occurred")
+    error.rethrow()
+}
+```
+
+The first argument passed to `catch` is the thrown value, and the second parameter contains the stack trace.
+The `rethrow()` method throws the exception again without altering the stack trace.
+It is used when the exception is caught where it can't be fully handled.
+
+If the exception reaches the top of the call stack, the exception value and the stack trace will be printed.
+
+
+# Catching any exception
+
+It is also posssible to catch any exception, regardless of its type, using the `catchAny` method:
+
+```firefly
+try {
+    let result = fragileOperation()
+    Some(result)
+} catchAny {error =>
+    None
+}
+```
+
+
+# Cleaning up
+
+Cleanup often needs to happen whether or not an exception is thrown.
+This is what the `finally` method guarantees:
+
+```firefly
+let fileHandle = path.readHandle()
+try {
+    process(fileHandle)
+} finally {
+    fileHandle.close()
+}
+```
+
+If the program is terminated abnormally (force closed, power is lost, etc.) there is no guarantee that `finally` will get called.
+In most environments, the operating system will occasionally terminate the program abnormally, so programs should be designed such that they can recover from abnormal termination.
+
+
+# Catching multiple exceptions
+
+The `try` function returns a value of type `Try[T]` that is defined as follows:
+
+```firefly
+data Try[T] {
+    Success(value: T)
+    Failure(error: Error)
+}
+```
+
+The `catch`, `catchAny` and `finally` methods are defined on this type. However, since they don't return a `Try[T]` value, they can't be chained.
+
+However, the alternative `tryCatch`, `tryCatchAny` and `tryFinally` methods do return a `Try[T]` value, and can thus be chained:
+
+```firefly
+try {
+    doSomething()
+} tryCatch {| GrabException, error =>
+    reportSpecificError()
+} tryCatchAny {error =>
+    reportGeneralError()
+} finally {
+    performCleanup()
+}
+```
+
+The last method in the chain here is `finally`. If it was `tryFinally`, a value of type `Try[T]` would be returned.

package/fireflysite/assets/markdown/reference/FunctionsAndMethods.md

@@ -3,9 +3,9 @@
 There are 5 kinds of functions in Firefly: 
  
  * Top-level functions
+ * Anonymous functions
  * Local functions 
  * Methods
- * Anonymous functions
  * Trait functions
  
  Trait functions are covered in section [Traits and instances](traits-and-instances), the rest are covered below. 
@@ -152,24 +152,58 @@ This version introduces an additional parameter, `acc`, which acts as an accumul
 
 # Anonymous functions
 
-Firefly has anonymous functions, where the function and the parameters do not have names. They have a concrete type without type parameters. They are first-class values and can be assigned and passed around like other values. Here is an example:
+In firefly anonymous functions are written in curlybrases and constucted like this:
 
 ```firefly
-let next: Int => Int = {i => i + 1}
+{a, b => 
+    let sum = a + b
+    sum
+}
+```
+
+This anonymous function takes two arguments and returns their sum. Like named functions, the body is a sequence of statements where the last expression is returned.
+
+Anonymous functions are often used right away, like below:
+:
+
+```firefly
+[1, 2, 3].map({x => x + 1}) // Returns [2, 3, 4]
+```
+
+An anonymous function that increments the given value by one is passed as argument to the methods `map` working on lists.
+
+These functions are anonymous in the sense that they do not bring a name into scope themselves. They are just expressions that construct a function value. Like all other values, they can be assigned to variables, passed as arguments, or returned from other functions. But unlike other values, they can also be called.
+
+This is in contrast to named functions, which are not first-class in Firefly. The name of a top-level function can only be called but is not an expression in Firefly. To pass a top-level function as an argument, for instance, it must be converted to an anonymous function first.
+
+The type of function values are writen like this:
+
+```firefly
+Int => Int         // One parameter
+(Int, Int) => Int  // Multiple parameters
+() => Int          // No parameters
 ```
 
-The fat arrow (`=>`) is used both in the type and in the definition. This arrow is always part of the function type and separates the parameter types from the return type. In the anonymous function definition, the arrow separates the arguments from the function body and can be omitted in some cases, as shown later.
+The type of an anonymous function cannot be written explicitly in the definition but is inferred from its usage. It will always have a monomorphic type where the argument and return types are concrete types.
 
-This is an anonymous function taking no arguments:
+Here are some examples of anonymous functions assigned to variables explicitly given a type.
+
+Anonymous function without parameters are written without the arrow (`=>`), like this:
 
 ```firefly
 let life: () => Int = {42}
 ```
 
-This is the anonymous function taking no arguments, returning `Unit`:
+This is an anonymous function taking no arguments and returning `Unit`:
 
 ```firefly
-let uhit: () => Unit = {}
+let unit: () => Unit = {}
+```
+
+This is an anonymous function that increments its input:
+
+```firefly
+let next: Int => Int = {i => i + 1}
 ```
 
 This anonymous function takes multiple arguments:
@@ -187,12 +221,25 @@ next(1)     // returns 2
 plus(1, 2)  // returns 3
 ```
 
-Placeholders...
+Parameter names are not part of the function type, and likewise, anonymous functions cannot be called with named arguments. The same goes for default argument values, which are not supported for anonymous functions.
+
+The parameter list and the function arrow can be omitted when the parameters are only used once in the function body. In such cases, the parameters in the body are replaced with underscores (`_`), like this:
+
 
 ```firefly
+let next: Int => Int = {_ + 1}
+let plus: (Int, Int) => Int = {_ + _}
 let identity: Int => Int = {_}
 ```
 
+These underscores, or anonymous parameters, always belong to the nearest anonymous function. Consider the following function:
+
+```firefly
+let f: Int => Int = {{_ + 1}(_)}
+```
+
+In this code, there is an outer and an inner anonymous function, both taking one argument. The first underscore belongs to the inner function, which is called immediately by the outer function with the outer function's anonymous parameter as the argument.
+
 
 # Local functions
 
@@ -205,4 +252,87 @@ function square(n: Int): Int {
 }
 ```
 
-# Methods
+The above local function definition is a statement, similar to local variables declared with `let`. The function name `square` will be in scope for the rest of the code block.
+
+Furthermore, local functions declared in sequence are in scope within each other's bodies, allowing them to be mutually recursive.
+
+# Trailing lambda calls
+
+```firefly
+if(x == 1) {"One"}
+```
+
+# Methods
+
+Firefly has methods, which are called like this:
+
+```firefly
+Some(1).isEmpty() // False
+Some(1).map {_ + 1} // Some(2)
+```
+
+The examples above, calls the two methods `isEmpty` and `map` defined on `Option`. The code below, shows how these methods are defined in `ff:core` package.
+
+```firefly
+data Option[T] {
+    None
+    Some(value: T)
+}
+
+extend self[T]: Option[T] {
+    isEmpty(): Bool {
+        self.{
+            | None => True
+            | Some(_) => False
+        }
+    }
+    
+    map[R](body: T => R): Option[R] {
+        self.{
+            | None => None
+            | Some(v) => Some(body(v))
+        }
+    }    
+}
+```
+
+Methods can be defined for a more narrow targer type, like `flatten` below:
+
+```firefly
+extend self[T]: Option[Option[T]] {
+    flatten(): Option[T] {
+        self.{
+            | None => None
+            | Some(v) => v
+        }
+    }
+}
+```
+
+The extend block above, will only define `flatten` for options types of options. 
+
+In code below, the extend block defines methods for the target type `Option[T]`, but only when `T` implements the `Equal` trait.
+
+
+```firefly
+extend self[T: Equal]: Option[T] {
+    contains(value: T): Bool {
+        self.{
+            | None => False
+            | Some(v) => v == value
+        }
+    }
+}
+```
+
+
+
+# Special method call syntax
+
+```firefly
+if(x == 1) {"One"} else {"Several"}
+```
+
+# Trait functions
+ 
+Trait functions are covered in the section about [traits and instances](traits-and-instances)

package/fireflysite/assets/markdown/reference/JavascriptInterop.md

@@ -0,0 +1,134 @@
+# JavaScript interop
+
+Firefly compiles to JavaScript, which enables it to run in the browser.
+It uses Node.js as its server side and desktop runtime.
+
+The JavaScript interop features enable the wrapping of libraries that are written in JavaScript so that they can be used in Firefly.
+
+
+# The JsSystem
+
+Most JavaScript functionality can be accessed via the `JsSystem` object.
+
+```firefly
+browserMain(system: BrowserSystem): Unit {
+    let document = system.js().global().get("document")
+    let element = document.call1("getElementById", "my-id")
+    element.set("innerText", "Hi!")
+}
+```
+
+This example gets the global `document`, calls `getElementId("my-id")` on it, and sets `innerText = "Hi!"`.
+
+The type of the `document` and `element` variables here is `JsValue`, which represents an arbitrary JavaScript value.
+
+
+# The ff:unsafejs package
+
+This package provides access to unsafe JavaScript features:
+
+```firefly
+// Obtains the JsSystem without a capability
+jsSystem(): JsSystem
+
+// Imports a JavaScript module (the import gets hoisted to a top level import)
+import(module: String): JsValue
+
+// Awaits an async function (only works in async context)
+await[T](body: () => T): T
+
+// Throws TaskAbortedException if the current task has been aborted
+throwIfCancelled(): Unit
+
+// Returns true if the current task has been aborted
+cancelled(): Bool
+```
+
+In the future, it may be possible to provide a whitelist of dependencies that are allowed to use this package.
+
+
+# Internal FFI
+
+The `target` keyword allows writing almost raw JavaScript.
+
+```firefly
+alertHi(name: String)
+    target browser sync """
+        alert("Hi " + name_ + "!");
+    """
+```
+
+Multiple target keywords are allowed per function or method. 
+The target type is `js` or the more specific types `browser` or `node`, and then a mode that's either `sync` for when called synchronously, or `async` for when called asynchronously.
+
+Argument names are avaliable with a `_` suffix in the JavaScript code block.
+
+JavaScript module imports can be done in the beginning of a JavaScript code block with the specfic syntax `import * as foo from 'bar'`. The import statement will be hoisted to a top level import.
+
+In the future, the `target` keyword and its functionality may be removed from the language.
+
+
+# Emitted JavaScript
+
+While most Firefly code maps directly to the JavaScript equivalent, there are two notable exceptions:
+
+ * I/O appears to be blocking, but compiles down to JavaScript `async`/`await`.
+ * Methods are resolved statically in Firefly and become top level functions in JavaScript.
+
+In addition, pattern matching doesn't have a direct equivalent in JavaScript, and neither does traits.
+
+Consider the following main function:
+
+```firefly
+nodeMain(system: NodeSystem) {
+    
+    let files = ["a.txt", "b.txt"]
+    
+    let contents = files.map {file =>
+        system.path(file).readText()
+    }
+    
+    let upper = contents.map {content =>
+        content.upper()
+    }
+    
+    system.writeLine("Result: " + upper.join(""))
+    
+}
+```
+
+The JavaScript that's emitted looks roughly like this:
+
+```js
+export async function nodeMain$(system) {
+    
+    const files = ["a.txt", "b.txt"]
+    
+    const contents = await List_map$(files, async file => {
+        return await Path_readText$(await NodeSystem_path$(system, file))
+    })
+    
+    const upper = List_map(contents, content => {
+        return String_upper(content)
+    })
+    
+    NodeSystem_writeLine$("Result: " + String_join(upper, ""))
+    
+}
+```
+
+In JavaScript, `nodeMain` becomes an `async` function and gets the `$` suffix to distinguish it from a synchronous function.
+
+The `let` keyword in Firefly corresponds to the `const` keyword in JavaScript, and Firefly list literals become JavaScript array literals.
+
+The `map` method becomes a top level function, or rather, one `async` top level function named `List_map$` and another synchronous function named `List_map`.
+A static analysis is performed to decide which version to call.
+
+Because the first call to `map` is passed an anonymous function that calls a method on `system`, which is a capability, and the current top level function is asynchronous,
+the analysis picks the asynchronous version `List_map$` and uses the `await` keyword.
+
+The second call to `map` is passed an anonymous function that doesn't involve any other capabilities, the analysis picks the synchronous version `List_map`.
+
+This static analysis is necessarily conservative, and may occasionally call the asynchronous version of a function where the synchrhonous version would suffice.
+When using the VSCode extension, the hover information for a call will note if the call is asynchronous.
+

package/fireflysite/assets/markdown/reference/ModulesAndPackages.md

@@ -86,7 +86,7 @@ include "node_modules"
 This instructs the compiler to copy the file or directory `mypackage/.firefly/include/node_modules` verbatim into the `mypackage/.firefly/ouput/node/mygroup/mypackage/node/node_modules` directory. It doesn't do anything for the browser target.
 
 
-# Imports
+# Imports and exports
 
 To access the symbols that a module exports, it is necessary to import it:
 
@@ -116,13 +116,10 @@ The symbols can then be accessed using the `W.` prefix:
 W.new(system, "localhost", 8080)
 ```
 
-
-# Exports
-
 Currently, all top level definitions are automatically exported. This is likely to change in the future.
 
 
-# Main
+# Main functions
 
 In Firefly, there are three targets, each with its own main function:
 
@@ -140,15 +137,12 @@ buildMain(system: BuildSystem) {
 }
 ```
 
-The three main functions may coexist in the same file.
-
-The `nodeMain` function runs when you run your executable.
-
-The `browserMain` function runs in the browser.
-
-The `buildMain` function runs when you build your program.
+The three main functions may coexist in the same file. 
+The `nodeMain` function runs when you run your executable,
+the `browserMain` function runs in the browser, and
+the `buildMain` function runs when you build your program.
 
-The `system` parameter is an object that lets you do I/O in the target system.
+The `system` parameter is an object with methods that let you do I/O in the target system.
 
 
 # Constants

package/fireflysite/assets/markdown/reference/OldStructuredConcurrency.md

@@ -0,0 +1,48 @@
+# Structured concurrency
+
+Firefly has a lightweight task system that supports structured concurrency and cancellation. 
+
+Tasks are structured in a parent-child relationship, where the parent scope waits for all its child tasks to complete before proceeding.
+
+If the parent task or a sibling subtask fails with an uncaught exception, the other subtasks are cancelled.
+
+
+# Spawning a subtask
+
+The `system` parameter for the main function has a `mainTask()` method that returns a `Task`.
+This is the main task whose lifecycle corresponds to that of the application.
+A task can `spawn` subtasks:
+
+```firefly
+nodeMain(system: NodeSystem) {
+    system.mainTask().spawn {subtask =>
+        while {True} {
+            Log.trace("Hello from subtask!")
+            subtask.sleep(Duration(1.0))
+        }
+    }
+    while {True} {
+        Log.trace("Hello from main task!")
+        system.mainTask().sleep(Duration(1.0))
+    }
+}
+```
+
+In the above example, there's one while loop running in the subtask, and another running in the main task.
+They run concurrently, and the `"Hello..."` messages are thus logged in an interleaved fashion.
+
+
+# Waiting for subtasks
+
+```firefly
+nodeMain(system: NodeSystem) {
+    system.mainTask().spawn {task =>
+        task.spawn {subtask =>
+            while {True} {
+                Log.trace("Hello from subtask!")
+                subtask.sleep(Duration(1.0))
+            }
+        }
+    }
+}
+```

package/fireflysite/assets/markdown/reference/StructuredConcurrency.md

@@ -0,0 +1,99 @@
+# Structured concurrency
+
+Firefly has a lightweight task system that supports structured concurrency and cancellation. 
+
+Tasks are structured in a parent-child relationship, where the parent scope waits for all its child tasks to complete before proceeding.
+
+If the parent task or a sibling subtask fails with an uncaught exception, the other subtasks are cancelled.
+
+
+# Waiting for results
+
+A simple use case is to concurrently run some tasks and waiting for their results.
+This can be done without explicitly spawning tasks, as there's a utility method `task.mapList()` for this:
+
+```firefly
+let results = system.mainTask().mapList(urls) {url =>
+    system.httpClient().get(url) {_.readText()}
+}
+```
+
+This fetches all of the URLs concurrently. 
+If any fetch throws an exception, the other fetches are cancelled and `task.mapList()` rethrows an exception. 
+Otherwise, the list of results is returned.
+
+Similarly, `task.raceList()` can be used to run some tasks concurrently, wait for the first one to complete, and cancel the others.
+
+
+# Spawning tasks
+
+A slightly more advanced use case is handling requests concurrently. It might look like this:
+
+```firefly
+while {True} {
+    let request = waitForRequest()
+    system.mainTask().spawn {subtask =>
+        handleRequest(subtask, request)
+    }
+}
+```
+
+The infinite loop here calls some function to wait for the next request.
+Then it spawns a subtask to handle the request, and loops back to waiting for the next request.
+The subtask executes concurrently, and thus doesn't block the loop while the request is being handled.
+
+
+# Channels
+
+Concurrently running tasks may need to communicate while executing.
+One mechanism for inter-task communication is the `Channel[T]` type, which represents an unbuffered multi-producer multi-consumer channel for messages of type `T`.
+
+A function to read URLs from a channel, fetch JSON from those URLs, and write the results to another channel could look like this:
+
+```firefly
+fetchTask(in: Channel[String], out: Channel[Json]) {
+    while {True} {
+        let url = in.read()
+        let result = system.httpClient().get(url) {_.readJson()}
+        out.write(result)
+    }
+}
+```
+
+The `in.read()` call waits until there's a task ready to write to the `in` channel.
+Similarly, the `out.write()` call waits until there's a task ready to read from the `out` channel.
+
+To do multiple requests concurrently, spawn multiple instances of the task:
+
+```firefly
+let in = system.mainTask().channel()
+let out = system.mainTask().channel()
+1.to(3).each {_ => 
+    system.mainTask().spawn {_ =>
+        fetchTask(in, out)
+    }
+}
+```
+
+Consider calling an API that either returns `{value: ...}` where `...` is some number, or `{add: ...}` where `...` is a list of API URLs to add up to a total.
+A first attempt could be adding the following code:
+
+```firefly
+mutable total = 0
+in.write("https://example.com/my-api")
+while {True} {
+    let json = out.read()
+    json.field("value").map {total += _.grabInt()}.else {
+        let urls = json.field("add").map {_.grabArray().map {_.grabString()}}
+        urls.each {url =>
+            in.write(url)
+        }
+    }
+}
+```
+
+However, there are two problems here:
+
+ * If all the fetch tasks are waiting to write to the `out` channel, `in.write(url)` will block forever.
+ * There's no logic to discover that there are no API calls left to do, so the `total` will never be reported.
+ 

package/lux/Lux.ff

@@ -5,6 +5,7 @@ import Css
 capability Lux(
     document: LuxDocument
     jsSystem: JsSystem
+    mutable dry: Option[Array[DryNode]]
     mutable cssClasses: StringMap[CssClass]
     mutable renderLock: Lock
     mutable task: Task
@@ -25,6 +26,49 @@ class LuxElement(element: JsValue, mutable child: Int, mutable keepChildren: Boo
 
 class LuxDocument(document: JsValue)
 
+data LuxInvaldNameException(name: String)
+
+class DryNode {
+    DryElement(tagName: String, attributes: StringMap[String], children: Array[DryNode])
+    DryFragment(children: Array[DryNode])
+    DryText(text: String)
+}
+
+extend self: DryNode {
+    toHtml(): String {
+        // https://www.w3.org/TR/xml/ - wrt. checkXmmlName, we only accept the ASCII subset
+        function checkXmlName(name: String): String {
+            if(name.size() == 0) {throw(LuxInvaldNameException(name))}
+            if(!name.grabFirst().isAsciiLetter() && !name.startsWith(":") && !name.startsWith("_")) {throw(LuxInvaldNameException(name))}
+            if(!name.all {c => c.isAsciiLetterOrDigit() || c == ':' || c == '_' || c == '-' || c == '.'}) {throw(LuxInvaldNameException(name))}
+            name
+        }
+        function escapeAttributeValue(value: String): String {
+            value.replace("&", "&#x26;").replace("<", "&#x3C;").replace(">", "&#x3E;").replace("\"", "&#x22;")
+        }
+        function escapeText(text: String): String {
+            text.replace("&", "&#x26;").replace("<", "&#x3C;").replace(">", "&#x3E;")
+        }
+        let voidHtmlElements = [
+            "area", "base", "br", "col", "embed", "hr", "img", "input", "link", "meta", "param", "source", "track", "wbr"
+        ].toSet()
+        function toHtml(node: DryNode): String {
+            | DryElement(tagName, attributes, children) => 
+                let attributeHtml = attributes.toList().map {| Pair(name, value) => 
+                    " " + checkXmlName(name) + "=\"" + escapeAttributeValue(value) + "\""
+                }.join()
+                let childrenHtml = children.toList().map {toHtml(_)}.join()
+                let endHtml = if(voidHtmlElements.contains(tagName)) {""} else {"</" + tagName + ">"}
+                "<" + checkXmlName(tagName) + attributeHtml + ">" + childrenHtml + endHtml
+            | DryFragment(children) => 
+                children.toList().map {toHtml(_)}.join()
+            | DryText(text) => 
+                escapeText(text)
+        }
+        toHtml(self)
+    }
+}
+
 extend self: LuxElement {
     childAt(index: Int): JsValue {
         self.element.get("childNodes").get(index)
@@ -69,6 +113,7 @@ extend self: Lux {
     }
     
     text(value: String) {
+        self.dry.map {_.push(DryText(value))}.else:
         let oldNode = self.element.childAt(self.element.child)
         let oldValue = if(!oldNode.isNullOrUndefined()) {oldNode.get("data")} else {oldNode}
         if(oldValue.isNullOrUndefined() || oldValue.grabString() != value) {
@@ -79,6 +124,24 @@ extend self: Lux {
     }
     
     add(tagName: String, body: () => Unit = {}) {
+        self.dry.map {dry => 
+            self.dry = Some([].toArray())
+            let savedAttributes = self.attributes
+            let savedKeys = self.keys
+            self.attributes = None
+            self.key = ""
+            self.depth += 1
+            try {
+                body()
+            } finally {
+                dry.push(DryElement(tagName, self.attributes.else {StringMap.new()}, self.dry.grab()))
+                self.depth -= 1
+                self.attributes = savedAttributes
+                self.keys = savedKeys
+                self.element.child += 1
+                self.dry = Some(dry)
+            }
+        }.else:
         let node = patchElement(self, tagName)
         if(!node.get("luxHandlers").isNullOrUndefined()) {
             node.get("luxHandlers").grabArray().each {pair =>
@@ -148,6 +211,7 @@ extend self: Lux {
     setId(value: String) {self.set("id", value)}
     
     setValue(value: String) { // TODO: Not an attribute
+        self.dry.map {_ => self.set("value", value)}.else:
         self.element.element.set("value", value)
     }
     
@@ -167,15 +231,22 @@ extend self: Lux {
     cssClass(class: CssClass) {
         if(!self.cssClasses.has(class.name())) {
             self.cssClasses.set(class.name(), class)
+            if(self.dry.isEmpty()):
             let styleSheet = self.document.createElement("style")
             styleSheet.set("textContent", class.show())
             self.document.document.get("head").call1("appendChild", styleSheet)
         }
-        self.element.element.get("classList").call1("add", class.name())
-        self.set("class", self.element.element.get("className").grabString())
+        if(!self.dry.isEmpty()) {
+            let classNames = self.attributes.flatMap {_.get("class")}.else {""}
+            self.set("class", (classNames + " " + class.name()).trim())
+        } else {
+            self.element.element.get("classList").call1("add", class.name())
+            self.set("class", self.element.element.get("className").grabString())
+        }
     }
     
     on(event: String, handler: LuxEvent => Unit) {
+        if(self.dry.isEmpty()):
         let jsHandler = unsafeAsyncFunction1ToJs(self) {jsEvent =>
             self.renderLock.do(reentrant = False) {
                 handler(unsafeJsToValue(jsEvent))
@@ -195,6 +266,7 @@ extend self: Lux {
     onInput(handler: LuxEvent => Unit) {self.on("input", handler)}
 
     useState[T: HasAnyTag](initialValue: T, body: (T, T => Unit) => Unit) {
+        self.dry.map {_ => body(initialValue, {_ => })}.else:
         self.depth += 1
         let value = getStateOnElement(self.element.element, self.depth, initialValue)
         mutable i = 0
@@ -231,6 +303,7 @@ extend self: Lux {
     }
 
     useCallback1[A1: Equal: HasAnyTag](callback: A1 => Unit, body: (A1 => Unit) => Unit) {
+        self.dry.map {_ => body(callback)}.else:
         self.depth += 1
         setStateOnElement(self.element.element, self.depth, callback)
         let element = self.element.element
@@ -246,6 +319,7 @@ extend self: Lux {
     }
 
     useLazy1[A1: Equal: HasAnyTag](a1: A1, body: A1 => Unit = {_ => }) {
+        self.dry.map {_ => body(a1)}.else:
         self.depth += 1
         try {
             let old = getStateOnElement(self.element.element, self.depth, None)
@@ -262,6 +336,7 @@ extend self: Lux {
     }
 
     useMemo1[A1: Equal: HasAnyTag, T: HasAnyTag](a1: A1, compute: A1 => T, body: T => Unit) {
+        self.dry.map {_ => body(compute(a1))}.else:
         self.depth += 1
         try {
             let old = getStateOnElement(self.element.element, self.depth, Pair(a1, None))
@@ -284,6 +359,7 @@ extend self: Lux {
     }
     
     useSuspense(suspense: () => Unit, body: Lux => Unit) {
+        self.dry.map {_ => suspense()}.else:
         let oldSubtask = getTaskOnElement(self.element.element)
         oldSubtask.each {task =>
             forceAsyncAbort(self, task)
@@ -463,10 +539,17 @@ render(browserSystem: BrowserSystem, element: JsValue, body: Lux => Unit) {
     while {!document.get("parentNode").isNullOrUndefined()} {
         document = document.get("parentNode")
     }
+    // [...document.querySelectorAll("[lux-class]")].map(x => x.getAttribute("lux-class")) 
+    let staticCssClasses = StringMap.new()
+    let dummyCssClass = CssClass([], [], [])
+    document.call1("querySelectorAll", "[lux-class]").each {e => 
+        staticCssClasses.set(e.call1("getAttribute", "lux-class").grabString(), dummyCssClass)
+    }
     let lux = Lux(
         jsSystem = browserSystem.js()
         renderLock = browserSystem.mainTask().lock()
-        cssClasses = StringMap.new()
+        dry = None
+        cssClasses = staticCssClasses
         task = browserSystem.mainTask()
         depth = 0
         document = LuxDocument(document)
@@ -485,3 +568,26 @@ renderById(browserSystem: BrowserSystem, id: String, body: Lux => Unit) {
     let element = browserSystem.js().global().get("document").call1("getElementById", id)
     render(browserSystem, element, body)
 }
+
+renderToString(nodeSystem: NodeSystem, body: Lux => Unit): Pair[String, String] {
+    let children = [].toArray()
+    let lux = Lux(
+        jsSystem = nodeSystem.js()
+        renderLock = nodeSystem.mainTask().lock()
+        dry = Some(children)
+        cssClasses = StringMap.new()
+        task = nodeSystem.mainTask()
+        depth = 0
+        document = LuxDocument(nodeSystem.js().null())
+        element = LuxElement(nodeSystem.js().null(), 0, keepChildren = False)
+        keys = None
+        key = ""
+        attributes = None
+        renderQueue = Array.new()
+    )
+    body(lux)
+    let styleTags = lux.cssClasses.values().map {c => 
+        "<style lux-class=\"" + c.name() + "\">" + c.show() + "</style>"
+    }.join()
+    Pair(children.toList().map {_.toHtml()}.join(), styleTags)
+}

package/lux/TestDry.ff

@@ -0,0 +1,27 @@
+import Lux
+
+nodeMain(system: NodeSystem) {
+    
+    
+    
+    let html = Lux.renderToString(system, render)
+    Log.trace(html)
+    
+}
+
+render(lux: Lux): Unit {
+    lux.div {
+        lux.set("id", "its-me")
+        lux.span {
+            lux.text("Hello")
+            lux.div {
+                lux.set("id", "it's \"a-me\"")
+                lux.span {
+                    lux.text("Hello ]]>")
+                }
+                lux.text("Hi")
+            }
+        }
+        lux.text("Hi")
+    }
+}

package/output/js/ff/core/Task.mjs

@@ -210,6 +210,22 @@ ff_core_Channel.ChannelAction_timeout(ff_core_Channel.readOr_(ff_core_Task.Task_
 }))
 }
 
+export function Task_mapList(self_, list_, body_) {
+return ff_core_Task.Task_all(self_, ff_core_List.List_map(list_, ((x_) => {
+return (() => {
+return body_(x_)
+})
+})))
+}
+
+export function Task_raceList(self_, list_, body_) {
+return ff_core_Task.Task_race(self_, ff_core_List.List_map(list_, ((x_) => {
+return (() => {
+return body_(x_)
+})
+})))
+}
+
 export function Task_all(self_, tasks_) {
 const successChannel_ = ff_core_Task.Task_channel(self_, 0);
 const failureChannel_ = ff_core_Task.Task_channel(self_, 0);
@@ -283,6 +299,22 @@ export async function Task_sleep$(self_, duration_, $task) {
 }), $task))
 }
 
+export async function Task_mapList$(self_, list_, body_, $task) {
+return (await ff_core_Task.Task_all$(self_, ff_core_List.List_map(list_, ((x_) => {
+return (async ($task) => {
+return (await body_(x_, $task))
+})
+})), $task))
+}
+
+export async function Task_raceList$(self_, list_, body_, $task) {
+return (await ff_core_Task.Task_race$(self_, ff_core_List.List_map(list_, ((x_) => {
+return (async ($task) => {
+return (await body_(x_, $task))
+})
+})), $task))
+}
+
 export async function Task_all$(self_, tasks_, $task) {
 const successChannel_ = (await ff_core_Task.Task_channel$(self_, 0, $task));
 const failureChannel_ = (await ff_core_Task.Task_channel$(self_, 0, $task));

package/package.json

@@ -4,7 +4,7 @@
     "description": "Firefly compiler",
     "author": "Firefly team",
     "license": "MIT",
-    "version": "0.4.80",
+    "version": "0.4.81",
     "repository": {
         "type": "git",
         "url": "https://github.com/Ahnfelt/firefly-boot"

package/vscode/package.json

@@ -4,7 +4,7 @@
     "description": "Firefly language support",
     "author": "Firefly team",
     "license": "MIT",
-    "version": "0.4.80",
+    "version": "0.4.81",
     "repository": {
         "type": "git",
         "url": "https://github.com/Ahnfelt/firefly-boot"