<HTML> <HEAD> <!-- Created by texi2html 1.56k + clip patches and <A href="http://www.clip.dia.fi.upm.es/Software">lpdoc</A> from ciao.texi on 28 January 2007 --> <LINK rel="stylesheet" href="ciao.css" type="text/css"> <TITLE>The Ciao Prolog System - Code translation utilities</TITLE> </HEAD> <BODY> Go to the <A HREF="ciao_1.html">first</A>, <A HREF="ciao_85.html">previous</A>, <A HREF="ciao_87.html">next</A>, <A HREF="ciao_241.html">last</A> section, <A HREF="ciao_toc.html">table of contents</A>. <P><HR><P> <H1><A NAME="SEC363" HREF="ciao_toc.html#TOC363">Code translation utilities</A></H1> <P> <A NAME="IDX4714"></A> <P> <STRONG>Author(s):</STRONG> Angel Fernandez Pineda. <P> <STRONG>Version:</STRONG> 1.10#7 (2006/4/26, 19:22:13 CEST) <P> <STRONG>Version of last change:</STRONG> 1.7#40 (2001/1/5, 19:7:40 CET) <P> This library offers a general way to perform clause body expansions. Goal, fact and spec translation predicates are authomatically called when needed, while this utility navigates through the meta-argument specification of the body itself. All predicates within this library must be called at <EM>second-pass expansions</EM>, since it uses information stored at <A NAME="IDX4715"></A> <CODE>c_itf</CODE> library. <UL> <LI><A HREF="ciao_86.html#SEC364">Usage and interface (expansion_tools)</A> <LI><A HREF="ciao_86.html#SEC365">Documentation on exports (expansion_tools)</A> <LI><A HREF="ciao_86.html#SEC366">Documentation on internals (expansion_tools)</A> <LI><A HREF="ciao_86.html#SEC367">Known bugs and planned improvements (expansion_tools)</A> </UL> <H2><A NAME="SEC364" HREF="ciao_toc.html#TOC364">Usage and interface (<CODE>expansion_tools</CODE>)</A></H2> <div class="cartouche"> <UL> <LI><STRONG>Library usage:</STRONG> This library is provided as a tool for those modules which performs source-to-source code translation, usually known as <EM>code expanders</EM>. It may be loaded as other modules using a <A NAME="IDX4716"></A> <CODE>use_module/1</CODE>. Nothing special needs to be done. <LI><STRONG>Exports:</STRONG> <UL> <LI><EM>Predicates:</EM> <A NAME="IDX4717"></A> <CODE>imports_meta_pred/3</CODE>, <A NAME="IDX4718"></A> <CODE>body_expander/6</CODE>, <A NAME="IDX4719"></A> <CODE>arg_expander/6</CODE>. </UL> <LI><STRONG>Other modules used:</STRONG> <UL> <LI><EM>System library modules:</EM> <A NAME="IDX4720"></A> <CODE>compiler/c_itf</CODE>. </UL> </UL> </div class="cartouche"> <H2><A NAME="SEC365" HREF="ciao_toc.html#TOC365">Documentation on exports (<CODE>expansion_tools</CODE>)</A></H2> <P> <A NAME="IDX4721"></A> <A NAME="IDX4722"></A> <DL> <DT><span class="define">PREDICATE:</span> <B>imports_meta_pred/3:</B> <DD><A NAME="IDX4723"></A> <P> Macro provided in order to know meta-predicate specifications accessible from a module. <P> <STRONG>Usage:</STRONG> <CODE>imports_meta_pred(Module, MetaSpec, AccessibleAt)</CODE> <UL> <LI><EM>Description:</EM> Tells whether <CODE>MetaSpec</CODE> meta-predicate specification is accessible from <CODE>Module</CODE>. <CODE>AccessibleAt</CODE> will be binded to '-' whether meta-predicate is a builtin one. If not, it will be unified with the module which defines the meta-predicate. <LI><EM>The following properties should hold at call time:</EM> <CODE>Module</CODE> is an atom. (<CODE>basic_props:atm/1</CODE>) <CODE>MetaSpec</CODE> is any term. (<CODE>basic_props:term/1</CODE>) <CODE>AccessibleAt</CODE> is a free variable. (<CODE>term_typing:var/1</CODE>) </UL> </DL> <P> <A NAME="IDX4724"></A> <A NAME="IDX4725"></A> <DL> <DT><span class="define">PREDICATE:</span> <B>body_expander/6:</B> <DD><A NAME="IDX4726"></A> <P> This predicate is the main translation tool. It navigates through a clause body, when a single <EM>goal</EM> appears, user-code is called in order to perform a translation. Whether user-code fails to translate the involved goal, it remains the same. Regardless that goal is translated or not, an argument expansion will be performed over all goals if applicable (see <A NAME="IDX4727"></A> <CODE>arg_expander/6</CODE> predicate). <P> Variable (unknown at compile time) goals will also be attempt to translate. <P> <EM>Meta-predicate</EM> with arguments: <CODE>body_expander(pred(3),pred(3),pred(3),?,?,?)</CODE>. <P> <STRONG>Usage:</STRONG> <CODE>body_expander(GoalTrans, FactTrans, SpecTrans, Module, Body, ExpandedBody)</CODE> <UL> <LI><EM>Description:</EM> Translates <CODE>Body</CODE> to <CODE>ExpandedBody</CODE> by the usage of user-defined translators <CODE>GoalTrans</CODE>, <CODE>FactTrans</CODE> and <CODE>SpecTrans</CODE>. The module where the original body appears must be unified with <CODE>Module</CODE> argument. <LI><EM>The following properties should hold at call time:</EM> <CODE>GoalTrans</CODE> is a user-defined predicate which performs <EM>goal</EM> meta-type translation (<CODE>expansion_tools:goal_expander/1</CODE>) <CODE>FactTrans</CODE> is a user-defined predicate which performs <EM>fact</EM> meta-type translation (<CODE>expansion_tools:fact_expander/1</CODE>) <CODE>SpecTrans</CODE> is a user-defined predicate which performs <EM>spec</EM> meta-type translation (<CODE>expansion_tools:spec_expander/1</CODE>) <CODE>Module</CODE> is an atom. (<CODE>basic_props:atm/1</CODE>) <CODE>Body</CODE> is currently a term which is not a free variable. (<CODE>term_typing:nonvar/1</CODE>) <CODE>ExpandedBody</CODE> is a free variable. (<CODE>term_typing:var/1</CODE>) </UL> </DL> <P> <A NAME="IDX4728"></A> <A NAME="IDX4729"></A> <DL> <DT><span class="define">PREDICATE:</span> <B>arg_expander/6:</B> <DD><A NAME="IDX4730"></A> <P> This predicate is an auxiliary translation tool, which is used by <A NAME="IDX4731"></A> <CODE>body_expander/6</CODE> predicate. It remains exported as a macro. The predicate navigates through the <EM>meta-argument specification</EM> of a goal. Whether a <EM>goal,fact or spec</EM> argument appears, user-code is called in order to perform a translation. Whether user-code fails to translate the involved argument, it remains the same. Builtins as ','/2 or ';'/2 are treated as meta-predicates defining <EM>goal</EM> meta-arguments. When a <EM>goal</EM> meta-argument is located, <A NAME="IDX4732"></A> <CODE>body_expander/6</CODE> will be called in order to navigate through it. Notice that a <EM>goal</EM> meta-argument may be unified with another goal defining another meta-argument, so navigation is required. If arguments are not known to arg_expander/6, translation will not occur. This is posible whether goal or qualifing module are variables. <P> <EM>Meta-predicate</EM> with arguments: <CODE>arg_expander(pred(3),pred(3),pred(3),?,?,?)</CODE>. <P> <STRONG>Usage:</STRONG> <CODE>arg_expander(GoalTrans, FactTrans, SpecTrans, Module, Goal, ExpandedGoal)</CODE> <UL> <LI><EM>Description:</EM> Translates <CODE>Goal</CODE> to <CODE>ExpandedGoal</CODE> by applying user-defined translators (<CODE>GoalTrans</CODE>, <CODE>FactTrans</CODE> and <CODE>SpecTrans</CODE>) to each meta-argument present at such goal. The module where the original goal appears must be unified with <CODE>Module</CODE> argument. <LI><EM>The following properties should hold at call time:</EM> <CODE>GoalTrans</CODE> is a user-defined predicate which performs <EM>goal</EM> meta-type translation (<CODE>expansion_tools:goal_expander/1</CODE>) <CODE>FactTrans</CODE> is a user-defined predicate which performs <EM>fact</EM> meta-type translation (<CODE>expansion_tools:fact_expander/1</CODE>) <CODE>SpecTrans</CODE> is a user-defined predicate which performs <EM>spec</EM> meta-type translation (<CODE>expansion_tools:spec_expander/1</CODE>) <CODE>Module</CODE> is an atom. (<CODE>basic_props:atm/1</CODE>) <CODE>Goal</CODE> is currently a term which is not a free variable. (<CODE>term_typing:nonvar/1</CODE>) <CODE>ExpandedBody</CODE> is a free variable. (<CODE>term_typing:var/1</CODE>) </UL> </DL> <H2><A NAME="SEC366" HREF="ciao_toc.html#TOC366">Documentation on internals (<CODE>expansion_tools</CODE>)</A></H2> <P> <A NAME="IDX4733"></A> <A NAME="IDX4734"></A> <DL> <DT><span class="define">PROPERTY:</span> <B>expander_pred/1:</B> <DD><A NAME="IDX4735"></A> <P> <STRONG>Usage:</STRONG> <CODE>expander_pred(Pred)</CODE> <UL> <LI><EM>Description:</EM> <CODE>Pred</CODE> is a user-defined predicate used to perform code translations. First argument will be binded to the corresponding term to be translated. Second argument must be binded to the corresponding translation. Third argument will be binded to the current module were first argument appears. Additional arguments will be user-defined. </UL> </DL> <H2><A NAME="SEC367" HREF="ciao_toc.html#TOC367">Known bugs and planned improvements (<CODE>expansion_tools</CODE>)</A></H2> <UL> <LI> <EM>pred(N)</EM> meta-arguments are not supported at this moment. </UL> <P><HR><P> Go to the <A HREF="ciao_1.html">first</A>, <A HREF="ciao_85.html">previous</A>, <A HREF="ciao_87.html">next</A>, <A HREF="ciao_241.html">last</A> section, <A HREF="ciao_toc.html">table of contents</A>. </BODY> </HTML>
