diff options
Diffstat (limited to 'docs/book/index.html')
| -rw-r--r-- | docs/book/index.html | 340 |
1 files changed, 340 insertions, 0 deletions
diff --git a/docs/book/index.html b/docs/book/index.html new file mode 100644 index 0000000..02df44f --- /dev/null +++ b/docs/book/index.html @@ -0,0 +1,340 @@ +<!DOCTYPE HTML> +<html lang="en" class="light" dir="ltr"> + <head> + <!-- Book generated using mdBook --> + <meta charset="UTF-8"> + <title>The Puck Programming Language</title> + + + <!-- Custom HTML head --> + + <meta name="description" content=""> + <meta name="viewport" content="width=device-width, initial-scale=1"> + <meta name="theme-color" content="#ffffff"> + + <link rel="icon" href="book/favicon.svg"> + <link rel="shortcut icon" href="book/favicon.png"> + <link rel="stylesheet" href="book/css/variables.css"> + <link rel="stylesheet" href="book/css/general.css"> + <link rel="stylesheet" href="book/css/chrome.css"> + <link rel="stylesheet" href="book/css/print.css" media="print"> + + <!-- Fonts --> + <link rel="stylesheet" href="book/FontAwesome/css/font-awesome.css"> + <link rel="stylesheet" href="book/fonts/fonts.css"> + + <!-- Highlight.js Stylesheets --> + <link rel="stylesheet" href="book/highlight.css"> + <link rel="stylesheet" href="book/tomorrow-night.css"> + <link rel="stylesheet" href="book/ayu-highlight.css"> + + <!-- Custom theme stylesheets --> + + </head> + <body class="sidebar-visible no-js"> + <div id="body-container"> + <!-- Provide site root to javascript --> + <script> + var path_to_root = ""; + var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light"; + </script> + + <!-- Work around some values being stored in localStorage wrapped in quotes --> + <script> + try { + var theme = localStorage.getItem('mdbook-theme'); + var sidebar = localStorage.getItem('mdbook-sidebar'); + + if (theme.startsWith('"') && theme.endsWith('"')) { + localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1)); + } + + if (sidebar.startsWith('"') && sidebar.endsWith('"')) { + localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1)); + } + } catch (e) { } + </script> + + <!-- Set the theme before any content is loaded, prevents flash --> + <script> + var theme; + try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { } + if (theme === null || theme === undefined) { theme = default_theme; } + var html = document.querySelector('html'); + html.classList.remove('light') + html.classList.add(theme); + var body = document.querySelector('body'); + body.classList.remove('no-js') + body.classList.add('js'); + </script> + + <input type="checkbox" id="sidebar-toggle-anchor" class="hidden"> + + <!-- Hide / unhide sidebar before it is displayed --> + <script> + var body = document.querySelector('body'); + var sidebar = null; + var sidebar_toggle = document.getElementById("sidebar-toggle-anchor"); + if (document.body.clientWidth >= 1080) { + try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { } + sidebar = sidebar || 'visible'; + } else { + sidebar = 'hidden'; + } + sidebar_toggle.checked = sidebar === 'visible'; + body.classList.remove('sidebar-visible'); + body.classList.add("sidebar-" + sidebar); + </script> + + <nav id="sidebar" class="sidebar" aria-label="Table of contents"> + <div class="sidebar-scrollbox"> + <ol class="chapter"><li class="chapter-item expanded affix "><a href="index.html" class="active">The Puck Programming Language</a></li><li class="chapter-item expanded "><a href="book/OVERVIEW.html"><strong aria-hidden="true">1.</strong> Basic Usage</a></li><li><ol class="section"><li class="chapter-item expanded "><div><strong aria-hidden="true">1.1.</strong> Variables and Comments</div></li><li class="chapter-item expanded "><div><strong aria-hidden="true">1.2.</strong> Basic Types</div></li><li class="chapter-item expanded "><div><strong aria-hidden="true">1.3.</strong> Functions and Calls</div></li><li class="chapter-item expanded "><div><strong aria-hidden="true">1.4.</strong> Boolean and Integer Operations</div></li><li class="chapter-item expanded "><div><strong aria-hidden="true">1.5.</strong> Conditionals and Control Flow</div></li><li class="chapter-item expanded "><div><strong aria-hidden="true">1.6.</strong> Error Handling</div></li><li class="chapter-item expanded "><div><strong aria-hidden="true">1.7.</strong> Loops and Iterators</div></li><li class="chapter-item expanded "><div><strong aria-hidden="true">1.8.</strong> Modules</div></li><li class="chapter-item expanded "><div><strong aria-hidden="true">1.9.</strong> Compile-time Programming</div></li><li class="chapter-item expanded "><div><strong aria-hidden="true">1.10.</strong> Async and Threading</div></li><li class="chapter-item expanded "><div><strong aria-hidden="true">1.11.</strong> Advanced Types</div></li></ol></li><li class="chapter-item expanded "><a href="book/SYNTAX.html"><strong aria-hidden="true">2.</strong> Syntax</a></li><li><ol class="section"><li class="chapter-item expanded "><div><strong aria-hidden="true">2.1.</strong> Indentation Rules [todo]</div></li><li class="chapter-item expanded "><div><strong aria-hidden="true">2.2.</strong> Reserved Keywords</div></li><li class="chapter-item expanded "><div><strong aria-hidden="true">2.3.</strong> A Formal Grammar</div></li></ol></li><li class="chapter-item expanded "><a href="book/TYPES.html"><strong aria-hidden="true">3.</strong> Type System</a></li><li><ol class="section"><li class="chapter-item expanded "><div><strong aria-hidden="true">3.1.</strong> Basic Types</div></li><li class="chapter-item expanded "><div><strong aria-hidden="true">3.2.</strong> Parameter Types</div></li><li class="chapter-item expanded "><div><strong aria-hidden="true">3.3.</strong> Reference Types</div></li><li class="chapter-item expanded "><div><strong aria-hidden="true">3.4.</strong> Abstract Types</div></li><li class="chapter-item expanded "><div><strong aria-hidden="true">3.5.</strong> Advanced Types</div></li></ol></li><li class="chapter-item expanded "><a href="book/MODULES.html"><strong aria-hidden="true">4.</strong> Module System</a></li><li><ol class="section"><li class="chapter-item expanded "><div><strong aria-hidden="true">4.1.</strong> Using Modules</div></li><li class="chapter-item expanded "><div><strong aria-hidden="true">4.2.</strong> Implicit Modules</div></li><li class="chapter-item expanded "><div><strong aria-hidden="true">4.3.</strong> Defining Module Interfaces [todo]</div></li><li class="chapter-item expanded "><div><strong aria-hidden="true">4.4.</strong> Defining an External API [todo]</div></li></ol></li><li class="chapter-item expanded "><a href="book/ERRORS.html"><strong aria-hidden="true">5.</strong> Error Handling</a></li><li><ol class="section"><li class="chapter-item expanded "><div><strong aria-hidden="true">5.1.</strong> Errors as Monads</div></li><li class="chapter-item expanded "><div><strong aria-hidden="true">5.2.</strong> Errors as Catchable Exceptions</div></li><li class="chapter-item expanded "><div><strong aria-hidden="true">5.3.</strong> Errors and Void Functions [todo]</div></li><li class="chapter-item expanded "><div><strong aria-hidden="true">5.4.</strong> Unrecoverable Exceptions</div></li></ol></li><li class="chapter-item expanded "><a href="book/ASYNC.html"><strong aria-hidden="true">6.</strong> Async System</a></li><li><ol class="section"><li class="chapter-item expanded "><div><strong aria-hidden="true">6.1.</strong> Threading [todo]</div></li></ol></li><li class="chapter-item expanded "><a href="book/METAPROGRAMMING.html"><strong aria-hidden="true">7.</strong> Metaprogramming</a></li><li class="chapter-item expanded "><div><strong aria-hidden="true">8.</strong> Memory Management [todo]</div></li><li><ol class="section"><li class="chapter-item expanded "><div><strong aria-hidden="true">8.1.</strong> Reference Counting Optimizations</div></li><li class="chapter-item expanded "><div><strong aria-hidden="true">8.2.</strong> Annotations and Ownership</div></li></ol></li><li class="chapter-item expanded "><a href="book/INTEROP.html"><strong aria-hidden="true">9.</strong> Language Interop [draft]</a></li><li><ol class="section"><li class="chapter-item expanded "><div><strong aria-hidden="true">9.1.</strong> Rust, Swift, Nim</div></li><li class="chapter-item expanded "><div><strong aria-hidden="true">9.2.</strong> Java, Kotlin</div></li><li class="chapter-item expanded "><div><strong aria-hidden="true">9.3.</strong> Python, Racket, C</div></li></ol></li><li class="chapter-item expanded "><div><strong aria-hidden="true">10.</strong> Refinement Types [draft]</div></li><li class="chapter-item expanded "><div><strong aria-hidden="true">11.</strong> Dependent Types [draft]</div></li><li class="chapter-item expanded "><div><strong aria-hidden="true">12.</strong> Effects System [draft]</div></li></ol> + </div> + <div id="sidebar-resize-handle" class="sidebar-resize-handle"> + <div class="sidebar-resize-indicator"></div> + </div> + </nav> + + <!-- Track and set sidebar scroll position --> + <script> + var sidebarScrollbox = document.querySelector('#sidebar .sidebar-scrollbox'); + sidebarScrollbox.addEventListener('click', function(e) { + if (e.target.tagName === 'A') { + sessionStorage.setItem('sidebar-scroll', sidebarScrollbox.scrollTop); + } + }, { passive: true }); + var sidebarScrollTop = sessionStorage.getItem('sidebar-scroll'); + sessionStorage.removeItem('sidebar-scroll'); + if (sidebarScrollTop) { + // preserve sidebar scroll position when navigating via links within sidebar + sidebarScrollbox.scrollTop = sidebarScrollTop; + } else { + // scroll sidebar to current active section when navigating via "next/previous chapter" buttons + var activeSection = document.querySelector('#sidebar .active'); + if (activeSection) { + activeSection.scrollIntoView({ block: 'center' }); + } + } + </script> + + <div id="page-wrapper" class="page-wrapper"> + + <div class="page"> + <div id="menu-bar-hover-placeholder"></div> + <div id="menu-bar" class="menu-bar sticky"> + <div class="left-buttons"> + <label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar"> + <i class="fa fa-bars"></i> + </label> + <button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list"> + <i class="fa fa-paint-brush"></i> + </button> + <ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu"> + <li role="none"><button role="menuitem" class="theme" id="light">Light</button></li> + <li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li> + <li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li> + <li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li> + <li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li> + </ul> + <button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar"> + <i class="fa fa-search"></i> + </button> + </div> + + <h1 class="menu-title">The Puck Programming Language</h1> + + <div class="right-buttons"> + <a href="book/print.html" title="Print this book" aria-label="Print this book"> + <i id="print-button" class="fa fa-print"></i> + </a> + + </div> + </div> + + <div id="search-wrapper" class="hidden"> + <form id="searchbar-outer" class="searchbar-outer"> + <input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header"> + </form> + <div id="searchresults-outer" class="searchresults-outer hidden"> + <div id="searchresults-header" class="searchresults-header"></div> + <ul id="searchresults"> + </ul> + </div> + </div> + + <!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM --> + <script> + document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible'); + document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible'); + Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) { + link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1); + }); + </script> + + <div id="content" class="content"> + <main> + <h1 id="-puck---an-experimental-programming-language"><a class="header" href="#-puck---an-experimental-programming-language"><span style="font-family: 'Noto Color Emoji'">🧚</span> Puck - A Programming Language</a></h1> +<p>A place where I can make some bad decisions.</p> +<p>Puck is an experimental, memory safe, structurally typed, interface-first, imperative programming language. +It aims to be clean and succinct while performant: inspired by the syntax and metaprogramming of <a href="https://nim-lang.org/">Nim</a>, the error handling of <a href="https://www.swift.org/">Swift</a>, the performance and safety guarantees of <a href="https://www.rust-lang.org/">Rust</a>, the async/await and comptime of <a href="https://ziglang.org/">Zig</a>, and the module system of <a href="https://ocaml.org/">OCaml</a>.</p> +<details> +<summary><b>Example: Interfaces</b></summary> +<pre><code class="language-nim"># Note: These declarations are adapted from the standard prelude. + +## The Result type. Represents either success or failure. +pub type Result[T, E] = union + Okay(T) + Error(E) + +## The Err interface. Useful for dynamically dispatching errors. +pub type Err = interface + str(Self): str + dbg(Self): str + +## A Result type that uses dynamically dispatched errors. +## The Error may be any type implementing Err. +pub type Result[T] = Result[T, ref Err] + +## Implements the dbg function for strings. +## As the str function is already defined for strings, +## this in turn means strings now implicitly implement Err. +pub func dbg(self: str) = "\"" & self & "\"" +</code></pre> +</details> +<details open> +<summary><b>Example: Pattern Matching</b></summary> +<pre><code class="language-nim">## Opens the std.tables module for unqualified use. +use std.tables + +pub type Value = string +pub type Ident = string +pub type Expr = ref union + Literal(Value) + Variable(Ident) + Abstraction(param: Ident, body: Expr) + Application(body: Expr, arg: Expr) + Conditional(condition: Expr, + then_branch: Expr, else_branch: Expr) + +## Evaluate an Expr down to a Value, or return an Error. +pub func eval(context: mut HashTable[Ident, Value], expr: Expr): Result[Value] + match expr + of Literal(value): Okay(value) + of Variable(ident): + context.get(ident) + .err("Could not find variable {} in context!".fmt(ident)) + of Application(body, arg): + if body of Abstraction(param, body as inner_body): + context.set(param, context.clone.eval(arg)?) + context.eval(inner_body) + else: + Error("Expected Abstraction, found body {} and argument {}".fmt(body, arg)) + of Conditional(condition, then_branch, else_branch): + if context.clone.eval(condition)? == "true": + context.eval(then_case) + else: + context.eval(else_case) + of _: Error("Invalid expression {}".fmt(expr)) +</code></pre> +</details> +<details> +<summary><b>Example: Modules</b></summary> +<pre><code class="language-nim">... +</code></pre> +</details> +<h2 id="why-puck"><a class="header" href="#why-puck">Why Puck?</a></h2> +<p>Puck is primarily a testing ground and should not be used in any important capacity. +Don't use it. Everything is unimplemented and it will break underneath your feet.</p> +<p>That said: in the future, once somewhat stabilized, reasons why you <em>would</em> use it would be for:</p> +<ul> +<li>The <strong>syntax</strong>, aiming to be flexible, predictable, and succinct, through the use of <em>uniform function call syntax</em> and significant whitespace</li> +<li>The <strong>type system</strong>, being modern and powerful with a strong emphasis on safety, optional and result types, algebraic data types, interfaces, and modules</li> +<li>The <strong>memory management system</strong>, implementing a model of strict ownership while allowing individual fallbacks to reference counts if so desired</li> +<li>The <strong>metaprogramming</strong>, providing integrated macros capable of rewriting the abstract syntax tree before or after typechecking</li> +<li>The <strong>interop system</strong>, allowing foreign functions to be usable with native semantics from a bevy of languages</li> +</ul> +<p>This is the language I keep in my head. It sprung from a series of unstructured notes I kept on language design, that finally became something more comprehensive in early 2023. The overarching goal is to provide a language capable of elegantly expressing any problem, and explore ownership and interop along the way.</p> +<h2 id="how-do-i-learn-more"><a class="header" href="#how-do-i-learn-more">How do I learn more?</a></h2> +<ul> +<li>The <a href="book/BASIC.html">basic usage</a> document lays out the fundamental semantics of Puck.</li> +<li>The <a href="book/SYNTAX.html">syntax</a> document provides a deeper and formal look into the grammar of Puck.</li> +<li>The <a href="book/TYPES.html">type system</a> document gives an in-depth analysis of Puck's extensive type system. <!-- and its relationship to classes and other abstractions. --></li> +<li>The <a href="book/MODULES.html">modules</a> document provides a more detailed look at the first-class module system.</li> +<li>The <a href="book/MEMORY_MANAGEMENT.html">memory management</a> document gives an overview of Puck's memory model. <!-- which is considered a mashup of the models pioneered by Lobster, Rust, and Nim. --></li> +<li>The <a href="book/METAPROGRAMMING.html">metaprogramming</a> document explains how using metaprogramming to extend the language works. <!-- and write more powerful code works. --></li> +<li>The <a href="book/ASYNC.html">asynchronous</a> document gives an overview of Puck's colourless asynchronous support.</li> +<li>The <a href="book/INTEROP.html">interop</a> document gives an overview of how the first-class language interop system works.</li> +<li>The <a href="book/STDLIB.html">standard library</a> document provides an overview and examples of usage of the standard library.</li> +<li>The <a href="book/ROADMAP.html">roadmap</a> provides a clear view of the current state and future plans of the language's development.</li> +</ul> +<p>These are best read in order.</p> +<p>Note that all of these documents (and parts of this README) are written as if everything already exists. Nothing already exists! You can see the <a href="book/ROADMAP.html">roadmap</a> for an actual sense as to the state of the language. I simply found writing in the present tense to be an easier way to collect my thoughts.</p> +<p>This language does not currently integrate ideas from the following areas of active research: effects systems, refinement types, and dependent types. It plans to integrate refinement types in the future as a basis for <code>range[]</code> types, and to explore safety and optimizations surrounding integer overflow.</p> +<h2 id="primary-references"><a class="header" href="#primary-references">Primary References</a></h2> +<ul> +<li><a href="https://graydon2.dreamwidth.org/307291.html">The Rust I wanted had no future</a></li> +<li><a href="https://boats.gitlab.io/blog/post/notes-on-a-smaller-rust/">Notes on a smaller Rust</a></li> +<li><a href="https://matklad.github.io/2023/01/25/next-rust-compiler.html">Notes on the next Rust compiler</a></li> +</ul> + + </main> + + <nav class="nav-wrapper" aria-label="Page navigation"> + <!-- Mobile navigation buttons --> + + <a rel="next prefetch" href="book/OVERVIEW.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right"> + <i class="fa fa-angle-right"></i> + </a> + + <div style="clear: both"></div> + </nav> + </div> + </div> + + <nav class="nav-wide-wrapper" aria-label="Page navigation"> + + <a rel="next prefetch" href="book/OVERVIEW.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right"> + <i class="fa fa-angle-right"></i> + </a> + </nav> + + </div> + + <!-- Livereload script (if served using the cli tool) --> + <script> + const wsProtocol = location.protocol === 'https:' ? 'wss:' : 'ws:'; + const wsAddress = wsProtocol + "//" + location.host + "/" + "__livereload"; + const socket = new WebSocket(wsAddress); + socket.onmessage = function (event) { + if (event.data === "reload") { + socket.close(); + location.reload(); + } + }; + + window.onbeforeunload = function() { + socket.close(); + } + </script> + + + + <script> + window.playground_copyable = true; + </script> + + + <script src="book/elasticlunr.min.js"></script> + <script src="book/mark.min.js"></script> + <script src="book/searcher.js"></script> + + <script src="book/clipboard.min.js"></script> + <script src="book/highlight.js"></script> + <script src="book/book.js"></script> + + <!-- Custom JS scripts --> + + + </div> + </body> +</html> |