firefly-compiler 0.4.78 → 0.4.80

package/fireflysite/FrontPage.ff

@@ -0,0 +1,344 @@
+import Guide
+import CountingButtonDemo
+import MatchingPasswordsDemo
+
+new(): Document {
+    ReadyDocument([
+        Section("The full-stack programming language", [
+            Paragraph([
+                Text("Firefly code runs in the browser and on the server, or even at build time. ")
+                Text("You can implement highly interactive webapps without resorting to JavaScript. ")
+                Text("The basic skeleton of a webapp looks like this: ")
+            ])
+            CodeBlock("""
+                dependency ff:webserver:0.0.0
+            
+                // Runs on the server
+                nodeMain(system: NodeSystem) {...}
+                    
+                // Runs in the browser
+                browserMain(system: BrowserSystem) {...}
+                
+                // Runs at build time
+                buildMain(system: BuildSystem) {...}
+            """, firefly = True)
+            Paragraph([
+                Text("When starting out, you can put everything in a single ")
+                Code(".ff")
+                Text(" file, including your dependency list. ")
+                Text("As the code base grows, you can split it into multiple files and packages. ")
+                Text("Read on for a tour of the language. ")
+            ])
+        ])
+        SplitSection(
+            "Concise type definitions"
+            Paragraph([
+                Text("Model your types in a brief format that fits multiple definitions on one screen.")
+                Text("Be precise about whether things can be missing with")
+                Code("Option[T]", firefly = True)
+                Text("and make invalid states unrepresentable with variants and type parameters.")
+            ])
+            CodeBlock("""
+                data User(
+                    id: UserId
+                    name: String
+                    email: Option[String]
+                )
+                
+                data BlockElement {
+                    Paragraph(text: String)
+                    Code(code: String, type: Option[String])
+                    Video(url: String)
+                }
+            """, firefly = True)
+        )
+        SplitSection(
+            "Deep pattern matching"
+            Paragraph([
+                Text("You can directly pattern match on function arguments, even in lambda functions.")
+                Text("The compiler checks for exhaustiveness, ensuring that all possible cases are covered.")
+                Text("Pattern guards are supported, so you can extract things with arbitrary logic.")
+            ])
+            CodeBlock("""
+                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)
+                }
+            """, firefly = True)
+        )
+        SplitSection(
+            "Convenient collections"
+            Paragraph([
+                Text("Immutable and mutable collections are part of the standard library.")
+                Text("Maps, sets, arrays, lists and streams come with a rich set of methods that you can use to write code that's instantly clear to the reader.")
+            ])
+            CodeBlock("""
+                let emails = houses
+                    .flatMap {_.owners}
+                    .map {_.email}
+                    .filter {!_.endsWith("example.com")}
+                    .toSet()
+                    
+                emails.each {email =>
+                    sendNeighborhoodNewsletter(email)
+                }
+            """, firefly = True)
+        )
+        SplitSection(
+            "Edit time error detection"
+            Paragraph([
+                Text("In Firefly, a large class of errors is detected by the IDE as you type.")
+                Text("You can usually fix these without even reading the error message.")
+                Text("And when you need to read the error messages, they're short and to the point.")
+            ])
+            Image("/assets/image/edit-time-error.png")
+        )
+        SplitSection(
+            "Type driven autocompletion"
+            Paragraph([
+                Text("The language server comes with type driven autocompletion.")
+                Text("It instantly presents a very precise list of completions, and the expected type is used to preselect a likely completion.")
+            ])
+            Image("/assets/image/autocomplete-small.png")
+        )
+        SplitSection(
+            "No async dilemma"
+            Paragraph([
+                Text("In Firefly, there's no")
+                Code("async")
+                Text("or")
+                Code("await")
+                Text("syntax.")
+                Text("Instead, the compiler infers which calls are asynchronous and automatically generates the appropriate code.")
+                Text("A method like")
+                Code(".map")
+                Text("on lists is called asynchronously only when the lambda function you pass is asynchronous.")
+            ])
+            CodeBlock("""
+                let files = ["a.txt", "b.txt"]
+                // async .map call
+                let contents = files.map {file =>
+                    system.path(file).readText()
+                }
+                // sync .map call
+                let upper = contents.map {content =>
+                    content.upper()
+                }
+            """, firefly = True)
+        )
+        SplitSection(
+            "No hidden I/O"
+            Paragraph([
+                Text("The main function is passed a")
+                Code("system")
+                Text("argument that represents all the I/O you can do.")
+                Text("It's a plain object, and you can simply wrap it to create a new")
+                Text("object with less capabilities. You can tell what effects a top level function")
+                Text("can have simply by looking at what arguments it receives.")
+            ])
+            CodeBlock("""
+                nodeMain(system: NodeSytem) {
+                    let html = fetchSite(system.httpClient())
+                    system.writeLine(html)
+                }
+
+                // this function can only do HTTP requests
+                fetchSite(httpClient: HttpClient): String {
+                    let url = "https://www.example.com/"
+                    httpClient.get(url, []) {_.readText()}
+                }
+            """, firefly = True)
+        )
+        SplitSection(
+            "Structural equality"
+            Paragraph([
+                Text("Traits are used for equality, ordering etc., and the core traits are automatically implemented for")
+                Code("data")
+                Text("types if you don't supply your own implementation.")
+                Text("They make")
+                Code("==")
+                Text("and")
+                Code("<")
+                Text("type safe, unlike in most languages, and")
+                Text("they're a lot simpler than the traits you find in Rust.")
+            ])
+            CodeBlock("""
+                trait T: Order {
+                    compare(x: T, y: T): Ordering
+                }
+                    
+                instance Bool: Order {
+                    compare(x: Bool, y: Bool): Ordering {
+                        | False, True => OrderingBefore
+                        | True, False => OrderingAfter
+                        | _, _ => OrderingSame
+                    }
+                }
+            """, firefly = True)
+        )
+        /*
+        SplitSection(
+            "Batteries included"
+            Paragraph([
+                Text("The standard library contains functionality that's required by most applications.")
+                Text("Apart from what you've seen above, there's also the following modules.")
+            ])
+            Bullets([
+                [Bold("Random:"), Text("Pseudorandom numbers")]
+                [Bold("Instant:"), Text("UTC timestamps")]
+                [Bold("Json:"), Text("JSON support")]
+                [Bold("Buffer:"), Text("Binary data")]
+                [Bold("Stream:"), Text("Streams (sync or async)")]
+                [Bold("Task:"), Text("Structured concurrency")]
+                [Bold("Log:"), Text("Simple logging")]
+            ])
+        )
+        */
+        Section("The Firefly Stack", [
+            Paragraph([
+                Bold("The Firefly Stack is a set of packages for building webapps.")
+                Text("The packages are maintained by the developers of Firefly.")
+                Text("You can use them individually or together.")
+                Italic("Here's what you can do with that.")
+            ])
+        ])
+        SplitSection(
+            "Interactive webapps"
+            Paragraph([
+                Text("The")
+                Code("ff:lux")
+                Text("package provides a declarative DOM framework for building highly interactive webapps.")
+                Text("Tasks that belong to removed nodes are automatically cancelled.")
+                Text("All without any virtual DOM.")
+            ])
+            CodeBlock("""
+                lux.useState(0): count, setCount => 
+                lux.button {
+                    lux.text("Clicked " + count + " times")
+                    lux.onClick {event =>
+                        event.preventDefault()
+                        setCount(count + 1)
+                    }
+                }
+            """, firefly = True)
+        )
+        SplitSection(
+            "Type safe RPC"
+            Paragraph([
+                Text("All your custom")
+                Code("data")
+                Text("types are automatically serializable in Firefly.")
+                Text("With ")
+                Code("ff:rpc")
+                Text("you can set up type safe remote procedure calls from the browser to the webserver or between services.")
+                Text("You can even")
+                Italic("go to definition")
+                Text("across RPC boundaries.")
+            ])
+            CodeBlock("""
+                data Message(text: String)
+                instance Message: Rpc[Int]
+
+                // the browser sends a Message
+                let client = Rpc.newClient(...)
+                let messageId = client.call(Message("Hello"))
+
+                // the webserver replies with an Int
+                let server = Rpc.newServer(...)
+                server.add {| context, Message(text) => 42 }
+            """, firefly = True)
+        )
+        SplitSection(
+            "WebSocket server & client"
+            Paragraph([
+                Text("The ")
+                Code("ff:webserver")
+                Text("package comes with WebSocket support.")
+                Text("In just a few lines of code, you can start serving WebSockets.")
+                Text("The ")
+                Code("ff:websocket")
+                Text("package allows you to connect to any WebSocket server.")
+                Text("If both ends are running Firefly, you can use the built-in binary serialization.")
+            ])
+            CodeBlock("""
+                let server = WebServer.new(system, host, port)
+                server.enableWebSockets()
+                
+                server.listen {request =>
+                    let ws = request.openWebSocket()
+                    ws.subscribe("chat")
+                    while {True} {
+                        let message = ws.readText().grab()
+                        ws.publishText("chat", message)
+                    }
+                }
+            """.replace("'''", "\"\"\""), firefly = True)
+        )
+        SplitSection(
+            "Database pooling"
+            Paragraph([
+                Text("The")
+                Code("ff:postgresql")
+                Text("package lets you create a connection pool for a PostgreSQL database.")
+                Text("You can then execute transactions and build stateful applications.")
+            ])
+            CodeBlock("""
+                let pool = Pg.newPool(...)
+                
+                let emails = pool.transaction {connection =>
+                    connection
+                        .statement('''
+                            select email from users
+                            where id <= $maxId
+                        ''')
+                        .withInt("maxId", 100)
+                        .map {_.getString("email").grab()}
+                }
+            """.replace("'''", "\"\"\""), firefly = True)
+        )
+        Section("What Firefly doesn't have", [
+            Bullets([
+                [
+                    Bold("No function overloading.")
+                    Text("Overloading leads to uninformative \"No matching overload\" errors.")
+                ]
+                [
+                    Bold("No implicit casts.")
+                    Text("Ever recieved an email addressed to \"Dear None\"? Static types fail to prevent this if you can implicitly cast an Option[T] to a String.")
+                ]
+                [
+                    Bold("No dynamic typing.")
+                    Text("Dynamic typing causes runtime errors and encourages hidden and underspecified contracts that makes refactoring harder than it needs to be.")
+                ]
+                [
+                    Bold("No nulls.")
+                    Text("Eliminating null ensures types accurately represent known values, reducing runtime errors and redundant checks.")
+                ]
+                [
+                    Bold("No subtyping.")
+                    Text("Subtyping introduces complexity via type bounds and variance. It also allows mixing loosely related types, promoting incomplete runtime type checks.")
+                ]
+                [
+                    Bold("No inheritance.")
+                    Text("Inheritance can lead to overgeneralization and scattering of business logic, making it hard to get the full picture at any level.")
+                ]
+                [
+                    Bold("No macros.")
+                    Text("Macros let you define whole new languages, that are typically wildly undertooled compared to the base language.")
+                ]
+                [
+                    Bold("No type level programming.")
+                    Text("Type level programming leads to inscrutable function signatures and hard to understand error messages.")
+                ]
+            ])
+        ])
+    ])
+}

package/fireflysite/{GuideIntroduction.ff → GettingStarted.ff}

@@ -1,31 +1,7 @@
 import Guide
 
-mock(): List[Document] {
-    [
-        new()
-        Document([Section("Control flow", [])])
-        Document([Section("Base types", [])])
-        Document([Section("Collections", [])])
-        Document([Section("Custom types", [])])
-        Document([Section("Async I/O", [])])
-        Document([Section("Structured concurrency", [])])
-        Document([Section("Applications", [])])
-        Document([Section("Packages and modules", [])])
-        Document([Section("Functions and methods", [])])
-        Document([Section("Traits and instances", [])])
-        Document([Section("JavaScript interop", [])])
-    ]
-}
-
 new(): Document {
-    Document([
-        Section("Introduction", [
-            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.")
-            ])
-        ])
+    ReadyDocument([
         Section("Getting started", [
             Paragraph([
                 Text("Firefly comes with a compiler, a build system and a package manager.")