firefly-compiler 0.4.79 → 0.4.80

package/fireflysite/Test.ff

@@ -0,0 +1,38 @@
+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))
+    
+}
+
+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/FunctionsAndMethods.md

@@ -0,0 +1,208 @@
+# Functions and methods
+
+There are 5 kinds of functions in Firefly: 
+ 
+ * Top-level 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. 
+ 
+# 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
+
+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:
+
+```firefly
+let next: Int => Int = {i => i + 1}
+```
+
+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.
+
+This is an anonymous function taking no arguments:
+
+```firefly
+let life: () => Int = {42}
+```
+
+This is the anonymous function taking no arguments, returning `Unit`:
+
+```firefly
+let uhit: () => Unit = {}
+```
+
+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
+```
+
+Placeholders...
+
+```firefly
+let identity: Int => Int = {_}
+```
+
+
+# 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
+}
+```
+
+# Methods

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

@@ -0,0 +1,168 @@
+# 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
+
+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)
+```
+
+
+# Exports
+
+Currently, all top level definitions are automatically exported. This is likely to change in the future.
+
+
+# Main
+
+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.
+
+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.
+
+
+# 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.