firefly-compiler 0.5.34 → 0.5.36

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

@@ -1,66 +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.
+# 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

@@ -1,101 +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.
+# 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.