firefly-compiler 0.4.79 → 0.4.81

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

@@ -0,0 +1,338 @@
+# Functions and methods
+
+There are 5 kinds of functions in Firefly: 
+ 
+ * Top-level functions
+ * Anonymous functions
+ * Local functions 
+ * Methods
+ * Trait functions
+ 
+ Trait functions are covered in section [Traits and instances](traits-and-instances), the rest are covered below. 
+ 
+# Top-level functions
+
+Functions at the top level are defined like this:
+
+```firefly
+add(a: Int, b: Int): Int {
+    let sum = a + b
+    sum
+}
+```
+
+This function takes two arguments of type `Int` and returns their sum as an `Int`. A function with a return type other than `Unit`, must have an expression as the last statement, which is returned. In the example above, the value of `sum` is returned. 
+
+When a function returns Unit, it can end with any statement. 
+
+```firefly
+class Counter(mutable value: Int)
+
+reset(counter: Counter): Unit {
+    counter.value = 0
+}
+```
+
+The example above defines a type `Counter` with a mutable field. The function `reset` sets this value to zero. 
+
+
+A `Unit` return type can be omitted in a function definition, like this:
+
+```firefly
+reset(counter: Counter) {
+    counter.value = 0
+}
+```
+
+The parameter types must be declares expitly and the parentheses are required, even if there are no parameters. The function name and parameter names must start with a lowercase letter.
+
+# Type parameters
+
+In a function signature, you can introduce a list of type parameters enclosed in square brackets, immediately following the function name. These type parameters can be used in the rest of the signature. 
+
+The following example defines a function `swap` that takes any Pair and returns a Pair with first and second values swapped:
+
+```firefly
+swap[A, B](pair: Pair[A, B]): Pair[B, A] {
+    Pair(pair.second, pair.first)
+}
+```
+
+Two type parameters `A` and `B` are first introduced in the square brackets. These type parameters are swapped in the input and return type, expressing the value swap at type level. The type parameters are unbuilded in the sense that `swap` may be called with `A` and `B` replaced by any types.
+
+Type parameters can be bounded or constrained like this:
+
+```firefly
+same[E: Equal](pair: Pair[E, E]): Bool {
+    pair.first == pair.second
+}
+```
+
+The type parameter `E` must implement the Equal trait, which is required to perform equality comparisons. The section on [traits and instances](traits-and-instances) will discuss constraints in more detail.
+
+Firefly cannot operate on the concrete types of type parameters at runtime. The behavior of a function is limited to what is specified in the function signature. 
+
+
+# Calling functions
+
+Functions are called like this:
+
+```firefly
+add(1, 2)              // 3
+same(Pair('A', 'a'))   // False
+```
+
+Just like variants, the arguments can be named, and given out of order, like this:
+
+```firefly
+add(b = 2, a = 1)
+add(b = 2, 1)     // Same as above
+```
+
+# Default Values
+
+Function parameters in Firefly can have default values, which are used when no argument is provided for that parameter during a function call. Default values are specified in the function signature by assigning a value to the parameter.
+
+Here’s an example of a function with a default value:
+
+```firefly
+add(a: Int, b: Int = 1): Int {
+    a + b
+}
+```
+
+When called without the second arguments, the function will use the default value:
+
+```firefly
+greet(1)  // returns 2
+```
+
+If an argument is provided, it overrides the default:
+
+```firefly
+greet(1, 2)  // returns 3
+```
+
+
+# Recursion
+
+Function definitions can be recursive, meaning that a function can call itself. Here’s an example of a recursive function that calculates the factorial of a number:
+
+```firefly
+factorial(n: Int): Int {
+    if(n == 0) {
+        1
+    } else {
+        n * factorial(n - 1)
+    }
+}
+```
+
+When calling `factorial(0)`, the base case is triggered, returning `1`. Calling the function with a positive integer will recursively calculate the factorial. However, calling it with negative values will result in infinite recursion, as no base case exists for such input.
+
+# Tail Recursion
+
+In some recursive functions, the recursive call is the last operation performed before returning the result. This is *tail recursion*. The Firefly compiler can optimize tail recursive calls, avoiding the buildup of function calls on the stack.
+
+You can use the `tailcall` keyword to explicitly mark a recursive call as tail-recursive, ensuring the compiler applies the optimization.
+
+Here is a tail-recursive implementation of the factorial function:
+
+```firefly
+factorial(n: Int, acc: Int = 1): Int {
+    if(n == 0) {
+        acc
+    } else {
+        tailcall factorial(n - 1, n * acc)
+    }
+}
+```
+
+This version introduces an additional parameter, `acc`, which acts as an accumulator to hold the running result of the factorial calculation. It is initialized to 1 by default, ensuring that when the function is first called with a single argument, the computation starts correctly. By moving the multiplication into the recursive call via the accumulator, the call becomes a tail-call, allowing the Firefly compiler to optimize it.
+
+# Anonymous functions
+
+In firefly anonymous functions are written in curlybrases and constucted like this:
+
+```firefly
+{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 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.
+
+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 an anonymous function taking no arguments and returning `Unit`:
+
+```firefly
+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:
+
+```firefly
+let plus: (Int, Int) => Int = {a, b => a + b}
+```
+
+Anonymous function are called like named function.
+
+```firefly
+life()      // returns 42
+unit()      // returns unit
+next(1)     // returns 2
+plus(1, 2)  // returns 3
+```
+
+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
+
+Local functions are declared exactly like top-level functions but with the `function` keyword in front of the signature, like this:
+
+
+```firefly
+function square(n: Int): Int {
+    n * n
+}
+```
+
+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

@@ -0,0 +1,162 @@
+# Modules and packages
+
+In Firefly, source code is organized in packages, which can be versioned, released and depended on. 
+Inside packages, there are modules, which are individual files that can be imported from other modules.
+
+The minimal package consists of just a single module file, and nothing else.
+Such a module can contain the following top level constructs:
+
+```firefly
+// Package information
+package mygroup:mypackage:1.2.3
+dependency ff:webserver:0.0.0
+include "node_modules"
+
+// Module imports
+import WebServer from ff:webserver
+
+// Named constants
+answer: Int = 42
+
+// Function definitions
+f(x: Int): Int {
+    
+}
+
+// Type definitions
+data Point(x: Int, y: Int)
+
+// Method definitions
+extend self: Point {
+
+}
+
+// Traits and trait instances
+trait T: HasCenter {
+
+}
+instance Point: HasCenter {
+
+}
+```
+
+In a multi-file package, the package information is instead specified in a separate `package.ff` file which must live in the `.firefly/` subdirectory. A typical multi-file package looks like this:
+
+```
+mypackage/
+    .firefly/
+        package.ff
+    MyModule.ff
+    MyOtherModule.ff
+```
+
+The two module files here `MyModule.ff` and `MyOtherModule.ff` defines the modules `MyModule` and `MyOtherModule` respectively. Module files must start with a capital letter.
+
+In general, identifiers of any kind in Firefly must start with an ASCII letter, and can only contain ASCII letters and numbers. This also applies to module and package names.
+
+Apart from containing the `package.ff` file, the `.firefly/` subdirectory is used for various compiler output and can contain an `include/` directory with JavaScript that you want to include verbatim into the build via the `include` directive.
+
+
+# Package information
+
+The `package` keyword specifies the group name, package name and major.minor.patch package version:
+
+```firefly
+package mygroup:mypackage:1.2.3
+```
+
+A group is a person, organization or similar entity that's allowed to publish packages under that group name.
+
+If present, the `package` keyword must be the first token in the file. In a single file package, all the package information goes before any other content.
+
+The `dependency` keyword specifies the group name, package name and major.minor.patch package version of a package that is a dependency of this package:
+
+```firefly
+dependency ff:webserver:0.0.0
+```
+
+There may be zero or more dependencies. If there are conflicting versions of the same package in the dependencies or transitive dependencies, the first version that's encountered in a breadth first search from top to bottom will be used.
+
+The `include` keyword includes files verbatim in the JavaScript that is emitted by the compiler:
+
+```firefly
+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 and exports
+
+To access the symbols that a module exports, it is necessary to import it:
+
+```firefly
+import WebServer from ff:webserver
+```
+
+This imports the `WebServer` module from the `ff:webserver` package, which must have been declared as a dependency.
+
+Symbols exported from the module can then be accessed using the `WebServer.` prefix:
+
+```firefly
+WebServer.new(system, "localhost", 8080)
+```
+
+Types, variants and traits are available under the prefix, but can also be accessed with no prefix at all. In the case of naming collisions between these, the last import wins.
+
+If two imported modules have the same name, or a different prefix is desired, the symbols can be imported under a different prefix:
+
+```firefly
+import WebServer as W from ff:webserver
+```
+
+The symbols can then be accessed using the `W.` prefix:
+
+```firefly
+W.new(system, "localhost", 8080)
+```
+
+Currently, all top level definitions are automatically exported. This is likely to change in the future.
+
+
+# Main functions
+
+In Firefly, there are three targets, each with its own main function:
+
+```firefly
+nodeMain(system: NodeSystem) {
+    system.writeLine("Hello server!")
+}
+
+browserMain(system: BrowserSystem) {
+    system.writeLine("Hello browser!")
+}
+
+buildMain(system: BuildSystem) {
+    system.writeLine("Hello build!")
+}
+```
+
+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 with methods that let you do I/O in the target system.
+
+
+# Constants
+
+Named constants may be defined at the top level, and must have an explict type:
+
+```firefly
+answer: Int = 42
+```
+
+Here `answer` is defined to be an `Int` with the value `42`.
+
+There's no global state in Firefly, and to enforce this, the type of a named constant must have be declared with the `data` or `newtype` keyword.
+
+Named constants that occur on the right hand side must not directly or indirecly refer to the named constant being defined.
+
+Neither of the requirements are enforced currently, but this is likely to change in the future.

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))
+            }
+        }
+    }
+}
+```