@ciao-lang/ts-ciao-interface

Version:

Simple Ciao interface for node.

49 lines • 20 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>Packages and language extension — 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="bundles_doc.html">←</a><a class="lpdoc-navbutton" href="condcomp_doc.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>Packages and language extension</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 internals">Documentation on internals</a></li><li><a href="#Documentation on imports">Documentation on imports</a></li></ul></div><div class="lpdoc-main"><div id=""><h1>Packages and language extension</h1><a class="lpdoc-idx-anchor" href="ciaosearch.html#packages"></a> <strong>Author(s):</strong> <a class="lpdoc-idx-anchor" id="Daniel Cabeza" href="ciaosearch.html#Daniel Cabeza">Daniel Cabeza</a>, <a class="lpdoc-idx-anchor" id="The Ciao Development Team" href="ciaosearch.html#The Ciao Development Team">The Ciao Development Team</a>.<p> This chapter documents <a class="lpdoc-idx-anchor" id="0" href="ciaosearch.html#package file">package file</a>s and the main <a class="lpdoc-idx-anchor" id="1" href="ciaosearch.html#builtin directives">builtin directives</a> that Ciao provides for implementing syntactic and semantic language extensions.<p>These directives allow the definition of new operators, new declarations, code translations, etc. Although these directives can be used directly in any source file, it is highly recommended to group them into <a class="lpdoc-idx-anchor" id="2" href="ciaosearch.html#package">package</a>s, where each package contains a set of operators and transformations that together provide a particular syntactic and semantic extension to the modules that load it. Most Ciao extensions, such as functional syntax, constraint solving, or breadth-first search are implemented as packages. The structure and code of these Ciao library packages can serve as useful examples of how to build packages in general.<p>See also [<a class="lpdoc-idx-anchor" id="3" href="ciaorefs.html#ciao-modules-cl2000">CH00a</a>] for a detailed description of the Ciao module system and, in particular, packages and the language extension primitives.<p><br/><div id="Usage and interface"><h2>Usage and interface</h2><div class="lpdoc-cartouche"><ul><li><strong>Library usage:</strong><br/>These directives are builtin in Ciao, so nothing special has to be done to use them.</ul></div></div><div id="Documentation on internals"><h2>Documentation on internals</h2><div><div class="lpdoc-defname"><span class="lpdoc-predtag">DECLARATION</span><a class="lpdoc-idx-anchor" id="package/1" href="ciaosearch.html#package/1">package/1</a></div><div class="lpdoc-deftext"><p><span class="lpdoc-usage-header">Usage:</span><span class="lpdoc-usage-decl">:- <tt>package(Name)</tt>. </span><p>Declares the current file to be a package of name <span class="lpdoc-var">Name</span>. Like in modules, <span class="lpdoc-var">Name</span> must match the name of the file where the package resides, without extension. This directive must appear first in the file.</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="4" href="modules.html#modulename/1"><tt>modules:modulename/1</tt></a>)</span><span><span class="lpdoc-var">Name</span> is a module name (an atom). </span> </ul></div></div><p> <div><div class="lpdoc-defname"><span class="lpdoc-predtag">DECLARATION</span><a class="lpdoc-idx-anchor" id="op/3" href="ciaosearch.html#op/3">op/3</a></div><div class="lpdoc-deftext"><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>op(Priority,Op_spec,Operator)</tt>.</span> </span><p>Updates the <a class="lpdoc-idx-anchor" id="5" href="ciaosearch.html#operator table">operator table</a> for reading the terms in the rest of the current text, in the same way as the builtin <a class="lpdoc-idx-anchor" id="6" href="#op/3"><tt>op/3</tt></a> does. Its scope is local to the current text. Usually included in <a class="lpdoc-idx-anchor" id="7" href="ciaosearch.html#package file">package file</a>s.</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="8" href="basic_props.html#int/1"><tt>basic_props:int/1</tt></a>)</span><span><span class="lpdoc-var">Priority</span> is an integer. </span><br/><span class="lpdoc-on-right"> (<a class="lpdoc-idx-anchor" id="9" href="basic_props.html#operator_specifier/1"><tt>basic_props:operator_specifier/1</tt></a>)</span><span><span class="lpdoc-var">Op_spec</span> specifies the type and associativity of an operator. </span><br/><span class="lpdoc-on-right"> (<a class="lpdoc-idx-anchor" id="10" href="basic_props.html#atm_or_atm_list/1"><tt>basic_props:atm_or_atm_list/1</tt></a>)</span><span><span class="lpdoc-var">Operator</span> is an atom or a list of atoms. </span> </ul></div></div><p> <div><div class="lpdoc-defname"><span class="lpdoc-predtag">DECLARATION</span><a class="lpdoc-idx-anchor" id="new_declaration/1" href="ciaosearch.html#new_declaration/1">new_declaration/1</a></div><div class="lpdoc-deftext"><p><span class="lpdoc-usage-header">Usage:</span><span class="lpdoc-usage-decl">:- <tt>new_declaration(Predicate)</tt>. </span><p>Declares <span class="lpdoc-var">Predicate</span> to be a valid declaration in the rest of the current text. Such declarations are simply ignored by the compiler or top level, but can be used by other code processing programs such as an automatic documentator. Also, they can easily translated into standard code (a set of facts and/or rules) by defining a suitable <a class="lpdoc-idx-anchor" id="11" href="ciaosearch.html#expansion">expansion</a> (e.g., by <a class="lpdoc-idx-anchor" id="12" href="ciaosearch.html#add_sentence_trans/1"><tt>add_sentence_trans/1</tt></a>, etc.). This is tipically done in <a class="lpdoc-idx-anchor" id="13" href="ciaosearch.html#package file">package file</a>s.<p>Equivalent to <tt>new_declaration(Predicate, off)</tt>.</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="14" href="basic_props.html#predname/1"><tt>basic_props:predname/1</tt></a>)</span><span><span class="lpdoc-var">Predicate</span> is a predicate name. </span> </ul></div></div><p> <div><div class="lpdoc-defname"><span class="lpdoc-predtag">DECLARATION</span><a class="lpdoc-idx-anchor" id="new_declaration/2" href="ciaosearch.html#new_declaration/2">new_declaration/2</a></div><div class="lpdoc-deftext"><p><span class="lpdoc-usage-header">Usage:</span><span class="lpdoc-usage-decl">:- <tt>new_declaration(Predicate,In_Itf)</tt>. </span><p>Declares <span class="lpdoc-var">Predicate</span> to be a valid declaration in the rest of the current text. Such declarations will be included in the <a class="lpdoc-idx-anchor" id="15" href="ciaosearch.html#interface file">interface file</a> for this file if <span class="lpdoc-var">In_Itf</span> is 'on', not if it is 'off'. Including such declarations in interface files makes them visible while processing other modules which make use of this one.</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="16" href="basic_props.html#predname/1"><tt>basic_props:predname/1</tt></a>)</span><span><span class="lpdoc-var">Predicate</span> is a predicate name. </span><br/><span class="lpdoc-on-right"> (<a class="lpdoc-idx-anchor" id="17" href="ciaosearch.html#switch/1"><tt>packages:switch/1</tt></a>)</span><span><span class="lpdoc-var">In_Itf</span> is 'on' or 'off' </span> </ul></div></div><p> <div><div class="lpdoc-defname"><span class="lpdoc-predtag">DECLARATION</span><a class="lpdoc-idx-anchor" id="load_compilation_module/1" href="ciaosearch.html#load_compilation_module/1">load_compilation_module/1</a></div><div class="lpdoc-deftext"><p><span class="lpdoc-usage-header">Usage:</span><span class="lpdoc-usage-decl">:- <tt>load_compilation_module(File)</tt>. </span><p>Loads code defined in <span class="lpdoc-var">File</span> into the compiler, usually including predicates which define translations of clauses, sentences, and terms, for use with the declarations <a class="lpdoc-idx-anchor" id="18" href="#add_sentence_trans/2"><tt>add_sentence_trans/2</tt></a> and similar ones. The application order of translations is determined by ascending <em>priority</em> numbers. Normally included in <a class="lpdoc-idx-anchor" id="19" href="ciaosearch.html#package file">package file</a>s.</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="20" href="stream_basic.html#sourcename/1"><tt>stream_basic:sourcename/1</tt></a>)</span><span><span class="lpdoc-var">File</span> is a source name. </span> </ul></div></div><p> <div><div class="lpdoc-defname"><span class="lpdoc-predtag">DECLARATION</span><a class="lpdoc-idx-anchor" id="add_sentence_trans/2" href="ciaosearch.html#add_sentence_trans/2">add_sentence_trans/2</a></div><div class="lpdoc-deftext"><p><span class="lpdoc-usage-header">Usage:</span><span class="lpdoc-usage-decl">:- <tt>add_sentence_trans(Predicate,Priority)</tt>. </span><p>Starts a translation, defined by <span class="lpdoc-var">Predicate</span>, of the terms read by the compiler in the rest of the current text. For each subsequent term read by the compiler, the translation predicate is called to obtain a new term which will be used by the compiler as if it where the term present in the file. If the call fails, the term is used as such. A list may be returned also, to translate a single term into several terms. Before calling the translation predicate with actual program terms, it is called with an input of <tt>0</tt> to give an opportunity of making initializations for the module, discarding the result (note that normally a 0 could not be there). <span class="lpdoc-var">Predicate</span> must be exported by a module previously loaded with a <a class="lpdoc-idx-anchor" id="21" href="#load_compilation_module/1"><tt>load_compilation_module/1</tt></a> declaration. Normally included in <a class="lpdoc-idx-anchor" id="22" href="ciaosearch.html#package file">package file</a>s.</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="#translation_predname/1"><tt>packages:translation_predname/1</tt></a>)</span><span><span class="lpdoc-var">Predicate</span> is a translation predicate spec (has arity 2 or 3). </span><br/><span class="lpdoc-on-right"> (<a class="lpdoc-idx-anchor" id="24" href="basic_props.html#int/1"><tt>basic_props:int/1</tt></a>)</span><span><span class="lpdoc-var">Priority</span> is an integer. </span> </ul></div></div><p> <div><div class="lpdoc-defname"><span class="lpdoc-predtag">DECLARATION</span><a class="lpdoc-idx-anchor" id="add_term_trans/2" href="ciaosearch.html#add_term_trans/2">add_term_trans/2</a></div><div class="lpdoc-deftext"><p><span class="lpdoc-usage-header">Usage:</span><span class="lpdoc-usage-decl">:- <tt>add_term_trans(P,Priority)</tt>. </span><p>Starts a translation, defined by <span class="lpdoc-var">Predicate</span>, of the terms and sub-terms read by the compiler in the rest of the current text. This translation is performed after all translations defined by <a class="lpdoc-idx-anchor" id="25" href="ciaosearch.html#add_sentence_trans/1"><tt>add_sentence_trans/1</tt></a> are done. For each subsequent term read by the compiler, and recursively any subterm included, the translation predicate is called to possibly obtain a new term to replace the old one. Care must be taken of not introducing an endless loop of translations. <span class="lpdoc-var">Predicate</span> must be exported by a module previously loaded with a <a class="lpdoc-idx-anchor" id="26" href="#load_compilation_module/1"><tt>load_compilation_module/1</tt></a> declaration. Normally included in <a class="lpdoc-idx-anchor" id="27" href="ciaosearch.html#package file">package file</a>s.</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="#translation_predname/1"><tt>packages:translation_predname/1</tt></a>)</span><span><span class="lpdoc-var">P</span> is a translation predicate spec (has arity 2 or 3). </span><br/><span class="lpdoc-on-right"> (<a class="lpdoc-idx-anchor" id="29" href="basic_props.html#int/1"><tt>basic_props:int/1</tt></a>)</span><span><span class="lpdoc-var">Priority</span> is an integer. </span> </ul></div></div><p> <div><div class="lpdoc-defname"><span class="lpdoc-predtag">DECLARATION</span><a class="lpdoc-idx-anchor" id="add_goal_trans/2" href="ciaosearch.html#add_goal_trans/2">add_goal_trans/2</a></div><div class="lpdoc-deftext"><p><span class="lpdoc-usage-header">Usage:</span><span class="lpdoc-usage-decl">:- <tt>add_goal_trans(Predicate,Priority)</tt>. </span><p>Declares a translation, defined by <span class="lpdoc-var">Predicate</span>, of the goals present in the clauses of the current text. This translation is performed after all translations defined by <a class="lpdoc-idx-anchor" id="30" href="ciaosearch.html#add_sentence_trans/1"><tt>add_sentence_trans/1</tt></a> and <a class="lpdoc-idx-anchor" id="31" href="ciaosearch.html#add_term_trans/1"><tt>add_term_trans/1</tt></a> are done. For each clause read by the compiler, the translation predicate is called with each goal present in the clause to possibly obtain other goal to substitute the original one, and the translation is subsequently applied to the resulting goal. Care must be taken of not introducing an endless loop of translations. <span class="lpdoc-var">Predicate</span> must be exported by a module previously loaded with a <a class="lpdoc-idx-anchor" id="32" href="#load_compilation_module/1"><tt>load_compilation_module/1</tt></a> declaration. Bear in mind that this type of translation noticeably slows down compilation. Normally included in <a class="lpdoc-idx-anchor" id="33" href="ciaosearch.html#package file">package file</a>s.</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="34" href="#translation_predname/1"><tt>packages:translation_predname/1</tt></a>)</span><span><span class="lpdoc-var">Predicate</span> is a translation predicate spec (has arity 2 or 3). </span><br/><span class="lpdoc-on-right"> (<a class="lpdoc-idx-anchor" id="35" href="basic_props.html#int/1"><tt>basic_props:int/1</tt></a>)</span><span><span class="lpdoc-var">Priority</span> is an integer. </span> </ul></div></div><p> <div><div class="lpdoc-defname"><span class="lpdoc-predtag">DECLARATION</span><a class="lpdoc-idx-anchor" id="add_clause_trans/2" href="ciaosearch.html#add_clause_trans/2">add_clause_trans/2</a></div><div class="lpdoc-deftext"><p><span class="lpdoc-usage-header">Usage:</span><span class="lpdoc-usage-decl">:- <tt>add_clause_trans(Predicate,Priority)</tt>. </span><p>Declares a translation, defined by <span class="lpdoc-var">Predicate</span>, of the clauses of the current text. The translation is performed before <a class="lpdoc-idx-anchor" id="36" href="ciaosearch.html#add_goal_trans/1"><tt>add_goal_trans/1</tt></a> translations but after <a class="lpdoc-idx-anchor" id="37" href="ciaosearch.html#add_sentence_trans/1"><tt>add_sentence_trans/1</tt></a> and <a class="lpdoc-idx-anchor" id="38" href="ciaosearch.html#add_term_trans/1"><tt>add_term_trans/1</tt></a> translations. The usefulness of this translation is that information of the interface of related modules is available when it is performed. For each clause read by the compiler, the translation predicate is called with the first argument instantiated to a structure <tt>clause(Head,Body)</tt>, and the predicate must return in the second argument a similar structure, without changing the functor in <tt>Head</tt> (or fail, in which case the clause is used as is). Before executing the translation predicate with actual clauses it is called with an input of <tt>clause(0,0)</tt>, discarding the result.</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="39" href="#translation_predname/1"><tt>packages:translation_predname/1</tt></a>)</span><span><span class="lpdoc-var">Predicate</span> is a translation predicate spec (has arity 2 or 3). </span><br/><span class="lpdoc-on-right"> (<a class="lpdoc-idx-anchor" id="40" href="basic_props.html#int/1"><tt>basic_props:int/1</tt></a>)</span><span><span class="lpdoc-var">Priority</span> is an integer. </span> </ul></div></div><p> <div><div class="lpdoc-defname"><span class="lpdoc-predtag">REGTYPE</span><a class="lpdoc-idx-anchor" id="translation_predname/1" href="ciaosearch.html#translation_predname/1">translation_predname/1</a></div><div class="lpdoc-deftext">A translation predicate is a predicate of arity 2 or 3 used to make compile-time translations. The compiler invokes a translation predicate instantiating its first argument with the item to be translated, and if the predicate is of arity 3 its third argument with the name of the module where the translation is done. If the call is successful, the second argument is used as if that item were in the place of the original, else the original item is used.<p><span class="lpdoc-usage-header">Usage:</span><span class="lpdoc-usage-decl"><tt>translation_predname(P)</tt> </span><p><span class="lpdoc-var">P</span> is a translation predicate spec (has arity 2 or 3).</p><ul class="lpdoc-itemize-minus"></ul></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>Packages:</em><br/><a class="lpdoc-idx-anchor" id="41" href="ciaosearch.html#prelude"><tt>prelude</tt></a>, <a class="lpdoc-idx-anchor" id="42" href="ciaosearch.html#initial"><tt>initial</tt></a>, <a class="lpdoc-idx-anchor" id="43" href="condcomp_doc.html"><tt>condcomp</tt></a>, <a class="lpdoc-idx-anchor" id="44" href="assertions_doc.html"><tt>assertions</tt></a>, <a class="lpdoc-idx-anchor" id="45" href="ciaosearch.html#assertions/assertions_basic"><tt>assertions/assertions_basic</tt></a>. </ul></div></div><div class="lpdoc-footer">Generated with LPdoc using Ciao</div></div><div class="lpdoc-clearer"></div></div></body></html>