aboutsummaryrefslogtreecommitdiff
path: root/docs/book/MODULES.html
diff options
context:
space:
mode:
authorJJ2024-01-28 09:32:52 +0000
committerJJ2024-01-28 09:32:52 +0000
commit22c4776f9fddef47a6ce3f309e4eafa2fbdc3a65 (patch)
tree49101d75a3f980eb8f8560f464f816a6fb9c564a /docs/book/MODULES.html
parenta409dd7ea7d6d363d5ef971526b81d95e6add51d (diff)
docs: host mdbook
Diffstat (limited to 'docs/book/MODULES.html')
-rw-r--r--docs/book/MODULES.html264
1 files changed, 264 insertions, 0 deletions
diff --git a/docs/book/MODULES.html b/docs/book/MODULES.html
new file mode 100644
index 0000000..4ee1fe5
--- /dev/null
+++ b/docs/book/MODULES.html
@@ -0,0 +1,264 @@
+<!DOCTYPE HTML>
+<html lang="en" class="light" dir="ltr">
+ <head>
+ <!-- Book generated using mdBook -->
+ <meta charset="UTF-8">
+ <title>Module System - 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="favicon.svg">
+ <link rel="shortcut icon" href="favicon.png">
+ <link rel="stylesheet" href="css/variables.css">
+ <link rel="stylesheet" href="css/general.css">
+ <link rel="stylesheet" href="css/chrome.css">
+ <link rel="stylesheet" href="css/print.css" media="print">
+
+ <!-- Fonts -->
+ <link rel="stylesheet" href="FontAwesome/css/font-awesome.css">
+ <link rel="stylesheet" href="fonts/fonts.css">
+
+ <!-- Highlight.js Stylesheets -->
+ <link rel="stylesheet" href="highlight.css">
+ <link rel="stylesheet" href="tomorrow-night.css">
+ <link rel="stylesheet" href="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">The Puck Programming Language</a></li><li class="chapter-item expanded "><a href="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="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="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="MODULES.html" class="active"><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="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="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="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="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="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="modules-and-namespacing"><a class="header" href="#modules-and-namespacing">Modules and Namespacing</a></h1>
+<blockquote>
+<p>! This section is <strong>incomplete</strong>. Proceed with caution.</p>
+</blockquote>
+<p>Puck has a first-class module system, inspired by such expressive designs in the ML family.</p>
+<h2 id="using-modules"><a class="header" href="#using-modules">Using Modules</a></h2>
+<pre><code class="language-puck"></code></pre>
+<p>Modules package up code for use by others. Identifiers known at compile time may be part of a <em>module signature</em>: these being constants, functions, macros, types, and other modules themselves. They may be made accessible to external users by prefixing them with the <code>pub</code> keyword. Files are modules, named with their filename. The <code>mod</code> keyword followed by an identifier and an indented block of code explicitly defines a module, inside of the current module. Modules are first class: they may be bound to constants (having the type <code>: mod</code>) and publicly exported, or bound to local variables and passed into functions for who knows what purpose.</p>
+<p>The <code>use</code> keyword lets you use other modules. The <code>use</code> keyword imports public symbols from the specified module into the current scope <em>unqualified</em>. This runs contrary to expectations coming from most other languages: from Python to Standard ML, the standard notion of an &quot;import&quot; usually puts the imported symbols behind another symbol to avoid &quot;polluting the namespace&quot;. As Puck is strongly typed and allows overloading, however, the author sees no reason for namespace pollution to be of concern. These unqualified imports have the added benefit of making uniform function call syntax more widely accessible. It is inevitable that identifier conflicts will exist on occasion, of course: when this happens, the compiler will force qualification (this then does restrict uniform function call syntax).</p>
+<pre><code class="language-puck"></code></pre>
+<p>Nonetheless, if qualification of imports is so desired, an alternative approach is available - binding a module to a constant. Both the standard library and external libraries are available behind identifiers without use of <code>use</code>: <code>std</code> and <code>lib</code>, respectively. (FFI and local modules will likely use more identifiers, but this is not hammered out yet.) A submodule - for example, <code>std.net</code> - may be bound in a constant as <code>const net = std.net</code>, providing all of the modules' public identifiers for use, as fields of the constant <code>net</code>. We will see this construction to be extraordinarily helpful in crafting high-level public APIs for libraries later on.</p>
+<p>Multiple modules can be imported at once, i.e. <code>use std.[logs, tests]</code>, <code>use lib.crypto, lib.http</code>. The standard namespaces (<code>std</code>, <code>lib</code>) deserve more than a passing mention. There are several of these: <code>std</code> for the standard library, <code>lib</code> for all external libraries, <code>crate</code> for the top-level namespace of a project (subject to change), <code>this</code> for the current containing module (subject to change)... In addition: there are a suite of <em>language</em> namespaces, for FFI - <code>rust</code>, <code>nim</code>, and <code>swift</code> preliminarily - that give access to libraries from other languages. Recall that imports are unqualified - so <code>use std</code> will allow use of the standard library without the <code>std</code> qualifier (not recommended: several modules have common names), and <code>use lib</code> will dump every library it can find into the global namespace (even less recommended). </p>
+<h2 id="implicit-modules"><a class="header" href="#implicit-modules">Implicit Modules</a></h2>
+<p>A major goal of Puck's module system is to allow the same level of expressiveness as the ML family, while cutting down on the extraneous syntax and boilerplate needed to do so. As such, access modifiers are written directly inline with their declaration, and the file system structure is reused to form an implicit module system for internal use. This - particularly the former - <em>limits</em> the structure a module can expose at first glance, but we will see later that interfaces recoup much of this lost specificity.</p>
+<p>We mentioned that the filesystem forms an implicit module structure. This begets a couple of design choices. Module names <strong>must</strong> be lowercase, for compatibility with case-insensitive filesystems. Both a file and a folder with the same name can exist. Files within the aforementioned folder are treated as submodules of the aforementioned file. This again restricts the sorts of module structures we can build, but we will again see later that this restriction can be bypassed.</p>
+<p>The <code>this</code> and <code>crate</code> modules are useful for this implicit structure...</p>
+<h2 id="defining-interfaces"><a class="header" href="#defining-interfaces">Defining Interfaces</a></h2>
+<p>...</p>
+<h2 id="defining-an-external-api"><a class="header" href="#defining-an-external-api">Defining an External API</a></h2>
+<p>The filesystem provides an implicit module structure, but it may not be the one you want to expose to users.</p>
+<p>...</p>
+
+ </main>
+
+ <nav class="nav-wrapper" aria-label="Page navigation">
+ <!-- Mobile navigation buttons -->
+ <a rel="prev" href="TYPES.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
+ <i class="fa fa-angle-left"></i>
+ </a>
+
+ <a rel="next prefetch" href="ERRORS.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="prev" href="TYPES.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
+ <i class="fa fa-angle-left"></i>
+ </a>
+
+ <a rel="next prefetch" href="ERRORS.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="elasticlunr.min.js"></script>
+ <script src="mark.min.js"></script>
+ <script src="searcher.js"></script>
+
+ <script src="clipboard.min.js"></script>
+ <script src="highlight.js"></script>
+ <script src="book.js"></script>
+
+ <!-- Custom JS scripts -->
+
+
+ </div>
+ </body>
+</html>
generated by cgit v1.2.3-70-g09d2 (git 2.46.0) at 2024-11-21 23:27:51 +0000