@ciao-lang/ts-ciao-interface

Version:

Simple Ciao interface for node.

67 lines • 16 kB

HTML

<!DOCTYPE HTML><html><head><meta http-equiv="Content-Type" content="text/html; charset=utf-8"/><meta name="viewport" content="width=device-width, initial-scale=1"/><meta name="theme-color" content="#273f79"/><link rel="stylesheet" href="lpdoc.css" type="text/css"/><script type="text/javascript" src="lpdoc.js"></script><title>Exception and signal handling — The Ciao System v1.22</title></head><body><div class="lpdoc-page fixleftbar"><a href="#" id="sidebar-toggle-button" class="lpdoc-navbutton"><span id="sidebar-button-arrow">☰</span></a><div id="sidebar" class="lpdoc-sidebar"><div style="height: 40px; margin-left: auto; margin-right: auto"><img src="ciao-logo_autofig.png" width=auto height=100%></div><div class="lpdoc-nav"><span class="lpdoc-on-right"><a class="lpdoc-navbutton" href="BasicLang.html">↑</a><a class="lpdoc-navbutton" href="basiccontrol.html">←</a><a class="lpdoc-navbutton" href="term_typing.html">→</a><a class="lpdoc-navbutton" href="ciaosearch.html">🔍</a></span><span><a href="ciaofulltoc.html">TOC</a></span></div><hr></hr><ul class="lpdoc-itemize-sectpath"><li><a href="ciao.html">The Ciao System</a> »<br/> </li><li><a href="BasicLang.html">PART II - The Ciao basic language</a> »<br/> </li><li><a href=""><strong>Exception and signal handling</strong></a></li></ul><hr></hr><em>ON THIS PAGE</em><ul><li><a href="#Usage and interface">Usage and interface</a></li><li><a href="#Documentation on exports">Documentation on exports</a></li><li><a href="#Documentation on imports">Documentation on imports</a></li></ul></div><div class="lpdoc-main"><div id=""><h1>Exception and signal handling</h1><a class="lpdoc-idx-anchor" href="ciaosearch.html#exceptions"></a> <strong>Author(s):</strong> <a class="lpdoc-idx-anchor" id="The Ciao Development Team" href="ciaosearch.html#The Ciao Development Team">The Ciao Development Team</a>, <a class="lpdoc-idx-anchor" id="Jose F. Morales" href="ciaosearch.html#Jose F. Morales">Jose F. Morales (global vars version)</a>.<p> This module includes predicates related to exceptions and signals, which alter the normal flow of execution.<br/><div id="Usage and interface"><h2>Usage and interface</h2><div class="lpdoc-cartouche"><ul><li><strong>Library usage:</strong><br/>This module is imported by default (unless the <a class="lpdoc-idx-anchor" id="0" href="noprelude_doc.html"><tt>noprelude</tt></a> or <a class="lpdoc-idx-anchor" id="1" href="pure_doc.html"><tt>pure</tt></a> packages are used). <li><strong>Exports:</strong><br/><ul class="lpdoc-itemize-minus"><li><em>Predicates:</em><br/><a class="lpdoc-idx-anchor" id="2" href="#catch/3"><tt>catch/3</tt></a>, <a class="lpdoc-idx-anchor" id="3" href="#intercept/3"><tt>intercept/3</tt></a>, <a class="lpdoc-idx-anchor" id="4" href="#throw/1"><tt>throw/1</tt></a>, <a class="lpdoc-idx-anchor" id="5" href="#send_signal/1"><tt>send_signal/1</tt></a>, <a class="lpdoc-idx-anchor" id="6" href="#send_signal/2"><tt>send_signal/2</tt></a>, <a class="lpdoc-idx-anchor" id="7" href="#halt/0"><tt>halt/0</tt></a>, <a class="lpdoc-idx-anchor" id="8" href="#halt/1"><tt>halt/1</tt></a>, <a class="lpdoc-idx-anchor" id="9" href="#abort/0"><tt>abort/0</tt></a>. </ul></ul></div></div><div id="Documentation on exports"><h2>Documentation on exports</h2><div><div class="lpdoc-defname"><span class="lpdoc-predtag">PREDICATE</span><a class="lpdoc-idx-anchor" id="catch/3" href="ciaosearch.html#catch/3">catch/3</a></div><div class="lpdoc-deftext"><span class="lpdoc-usage-decl"><tt>catch(Goal,Error,Handler)</tt> </span><p>Executes <span class="lpdoc-var">Goal</span>. If an exception is raised during its execution, <span class="lpdoc-var">Error</span> is unified with the exception, and if the unification succeeds, the entire execution derived from <span class="lpdoc-var">Goal</span> is aborted, and <span class="lpdoc-var">Handler</span> is executed. The execution resumes with the continuation of the <tt>catch/3</tt> call. For example, given the code <pre class="lpdoc-codeblock">p(X) :- throw(error), display('---'). p(X) :- display(X). </pre> the execution of "<tt>catch(p(0), E, display(E)), display(.), fail.</tt>" results in the output "<tt>error.</tt>".<p><span class="lpdoc-usage-header">Usage:</span><span class="lpdoc-usage-decl"><span class="lpdoc-on-right"><span class="lpdoc-iso">ISO</span></span><span></span> </span><p></p><ul class="lpdoc-itemize-minus"><li><em>Calls should, and exit will be compatible with:</em><br/><span class="lpdoc-on-right"> (<a class="lpdoc-idx-anchor" id="10" href="basic_props.html#term/1"><tt>basic_props:term/1</tt></a>)</span><span><span class="lpdoc-var">Error</span> is any term. </span><br/><span class="lpdoc-on-right"> (<a class="lpdoc-idx-anchor" id="11" href="basic_props.html#cgoal/1"><tt>basic_props:cgoal/1</tt></a>)</span><span><span class="lpdoc-var">Handler</span> is a term which represents a goal, i.e., an atom or a structure. </span> <li><em>The following properties should hold at call time:</em><br/><span class="lpdoc-on-right"> (<a class="lpdoc-idx-anchor" id="12" href="basic_props.html#cgoal/1"><tt>basic_props:cgoal/1</tt></a>)</span><span><span class="lpdoc-var">Goal</span> is a term which represents a goal, i.e., an atom or a structure. </span> <li><em>The following properties hold upon exit:</em><br/><span class="lpdoc-on-right"> (<a class="lpdoc-idx-anchor" id="13" href="basic_props.html#term/1"><tt>basic_props:term/1</tt></a>)</span><span><span class="lpdoc-var">Error</span> is any term. </span><br/><span class="lpdoc-on-right"> (<a class="lpdoc-idx-anchor" id="14" href="basic_props.html#cgoal/1"><tt>basic_props:cgoal/1</tt></a>)</span><span><span class="lpdoc-var">Handler</span> is a term which represents a goal, i.e., an atom or a structure. </span> <li><em>The following properties hold globally:</em><br/><span class="lpdoc-on-right"> (<a class="lpdoc-idx-anchor" id="15" href="basic_props.html#native/1"><tt>basic_props:native/1</tt></a>)</span><span>This predicate is understood natively by CiaoPP. </span> </ul> <em>Meta-predicate</em> with arguments: <tt>catch(goal,?,goal)</tt>.<br/></div></div><p> <div><div class="lpdoc-defname"><span class="lpdoc-predtag">PREDICATE</span><a class="lpdoc-idx-anchor" id="intercept/3" href="ciaosearch.html#intercept/3">intercept/3</a></div><div class="lpdoc-deftext"><span class="lpdoc-usage-decl"><tt>intercept(Goal,Signal,Handler)</tt> </span><p>Executes <span class="lpdoc-var">Goal</span>. If a signal is sent during its execution, <span class="lpdoc-var">Signal</span> is unified with the exception, and if the unification succeeds, <span class="lpdoc-var">Handler</span> is executed and then the execution resumes after the point where the exception was thrown. To avoid infinite loops if <span class="lpdoc-var">Handler</span> raises an exception which unifies with <span class="lpdoc-var">Error</span>, the exception handler is deactivated before executing <span class="lpdoc-var">Handler</span>. Note the difference with builtin <a class="lpdoc-idx-anchor" id="16" href="#catch/3"><tt>catch/3</tt></a>, given the code <pre class="lpdoc-codeblock">p(X) :- send_signal(error), display('---'). p(X) :- display(X). </pre> the execution of "<tt>intercept(p(0), E, display(E)), display(.), fail.</tt>" results in the output "<tt>error---.0.</tt>".<p><span class="lpdoc-usage-header">Usage:</span><p></p><ul class="lpdoc-itemize-minus"><li><em>Call and exit should be compatible with:</em><br/><span class="lpdoc-on-right"> (<a class="lpdoc-idx-anchor" id="17" href="basic_props.html#term/1"><tt>basic_props:term/1</tt></a>)</span><span><span class="lpdoc-var">Signal</span> is any term. </span> <li><em>The following properties should hold at call time:</em><br/><span class="lpdoc-on-right"> (<a class="lpdoc-idx-anchor" id="18" href="basic_props.html#cgoal/1"><tt>basic_props:cgoal/1</tt></a>)</span><span><span class="lpdoc-var">Goal</span> is a term which represents a goal, i.e., an atom or a structure. </span><br/><span class="lpdoc-on-right"> (<a class="lpdoc-idx-anchor" id="19" href="basic_props.html#cgoal/1"><tt>basic_props:cgoal/1</tt></a>)</span><span><span class="lpdoc-var">Handler</span> is a term which represents a goal, i.e., an atom or a structure. </span> <li><em>The following properties should hold upon exit:</em><br/><span class="lpdoc-on-right"> (<a class="lpdoc-idx-anchor" id="20" href="basic_props.html#term/1"><tt>basic_props:term/1</tt></a>)</span><span><span class="lpdoc-var">Signal</span> is any term. </span> </ul> <em>Meta-predicate</em> with arguments: <tt>intercept(goal,?,goal)</tt>.<br/></div></div><p> <div><div class="lpdoc-defname"><span class="lpdoc-predtag">PREDICATE</span><a class="lpdoc-idx-anchor" id="throw/1" href="ciaosearch.html#throw/1">throw/1</a></div><div class="lpdoc-deftext"><span class="lpdoc-usage-decl"><tt>throw(Ball)</tt> </span><p>Raises an error, throwing the exception <span class="lpdoc-var">Ball</span>, to be caught by an ancestor <a class="lpdoc-idx-anchor" id="21" href="#catch/3"><tt>catch/3</tt></a>. The closest matching ancestor is chosen. In addition to calls to <a class="lpdoc-idx-anchor" id="22" href="ciaosearch.html#throw/2"><tt>throw/2</tt></a> in user code, exceptions are also thrown by many library predicates in cases of error.<p><span class="lpdoc-usage-header">Usage:</span><span class="lpdoc-usage-decl"><span class="lpdoc-on-right"><span class="lpdoc-iso">ISO</span></span><span><tt>throw(Term)</tt></span> </span><p></p><ul class="lpdoc-itemize-minus"><li><em>The following properties should hold at call time:</em><br/><span class="lpdoc-on-right"> (<a class="lpdoc-idx-anchor" id="23" href="term_typing.html#nonvar/1"><tt>term_typing:nonvar/1</tt></a>)</span><span><span class="lpdoc-var">Term</span> is currently a term which is not a free variable. </span> <li><em>The following properties hold globally:</em><br/><span class="lpdoc-on-right"> (<a class="lpdoc-idx-anchor" id="24" href="basic_props.html#equiv/2"><tt>basic_props:equiv/2</tt></a>)</span><span><span class="lpdoc-var">throw(Term)</span> is equivalent to <span class="lpdoc-var">fail</span>. </span> </ul></div></div><p> <div><div class="lpdoc-defname"><span class="lpdoc-predtag">PREDICATE</span><a class="lpdoc-idx-anchor" id="send_signal/1" href="ciaosearch.html#send_signal/1">send_signal/1</a></div><div class="lpdoc-deftext"><span class="lpdoc-usage-decl"><tt>send_signal(Signal)</tt> </span><p>Emits a signal, to be intercepted by an ancestor <a class="lpdoc-idx-anchor" id="25" href="#intercept/3"><tt>intercept/3</tt></a>. The closest matching ancestor is chosen. If the signal is not intercepted, the following error is thrown: <tt>error(unintercepted_signal(Signal), send_signal/1-1)</tt>.<p><span class="lpdoc-usage-header">Usage:</span><span class="lpdoc-usage-decl"><tt>send_signal(Term)</tt> </span><p></p><ul class="lpdoc-itemize-minus"><li><em>The following properties should hold at call time:</em><br/><span class="lpdoc-on-right"> (<a class="lpdoc-idx-anchor" id="26" href="term_typing.html#nonvar/1"><tt>term_typing:nonvar/1</tt></a>)</span><span><span class="lpdoc-var">Term</span> is currently a term which is not a free variable. </span> </ul></div></div><p> <div><div class="lpdoc-defname"><span class="lpdoc-predtag">PREDICATE</span><a class="lpdoc-idx-anchor" id="send_signal/2" href="ciaosearch.html#send_signal/2">send_signal/2</a></div><div class="lpdoc-deftext"><span class="lpdoc-usage-decl"><tt>send_signal(Signal,Intercepted)</tt> </span><p>Emits a signal as <a class="lpdoc-idx-anchor" id="27" href="#send_signal/1"><tt>send_signal/1</tt></a>, <tt>Intercepted=false</tt> if the signal is not intercepted (i.e. just suceeds) or <tt>true</tt> otherwise.<p><span class="lpdoc-usage-header">Usage:</span><span class="lpdoc-usage-decl"><tt>send_signal(Term,Intercepted)</tt> </span><p></p><ul class="lpdoc-itemize-minus"><li><em>The following properties should hold at call time:</em><br/><span class="lpdoc-on-right"> (<a class="lpdoc-idx-anchor" id="28" href="term_typing.html#nonvar/1"><tt>term_typing:nonvar/1</tt></a>)</span><span><span class="lpdoc-var">Term</span> is currently a term which is not a free variable. </span> </ul></div></div><p> <div><div class="lpdoc-defname"><span class="lpdoc-predtag">PREDICATE</span><a class="lpdoc-idx-anchor" id="halt/0" href="ciaosearch.html#halt/0">halt/0</a></div><div class="lpdoc-deftext"><span class="lpdoc-usage-decl"><tt>halt</tt> </span><p>Halt the system, exiting to the invoking shell.<p><span class="lpdoc-usage-header">Usage:</span><span class="lpdoc-usage-decl"><span class="lpdoc-on-right"><span class="lpdoc-iso">ISO</span></span><span></span> </span><p></p><ul class="lpdoc-itemize-minus"><li><em>The following properties should hold globally:</em><br/><span class="lpdoc-on-right"> (<a class="lpdoc-idx-anchor" id="29" href="basic_props.html#native/1"><tt>basic_props:native/1</tt></a>)</span><span>This predicate is understood natively by CiaoPP. </span> </ul></div></div><p> <div><div class="lpdoc-defname"><span class="lpdoc-predtag">PREDICATE</span><a class="lpdoc-idx-anchor" id="halt/1" href="ciaosearch.html#halt/1">halt/1</a></div><div class="lpdoc-deftext"><span class="lpdoc-usage-decl"><tt>halt(Code)</tt> </span><p>Halt the system, exiting to the invoking shell, returning exit code <span class="lpdoc-var">Code</span>.<p><span class="lpdoc-usage-header">Usage:</span><span class="lpdoc-usage-decl"><span class="lpdoc-on-right"><span class="lpdoc-iso">ISO</span></span><span></span> </span><p></p><ul class="lpdoc-itemize-minus"><li><em>The following properties should hold at call time:</em><br/><span class="lpdoc-on-right"> (<a class="lpdoc-idx-anchor" id="30" href="basic_props.html#int/1"><tt>basic_props:int/1</tt></a>)</span><span><span class="lpdoc-var">Code</span> is an integer. </span> <li><em>The following properties should hold upon exit:</em><br/><span class="lpdoc-on-right"> (<a class="lpdoc-idx-anchor" id="31" href="basic_props.html#int/1"><tt>basic_props:int/1</tt></a>)</span><span><span class="lpdoc-var">Code</span> is an integer. </span> <li><em>The following properties should hold globally:</em><br/><span class="lpdoc-on-right"> (<a class="lpdoc-idx-anchor" id="32" href="basic_props.html#equiv/2"><tt>basic_props:equiv/2</tt></a>)</span><span><span class="lpdoc-var">halt(Code)</span> is equivalent to <span class="lpdoc-var">fail</span>. </span> </ul></div></div><p> <div><div class="lpdoc-defname"><span class="lpdoc-predtag">PREDICATE</span><a class="lpdoc-idx-anchor" id="abort/0" href="ciaosearch.html#abort/0">abort/0</a></div><div class="lpdoc-deftext"><span class="lpdoc-usage-decl"><tt>abort</tt> </span><p>Abort the current execution.</div></div><p> </div><div id="Documentation on imports"><h2>Documentation on imports</h2>This module has the following direct dependencies:<ul class="lpdoc-itemize-minus"><li><em>System library modules:</em><br/><a class="lpdoc-idx-anchor" id="33" href="datafacts_rt.html"><tt>datafacts_rt</tt></a>. <li><em>Packages:</em><br/><a class="lpdoc-idx-anchor" id="34" href="ciaosearch.html#prelude"><tt>prelude</tt></a>, <a class="lpdoc-idx-anchor" id="35" href="ciaosearch.html#initial"><tt>initial</tt></a>, <a class="lpdoc-idx-anchor" id="36" href="condcomp_doc.html"><tt>condcomp</tt></a>, <a class="lpdoc-idx-anchor" id="37" href="assertions_doc.html"><tt>assertions</tt></a>, <a class="lpdoc-idx-anchor" id="38" href="ciaosearch.html#assertions/assertions_basic"><tt>assertions/assertions_basic</tt></a>, <a class="lpdoc-idx-anchor" id="39" href="ciaosearch.html#nortchecks"><tt>nortchecks</tt></a>, <a class="lpdoc-idx-anchor" id="40" href="isomodes_doc.html"><tt>isomodes</tt></a>, <a class="lpdoc-idx-anchor" id="41" href="datafacts_doc.html"><tt>datafacts</tt></a>. </ul></div></div><div class="lpdoc-footer">Generated with LPdoc using Ciao</div></div><div class="lpdoc-clearer"></div></div></body></html>