firefly-compiler 0.4.77 → 0.4.79

package/fireflysite/GuideControlFlow.ff

@@ -0,0 +1,212 @@
+import Guide
+
+new(): Document {
+    ReadyDocument([
+
+        Section("Control flow", [
+            Paragraph([
+                Text("Firefly provides several ways to implement branching. ")
+                Anchor("Pattern matching")
+                Text(" is the most powerful, built directly into the language. ")
+                Code("if")
+                Text(", ")
+                Code("elseIf")
+                Text(" and ")
+                Code("else")
+                Text(" do what you expect and are functions and methods in the standard library, implemented using the")
+                Anchor("Option")
+                Text(" type. An then finally, there are ")
+                Anchor("exceptions")
+                Text(".")
+            ])
+        ])
+
+        Section("Pattern matching", [
+            Paragraph([
+                Text("Pattern matching allows you to check a given data structure against a pattern. ")
+                Text("For example, if we want to parse the command line arguments provided by the user, we could do it like this:")
+            ])
+            CodeBlock("""
+                let pair = system.arguments().{
+                    | [host] => Pair(host, 80)
+                    | ["localhost", port] => Pair("localhost", port.grabInt())
+                    | _ => 
+                        system.writeErrorLine("Usage: 'localhost' | (host port)")
+                        system.exit(0)
+                }            
+            """, firefly = True)
+            Paragraph([
+                Text("In Firefly you construct a list of strings (")
+                Code("List[String]")
+                Text(") like this ")
+                Code("""["example.com", "80"]""")
+                Text(", and using pattern matching you can de-construct in the same way.")
+            ])  
+            Paragraph([
+                Text("The basic syntax for pattern matching is:")
+            ])
+            CodeBlock("""
+                data.{
+                    | pattern1 => // case 1
+                    | pattern2 => // case N
+                    ...
+                }
+            """, firefly = True)
+            Paragraph([
+                Text("The patterns must be exhaustive, that is, for any possible value of the given type, there must be a matching pattern. ")
+                Text("In the example above, there are no value for the empty list ")
+                Code("[]")
+                Text(", list with two values, where the first is not ")
+                Code(""""localhost"""")
+                Text(" or lists with more than 2 arguments. That's why we need the wildcard case at the end. ")
+                Text("Without this last case, the compiler would  produce a compile-time error, stating that the patterns must be exhaustive.")
+            ])
+            Paragraph([
+                Text("Here are more examples — all exhaustive. Let's start with records:")
+            ])  
+            CodeBlock("""
+                pair.{
+                    | Pair(first, second) => 
+                }
+            """, firefly = True)
+
+            Paragraph([
+                Text("Numbers")
+            ])  
+            CodeBlock("""
+                n.{
+                    | 1 => 
+                    | 2 => 
+                    | n => 
+                }
+            """, firefly = True)    
+            
+            Paragraph([
+                Text("Booleans")
+            ])  
+            CodeBlock("""
+                n.{
+                    | True => 
+                    | False => 
+                }
+            """, firefly = True)    
+            Paragraph([
+                Text("And you can combine pattern as needed. Imagine you have a pair of type ")
+                Code("Pair[List[Bool], Pair(Int, String)]")
+            ])  
+            CodeBlock("""
+                pair.{
+                    | Pair([True, False], Pair(42, "foo")) => 
+                    | other => 
+                }
+            """, firefly = True)          
+        ])
+
+        Section("Option", [
+            Paragraph([
+                Text("Sometimes you don't have a value. Other languages uses ")
+                Code("null")
+                Text(" for this purpose, but Firefly does not have ")
+                Code("null")
+                Text(". Instead, we have ")
+                Code("Option")
+                Text(" from the core package.")
+            ])
+            CodeBlock("""
+                data Option[T] {
+                    None
+                    Some(value: T)
+                }
+            """, firefly = True)
+            Paragraph([
+                Text("For some type T, say String, Option[String] is either some string or no value (")
+                Code("None")
+                Text("). This way, the type system guides you to check for no-value.")                
+            ])
+
+            Paragraph([
+                Text("Many functions and methods returns an ") 
+                Code("Option")
+                Text(" in Firefly. For instance the ")
+                Code("getInt ")
+                Text(" method on ")
+                Code("String")
+                Text(" . This method returns ")
+                Code("Some[Int]")
+                Text(" when the string consists only of digits and ")
+                Code("None")
+                Text(" otherwise. We can perform pattern matching on ")
+                Code("Option")
+                Text("like this:")
+            ])
+            CodeBlock("""
+                port.getInt().{
+                    | None => 80
+                    | Some(p) => p
+                }
+            """, firefly = True)  
+            Paragraph([
+                Text("Many methods like ")
+                Code("getInt")
+                Text(" have a non-total counterpart ")
+                Code("grabInt")
+                Text(" , which returns an ")
+                Code("Int")
+                Text(" . But it will throw an exception when the input cannot be parsed. Options let's you code in an exception-safe manner.")
+            ])
+        ])
+
+
+        Section("if - elseIf - else", [
+            Paragraph([
+                Text("You write if-statements in Firefly like this:")
+            ])
+            CodeBlock("""
+                if(path == "/") {
+                    response.writeText("<!doctype html>")
+                } elseIf {path.startsWith("/js/")} {
+                    response.writeText("<script>")
+                } else {
+                    response.writeStatus("404 Not found")
+                }
+            """, firefly = True)
+            Paragraph([
+                Text("You can also use it as an expression like this")
+            ])
+            CodeBlock("""
+                let contentType = if(path == "/") {
+                    "text/html; charset=UTF-8"
+                } elseIf(directory2.exists) {
+                    "text/javascript; charset=UTF-8"
+                } else {
+                    "text/plain; charset=UTF-8"
+                }
+            """, firefly = True)
+            Paragraph([
+                Code("if")
+                Text(", ")
+                Code("elseIf")
+                Text(" and ")
+                Code("else")
+                Text(" are not keywords or construct build into Firefly. ")
+                Text("If you are curious, you can look at how they are implemented. ")
+                Code("if")
+                Text(" is just a function defined like this: ")
+            ])
+            CodeBlock("""
+                if[T](condition: Bool, body: () => T): Option[T] {
+                    condition.{
+                        | False => None
+                        | True => Some(body())
+                    }
+                }
+            """, firefly = True)
+            // TODO: But still, why are this syntactically correct?            
+        ])
+        Section("Exceptions", [
+            Paragraph([
+                Text("...")
+            ])
+        ])
+    ])
+}

package/fireflysite/GuideIntroduction.ff

@@ -0,0 +1,52 @@
+import Guide
+
+new(): Document {
+    ReadyDocument([
+        Section("Guide", [
+            Paragraph([
+                Text("In this guide you will learn to use Firefly.")
+                Text("Firefly is a programming language that compiles to JavaScript.")
+                Text("It runs in the browser and on the server, and lets you develop webapps with a minimum of hassle.")
+            ])
+        ])
+        Section("Getting started", [
+            Paragraph([
+                Text("Firefly comes with a compiler, a build system and a package manager.")
+            ])
+            Paragraph([
+                Text("Install Firefly:")
+            ])
+            CodeBlock("npm install -g firefly-compiler")
+            Paragraph([
+                Text("Save this code as")
+                Code("Hello.ff")
+                Text(":")
+            ])
+            CodeBlock("""
+                nodeMain(system: NodeSystem) {
+                    system.writeLine("Hello, World!")
+                }
+            """, firefly = True)
+            Paragraph([
+                Text("And run it:")
+            ])
+            CodeBlock("firefly Hello.ff")
+            Paragraph([
+                Text("You now know how to run Firefly code!")
+            ])
+        ])
+        Section("Editor support", [
+            Paragraph([
+                Text("Install the")
+                Link("Firefly Language VSCode extension", "https://marketplace.visualstudio.com/items?itemName=firefly-team.firefly-lang")
+                Text(" to get autocompletion, renaming, go to definition, highlighting, etc. You can find it under Extensions in VSCode.")
+            ])
+            Paragraph([
+                Text("The Firefly code highlighting on this site matches the Dark Modern theme in VSCode.")
+            ])
+            Paragraph([
+                Text("If you'd like to make an extension for a different editor, the language server is available, as well as the source code for the VSCode extension.")
+            ])
+        ])
+    ])
+}

package/fireflysite/Main.ff

@@ -1,15 +1,137 @@
-dependency ff:webserver:0.0.0
-import WebServer from ff:webserver
-
-nodeMain(system: NodeSystem): Unit {
-    let host = system.arguments().grab(0)
-    let port = system.arguments().grab(1).grabInt()
-    WebServer.new(system, host, port).listen {request =>
-        let parameters = if(request.readRawQueryString().size() == 0) {""} else {
-            "?" + request.readRawQueryString()
-        }
-        request.writeHeader("Location", "https://www.firefly-lang.org" + request.readPath() + parameters)
-        request.writeStatus("302 Found")
-    }
-}
-
+import WebServer from ff:webserver
+import Lux from ff:lux
+import Guide
+import GuideAll
+import ExamplesOverview
+import PackagesOverview
+import CommunityOverview
+import FrontPage
+import Styles
+
+nodeMain(system: NodeSystem): Unit {
+    let host = system.arguments().grab(0)
+    let port = system.arguments().grab(1).grabInt()
+    let cacheSalt = system.crypto().randomBuffer(16)
+    system.writeLine("Listening on " + host + ":" + port)
+    WebServer.new(system, host, port).listen {request =>
+        let path = request.readPath()
+        let segments = path.split('/').filter {s => s != "" && s != "." && s != ".."}
+        segments.{
+            | ["guide", ...] => 
+                serveGuideHtml("Firefly Guide", request)
+            | ["examples", ...] => 
+                serveGuideHtml("Firefly Examples", request)
+            | ["packages", ...] => 
+                serveGuideHtml("Firefly Examples", request)
+            | ["community", ...] => 
+                serveGuideHtml("Firefly Examples", request)
+            | ["front", ...] => 
+                serveGuideHtml("Firefly Examples", request)
+            | ["js", ...] => 
+                let asset = if(path == "/js/ff/fireflysite/Main.mjs" && system.assets().exists("/js/Main.bundle.js")) {
+                    "/js/Main.bundle.js"
+                } else {
+                    path
+                }
+                serveAsset(system, cacheSalt, request, "text/javascript; charset=UTF-8", asset)
+            | ["favicon.ico"] =>
+                serveAsset(system, cacheSalt, request, "image/png", "/assets/firefly-logo-notext.png")
+            | ["assets", "FireflyMono.ttf"] => 
+                serveAsset(system, cacheSalt, request, "image/png", "/assets/NotoSansMono-Regular.ttf")
+            | ["assets", "FireflySans.ttf"] => 
+                serveAsset(system, cacheSalt, request, "image/png", "/assets/NunitoSans-VariableFont_YTLC,opsz,wdth,wght.ttf")
+            | ["assets", ...rest] => serveAssets(system, cacheSalt, request, rest)
+            | _ =>
+                let parameters = if(request.readRawQueryString().size() == 0) {""} else {
+                    "?" + request.readRawQueryString()
+                }
+                request.writeHeader("Location", "https://www.firefly-lang.org" + path + parameters)
+                request.writeStatus("302 Found")
+        }
+    }    
+}
+
+browserMain(system: BrowserSystem): Unit {
+    let demos = ExamplesOverview.demos()
+    let guides = [
+        Guide("/front/", [FrontPage.new()])
+        Guide("/guide/", GuideAll.mock())
+        Guide("/examples/", ExamplesOverview.mock())
+        Guide("/packages/", [PackagesOverview.new()])
+        Guide("/community/", [CommunityOverview.new()])
+    ]
+    guides.collect {guide => 
+        if(system.urlPath().startsWith(guide.prefix)):
+        Lux.renderById(system, "main") {lux => 
+            let kebab = system.urlPath().dropFirst(guide.prefix.size())
+            Guide.render(lux, system, guide.prefix, kebab, guides, demos)
+        }
+    }
+}
+
+buildMain(system: BuildSystem) {
+    let browser = system.compileForBrowser("Main.ff")
+    let assets = AssetSystem.create()
+        .addAssets("/js/", browser.assets())
+        .addAssets("/assets/", system.packageAssets().assets("/assets/"))
+    system.setAssets(assets)
+}
+
+serveAssets(system: NodeSystem, salt: Buffer, request: WebRequest[WebResponse], segments: List[String]): Unit {
+    let asset = "/assets/" + segments.join("/")
+    if(!system.assets().exists(asset)) {
+        request.writeStatus("404 Not Found")
+    } else:
+    
+    guessContentType(asset).or {
+        request.writeStatus("404 Not Found")
+    }: contentType =>
+
+    serveAsset(system, salt, request, contentType, asset)
+}
+
+guessContentType(path: String): Option[String] {
+    path.split('.').last().flatMap {
+        | "md" => Some("text/markdown")
+        | "png" => Some("image/png")
+        | "ttf" => Some("font/ttf")
+        | _ => None
+    }
+}
+
+serveAsset(system: NodeSystem, salt: Buffer, request: WebRequest[WebResponse], contentType: String, asset: String): Unit {
+    let etag = "\"" + system.crypto().hmacSha256(salt, asset.toBuffer()).toHex() + "\""
+    request.writeHeader("Content-Type", contentType)
+    if(request.readHeader("host") == Some("localhost:8080")) {
+        request.writeHeader("Cache-Control", "public, max-age=0, must-revalidate")
+    } else {
+        request.writeHeader("Cache-Control", "public, max-age=60, must-revalidate")
+    }
+    request.writeHeader("ETag", etag)
+    if(request.readHeader("if-none-match").any {_.trim() == etag}) {
+        request.writeStatus("304 Not Modified")
+    } else {
+        request.writeStream(system.assets().readStream(asset))
+    }
+}
+
+serveGuideHtml(title: String, request: WebRequest[WebResponse]): Unit {
+    request.writeHeader("Content-Type", "text/html; charset=UTF-8")
+    request.writeText("<!doctype html>")
+    request.writeText("<html lang='en' style='background-color: #ffffff; color: #333333; width: 100%; height: 100%; color-scheme: light;'>")
+    request.writeText("<head>")
+    request.writeText("<title>" + title + "</title>")
+    request.writeText("<meta name='viewport' content='width=device-width, initial-scale=1.0'>")
+    request.writeText("<meta name='theme-color' content='#ecc45e'>")
+    request.writeText("<link rel='preload' href='/assets/FireflyMono.ttf' as='font' crossorigin='anonymous'>")
+    request.writeText("<link rel='preload' href='/assets/FireflySans.ttf' as='font' crossorigin='anonymous'>")
+    request.writeText("<link rel='preload' href='/assets/firefly-logo-yellow.png' as='image'>")
+    request.writeText("<style>@font-face { font-family: 'Firefly Mono'; font-display: fallback; src: url('/assets/FireflyMono.ttf'); unicode-range: U+000-5FF; }</style>")
+    request.writeText("<style>@font-face { font-family: 'Firefly Sans'; font-display: fallback; src: url('/assets/FireflySans.ttf'); unicode-range: U+000-5FF; }</style>")
+    request.writeText("</head>")
+    request.writeText("<body style='margin: 0; padding: 0; width: 100%; height: 100%; touch-action: manipulation;'>")
+    request.writeText("<div id='main'></div>")
+    request.writeText("<script type='module' src='/js/ff/fireflysite/Main.mjs'></script>")
+    request.writeText("</body>")
+    request.writeText("</html>")
+}

package/fireflysite/MatchingPasswordsDemo.ff

@@ -0,0 +1,82 @@
+import Guide
+import Lux from ff:lux
+import LuxEvent from ff:lux
+
+name = "Matching passwords"
+
+new(): Demo {
+    Demo(
+        name
+        {render(_)}
+    )
+}
+
+render(lux: Lux): Unit {
+    function passwordInput(password: String, setPassword: String => Unit) {
+        lux.div {
+            lux.input {
+                lux.set("type", "password")
+                lux.set("autocomplete", "new-password")
+                lux.setValue(password)
+                lux.onInput {event =>
+                    setPassword(event.text())
+                }
+            }
+        }
+    }
+    lux.form {
+        lux.useState(""): password1, setPassword1 => 
+        lux.useState(""): password2, setPassword2 => 
+        passwordInput(password1, setPassword1)
+        passwordInput(password2, setPassword2)
+        lux.div {
+            if(password1 != password2) {
+                lux.text("Passwords don't match!")
+            } elseIf {password2.size() != 0} {
+                lux.text("Passwords match!")
+            }
+        }
+    }
+}
+
+newDocument(): Document {
+    ReadyDocument([
+        Section(name, [
+            Paragraph([Text("Two passwords fields and a check that they match.")])
+        ])
+        Section("Demo", [
+            LuxDemo(name)
+        ])
+        Section("Code", [
+            CodeBlock("""
+                render(lux: Lux): Unit {
+                    function passwordInput(password: String, setPassword: String => Unit) {
+                        lux.div {
+                            lux.input {
+                                lux.set("type", "password")
+                                lux.set("autocomplete", "new-password")
+                                lux.setValue(password)
+                                lux.onInput {event =>
+                                    setPassword(event.text())
+                                }
+                            }
+                        }
+                    }
+                    lux.form {
+                        lux.useState(""): password1, setPassword1 => 
+                        lux.useState(""): password2, setPassword2 => 
+                        passwordInput(password1, setPassword1)
+                        passwordInput(password2, setPassword2)
+                        lux.div {
+                            if(password1 != password2) {
+                                lux.text("Passwords don't match!")
+                            } elseIf {password2.size() != 0} {
+                                lux.text("Passwords match!")
+                            }
+                        }
+                    }
+                }
+            """, firefly = True)
+        ])
+    ])
+}

package/fireflysite/PackagesOverview.ff

@@ -0,0 +1,49 @@
+import Guide
+import CountingButtonDemo
+import MatchingPasswordsDemo
+
+new(): Document {
+    ReadyDocument([
+        Section("Packages", [
+            Paragraph([
+                Text("Here you'll eventually find the package index.")
+                Text("For now, here's a short list of essential packages.") 
+            ])
+        ])
+        Section("ff:core", [
+            Paragraph([
+                Text("The standard library of Firefly.")
+            ])
+        ])
+        Section("ff:webserver", [
+            Paragraph([
+                Text("A webserver package. Has HTTPS and WebSocket support.")
+            ])
+        ])
+        Section("ff:websocket", [
+            Paragraph([
+                Text("A package for making websocket connections.")
+            ])
+        ])
+        Section("ff:postgresql", [
+            Paragraph([
+                Text("A package for connecting to PostgreSQL. Has connection pool support.")
+            ])
+        ])
+        Section("ff:lux", [
+            Paragraph([
+                Text("A package for building interactive web interfaces.")
+            ])
+        ])
+        Section("ff:rpc", [
+            Paragraph([
+                Text("A package for type safe remote procedure calls.")
+            ])
+        ])
+        Section("ff:unsafejs", [
+            Paragraph([
+                Text("A FFI package for JavaScript.")
+            ])
+        ])
+    ])
+}

package/fireflysite/PostgresqlDemo.ff

@@ -0,0 +1,34 @@
+import Guide
+import Lux from ff:lux
+import LuxEvent from ff:lux
+
+name = "Connecting to PostgreSQL"
+
+newDocument(): Document {
+    ReadyDocument([
+        Section(name, [
+            Paragraph([Text("Connect to a PostgreSQL database and run a query.")])
+            Paragraph([Text("Add a dependency on "), Code("ff:postgresql"), Text(":")])
+            CodeBlock("""
+                dependency ff:postgresql:0.0.0
+            """, firefly = True)
+            Paragraph([Text("Import the"), Code("Pg"), Text("module from it:")])
+            CodeBlock("""
+                import Pg from ff:postgresql
+            """, firefly = True)
+            Paragraph([Text("Create a connection pool with the appropriate connection parameters:")])
+            CodeBlock("""
+                let pool = Pg.newPool(...)
+            """, firefly = True)
+            Paragraph([Text("And run your first transaction, e.g.:")])
+            CodeBlock("""
+                pool.transaction {connection =>
+                    let emails = connection.statement("select email from users")
+                        .map {row => row.getString("email").grab()}
+                    Log.debug(emails)
+                }
+            """, firefly = True)
+            Paragraph([Text("Note that"), Code(".map", firefly = True), Text("here runs for each row of the result.")])
+        ])
+    ])
+}