aboutsummaryrefslogtreecommitdiff
path: root/docs/book/index.html
diff options
context:
space:
mode:
Diffstat (limited to 'docs/book/index.html')
-rw-r--r--docs/book/index.html340
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) = &quot;\&quot;&quot; &amp; self &amp; &quot;\&quot;&quot;
+</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(&quot;Could not find variable {} in context!&quot;.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(&quot;Expected Abstraction, found body {} and argument {}&quot;.fmt(body, arg))
+ of Conditional(condition, then_branch, else_branch):
+ if context.clone.eval(condition)? == &quot;true&quot;:
+ context.eval(then_case)
+ else:
+ context.eval(else_case)
+ of _: Error(&quot;Invalid expression {}&quot;.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>