diff options
Diffstat (limited to 'docs/book/ERRORS.html')
| -rw-r--r-- | docs/book/ERRORS.html | 304 |
1 files changed, 304 insertions, 0 deletions
diff --git a/docs/book/ERRORS.html b/docs/book/ERRORS.html new file mode 100644 index 0000000..1e4d27a --- /dev/null +++ b/docs/book/ERRORS.html @@ -0,0 +1,304 @@ +<!DOCTYPE HTML> +<html lang="en" class="light" dir="ltr"> + <head> + <!-- Book generated using mdBook --> + <meta charset="UTF-8"> + <title>Error Handling - 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"><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" class="active"><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="error-handling"><a class="header" href="#error-handling">Error Handling</a></h1> +<p>Puck's error handling is shamelessly stolen from Swift. It uses a combination of <code>Option</code>/<code>Result</code> types and <code>try</code>/<code>catch</code> statements, and leans somewhat on Puck's metaprogramming capabilities.</p> +<p>There are several ways to handle errors in Puck. If the error is encoded in the type, one can:</p> +<ol> +<li><code>match</code> on the error</li> +<li>compactly match on the error with <code>if ... of</code></li> +<li>propagate the error with <code>?</code></li> +<li>throw the error with <code>!</code></li> +</ol> +<p>If an error is thrown, one <strong>must</strong> explicitly handle (or disregard) it with a <code>try/catch</code> block or risk runtime failure. This method of error handling may feel more familiar to Java programmers.</p> +<h2 id="errors-as-monads"><a class="header" href="#errors-as-monads">Errors as Monads</a></h2> +<p>Puck provides <a href="std/default/options.pk"><code>Option[T]</code></a> and a <a href="std/default/results.pk"><code>Result[T, E]</code></a> types, imported by default. These are <code>union</code> types and so must be pattern matched upon to be useful: but the standard library provides <a href="std/default/results.pk">a bevy of helper functions</a>. +Two in particular are of note. The <code>?</code> operator unwraps a Result or propagates its error up a function call (and may only be used in type-appropriate contexts). The <code>!</code> operator unwraps an Option or Result directly or throws an exception in the case of None or Error.</p> +<pre><code class="language-puck">pub macro `?`[T, E](self: Result[T, E]) = + quote: + match `self` + of Okay(x): x + of Error(e): return Error(e) +</code></pre> +<pre><code class="language-puck">pub func `!`[T](self: Option[T]): T = + match self + of Some(x): x + of None: raise EmptyValue + +pub func `!`[T, E](self: Result[T, E]): T = + of Okay(x): x + of Error(e): raise e +</code></pre> +<p>The utility of the provided helpers in <a href="std/default/options.pk"><code>std.options</code></a> and <a href="std/default/results.pk"><code>std.results</code></a> should not be understated. While encoding errors into the type system may appear restrictive at first glance, some syntactic sugar goes a long way in writing compact and idiomatic code. Java programmers in particular are urged to give type-first errors a try, before falling back on unwraps and <code>try</code>/<code>catch</code>.</p> +<p>A notable helpful type is the aliasing of <code>Result[T]</code> to <code>Result[T, ref Err]</code>, for when the particular error does not matter. This breaks <code>try</code>/<code>catch</code> exhaustion (as <code>ref Err</code> denotes a reference to <em>any</em> Error), but is particularly useful when used in conjunction with the propagation operator.</p> +<h2 id="errors-as-catchable-exceptions"><a class="header" href="#errors-as-catchable-exceptions">Errors as Catchable Exceptions</a></h2> +<p>Errors raised by <code>raise</code>/<code>throw</code> (or subsequently the <code>!</code> operator) must be explicitly caught and handled via a <code>try</code>/<code>catch</code>/<code>finally</code> statement. +If an exception is not handled within a function body, the function must be explicitly marked as a throwing function via the <code>yeet</code> prefix (name to be determined). The compiler will statically determine which exceptions in particular are thrown from any given function, and enforce them to be explicitly handled or explicitly ignored.</p> +<p>Despite functioning here as exceptions: errors remain types. An error thrown from an unwrapped <code>Result[T, E]</code> is of type <code>E</code>. <code>catch</code> statements, then, may pattern match upon possible errors, behaving similarly to <code>of</code> branches.</p> +<pre><code class="language-puck">try: + ... +catch "Error": + ... +finally: + ... +</code></pre> +<p>This creates a distinction between two types of error handling, working in sync: functional error handling with <a href="https://en.wikipedia.org/wiki/Option_type">Option</a> and <a href="https://en.wikipedia.org/wiki/Result_type">Result</a> types, and object-oriented error handling with <a href="https://en.wikipedia.org/wiki/Exception_handling">catchable exceptions</a>. These styles may be swapped between with minimal syntactic overhead. Libraries, however, should universally use <code>Option</code>/<code>Result</code>, as this provides the best support for both styles.</p> +<!-- [nullable types](https://en.wikipedia.org/wiki/Nullable_type)?? --> +<h2 id="errors-and-void-functions"><a class="header" href="#errors-and-void-functions">Errors and Void Functions</a></h2> +<p>Some functions do not return a value but can still fail: for example, setters. +This can make it difficult to do monadic error handling elegantly: one could return a <code>Result[void, E]</code>, but...</p> +<pre><code class="language-puck">pub func set[T](self: list[T], i: uint, val: T) = + if i > self.length: + raise IndexOutOfBounds + self.data.raw_set(offset = i, val) +</code></pre> +<h2 id="unrecoverable-exceptions"><a class="header" href="#unrecoverable-exceptions">Unrecoverable Exceptions</a></h2> +<p>There exist errors from which a program can not reasonably recover. These are the following:</p> +<ul> +<li><code>Assertation Failure</code>: a call to an <code>assert</code> function has returned false at runtime.</li> +<li><code>Out of Memory</code>: the executable is out of memory.</li> +<li><code>Stack Overflow</code>: the executable has overflowed the stack.</li> +<li>any others?</li> +</ul> +<p>They are not recoverable, but the user should be aware of them as possible failure conditions.</p> +<p>References: <a href="https://docs.swift.org/swift-book/documentation/the-swift-programming-language/errorhandling">Error Handling in Swift</a></p> + + </main> + + <nav class="nav-wrapper" aria-label="Page navigation"> + <!-- Mobile navigation buttons --> + <a rel="prev" href="MODULES.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="ASYNC.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="MODULES.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="ASYNC.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> |