@ciao-lang/ts-ciao-interface
Version:
Simple Ciao interface for node.
8 lines (7 loc) • 12.6 kB
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>Run-time checking of assertions — The CiaoPP Program Processor v1.5</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="part_assertions.html">↑</a><a class="lpdoc-navbutton" href="native_props_cost_doc.html">←</a><a class="lpdoc-navbutton" href="apply_assertions.html">→</a><a class="lpdoc-navbutton" href="ciaopp_ref_mansearch.html">🔍</a></span><span><a href="ciaopp_ref_manfulltoc.html">TOC</a></span></div><hr></hr><ul class="lpdoc-itemize-sectpath"><li><a href="ciaopp_ref_man.html">The CiaoPP Program Processor</a> »<br/> </li><li><a href="part_assertions.html">PART II - The Assertion Language and Its Use</a> »<br/> </li><li><a href=""><strong>Run-time checking of assertions</strong></a></li></ul><hr></hr><em>ON THIS PAGE</em><ul><li><a href="#Run-time checks configuration with flags">Run-time checks configuration with flags</a></li><li><a href="#Custom implementation for property checks">Custom implementation for property checks</a></li><li><a href="#Usage and interface">Usage and interface</a></li><li><a href="#Other information">Other information</a></li></ul></div><div class="lpdoc-main"><div id=""><h1>Run-time checking of assertions</h1><a class="lpdoc-idx-anchor" href="ciaopp_ref_mansearch.html#rtchecks"></a>
<strong>Author(s):</strong> <a class="lpdoc-idx-anchor" id="Edison Mera" href="ciaopp_ref_mansearch.html#Edison Mera">Edison Mera</a>, <a class="lpdoc-idx-anchor" id="Nataliia Stulova" href="ciaopp_ref_mansearch.html#Nataliia Stulova">Nataliia Stulova</a>.<p>
<strong>Stability: [</strong><strong>beta</strong><strong>] </strong>Most of the functionality is there but it is still missing some testing and/or verification.<p><br/>
This package provides a complete implementation of run-time checks of predicate assertions. The program is instrumented to check such assertions at run time, and in case a property does not hold, the error is reported. Note that there is also an older package called rtchecks, by David Trallero. The advantage of this one is that it can be used independently of CiaoPP and also has updated functionality.<p>There are two main applications of run-time checks:<p><ul> <p><li>To improve debugging of certain predicates, specifying some expected behavior that is checked at run-time with the assertions.<p><li>To avoid manual implementation of run-time checks that should be done in some predicates, leaving the code clean and understandable.<p></ul> <p><div id="Run-time checks configuration with flags"><h2>Run-time checks configuration with flags</h2> <p>The run-time checks can be configured using prolog flags. Below we itemize the valid prolog flags with its values and a brief explanation of the meaning:<p><ul> <p><li><a class="lpdoc-idx-anchor" id="0" href="ciaopp_ref_mansearch.html#rtchecks_level"><tt>rtchecks_level</tt></a> <ul> <li><a class="lpdoc-idx-anchor" id="1" href="ciaopp_ref_mansearch.html#exports"><tt>exports</tt></a>: Only use rtchecks for external calls of the exported predicates. <li><a class="lpdoc-idx-anchor" id="2" href="ciaopp_ref_mansearch.html#inner"><tt>inner</tt></a> : Use also rtchecks for internal calls. Default. </ul> <p><li><a class="lpdoc-idx-anchor" id="3" href="ciaopp_ref_mansearch.html#rtchecks_trust"><tt>rtchecks_trust</tt></a> <ul> <li><a class="lpdoc-idx-anchor" id="4" href="ciaopp_ref_mansearch.html#no"><tt>no</tt></a> : Disable rtchecks for trust assertions. <li><a class="lpdoc-idx-anchor" id="5" href="ciaopp_ref_mansearch.html#yes"><tt>yes</tt></a> : Enable rtchecks for trust assertions. Default. </ul> <p><li><a class="lpdoc-idx-anchor" id="6" href="ciaopp_ref_mansearch.html#rtchecks_entry"><tt>rtchecks_entry</tt></a> <ul> <li><a class="lpdoc-idx-anchor" id="7" href="ciaopp_ref_mansearch.html#no"><tt>no</tt></a> : Disable rtchecks for entry assertions. <li><a class="lpdoc-idx-anchor" id="8" href="ciaopp_ref_mansearch.html#yes"><tt>yes</tt></a> : Enable rtchecks for entry assertions. Default. </ul> <p><li><a class="lpdoc-idx-anchor" id="9" href="ciaopp_ref_mansearch.html#rtchecks_exit"><tt>rtchecks_exit</tt></a> <ul> <li><a class="lpdoc-idx-anchor" id="10" href="ciaopp_ref_mansearch.html#no"><tt>no</tt></a> : Disable rtchecks for exit assertions. <li><a class="lpdoc-idx-anchor" id="11" href="ciaopp_ref_mansearch.html#yes"><tt>yes</tt></a> : Enable rtchecks for exit assertions. Default. </ul> <p><li><a class="lpdoc-idx-anchor" id="12" href="ciaopp_ref_mansearch.html#rtchecks_test"><tt>rtchecks_test</tt></a> <ul> <li><a class="lpdoc-idx-anchor" id="13" href="ciaopp_ref_mansearch.html#no"><tt>no</tt></a> : Disable rtchecks for test assertions. Default. <li><a class="lpdoc-idx-anchor" id="14" href="ciaopp_ref_mansearch.html#yes"><tt>yes</tt></a> : Enable rtchecks for test assertions. Used for debugging purposes, but is better to use the unittest library. </ul> <p><li><a class="lpdoc-idx-anchor" id="15" href="ciaopp_ref_mansearch.html#rtchecks_asrloc"><tt>rtchecks_asrloc</tt></a> Controls the usage of locators for the assertions in the error messages. The locator says the file and lines that contains the assertion that had failed. Valid values are: <ul> <li><a class="lpdoc-idx-anchor" id="16" href="ciaopp_ref_mansearch.html#no"><tt>no</tt></a> : Disabled. <li><a class="lpdoc-idx-anchor" id="17" href="ciaopp_ref_mansearch.html#yes"><tt>yes</tt></a> : Enabled. Default. </ul> <p><li><a class="lpdoc-idx-anchor" id="18" href="ciaopp_ref_mansearch.html#rtchecks_predloc"><tt>rtchecks_predloc</tt></a> Controls the usage of locators for the predicate that caused the run-time check error. The locator says the first clause of the predicate that the violated assertion refers to. <ul> <li><a class="lpdoc-idx-anchor" id="19" href="ciaopp_ref_mansearch.html#no"><tt>no</tt></a> : Disabled. <li><a class="lpdoc-idx-anchor" id="20" href="ciaopp_ref_mansearch.html#yes"><tt>yes</tt></a> : Enabled, Default. </ul> <p><li><a class="lpdoc-idx-anchor" id="21" href="ciaopp_ref_mansearch.html#rtchecks_callloc"><tt>rtchecks_callloc</tt></a> <ul> <li><a class="lpdoc-idx-anchor" id="22" href="ciaopp_ref_mansearch.html#no"><tt>no</tt></a> : Do not show the stack of predicates that caused the failure <li><a class="lpdoc-idx-anchor" id="23" href="ciaopp_ref_mansearch.html#predicate"><tt>predicate</tt></a>: Show the stack of predicates that caused the failure. Instrument it in the predicate. Default. <li><a class="lpdoc-idx-anchor" id="24" href="ciaopp_ref_mansearch.html#literal"><tt>literal</tt></a> : Show the stack of predicates that caused the failure. Instrument it in the literal. This mode provides more information, because reports also the literal in the body of the predicate. </ul> <p><li><a class="lpdoc-idx-anchor" id="25" href="ciaopp_ref_mansearch.html#rtchecks_namefmt"><tt>rtchecks_namefmt</tt></a> <ul> <li><a class="lpdoc-idx-anchor" id="26" href="ciaopp_ref_mansearch.html#long"><tt>long</tt></a> : Show the name of predicates, properties and the values of the variables. Default. <li><a class="lpdoc-idx-anchor" id="27" href="ciaopp_ref_mansearch.html#short"><tt>short</tt></a> : Only show the name of the predicate in a reduced format. </ul> <p></ul> <p></div><div id="Custom implementation for property checks"><h2>Custom implementation for property checks</h2> <p><div class="lpdoc-note"> <strong>Note:</strong> this is a new feature and under active development. The documentation may be partial/obsolete. </div> <p>The run-time check instrumentation can use custom property checks implementations. This is useful when defining native properties (without a clause-based definition supported by the default instrumentation) or when the generic run-time checks are not efficient enough. The custom implementation can be used specifically in run-time checks, while keeping a declarative version (which might be easier to read or is better understood by some static analyzer).<p>To provide the custom property implementation for run-time checking it is recommended to edit two files (suppose the original property is defined in a module <a class="lpdoc-idx-anchor" id="28" href="ciaopp_ref_mansearch.html#foo.pl"><tt>foo.pl</tt></a>):<p><ul> <p><li>the <a class="lpdoc-idx-anchor" id="29" href="ciaopp_ref_mansearch.html#foo_rtc.pl"><tt>foo_rtc.pl</tt></a> module that contains the custom property implementation and is placed in the same folder as <a class="lpdoc-idx-anchor" id="30" href="ciaopp_ref_mansearch.html#foo.pl"><tt>foo.pl</tt></a>. Make sure the custom property implementation is exported from both modules.<p><li><a class="lpdoc-idx-anchor" id="31" href="ciaopp_ref_mansearch.html#$CIAOROOT/core/lib/rtchecks/rtchecks_rt_propimpl.pl"><tt>$CIAOROOT/core/lib/rtchecks/rtchecks_rt_propimpl.pl</tt></a>, a database file that stores the links between different property implementations in the format of declarations '<tt>:- rtc_impl(ModOr:PropOr/ArityOr, ModRt:PropRt/ArityRt).</tt>' where <span class="lpdoc-var">ModOr</span> and <span class="lpdoc-var">ModRt</span> are names of the two modules that contain the original and the custom property definitions, <span class="lpdoc-var">PropOr</span> and <span class="lpdoc-var">PropRt</span> are the two different property implementations with respective arities <span class="lpdoc-var">ArityOr</span> and <span class="lpdoc-var">ArityRt</span>.<p></ul> <p>After these edits the <a class="lpdoc-idx-anchor" id="32" href=""><tt>rtchecks</tt></a> library needs to be rebuilt.<p>For an example of a system library that uses this feature see the <a class="lpdoc-idx-anchor" id="33" href="ciaopp_ref_mansearch.html#assertions/native_props"><tt>assertions/native_props</tt></a> library.<p></div><br/><div id="Usage and interface"><h2>Usage and interface</h2><div class="lpdoc-cartouche"><ul><li><strong>Library usage:</strong><br/>:- module(...,...,[...,rtchecks]).<li><strong>Implicit imports:</strong><br/><ul class="lpdoc-itemize-minus"><li><em>Internal (engine) modules:</em><br/><a class="lpdoc-idx-anchor" id="34" href="ciaopp_ref_mansearch.html#term_basic"><tt>term_basic</tt></a>, <a class="lpdoc-idx-anchor" id="35" href="ciaopp_ref_mansearch.html#arithmetic"><tt>arithmetic</tt></a>, <a class="lpdoc-idx-anchor" id="36" href="ciaopp_ref_mansearch.html#atomic_basic"><tt>atomic_basic</tt></a>, <a class="lpdoc-idx-anchor" id="37" href="ciaopp_ref_mansearch.html#basiccontrol"><tt>basiccontrol</tt></a>, <a class="lpdoc-idx-anchor" id="38" href="ciaopp_ref_mansearch.html#exceptions"><tt>exceptions</tt></a>, <a class="lpdoc-idx-anchor" id="39" href="ciaopp_ref_mansearch.html#term_compare"><tt>term_compare</tt></a>, <a class="lpdoc-idx-anchor" id="40" href="ciaopp_ref_mansearch.html#term_typing"><tt>term_typing</tt></a>, <a class="lpdoc-idx-anchor" id="41" href="ciaopp_ref_mansearch.html#debugger_support"><tt>debugger_support</tt></a>, <a class="lpdoc-idx-anchor" id="42" href="basic_props.html"><tt>basic_props</tt></a>.
<li><em>Packages:</em><br/><a class="lpdoc-idx-anchor" id="43" href="ciaopp_ref_mansearch.html#prelude"><tt>prelude</tt></a>, <a class="lpdoc-idx-anchor" id="44" href="ciaopp_ref_mansearch.html#initial"><tt>initial</tt></a>, <a class="lpdoc-idx-anchor" id="45" href="ciaopp_ref_mansearch.html#condcomp"><tt>condcomp</tt></a>, <a class="lpdoc-idx-anchor" id="46" href="assertions_doc.html"><tt>assertions</tt></a>, <a class="lpdoc-idx-anchor" id="47" href="ciaopp_ref_mansearch.html#assertions/assertions_basic"><tt>assertions/assertions_basic</tt></a>.
</ul></ul></div></div><div id="Other information"><h2>Other information</h2>
<div class="lpdoc-note"> <strong>Note:</strong> the <tt>assertions</tt> package must always be included together with the <tt>rtchecks</tt> package (see <tt>core/lib/compiler/global_module_options.pl</tt> for details). </div><br/></div></div><div class="lpdoc-footer">Generated with LPdoc using Ciao</div></div><div class="lpdoc-clearer"></div></div></body></html>