firefly-compiler 0.4.79 → 0.4.80

package/fireflysite/FrontPage.ff

@@ -1,360 +1,344 @@
-import Guide
-import CountingButtonDemo
-import MatchingPasswordsDemo
-
-new(): Document {
-    ReadyDocument([
-        /*Section("Is DX an add-on feature?", [
-            Paragraph([
-                Bold("We don't think so.")
-                Text("Firefly is designed from the ground up as a full stack language with great developer experience.")
-            ])
-            Image("/assets/autocomplete.png")
-            Paragraph([
-                Italic("Firefly in VSCode, showcasing instant type driven autocompletion and edit time error detection.")
-                Italic("An example of DX that's only possible for a certain class of languages. Read on for more Firefly DX.")
-            ])
-        ])*/
-        Section("The full stack programming language", [
-            Paragraph([
-                Text("Firefly doesn't just run in the browser and on the server,")
-                Text("it comes with a complete stack that allows you to implement full webapps.")
-                Text("Everything in the stack is designed to fit together nicely, all with excellent IDE support.")
-                Text("It's really easy to ")
-                Link("get started", "/guide/")
-                Text("and there's no magic.")
-            ])
-        ])
-        SplitSection(
-            "Single file webapps"
-            Paragraph([
-                Text("Firefly code runs in the browser and on the server, or even at build time.")
-                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 or packages.")
-            ])
-            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)
-        )
-        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 Tree[T] {
-                    Leaf(value: T)
-                    Branch(left: Tree[T], right: Tree[T])
-                }
-            """, 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(
-            "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(inlines) => 
-                        renderParagraph(inlines)
-                    | Code(code, Some(language)) => 
-                        renderHighlighted(code, language)
-                    | Code(code, None) => 
-                        renderCode(code)
-                    | Video(url) {vimeoId(url) | Some(id)} => 
-                        renderVimeo(id)
-                    | Video(url) => 
-                        renderVideo(url)
-                }
-            """, 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/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/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.")
-                ]
-            ])
-        ])
-    ])
-}
+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.")
+                ]
+            ])
+        ])
+    ])
+}