diff options
Diffstat (limited to 'docs/book/index.html')
| -rw-r--r-- | docs/book/index.html | 340 |
1 files changed, 0 insertions, 340 deletions
diff --git a/docs/book/index.html b/docs/book/index.html deleted file mode 100644 index 02df44f..0000000 --- a/docs/book/index.html +++ /dev/null @@ -1,340 +0,0 @@ -<!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> |