ref/error.html

<html dir="ltr">
<head>
<meta content="text/html; charset=UTF-8" http-equiv="Content-Type"/>
<title>Arc: Error handling and continuations</title>
<link rel="shortcut icon" href="/assets/favicon.png">
<link rel="stylesheet" type="text/css" href="code.css">
<link href="/assets/bootstrap.css" rel="stylesheet">
</head>
<body style='margin:12px 50px 0'>
  <div class="navbar navbar-inverse">
    <div class="navbar-inner">
      <ul class="nav navbar-nav">
        <li><a href="/ref/">Arc 3.1</a>
        <li><a href="http://tryarc.org">Try it</a></li>
        <li><a href="http://github.com/arclanguage/anarki">Get it</a></li>
        <li><a href="http://ycombinator.com/arc/tut.txt">Tutorial</a></li>
        <li><a href="http://arclanguage.org/forum">Forum</a></li>
      </ul>
    </div>
  </div> <!-- end of navbar -->
<div class="links">Previous: <a href="queue.html">Queues</a>
Up: <a href="index.html">Contents</a>
Next: <a href="anaphoric.html">Anaphoric operations</a>
</div>
<h1 class="links">Error handling and continuations</h1>
<h2>Error handling and continuations</h2>
Arc provides several operations for error handling and non-linear control flow.
Since Arc's control flow mechanisms are built on top of MzScheme, see the MzScheme manual on <a href='http://download.plt-scheme.org/doc/mzscheme/mzscheme-Z-H-6.html#node_chap_6'>exceptions and control flow</a> for details.
<p>
Arc's simplest mechanism for non-linear control flow is <code>catch</code> and <code>throw</code>.  This allows execution to jump back to the <code>catch</code> expression, for example to exit a loop early.
<pre class="repl">
arc> (catch (each x '(2 4 6 9 10 12) (prn "Examining " x) (if (odd x) (throw x))))
Examining 2
Examining 4
Examining 6
Examining 9
9
</pre>
<p>
Arc also provides access to MzScheme's exception mechanism, which provides a way to trap errors or raise error.
<p>
The <code>ccc</code> function is equivalent to Scheme's <code>call-with-current-continuation</code> (often abbreviated as <code>call/cc</code>).  Continuations are extremely powerful; for details
see <a href="http://gd.tuwien.ac.at/languages/scheme/tutorial-dsitaram/t-y-scheme-Z-H-14.html">Teach Yourself Scheme in Fixnum Days</a>, <a href="http://www.bookshelf.jp/texi/onlisp/onlisp_21.html">Chapter 20</a> of "On Lisp",
<a href="http://jerry.cs.uiuc.edu/~plop/plop2001/accepted_submissions/PLoP2001/dferguson0/PLoP2001_dferguson0_1.pdf">Call with Current Continuation Patterns</a>, or <a href="http://people.csail.mit.edu/jhbrown/scheme/continuationslides04.pdf">Advanced Scheme Techniques</a>.  In MzScheme, continuations are relatively expensive if the call stack is deep since capturing a continuation copies the stack.
<p><table class='arc'>
  <tr>
    <td class='arc'><a name='point'></a>
<img src='macro.gif' title='Macro'/>
<span class='op'>point</span> <span class='args'>name [body ...]</span>
    <div class='desc'>Creates a 'throw' function called
<code>name</code> and executes <code>body</code>.  If <code>name</code> is
executed within <code>body</code>, that value will be returned from
<code>point</code>.  Otherwise, <code>point</code> has no effect and the value from <code>body</code> will be
returned.</div>
    </td>
    <td class='arc'><pre>
&gt;(+ 10 (point throw (+ 20 (throw 3) 30)))
<span class="return">13
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='catch'></a>
<img src='macro.gif' title='Macro'/>
<span class='op'>catch</span> <span class='args'>body</span>
    <div class='desc'>Executes <code>body</code> and catches any value passed to <code>throw</code>.  This is the same as <code>point</code> with the throw function's name predefined.</div>
    </td>
    <td class='arc'><pre>
&gt;(+ 10 (catch (+ 20 (throw 3) 30)))
<span class="return">13
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='ccc'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>ccc</span> <span class='args'>procedure</span>
    <div class='desc'>Packages up the current continuation into an 'escape
  procedure' and passes it to the procedure.  Equivalent to Scheme's <code>call/cc</code> or <a
  href='http://www.schemers.org/Documents/Standards/R5RS/HTML/r5rs-Z-H-9.html#%_idx_566'>call-with-current-continuation</a>.</div>
    </td>
    <td class='arc'><pre>
&gt;(ccc (fn (ep) (ep "bailout value") 42))
<span class="return">"bailout value"
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='protect'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>protect</span> <span class='args'>during-procedure after-procedure</span>
    <div class='desc'>Uses Scheme's
  <a
  href='http://www.schemers.org/Documents/Standards/R5RS/HTML/r5rs-Z-H-9.html#%_idx_576'>dynamic-wind</a> to
  ensure that <code>after-procedure</code> is executed whenever <code>during-procedure</code> exits.</div>
    </td>
    <td class='arc'><pre>
&gt;(protect (fn () (/ 1 0))
    (fn () (prn "after")))
<span class="stdout">after
Error: /: division by zero

</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='after'></a>
<img src='macro.gif' title='Macro'/>
<span class='op'>after</span> <span class='args'>during-body [after-body ...]</span>
    <div class='desc'>Ensures that
<code>after-body</code> executes whenever <code>during-body</code> exits.</div>
    </td>
    <td class='arc'>  </td></tr>
  <tr>
    <td class='arc'><a name='details'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>details</span> <span class='args'>exception</span>
    <div class='desc'>Returns the message associated with an exception.</div>
    </td>
    <td class='arc'><pre>
&gt;(on-err (fn (ex) (details ex)) (err "boo"))
<span class="stdout">Error: boo

</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='err'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>err</span> <span class='args'>string ...</span>
    <div class='desc'>Raises an exception with the given text.</div>
    </td>
    <td class='arc'><pre>
&gt;(err "Failure" 42)
<span class="stdout">Error: Failure 42

</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='on-err'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>on-err</span> <span class='args'>err-proc proc</span>
    <div class='desc'>Executes proc.  Calls err-proc if an exception
  occurs in proc.  The exception is passed to err-proc</div>
    </td>
    <td class='arc'><pre>
&gt;(on-err (fn (ex) (string "caught " (details ex)))
          (fn () (/ 1 0)))
<span class="return">"caught /: division by zero"
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='errsafe'></a>
<img src='macro.gif' title='Macro'/>
<span class='op'>errsafe</span> <span class='args'>expr</span>
    <div class='desc'>Executes expr, returning nil if an error occurs.</div>
    </td>
    <td class='arc'><pre>
&gt;(errsafe (/ 1 2))
<span class="return">1/2
</span></pre>
<pre>
&gt;(errsafe (/ 1 0))
<span class="return">nil
</span></pre>
  </td></tr>
</table>
<p>
Copyright 2008 Ken Shirriff.
</body>
</html>