firefly-compiler 0.4.79 → 0.4.81

package/fireflysite/Test.ff

@@ -0,0 +1,46 @@
+import WebServer from ff:webserver // This is required to run the file.
+
+nodeMain(system: NodeSystem) {
+    let f = {x, y => Pair(x, y)}
+    let g = {Pair(_, _)}
+    Log.show(f(1, 2))
+    Log.show(g(1, 2))
+    Log.show(factorial(5))
+    Log.show(factorialTail(5))
+    Log.show([1, 2].map({x => x + x}))
+    
+    let x = {a, b => Pair(a, b)}(1, 2)
+    let f0: () => Unit = {42}
+    let p = {Pair(1, _)}
+    let p2 = {Pair(_, _)}
+
+    let increment: Int => Int = {i => i + 1}
+    let plus: (Int, Int) => Int = {a, b => a + b}
+        
+    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 {
+    if(n == 0) {
+        1
+    } else {
+        n * factorial(n - 1)
+    }
+}
+
+factorialTail(n: Int, acc: Int = 1): Int {
+    if(n == 0) {
+        acc
+    } else {
+        tailcall factorialTail(n - 1, n * acc)
+    }
+}

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

@@ -0,0 +1,209 @@
+# Base types
+
+In Firefly, all named types are defined in a `.ff` file somewhere. 
+However, some of the types in the `ff:core` package have dedicated syntax.
+These are considered base types and are documented in the following sections.
+
+
+# Bool
+
+Values of the `Bool` type represent truth values. They are either `False` or `True`.
+
+The type is defined in `ff:core` as follows:
+
+```firefly
+data Bool {
+    False
+    True
+}
+```
+
+Logical negation is an operator on booleans:
+
+```firefly
+!True  == False
+!False == True
+```
+
+Logical and is an operator on booleans. The right hand side is only evaluated when the left hand side is `True`:
+
+```firefly
+True  && True  == True
+True  && False == False
+False && True  == False
+False && False == False
+```
+
+Logical or is an operator on booleans. The right hand side is only evaluated when the left hand side is `False`:
+
+```firefly
+True  || True  == True
+True  || False == True
+False || True  == True
+False || False == False
+```
+
+The comparison operators are supported for `Bool`:
+
+```firefly
+True  == True     // Equality
+True  != False    // Inequality
+False <  True     // Less than
+False <= True     // Less than or equal
+True  >  False    // Greater than
+True  >= True     // Greater than or equal
+```
+
+In addition, the standard library defines `if`, `while`, etc. as a functions with a `Bool` condition.
+
+
+# Int
+
+Values of the `Int` type represent whole numbers in the range `-9,007,199,254,740,991` to `9,007,199,254,740,991`. This range is specifically chosen to work inside the safe integer range of the `Number` type in JavaScript. Outside of this range, `Int` values may act like `Float` values.
+
+They can be constructed using the following literal syntax:
+
+```firefly
+42  // Fourty two
+0   // Zero
+-1  // Minus one
+```
+
+Basic arithmetic operators are supported:
+
+```firefly
+3 + 5       // Addition, == 8
+3 - 5       // Subtraction, == -2
+3 * 5       // Multiplication, == 15
+-(3 + 5)    // Negation, == -8
+3 / 5       // Division, == 0.6
+```
+
+As are the comparison operators.
+
+Note that the division `3 / 5` does not return an `Int`, but rather a `Float` value `0.6`. If you want integer division, which rounds towards zero, you can do `3.div(5) == 0`.
+
+
+# Float
+
+Values of the `Float` type are floating point numbers with the semantics of the `Number` type in JavaScript.
+
+They be constructed using following literal syntax:
+
+```firefly
+42.0    // Fourty two point zero
+0.0     // Zero point zero
+-1.0    // Minus one point zero
+1.0e3   // == 1000.0
+1.0e-3  // == 0.001
+```
+
+Like `Number` values in JavaScript, `Float` values may also be `Float.nan()`, `Float.infinity()` or `-Float.infinity()`.
+
+Basic arithmetic operators are supported:
+
+```firefly
+3.5 + 5.75      // Addition, == 9.25
+3.0 - 5.0       // Subtraction, == -2.0
+3.0 * 5.0       // Multiplication, == 15.0
+-(3.0 + 5.0)    // Negation, == -8.0
+3.0 / 5.0       // Division, == 0.6
+```
+
+As are the comparison operators. 
+However, as with `Number` values in JavaScript, comparing `Float.nan()` with any floating point value, including `Float.nan()` will return `False`.
+To test whether a number is `Float.nan()`, use the `isNan()` method, e.g. `x.isNan()`.
+
+
+# Char
+
+Values of the `Char` type represent UTF-16 code units. 
+Graphemes outside of the Unicode Basic Multilingual Plane may consist of multiple UTF-16 code units and thus require multiple `Char` values.
+
+They can be constructed using following literal syntax, where `\` (backslash) is used to escape characters:
+
+```firefly
+' '     // A space
+'\''    // Single quote
+'\r'    // Carriage return
+'\n'    // Line feed (Unix newline)
+'\t'    // Horizontal tab
+'\\'    // Backslash
+'A'     // Capital A
+```
+
+The comparison operators also works for `Char` values, but note that they compare the code unit rather than compare by any language-specific character ordering.
+
+
+# String
+
+Values of the `String` type are immutable sequences of `Char` values, representing Unicode strings. 
+
+Single line strings must be contained within a single line, and can be constructed using following literal syntax:
+
+```firefly
+"Hello, World!"
+```
+
+Multiline string literals begin and end with three double quotes, and may contain newlines:
+
+```firefly
+"""
+    Once upon a time,
+    in a land far, far away...
+"""
+```
+
+There's an operator for string concatenation:
+
+```firefly
+"ban" + "ana" == "banana"
+```
+
+The comparison operators are supported, but note that they compare the string as a sequence of `Char` values rather than by any language-specific ordering.
+
+The escape mechanism is the same as with the `Char` type.
+
+
+# List
+
+Values of the `List[T]` types are immutable sequences of `T` values, where `T` is a type of your choice.
+
+They can be constructed using list literals:
+
+```firefly
+[1, 2, 3]   // A List[Int] with three elements
+```
+
+Note that commas can be omitted when they would occur before a newline:
+
+```firefly
+[
+    1
+    2
+    3
+]
+```
+
+Lists can be flattened into other lists using the spread syntax:
+
+```firefly
+[1, ...[2, 3], 4, 5] == [1, 2, 3, 4, 5]
+```
+
+The comparison operators are available for values of type `List[T]` when they're available for values of type `T`.
+
+
+# Unit
+
+The `Unit` type has just one possible value, and is used as the return type for functions that have no interesting return value.
+
+The type is defined in `ff:core` as follows:
+
+```firefly
+data Unit {
+    Unit
+}
+```
+
+If you omit the return type, the `Unit` type is assumed. If you don't end a function with an expression, the `Unit` value is returned.

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.