firefly-compiler 0.4.79 → 0.4.80

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

@@ -0,0 +1,224 @@
+# Pattern matching
+
+Every function lets you pattern match on its arguments. Pattern matching lets you branch on the structure of arguments and extract nested values.
+
+
+# In anonymous functions
+
+In the following example, `map` is passed an anonymous function, which pattern matches on its argument:
+
+```firefly
+blockElements.map {
+    | Paragraph(text) => 
+        renderParagraph(text)
+    | Code(code, Some(type)) => 
+        renderHighlighted(code, type)
+    | Code(code, None) => 
+        renderCode(code)
+    | Video(url) {vimeoId(url) | Some(id)} => 
+        renderVimeo(id)
+    | Video(url) => 
+        renderVideo(url)
+}
+```
+
+In this example there are five cases, and `blockElements: List[BlockElement]` with the following type definition:
+
+```firefly
+data BlockElement {
+    Paragraph(text: String)
+    Code(code: String, type: Option[String])
+    Video(url: String)
+}
+```
+
+If you have multiple arguments, you need to provide a pattern for each argument, separated by commas.
+
+
+# Cases
+
+Each case must have one or more patterns, zero or more guards, and zero or more statements.
+
+The first case starts with a pattern that matches when the argument is `Paragraph`, and extracts its `text` field into a variable named `text`:
+
+```firefly
+| Paragraph(text) => 
+```
+
+The variable is in scope in the statements of the case following the `=>`.
+The field name and the variable name do not have to be the same. 
+The variable could be named `t` or `foo`, even though the type defines a field named `text`.
+
+The second case starts with a pattern that matches when the argument is `Code`, and the second field of that is `Some`:
+
+```firefly
+| Code(code, Some(type)) => 
+```
+
+The third case starts with a pattern that matches when the argument is `Code`, and the second field of that is `None`:
+
+```firefly
+| Code(code, None) => 
+```
+
+Together with the case above, it covers all the values that can be constructed using the `Code` variant.
+
+The fourth case starts with a pattern that matches when the argument is `Video`, and then uses a guard:
+
+```firefly
+| Video(url) {vimeoId(url) | Some(id)} =>
+```
+
+The guard calls a function on the extracted field, and matches the result against the pattern `Some(id)`.
+
+The fifth and final case starts with a pattern that matches when the argument is `Video`, and has no guard:
+
+```firefly
+| Video(url) =>
+```
+
+Together with the case above, it convers all the values that can be constructed using the `Video` variant.
+
+
+# Exhaustiveness
+
+Since all the ways to construct a `BlockElement` has been covered by the cases, the pattern match is exhaustive. 
+Exhaustiveness is enforced in Firefly, so it's never possible to end up in a situation at runtime where no case matches the arguments.
+
+Cases are tried in order until one of them matches. When a case matches, its statements will be run.
+In this case a return value is expected, and thus the last statement must be an expression, whose value will be returned.
+
+
+# Alias patterns
+
+To extract all the fields of a variant as an anonymous record, use the a pattern like this:
+
+```firefly
+| Code c => 
+    renderCode(c.code)
+```
+
+Here `c: (code: String, type: Option[String])` - that is, it's an anonymous record with the fields of the variant.
+
+To pattern match on a value while also extracting that value into a variable, use a pattern like this:
+
+```firefly
+| Code(code, Some(_) @ typeOption) => 
+```
+
+This ensures that the case only matches if the type field is `Some`, but binds the whole option into a variable `typeOption: Option[String]`.
+
+
+# In pipes
+
+Another way to write the above is to pipe the argument into an anonymous function that pattern matches on it:
+
+```firefly
+blockElements.map {blockElement =>
+    blockElement.{
+        | Paragraph(text) => 
+            renderParagraph(text)
+        | Code(code, Some(type)) => 
+            renderHighlighted(code, type)
+        | Code(code, None) => 
+            renderCode(code)
+        | Video(url) {vimeoId(url) | Some(id)} => 
+            renderVimeo(id)
+        | Video(url) => 
+            renderVideo(url)
+    }
+}
+```
+
+This is also a way to pattern match on one of many arguments, a local variable or an expression.
+
+
+# In named functions
+
+Pattern matching may also be used for the arguments of named functions and methods. Here's an example of pattern matching in a local function:
+
+```firefly
+function render(element: BlockElement) {
+    | Paragraph(text) => 
+        renderParagraph(text)
+    | Code(code, Some(type)) => 
+        renderHighlighted(code, type)
+    | Code(code, None) => 
+        renderCode(code)
+    | Video(url) {vimeoId(url) | Some(id)} => 
+        renderVimeo(id)
+    | Video(url) => 
+        renderVideo(url)    
+}
+```
+
+Here's an example of pattern matching in a method:
+
+```firefly
+extend self: Renderer {
+    render(element: BlockElement) {
+        | Paragraph(text) => 
+            self.renderParagraph(text)
+        | Code(code, Some(type)) => 
+            self.renderHighlighted(code, type)
+        | Code(code, None) => 
+            self.renderCode(code)
+        | Video(url) {vimeoId(url) | Some(id)} => 
+            self.renderVimeo(id)
+        | Video(url) => 
+            self.renderVideo(url)    
+    }
+}
+```
+
+
+# Literals and wildcards
+
+It's also possible to match on `Int`, `Char`, `String`, and `List[T]` values. 
+
+Here's an example that matches on `Int`:
+
+```firefly
+fib(n: Int): Int {
+    | 0 => 0
+    | 1 => 1
+    | _ => fib(n - 1) + fib(n - 2)
+}
+```
+
+The wildcard pattern `_` matches any value without binding it to a variable.
+
+Here's an example that matches on `Char`:
+
+```firefly
+extend self: Player {
+    go(key: Char) {
+        | 'w' => self.goUp()
+        | 'a' => self.goLeft()
+        | 's' => self.goDown()
+        | 'd' => self.goRight()
+        | _ =>
+    }
+}
+```
+
+Here's an example that matches on `String`:
+
+```firefly
+name.{
+    | "" => "Hello, there!"
+    | _ => "Hello, " + name + "!"
+}
+```
+
+Here's an example that matches on `List[Int]`:
+
+```firefly
+numbers.{
+    | [] => "No numbers!"
+    | [n] => "One number, " + n + "!"
+    | [n, ...ns] => "A number, " + n + ", and " + ns.size() + " more numbers!"
+}
+```
+
+In patterns, the spread syntax `...` matches the rest of a list.

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

@@ -0,0 +1,86 @@
+# Statements and expressions
+
+In Firefly, the body of functions and methods consist of zero or more statements, separated by `;`.
+
+When `;` is the last token on a line, it can be omitted.
+
+A statement is either a [local function definition](functions-and-methods), a local variable definition, an assignment or an expression.
+
+Field assignments were covered in [user defined types](user-defined types).
+
+
+# Local variables
+
+Local variables need an initial value:
+
+```firefly
+let x = 42
+```
+
+This defines immutable local variable `x: Int` with the value `42`.
+
+Variables can be reffered to by name:
+
+```firefly
+x + x       // Returns 84
+```
+
+The type of a variable can be stated explicitly:
+
+```firefly
+let y: String = "Hello"
+```
+
+Mutable variables are introduced using the `mutable` keyword:
+
+```firefly
+mutable z = 1
+```
+
+This works like `let`, except that you're allowed to update mutable variables by assigning to them:
+
+```firefly
+z = 2       // z is now 2
+z += 2      // z is now 4
+z -= 1      // z is now 3
+```
+
+
+# Expressions
+
+Expressions can be one of the following syntactic constructs:
+
+```firefly
+42          // Int literal
+42.0        // Float literal
+'a'         // Char literal
+"foo"       // String literal
+[]          // List literal
+{}          // Function literal
+()          // Record literal
+True        // Variant construction
+x           // Variable
+_           // Anonymous parameter
+f()         // Function call
+x.y         // Field access
+x.V()       // Copy construction
+x.{_}       // Piping
+!x          // Unary operator
+a + b       // Binary operator
+(a + b) * c // Grouping parenthesis
+```
+
+Binary operators are left associative and the operator precedence is as follows, lowest to highest:
+
+ * `||`
+ * `&&`
+ * `!=` `==`
+ * `<=` `>=` `<` `>`
+ *  `+` `-`
+ * `*` `/` `%`
+ * `^`
+ * `f()`
+ * `x.y` `x.V()` `x.{_}`
+
+Unary operators `!` and `-` have higher precedence than `^` and lower precedence than `f()`.
+

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

@@ -0,0 +1,100 @@
+# Traits and instances
+
+A trait defines an open set of types that support a common set of functions. 
+For example, here's a trait for shapes with a common function to compute the area:
+
+```firefly
+trait T: Shape {
+    area(shape: T): Float
+}
+```
+
+The function becomes a top level function `area[T: Shape](shape: T): Float`.
+Here `T` is a bounded type parameter: It can only be instantiated to a type that has an instance of the `Shape` trait.
+
+Consider these two types that would be good candidates for having an instance of the `Shape` trait:
+
+```firefly
+data Circle(radius: Float)
+data Rectangle(width: Float, height: Float)
+```
+
+Only types defined with the `data` or `newtype` keyword can have trait instances.
+
+Instances for these types can be created with the `instance` keyword as follows:
+
+```firefly
+instance Circle: Shape {
+    area(shape: Circle): Float {
+        Float.pi() * (shape.radius ^ 2.0)
+    }
+}
+
+instance Rectangle: Shape {
+    area(shape: Rectangle): Float {
+        shape.width * shape.height
+    }
+}
+```
+
+Each instance provides an implementation of `area` specific to the type.
+
+Here's an example of how to define a normal top level function with a bounded type parameter:
+
+```firefly
+printArea[T: Shape](shape: T) {
+    Log.trace("Area: " + area(shape))
+}
+
+printArea(Circle(0.0))          // Prints "Area: 0"
+printArea(Rectangle(5.0, 6.0))  // Prints "Area: 30"
+```
+
+Multiple bounds are separated by colons, e.g. `foo[T: Bar: Baz]` means that `T` must have instances for both `Bar` and `Baz`.
+
+
+# Traits with type parameters
+
+Traits can have type parameters:
+
+```firefly
+trait I: Rpc[O] {}
+
+instance MyMessage: Rpc[Int] {}
+```
+
+The choice of `I` fully determines `O` - in this case, if `I` is `MyMessage`, then `O` is `Int`.
+
+
+# Automatic traits
+
+If instances for the following traits are not explicitly defined, they will be generated automatically.
+This only applies to types defined with the `data` or `newtype` keyword.
+
+```firefly
+// Used for == !=
+trait T: Equal {
+    equals(x: T, y: T): Bool
+}
+
+// Used for < > <= >= and sorting
+trait T: Order {
+    compare(x: T, y: T): Ordering
+}
+
+// Used to display values for debugging
+trait T: Show {
+    show(value: T): String
+}
+
+// Used for binary serialization
+trait T: Serializable {
+    serializeUsing(serialization: Serialization, value: T): Unit
+    deserializeUsing(serialization: Serialization): T
+}
+
+// Used for throwing and catching exceptions
+trait T: HasAnyTag {
+    anyTag(): AnyTag[T]
+}
+```

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

@@ -0,0 +1,184 @@
+# User defined types
+
+Named types can be defined at the top level, using one of four keywords: `data`, `class`, `capability` or `newtype`.
+
+
+# data
+
+To define an immutable type, you can use the `data` keyword.
+
+```firefly
+data Shape {
+    Circle(x: Float, y: Float, radius: Float)
+    Rectangle(x: Float, y: Float, width: Float, height: Float)
+}
+```
+
+This defines a type called `Shape` with two variants `Circle` and `Rectangle`. 
+The `Circle` variant has three named fields of type `Float`, while the `Rectangle` variant has four.
+
+Type and variant names must start with a capital letter.
+
+No `class` or `capability` types can occur in the definition of a `data` type.
+
+A value of type `Shape` is either a `Circle` or a `Rectangle`, and they can be constructed as follows:
+
+```firefly
+Circle(0.0, 0.0, 1.0)           // Variant, : Shape
+Rectangle(5.0, 7.0, 3.0, 2.0)   // Variant, : Shape
+```
+
+Above the variants are constructed using positional arguments, whose order must coincide with the order of the parameters in the type definition.
+
+Named arguments are supported as well:
+
+```firefly
+Circle(x = 0.0, y = 0.0, radius = 1.0)
+```
+
+Named parameters don't have to be in order, and can be mixed with positional arguments:
+
+```firefly
+Circle(radius = 1.0, 0.0, 0.0)
+```
+
+To branch on the specific variant of a type, use [pattern matching](pattern-matching).
+
+
+# Common fields
+
+When all the variants share a set of fields, they can be moved to the common fields section of the declaration:
+
+```firefly
+data Shape(x: Float, y: Float) {
+    Circle(radius: Float)
+    Rectangle(width: Float, height: Float)
+}
+```
+
+This is similar to the `Shape` definition above, but the `x` and `y` fields have been pulled out as common fields. 
+Given a value of a type, e.g. `shape: Shape`, common fields can be accessed without knowing which specific variant it is:
+
+```firefly
+shape.x     // Returns a Float
+shape.y     // Returns a Float
+```
+
+When there is only one variant of a type, and its name coincides with the name of the type, we can use a shorthand definition:
+
+```firefly
+data Point(x: Float, y: Float)
+```
+
+This defines a type called `Point` with a single variant, also named `Point`, and two common fields of type `Float`.
+
+
+# Copying
+
+If you have a value and want to construct a variant, you can copy each field explicitly:
+
+```firefly
+Rectangle(x = point.x, y = point.y, width = 2.0, height = 1.5)
+```
+
+There's a shorthand for doing this, however:
+
+```firefly
+point.Rectangle(width = 2.0, height = 1.5)
+```
+
+Using this shorthand, the fields of `Rectangle` that aren't specified will be copied from `point`.
+
+
+
+# class
+
+Types defined with the `class` keyword work like `data` types, except for the differences noted here.
+
+Fields of `class` types may be declared `mutable`:
+
+```firefly
+class FruitBasket(
+    mutable apples: Int
+    mutable oranges: Int
+    mutable bananas: Int
+)
+```
+
+Mutable fields can be updated. Given a value `basket: FruitBasket`, its fields can be assigned to:
+
+```firefly
+basket.apples = 42      // The apples field now holds the value 42
+basket.oranges += 1     // The oranges field is now one greater
+basket.bananas -= 1     // The bananas field is now one less
+```
+
+Except for `capability` types, all types can occur in the definition of a `class` type.
+
+
+# capability
+
+Types defined with the `capability` keyword work like `class` types, except for the differences noted here.
+
+```firefly
+capability EventHandler(
+    onEvent: () => Unit
+)
+```
+
+The `onEvent` field here contains a first class function, which may have captured other capabilities or classes in its closure.
+Therefore, calling the function contained in this field may cause side effects.
+
+In particular, it may have captured the `system` argument that's passed to the main function, or other capabilities that allow it to do I/O.
+
+There are no restrictions on the types of fields that `capability` types can have.
+
+Function types `=>` are considered `capability` types.
+
+
+# newtype
+
+Types defined with the `newtype` keyword work like `data` types, except that they must have exactly one common field and no explicitly listed variants.
+
+```firefly
+newtype UserId(id: Int)
+```
+
+At runtime, they are represented as values of the field type.
+In this case, it means that `UserId(42)` is represented as the `Int` value `42` at runtime, with zero overhead.
+
+
+# Generic types
+
+Whether you use `data`, `class`, `capability` or `newtype` to define a type, it may have type parameters.
+
+```firefly
+data Basket[T](
+    items: List[T]
+)
+```
+
+Here the `T` in `Basket[T]` is a type parameter, and it's used as a type argument in `List[T]`.
+
+An unbounded type parameter can be instantiated to any type. 
+We can have a `Basket[Shape]`, which has a field `items: List[Shape]`, and a different type `Basket[EventHandler]`, which has a field `items: List[EventHandler]`.
+
+Note that type parameters are not concrete types, and are thus not subject to the field type restrictions stated earlier.
+
+
+# Anonymous records
+
+An anonymous record is not defined anywhere, but consists of zero or more fields. The fields may have any type, but can't be reassigned after creation.
+
+```firefly
+(red = 255, green = 255, blue = 0)
+```
+
+This constructs an anonymous record.
+If you have an anonymous record value, e.g. `color: (red: Int, green: Int, blue: Int)`, you can access its fields:
+
+```firefly
+color.red       // Returns an Int
+color.green     // Returns an Int
+color.blue      // Returns an Int
+```