class Failure | Raku Documentation

<!DOCTYPE html> <html lang="en" class="fontawesome-i2svg-active fontawesome-i2svg-complete" style="scroll-padding-top:60px"> <head> <title>class Failure | Raku Documentation</title> <meta charset="UTF-8" /> <link href="/assets/images/Camelia.ico" rel="icon" type="image/x-icon"/> <link rel="stylesheet" href="/assets/css/Website.css"/> <link rel="stylesheet" href="/assets/css/typegraph-styling.css"/> <link rel="stylesheet" href="/assets/css/typegraph-dark.css" title="dark"/> <link rel="stylesheet" href="/assets/css/typegraph-light.css" title="light"/> <link rel="stylesheet" href="/assets/css/css/filtered-toc-dark.css" title="dark"/> <link rel="stylesheet" href="/assets/css/css/filtered-toc-light.css" title="light"/> <link rel="stylesheet" href="/assets/css/css/announce-light.css" title="light"/> <link rel="stylesheet" href="/assets/css/css/announce-dark.css" title="dark"/> <link rel="stylesheet" href="/assets/css/all.min.css"/> <link rel="stylesheet" href="/assets/css/listf-styling-light.css" title="light"/> <link rel="stylesheet" href="/assets/css/listf-styling-dark.css" title="dark"/> <link rel="stylesheet" href="/assets/css/css/options-search-light.css" title="light"/> <link rel="stylesheet" href="/assets/css/css/options-search-dark.css" title="dark"/> <link rel="stylesheet" href="/assets/css/css/page-styling-main.css"/> <link rel="stylesheet" href="/assets/css/css/page-styling-dark.css" title="dark"/> <link rel="stylesheet" href="/assets/css/css/page-styling-light.css" title="light"/> <link rel="stylesheet" href="/assets/css/css/chyronToggle-dark.css" title="dark"/> <link rel="stylesheet" href="/assets/css/css/chyronToggle-light.css" title="light"/> <link rel="stylesheet" href="/assets/css/css/centreToggle-dark.css" title="dark"/> <link rel="stylesheet" href="/assets/css/css/centreToggle-light.css" title="light"/> <link rel="stylesheet" href="/assets/css/tm-styling.css"/> <link rel="stylesheet" href="/assets/css/tm-light.css" title="light"/> <link rel="stylesheet" href="/assets/css/tm-dark.css" title="dark"/> <link rel="stylesheet" href="/assets/css/css/rainbow-dark.css" title="dark"/> <link rel="stylesheet" href="/assets/css/css/rainbow-light.css" title="light"/> <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@tarekraafat/autocomplete.js@10.2.7/dist/css/autoComplete.min.css" /> <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/atom-one-light.min.css" title="light" /> <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/atom-one-dark.min.css" title="dark" /> <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.6.0/jquery.min.js"></script> <script src="/assets/scripts/all.min.js"></script><script src="/assets/scripts/filter-script.js"></script><script src="/assets/scripts/tableManager.js"></script><script src="https://cdn.jsdelivr.net/npm/fuzzysort@2.0.4/fuzzysort.min.js"></script><script src="https://cdn.jsdelivr.net/npm/@tarekraafat/autocomplete.js@10.2.7/dist/autoComplete.min.js"></script><script src="/assets/scripts/filtered-toc.js"></script><script src="/assets/scripts/options-search.js"></script><script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/highlight.min.js"></script><script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/languages/haskell.min.js"></script><script src="/assets/scripts/page-styling.js"></script><script src="/assets/scripts/announcements.js"></script><script src="/assets/scripts/rainbow.js"></script> </head> <body class="has-navbar-fixed-top"> <div id="class_Failure" class="top-of-page"></div> <nav class="navbar is-fixed-top is-flex-touch" role="navigation" aria-label="main navigation"> <div class="navbar-item" style="margin-left: auto;"> <div class="left-bar-toggle" title="Toggle Table of Contents & Index"> <label class="chyronToggle left"> <input id="navbar-left-toggle" type="checkbox"> <span class="text">Contents</span> </label> </div> </div> <div class="container is-justify-content-space-around"> <div class="navbar-brand"> <div class="navbar-logo"> <a class="navbar-item" href="/"> <img src="/assets/images/camelia-recoloured.png" alt="Raku" width="52.83" height="38"> </a> <span class="navbar-logo-tm">tm</span> </div> <a role="button" class="navbar-burger burger" aria-label="menu" aria-expanded="false" data-target="navMenu"> <span aria-hidden="true"></span> <span aria-hidden="true"></span> <span aria-hidden="true"></span> </a> </div> <div id="navMenu" class="navbar-menu"> <div class="navbar-start"> <a class="navbar-item" href="/introduction" title="Getting started, Tutorials, Migration guides"> Introduction </a> <a class="navbar-item" href="/reference" title="Fundamentals, General reference"> Reference </a> <a class="navbar-item" href="/miscellaneous" title="Programs, Experimental"> Miscellaneous </a> <a class="navbar-item" href="/types" title="The core types (classes) available"> Types </a> <a class="navbar-item" href="/routines" title="Searchable table of routines"> Routines </a> <a class="navbar-item" href="https://raku.org" title="Home page for community"> Raku<sup>®</sup> </a> <a class="navbar-item" href="https://web.libera.chat/#raku" title="IRC live chat"> Chat </a> <div class="navbar-item has-dropdown is-hoverable"> <a class="navbar-link"> More </a> <div class="navbar-dropdown is-right is-rounded"> <hr class="navbar-divider"> <a class="navbar-item js-modal-trigger" data-target="download-ebook"> Download E-Book (epub) </a> <hr class="navbar-divider"> <a class="navbar-item" href="/about"> About </a> <hr class="navbar-divider"> <a class="navbar-item has-text-red" href="https://github.com/raku/doc-website/issues"> Report an issue with this site </a> <hr class="navbar-divider"> <a class="navbar-item" href="https://github.com/raku/doc/issues"> Report an issue with the documentation content </a> <hr class="navbar-divider"> <label class="navbar-item centreToggle" title="Enable/Disable Announcements" style="--switch-width: 18"> <input id="cancelAnnouncements" type="checkbox"> <span class="text">Announcements</span> <span class="on">suppressed</span> <span class="off">allowed</span> </label> </div> </div> </div> <div class="navbar-end navbar-search-wrapper"> <div class="navbar-item"> <div class="field has-addons"> <div class="autoComplete_options"> <input class="control input" id="autoComplete" type="search" dir="ltr" spellcheck=false autocorrect="off" autocomplete="off" autocapitalize="off" placeholder="🔍 Type f to search for ..."> </div> <div class="control" title="Search options"> <a class="button is-primary js-modal-trigger" data-target="options-search-info"> <span class="icon"> <i class="fas fa-cogs"></i> </span> </a> </div> </div> </div> </div> <div id="options-search-info" class="modal"> <div class="modal-background"></div> <div class="modal-content"> <div class="box"> <p>The last search was: <span id="selected-candidate" class="ss-selected"></span></p> <div class="control is-grouped is-grouped-centered options-search-controls"> <label class="centreToggle" title="Include extra information (Alt-E)" style="--switch-width: 10.5"> <input id="options-search-extra" type="checkbox"> <span class="text">Extra info</span> <span class="on">yes</span> <span class="off">no</span> </label> <p>The search response can be shortened by excluding the extra information line (Alt-E)</p> <label class="centreToggle" title="Search engine type Strict/Loose (Alt-L)" style="--switch-width: 10.5"> <input id="options-search-loose" type="checkbox"> <span class="text">Search type</span> <span class="on">loose</span> <span class="off">strict</span> </label> <p> The search engine can perform a strict search (only the characters in the search box) or a loose search (Alt-L)</p> <label class="centreToggle" title="Search in headings (Alt-H)" style="--switch-width: 10.5"> <input id="options-search-headings" type="checkbox"> <span class="text">Headings</span> <span class="on">yes</span> <span class="off">no</span> </label> <p>Search through headings in all web-pages (Alt-H)</p> <label class="centreToggle" title="Search indexed items (Alt-I)" style="--switch-width: 10.5"> <input id="options-search-indexed" type="checkbox"> <span class="text">Indexed</span> <span class="on">yes</span> <span class="off">no</span> </label> <p>Search through all indexed items (Alt-I)</p> <label class="centreToggle" title="Search composite pages (Alt-C)" style="--switch-width: 10.5"> <input id="options-search-composite" type="checkbox"> <span class="text">Composite</span> <span class="on">yes</span> <span class="off">no</span> </label> <p>Search in the names of composite pages, which combine similar information from the main web pages (Alt-C)</p> <label class="centreToggle" title="Search primary sources (Alt-P)" style="--switch-width: 10.5"> <input id="options-search-primary" type="checkbox"> <span class="text">Primary</span> <span class="on">yes</span> <span class="off">no</span> </label> <p>Search through the names of the main web pages (Alt-P)</p> <label class="centreToggle" title="Open in new tab (Alt-Q)" style="--switch-width: 10.5"> <input id="options-search-newtab" type="checkbox"> <span class="text">New tab</span> <span class="on">yes</span> <span class="off">no</span> </label> <p>Once a search candidate has been chosen, it can be opened in a new tab or in the current tab (Alt-Q)</p> <p>If all else fails, an item is added to use the Google search engine on the whole site</p> <button class="button is-warning" id="options-search-reset-defaults">Clear options, reset to defaults</button> <p>Exit this page by pressing <Escape>, or clicking on X or on the background.</p> </div> </div> </div> <button class="modal-close is-large" aria-label="close"></button> </div> </div> <div id="download-ebook" class="modal"> <div class="modal-background"></div> <div class="modal-content"> <div class="box"> <p><a href="/RakuDocumentation.epub" download>RakuDocumentation.epub</a> is a work in progress e-book. It targets the <a href="https://www.w3.org/publishing/epub3/">EPUB v3 specification</a>. It needs testing on a variety of ereaders (some of which may still implicitly expect compliance with EPUB v2). The CSS definitely needs enhancing (especially for code snippets). The Ebook opens in a Calibre reader, which is available on all operating systems.</p> <p>Suggestions are welcome and should be addressed by opening an issue on the Raku/doc-website repository</p> <p>Exit this popup by pressing <Escape>, or clicking on X or on the background.</p> </div> </div> <button class="modal-close is-large" aria-label="close"></button> </div> <div id="announcement-modal" class="modal"> <div class="modal-background"></div> <div class="modal-content"> <div class="box"> <div id="raku-doc-announcement"></div> <p>For more see <a href="/announcements">Announcements page</a>.</p> <p>Exit this popup by pressing <Escape>, or clicking on X or on the background.</p> </div> </div> <button class="modal-close is-large" aria-label="close"></button> </div> </div> </nav> <div class="tile is-ancestor section"> <div class="page-edit"> <a class="button page-edit-button" href="https://github.com/Raku/doc/edit/main/doc/Type/Failure.rakudoc" title="Edit this page.Commit: 414dd1bac 2024-07-13"> <span class="icon is-right"> <i class="fas fa-pen-alt is-medium"></i> </span> </a> </div> <div id="left-column" class="tile is-parent is-2 is-hidden"> <div id="left-col-inner"> <div class="tabs" id="tabs"> <ul> <li class="is-active" id="toc-tab"> <a>Table of Contents</a> </li> <li id="index-tab"> <a>Index</a> </li> </ul> </div> <div class="field"> <div class="control has-icons-right"> <input id="toc-filter" class="input" type="text" placeholder="Filter"> <span class="icon is-right has-text-grey"> <i class="fas fa-search is-medium"></i> </span> </div> </div> <div class="raku-sidebar"> <aside id="toc-menu" class="menu"> <ul class="menu-list"> <li><a href="#Methods">Methods</a></li> <ul> <li><a href="#method_new">method new</a></li> <li><a href="#method_handled">method handled</a></li> <li><a href="#method_exception">method exception</a></li> <li><a href="#method_self">method self</a></li> <li><a href="#method_Bool">method Bool</a></li> <li><a href="#method_Capture">method Capture</a></li> <li><a href="#method_defined">method defined</a></li> <li><a href="#method_list">method list</a></li> <li><a href="#sub_fail">sub fail</a></li> </ul> </aside> <aside id="index-menu" class="menu is-hidden"> </aside> </div> </div> </div> <div id="main-column" class="tile is-parent" style="overflow-x: hidden;"> <div id="main-col-inner"> <section class="raku page-header"> <div class="container px-4"> <div class="raku page-title has-text-centered"> class Failure </div> <div class="raku page-subtitle has-text-centered"> <p>Delayed exception</p> </div> </div> </section> <section class="raku page-content"><div class="container px-4"><div class="columns one-col"> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">class</span> <span class="highlite-TYPE">Failure</span> <span class="highlite-KEYWORD">is</span> <span class="highlite-TYPE">Nil</span> { }</pre> </div> </div> <p>A <code>Failure</code> is a <em>soft</em> or <em>unthrown</em> <a href="/type/Exception"><code>Exception</code></a>, usually generated by calling <code>&fail</code>. It acts as a wrapper around an <a href="/type/Exception"><code>Exception</code></a> object.</p><p>Sink (void) context causes a <code>Failure</code> to throw, i.e. turn into a regular exception. The <a href="/language/pragmas#fatal"><code>use fatal</code> pragma</a> causes this to happen in all contexts within the pragma's scope. Inside <a href="/language/exceptions#try_blocks"><code>try</code> blocks</a>, <code>use fatal</code> is automatically set, and you can <em>disable</em> it with <code>no fatal</code>.</p><p>That means that Failures are generally only useful in cases of code that normally would produce an rvalue; Failures are more or less equivalent to Exceptions in code that will frequently be called in sink context (i.e., for its side-effects, such as with <code>say</code>).</p><p>Similarly, you should generally use <code>&fail</code> only inside code that is normally expected to return something.</p><p>Checking a Failure for truth (with the <code>Bool</code> method) or definedness (with the <code>defined</code> method) marks the failure as handled, and causes it not to throw in sink context anymore.</p><p>You can call the <code>handled</code> method to check if a failure has been handled.</p><p>Calling methods on unhandled failures propagates the failure. The specification says the result is another <code>Failure</code>; in Rakudo it causes the failure to throw.</p><p>Because a Failure is <a href="/type/Nil"><code>Nil</code></a>, which is undefined, a common idiom for safely executing code that may fail uses a <a href="/language/control#with_orwith_without"><code>with/else</code></a> statement:</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">sub</span> may_fail( <span class="highlite-KEYWORD">--></span> Numeric:D ) { <span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_SCALAR">$value</span> <span class="highlite-OPERATOR">=</span> (^10).<span class="highlite-ROUTINE">pick</span> <span class="highlite-OPERATOR">||</span> <span class="highlite-ROUTINE">fail</span> <span class="highlite-STRING_DELIMITER">"</span><span class="highlite-STRING">Zero is unacceptable</span><span class="highlite-STRING_DELIMITER">"</span>; <span class="highlite-ROUTINE">fail</span> <span class="highlite-STRING_DELIMITER">"</span><span class="highlite-STRING">Odd is also not okay</span><span class="highlite-STRING_DELIMITER">"</span> <span class="highlite-KEYWORD">if</span> <span class="highlite-NAME_SCALAR">$value</span> <span class="highlite-OPERATOR">%</span> 2; <span class="highlite-KEYWORD">return</span> <span class="highlite-NAME_SCALAR">$value</span>; } <span class="highlite-KEYWORD">with</span> may_fail() <span class="highlite-KEYWORD">-></span> <span class="highlite-NAME_SCALAR">$value</span> { <span class="highlite-COMMENT"># defined, so didn't fail </span> <span class="highlite-ROUTINE">say</span> <span class="highlite-STRING_DELIMITER">"</span><span class="highlite-STRING">I know </span><span class="highlite-NAME_SCALAR">$value</span><span class="highlite-STRING"> isn't zero or odd.</span><span class="highlite-STRING_DELIMITER">"</span> } <span class="highlite-KEYWORD">else</span> { <span class="highlite-COMMENT"># undefined, so failed, and the Failure is the topic </span> <span class="highlite-ROUTINE">say</span> <span class="highlite-STRING_DELIMITER">"</span><span class="highlite-STRING">Uh-oh: </span><span class="highlite-ESCAPE">{</span>.<span class="highlite-ROUTINE">exception</span>.<span class="highlite-ROUTINE">message</span><span class="highlite-ESCAPE">}</span><span class="highlite-STRING">.</span><span class="highlite-STRING_DELIMITER">"</span> } </pre> </div> </div> <h1 id="Methods" class="raku-h1"><a href="#class_Failure" title="go to top of document">Methods<a class="raku-anchor" title="direct link" href="#Methods">§</a></a></h1> <h2 id="method_new" class="raku-h2"><a href="#class_Failure" title="go to top of document">method new<a class="raku-anchor" title="direct link" href="#method_new">§</a></a></h2>  <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">multi</span> <span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">new</span>(Failure:D:) <span class="highlite-KEYWORD">multi</span> <span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">new</span>(Failure:U:) <span class="highlite-KEYWORD">multi</span> <span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">new</span>(Failure:U: Exception:D \<span class="highlite-ROUTINE">exception</span>) <span class="highlite-KEYWORD">multi</span> <span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">new</span>(Failure:U: <span class="highlite-NAME_SCALAR">$payload</span>) <span class="highlite-KEYWORD">multi</span> <span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">new</span>(Failure:U: |cap (<span class="highlite-OPERATOR">*</span><span class="highlite-NAME_ARRAY">@msg</span>))</pre> </div> </div> <p>Returns a new <code>Failure</code> instance with payload given as argument. If called without arguments on a <code>Failure</code> object, it will throw; on a type value, it will create an empty <code>Failure</code> with no payload. The latter can be either an <a href="/type/Exception"><code>Exception</code></a> or a payload for an <a href="/type/Exception"><code>Exception</code></a>. A typical payload would be a <a href="/type/Str"><code>Str</code></a> with an error message. A list of payloads is also accepted.</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_SCALAR">$e</span> <span class="highlite-OPERATOR">=</span> <span class="highlite-TYPE">Failure</span>.<span class="highlite-ROUTINE">new</span>(<span class="highlite-ROUTINE">now</span>.<span class="highlite-TYPE">DateTime</span><span class="highlite-OPERATOR">,</span> <span class="highlite-STRING_DELIMITER">'</span><span class="highlite-STRING">WELP‼</span><span class="highlite-STRING_DELIMITER">'</span>); <span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_SCALAR">$e</span>; <span class="highlite-KEYWORD">CATCH</span>{ <span class="highlite-KEYWORD">default</span> { <span class="highlite-ROUTINE">say</span> .^<span class="highlite-ROUTINE">name</span><span class="highlite-OPERATOR">,</span> <span class="highlite-STRING_DELIMITER">'</span><span class="highlite-STRING">: </span><span class="highlite-STRING_DELIMITER">'</span><span class="highlite-OPERATOR">,</span> .<span class="highlite-TYPE">Str</span> } } <span class="highlite-COMMENT"># OUTPUT: «X::AdHoc: 2017-09-10T11:56:05.477237ZWELP‼␤»</span></pre> </div> </div> <h2 id="method_handled" class="raku-h2"><a href="#class_Failure" title="go to top of document">method handled<a class="raku-anchor" title="direct link" href="#method_handled">§</a></a></h2>  <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">handled</span>(Failure:D: <span class="highlite-KEYWORD">--></span> Bool:D) <span class="highlite-KEYWORD">is</span> <span class="highlite-KEYWORD">rw</span></pre> </div> </div> <p>Returns <code>True</code> for handled failures, <code>False</code> otherwise.</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">sub</span> <span class="highlite-ROUTINE">f</span>() { <span class="highlite-ROUTINE">fail</span> }; <span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_SCALAR">$v</span> <span class="highlite-OPERATOR">=</span> <span class="highlite-ROUTINE">f</span>; <span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_SCALAR">$v</span>.<span class="highlite-ROUTINE">handled</span>; <span class="highlite-COMMENT"># OUTPUT: «False␤»</span></pre> </div> </div> <p>The <code>handled</code> method is an <a href="/language/glossary#lvalue">lvalue</a>, see <a href="/type/Routine#trait_is_rw">routine trait <code>is rw</code></a>, which means you can also use it to set the handled state:</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">sub</span> <span class="highlite-ROUTINE">f</span>() { <span class="highlite-ROUTINE">fail</span> } <span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_SCALAR">$v</span> <span class="highlite-OPERATOR">=</span> <span class="highlite-ROUTINE">f</span>; <span class="highlite-NAME_SCALAR">$v</span>.<span class="highlite-ROUTINE">handled</span> <span class="highlite-OPERATOR">=</span> <span class="highlite-TYPE">True</span>; <span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_SCALAR">$v</span>.<span class="highlite-ROUTINE">handled</span>; <span class="highlite-COMMENT"># OUTPUT: «True␤»</span></pre> </div> </div> <h2 id="method_exception" class="raku-h2"><a href="#class_Failure" title="go to top of document">method exception<a class="raku-anchor" title="direct link" href="#method_exception">§</a></a></h2>  <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">exception</span>(Failure:D: <span class="highlite-KEYWORD">--></span> <span class="highlite-TYPE">Exception</span>)</pre> </div> </div> <p>Returns the <a href="/type/Exception"><code>Exception</code></a> object that the failure wraps.</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">sub</span> failer() { <span class="highlite-ROUTINE">fail</span> }; <span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_SCALAR">$failure</span> <span class="highlite-OPERATOR">=</span> failer; <span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_SCALAR">$ex</span> <span class="highlite-OPERATOR">=</span> <span class="highlite-NAME_SCALAR">$failure</span>.<span class="highlite-ROUTINE">exception</span>; <span class="highlite-ROUTINE">put</span> <span class="highlite-STRING_DELIMITER">"</span><span class="highlite-NAME_SCALAR">$ex</span><span class="highlite-STRING">.^name(): </span><span class="highlite-NAME_SCALAR">$ex</span><span class="highlite-STRING_DELIMITER">"</span>; <span class="highlite-COMMENT"># OUTPUT: «X::AdHoc: Failed␤»</span></pre> </div> </div> <h2 id="method_self" class="raku-h2"><a href="#class_Failure" title="go to top of document">method self<a class="raku-anchor" title="direct link" href="#method_self">§</a></a></h2>  <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">self</span>(Failure:D: <span class="highlite-KEYWORD">--></span> Failure:D)</pre> </div> </div> <p>If the invocant is a <a href="/routine/handled">handled</a> <code>Failure</code>, returns it as is. If not handled, throws its <a href="/type/Exception"><code>Exception</code></a>. Since <a href="/type/Mu"><code>Mu</code></a> type <a href="/type/Mu#method_self">provides <code>.self</code></a> for every class, calling this method is a handy way to explosively filter out Failures:</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_SCALAR">$num1</span> <span class="highlite-OPERATOR">=</span> <span class="highlite-STRING_DELIMITER">'</span><span class="highlite-STRING">♥</span><span class="highlite-STRING_DELIMITER">'</span>.<span class="highlite-TYPE">Int</span>; <span class="highlite-COMMENT"># $num1 now contains a Failure object, which may not be desirable </span> <span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_SCALAR">$num2</span> <span class="highlite-OPERATOR">=</span> <span class="highlite-STRING_DELIMITER">'</span><span class="highlite-STRING">♥</span><span class="highlite-STRING_DELIMITER">'</span>.<span class="highlite-TYPE">Int</span>.<span class="highlite-ROUTINE">self</span>; <span class="highlite-COMMENT"># .self method call on Failure causes an exception to be thrown </span> <span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_SCALAR">$num3</span> <span class="highlite-OPERATOR">=</span> <span class="highlite-STRING_DELIMITER">'</span><span class="highlite-STRING">42</span><span class="highlite-STRING_DELIMITER">'</span>.<span class="highlite-TYPE">Int</span>.<span class="highlite-ROUTINE">self</span>; <span class="highlite-COMMENT"># Int type has a .self method, so here $num3 has `42` in it </span> (<span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_SCALAR">$stuff</span> <span class="highlite-OPERATOR">=</span> <span class="highlite-STRING_DELIMITER">'</span><span class="highlite-STRING">♥</span><span class="highlite-STRING_DELIMITER">'</span>.<span class="highlite-TYPE">Int</span>).<span class="highlite-OPERATOR">so</span>; <span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_SCALAR">$stuff</span>.<span class="highlite-ROUTINE">self</span>; <span class="highlite-COMMENT"># OUTPUT: «(HANDLED) Cannot convert string to number…» </span><span class="highlite-COMMENT"># Here, Failure is handled, so .self just returns it as is</span></pre> </div> </div> <h2 id="method_Bool" class="raku-h2"><a href="#class_Failure" title="go to top of document">method Bool<a class="raku-anchor" title="direct link" href="#method_Bool">§</a></a></h2>  <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">multi</span> <span class="highlite-KEYWORD">method</span> <span class="highlite-TYPE">Bool</span>(Failure:D: <span class="highlite-KEYWORD">--></span> Bool:D)</pre> </div> </div> <p>Returns <code>False</code>, and marks the failure as handled.</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">sub</span> <span class="highlite-ROUTINE">f</span>() { <span class="highlite-ROUTINE">fail</span> }; <span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_SCALAR">$v</span> <span class="highlite-OPERATOR">=</span> <span class="highlite-ROUTINE">f</span>; <span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_SCALAR">$v</span>.<span class="highlite-ROUTINE">handled</span>; <span class="highlite-COMMENT"># OUTPUT: «False␤» </span><span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_SCALAR">$v</span>.<span class="highlite-TYPE">Bool</span>; <span class="highlite-COMMENT"># OUTPUT: «False␤» </span><span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_SCALAR">$v</span>.<span class="highlite-ROUTINE">handled</span>; <span class="highlite-COMMENT"># OUTPUT: «True␤»</span></pre> </div> </div> <h2 id="method_Capture" class="raku-h2"><a href="#class_Failure" title="go to top of document">method Capture<a class="raku-anchor" title="direct link" href="#method_Capture">§</a></a></h2>  <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">method</span> <span class="highlite-TYPE">Capture</span>()</pre> </div> </div> <p>Throws <code>X::Cannot::Capture</code> if the invocant is a type object or a <a href="/routine/handled">handled</a> <code>Failure</code>. Otherwise, throws the invocant's <a href="/routine/exception">exception</a>.</p> <h2 id="method_defined" class="raku-h2"><a href="#class_Failure" title="go to top of document">method defined<a class="raku-anchor" title="direct link" href="#method_defined">§</a></a></h2>  <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">multi</span> <span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">defined</span>(Failure:D: <span class="highlite-KEYWORD">--></span> Bool:D)</pre> </div> </div> <p>Returns <code>False</code> (failures are officially undefined), and marks the failure as handled.</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">sub</span> <span class="highlite-ROUTINE">f</span>() { <span class="highlite-ROUTINE">fail</span> }; <span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_SCALAR">$v</span> <span class="highlite-OPERATOR">=</span> <span class="highlite-ROUTINE">f</span>; <span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_SCALAR">$v</span>.<span class="highlite-ROUTINE">handled</span>; <span class="highlite-COMMENT"># OUTPUT: «False␤» </span><span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_SCALAR">$v</span>.<span class="highlite-ROUTINE">defined</span>; <span class="highlite-COMMENT"># OUTPUT: «False␤» </span><span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_SCALAR">$v</span>.<span class="highlite-ROUTINE">handled</span>; <span class="highlite-COMMENT"># OUTPUT: «True␤»</span></pre> </div> </div> <h2 id="method_list" class="raku-h2"><a href="#class_Failure" title="go to top of document">method list<a class="raku-anchor" title="direct link" href="#method_list">§</a></a></h2>  <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">multi</span> <span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">list</span>(Failure:D:)</pre> </div> </div> <p>Marks the failure as handled and throws the invocant's <a href="/type/Failure#method_exception">exception</a>.</p> <h2 id="sub_fail" class="raku-h2"><a href="#class_Failure" title="go to top of document">sub fail<a class="raku-anchor" title="direct link" href="#sub_fail">§</a></a></h2>  <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">multi</span> <span class="highlite-ROUTINE">fail</span>(<span class="highlite-KEYWORD">--></span> <span class="highlite-TYPE">Nil</span>) <span class="highlite-KEYWORD">multi</span> <span class="highlite-ROUTINE">fail</span>(<span class="highlite-OPERATOR">*</span><span class="highlite-NAME_ARRAY">@text</span>) <span class="highlite-KEYWORD">multi</span> <span class="highlite-ROUTINE">fail</span>(Exception:U <span class="highlite-NAME_SCALAR">$e</span> <span class="highlite-KEYWORD">--></span> <span class="highlite-TYPE">Nil</span> ) <span class="highlite-KEYWORD">multi</span> <span class="highlite-ROUTINE">fail</span>(<span class="highlite-NAME_SCALAR">$payload</span> <span class="highlite-KEYWORD">--></span> <span class="highlite-TYPE">Nil</span>) <span class="highlite-KEYWORD">multi</span> <span class="highlite-ROUTINE">fail</span>(|cap (<span class="highlite-OPERATOR">*</span><span class="highlite-NAME_ARRAY">@msg</span>) <span class="highlite-KEYWORD">--></span> <span class="highlite-TYPE">Nil</span>) <span class="highlite-KEYWORD">multi</span> <span class="highlite-ROUTINE">fail</span>(Failure:U <span class="highlite-NAME_SCALAR">$f</span> <span class="highlite-KEYWORD">--></span> <span class="highlite-TYPE">Nil</span>) <span class="highlite-KEYWORD">multi</span> <span class="highlite-ROUTINE">fail</span>(Failure:D <span class="highlite-NAME_SCALAR">$fail</span> <span class="highlite-KEYWORD">--></span> <span class="highlite-TYPE">Nil</span>)</pre> </div> </div> <p>Exits the calling <a href="/type/Routine"><code>Routine</code></a> and returns a <code>Failure</code> object wrapping the exception <code>$e</code> - or, for the <code>cap</code> or <code>$payload</code> form, an <a href="/type/X/AdHoc"><code>X::AdHoc</code></a> exception constructed from the concatenation of <code>@text</code>. If the caller activated fatal exceptions via the pragma <code>use fatal;</code>, the exception is thrown instead of being returned as a <code>Failure</code>.</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-COMMENT"># A custom exception defined </span><span class="highlite-KEYWORD">class</span> ForbiddenDirectory <span class="highlite-KEYWORD">is</span> <span class="highlite-TYPE">Exception</span> { <span class="highlite-KEYWORD">has</span> <span class="highlite-TYPE">Str</span> <span class="highlite-NAME_SCALAR">$.name</span>; <span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">message</span> { <span class="highlite-STRING_DELIMITER">"</span><span class="highlite-STRING">This directory is forbidden: '</span><span class="highlite-NAME_SCALAR">$!name'</span><span class="highlite-STRING_DELIMITER">"</span> } } <span class="highlite-KEYWORD">sub</span> copy-directory-tree (<span class="highlite-NAME_SCALAR">$dir</span>) { <span class="highlite-COMMENT"># We don't allow for non-directories to be copied </span> <span class="highlite-ROUTINE">fail</span> <span class="highlite-STRING_DELIMITER">"</span><span class="highlite-NAME_SCALAR">$dir</span><span class="highlite-STRING"> is not a directory</span><span class="highlite-STRING_DELIMITER">"</span> <span class="highlite-KEYWORD">if</span> <span class="highlite-OPERATOR">!</span><span class="highlite-NAME_SCALAR">$dir</span>.<span class="highlite-TYPE">IO</span>.<span class="highlite-ROUTINE">d</span>; <span class="highlite-COMMENT"># We don't allow 'foo' directory to be copied too </span> <span class="highlite-ROUTINE">fail</span> ForbiddenDirectory.<span class="highlite-ROUTINE">new</span>(:name(<span class="highlite-NAME_SCALAR">$dir</span>)) <span class="highlite-KEYWORD">if</span> <span class="highlite-NAME_SCALAR">$dir</span> <span class="highlite-OPERATOR">eq</span> <span class="highlite-STRING_DELIMITER">'</span><span class="highlite-STRING">foo</span><span class="highlite-STRING_DELIMITER">'</span>; <span class="highlite-COMMENT"># or above can be written in method form as: </span> <span class="highlite-COMMENT"># ForbiddenDirectory.new(:name($dir)).fail if $dir eq 'foo'; </span> <span class="highlite-COMMENT"># Do some actual copying here </span> <span class="highlite-OPERATOR">...</span> } <span class="highlite-COMMENT"># A Failure with X::AdHoc exception object is returned and </span><span class="highlite-COMMENT"># assigned, so no throwing Would be thrown without an assignment </span><span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_SCALAR">$result</span> <span class="highlite-OPERATOR">=</span> copy-directory-tree(<span class="highlite-STRING_DELIMITER">"</span><span class="highlite-STRING">cat.jpg</span><span class="highlite-STRING_DELIMITER">"</span>); <span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_SCALAR">$result</span>.<span class="highlite-ROUTINE">exception</span>; <span class="highlite-COMMENT"># OUTPUT: «cat.jpg is not a directory␤» </span> <span class="highlite-COMMENT"># A Failure with a custom Exception object is returned </span><span class="highlite-NAME_SCALAR">$result</span> <span class="highlite-OPERATOR">=</span> copy-directory-tree(<span class="highlite-STRING_DELIMITER">'</span><span class="highlite-STRING">foo</span><span class="highlite-STRING_DELIMITER">'</span>); <span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_SCALAR">$result</span>.<span class="highlite-ROUTINE">exception</span>; <span class="highlite-COMMENT"># OUTPUT: «This directory is forbidden: 'foo'␤»</span></pre> </div> </div> <p>If it's called with a generic <code>Failure</code>, an ad-hoc undefined failure is thrown; if it's a defined <code>Failure</code>, it will be marked as unhandled.</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">sub</span> re-fail { <span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_SCALAR">$x</span> <span class="highlite-OPERATOR">=</span> <span class="highlite-OPERATOR">+</span><span class="highlite-STRING_DELIMITER">"</span><span class="highlite-STRING">a</span><span class="highlite-STRING_DELIMITER">"</span>; <span class="highlite-KEYWORD">unless</span> <span class="highlite-NAME_SCALAR">$x</span>.<span class="highlite-ROUTINE">defined</span> { <span class="highlite-NAME_SCALAR">$x</span>.<span class="highlite-ROUTINE">handled</span> <span class="highlite-OPERATOR">=</span> <span class="highlite-TYPE">True</span>; <span class="highlite-ROUTINE">say</span> <span class="highlite-STRING_DELIMITER">"</span><span class="highlite-STRING">Something has failed in </span><span class="highlite-ESCAPE">\$</span><span class="highlite-STRING">x </span><span class="highlite-STRING_DELIMITER">"</span><span class="highlite-OPERATOR">,</span> <span class="highlite-NAME_SCALAR">$x</span>.^<span class="highlite-ROUTINE">name</span>; <span class="highlite-COMMENT"># OUTPUT: «Something has failed in $x Failure␤» </span> <span class="highlite-ROUTINE">fail</span>(<span class="highlite-NAME_SCALAR">$x</span>); <span class="highlite-KEYWORD">return</span> <span class="highlite-NAME_SCALAR">$x</span>; } } <span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_SCALAR">$x</span> <span class="highlite-OPERATOR">=</span> re-fail; <span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_SCALAR">$x</span>.<span class="highlite-ROUTINE">handled</span>; <span class="highlite-COMMENT"># OUTPUT: «False␤» </span></pre> </div> </div> <h1 id="typegraphrelations" class="raku-h1"><a href="#" title="go to top of document">Typegraph<a class="raku-anchor" title="direct link" href="#typegraphrelations">§</a></a></h1> <figure class="typegraph" > <figcaption>Type relations for <code>Failure</code></figcaption> <svg width="89pt" height="332pt" viewBox="0.00 0.00 88.59 332.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"> <g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 328)"> <title>raku-type-graph</title> <polygon fill="#ffffff" stroke="transparent" points="-4,4 -4,-328 84.59,-328 84.59,4 -4,4"/>  <g id="node1" class="node"> <title>Failure</title> <g id="a_node1"><a xlink:href="/type/Failure" xlink:title="Failure"> <ellipse fill="none" stroke="#000000" cx="40.3" cy="-18" rx="40.09" ry="18"/> <text text-anchor="middle" x="40.3" y="-14.3" font-family="FreeSans" font-size="14.00" fill="#000000">Failure</text> </a> </g> </g>  <g id="node5" class="node"> <title>Nil</title> <g id="a_node5"><a xlink:href="/type/Nil" xlink:title="Nil"> <ellipse fill="none" stroke="#000000" cx="40.3" cy="-90" rx="27" ry="18"/> <text text-anchor="middle" x="40.3" y="-86.3" font-family="FreeSans" font-size="14.00" fill="#000000">Nil</text> </a> </g> </g>  <g id="edge1" class="edge"> <title>Failure->Nil</title> <path fill="none" stroke="#000000" d="M40.3,-36.3C40.3,-44.02 40.3,-53.29 40.3,-61.89"/> <polygon fill="#000000" stroke="#000000" points="36.8,-61.9 40.3,-71.9 43.8,-61.9 36.8,-61.9"/> </g>  <g id="node2" class="node"> <title>Mu</title> <g id="a_node2"><a xlink:href="/type/Mu" xlink:title="Mu"> <ellipse fill="none" stroke="#000000" cx="40.3" cy="-306" rx="27" ry="18"/> <text text-anchor="middle" x="40.3" y="-302.3" font-family="FreeSans" font-size="14.00" fill="#000000">Mu</text> </a> </g> </g>  <g id="node3" class="node"> <title>Any</title> <g id="a_node3"><a xlink:href="/type/Any" xlink:title="Any"> <ellipse fill="none" stroke="#000000" cx="40.3" cy="-234" rx="28.7" ry="18"/> <text text-anchor="middle" x="40.3" y="-230.3" font-family="FreeSans" font-size="14.00" fill="#000000">Any</text> </a> </g> </g>  <g id="edge2" class="edge"> <title>Any->Mu</title> <path fill="none" stroke="#000000" d="M40.3,-252.3C40.3,-260.02 40.3,-269.29 40.3,-277.89"/> <polygon fill="#000000" stroke="#000000" points="36.8,-277.9 40.3,-287.9 43.8,-277.9 36.8,-277.9"/> </g>  <g id="node4" class="node"> <title>Cool</title> <g id="a_node4"><a xlink:href="/type/Cool" xlink:title="Cool"> <ellipse fill="none" stroke="#000000" cx="40.3" cy="-162" rx="30.59" ry="18"/> <text text-anchor="middle" x="40.3" y="-158.3" font-family="FreeSans" font-size="14.00" fill="#000000">Cool</text> </a> </g> </g>  <g id="edge3" class="edge"> <title>Cool->Any</title> <path fill="none" stroke="#000000" d="M40.3,-180.3C40.3,-188.02 40.3,-197.29 40.3,-205.89"/> <polygon fill="#000000" stroke="#000000" points="36.8,-205.9 40.3,-215.9 43.8,-205.9 36.8,-205.9"/> </g>  <g id="edge4" class="edge"> <title>Nil->Cool</title> <path fill="none" stroke="#000000" d="M40.3,-108.3C40.3,-116.02 40.3,-125.29 40.3,-133.89"/> <polygon fill="#000000" stroke="#000000" points="36.8,-133.9 40.3,-143.9 43.8,-133.9 36.8,-133.9"/> </g> </g> </svg> <p class="fallback"> <a rel="alternate" href="/assets/typegraphs/Failure.svg"> Expand chart above </a></p> </figure> </div></div></section> </div> </div> </div> <footer class="footer main-footer"> <div class="container px-4"> <nav class="level"> <div class="level-left"> <div class="level-item"> <a href="/about">About</a> </div> <div class="level-item"> <a id="toggle-theme">Toggle theme</a> </div> <div class="level-item" title="414dd1bac 2024-07-13"> <a>Commit</a> </div> </div> <div class="level-right"> <div class="level-item"> <a href="/license">License</a> </div> </div> </nav> </div> </footer> </body> </html>

CINXE.COM

class Failure | Raku Documentation