<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 - Dynamic predicates</TITLE> </HEAD> <BODY> Go to the <A HREF="ciao_1.html">first</A>, <A HREF="ciao_36.html">previous</A>, <A HREF="ciao_38.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="SEC196" HREF="ciao_toc.html#TOC196">Dynamic predicates</A></H1> <P> <A NAME="IDX2721"></A> <P> <STRONG>Author(s):</STRONG> The CLIP Group. <P> <STRONG>Version:</STRONG> 1.10#7 (2006/4/26, 19:22:13 CEST) <P> <STRONG>Version of last change:</STRONG> 1.9#197 (2003/12/19, 17:4:32 CET) <P> This module implements the assert/retract family of predicates to manipulate dynamic predicates. <P> The predicates defined in this module allow modification of the program as it is actually running. Clauses can be added to the program (<EM>asserted</EM>) or removed from the program (<EM>retracted</EM>). For these predicates, the argument which corresponds to the clause head must be instantiated to an atom or a compound term. The argument corresponding to the clause must be instantiated either to a term <CODE>Head :- Body</CODE> or, if the body part is empty, to <CODE>Head</CODE>. An empty body part is represented as <CODE>true</CODE>. Note that using this library is very detrimental to global analysis, and that for most uses the predicates listed in section <A HREF="ciao_28.html#SEC167">Fast/concurrent update of facts</A> suffice. <UL> <LI><A HREF="ciao_37.html#SEC197">Usage and interface (dynamic)</A> <LI><A HREF="ciao_37.html#SEC198">Documentation on exports (dynamic)</A> <LI><A HREF="ciao_37.html#SEC199">Documentation on multifiles (dynamic)</A> </UL> <H2><A NAME="SEC197" HREF="ciao_toc.html#TOC197">Usage and interface (<CODE>dynamic</CODE>)</A></H2> <div class="cartouche"> <UL> <LI><STRONG>Library usage:</STRONG> <CODE>:- use_module(library(dynamic)).</CODE> <LI><STRONG>Exports:</STRONG> <UL> <LI><EM>Predicates:</EM> <A NAME="IDX2722"></A> <CODE>asserta/1</CODE>, <A NAME="IDX2723"></A> <CODE>asserta/2</CODE>, <A NAME="IDX2724"></A> <CODE>assertz/1</CODE>, <A NAME="IDX2725"></A> <CODE>assertz/2</CODE>, <A NAME="IDX2726"></A> <CODE>assert/1</CODE>, <A NAME="IDX2727"></A> <CODE>assert/2</CODE>, <A NAME="IDX2728"></A> <CODE>retract/1</CODE>, <A NAME="IDX2729"></A> <CODE>retractall/1</CODE>, <A NAME="IDX2730"></A> <CODE>abolish/1</CODE>, <A NAME="IDX2731"></A> <CODE>clause/2</CODE>, <A NAME="IDX2732"></A> <CODE>clause/3</CODE>, <A NAME="IDX2733"></A> <CODE>current_predicate/1</CODE>, <A NAME="IDX2734"></A> <CODE>current_predicate/2</CODE>, <A NAME="IDX2735"></A> <CODE>dynamic/1</CODE>, <A NAME="IDX2736"></A> <CODE>data/1</CODE>, <A NAME="IDX2737"></A> <CODE>wellformed_body/3</CODE>. <LI><EM>Multifiles:</EM> <A NAME="IDX2738"></A> <CODE>do_on_abolish/1</CODE>. </UL> <LI><STRONG>Other modules used:</STRONG> <UL> <LI><EM>System library modules:</EM> <A NAME="IDX2739"></A> <CODE>prolog_sys</CODE>. </UL> </UL> </div class="cartouche"> <H2><A NAME="SEC198" HREF="ciao_toc.html#TOC198">Documentation on exports (<CODE>dynamic</CODE>)</A></H2> <P> <A NAME="IDX2740"></A> <A NAME="IDX2741"></A> <DL> <DT><span class="define">PREDICATE:</span> <B>asserta/1:</B> <DD><A NAME="IDX2742"></A> <P> <EM>Meta-predicate</EM> with arguments: <CODE>asserta(clause)</CODE>. <P> <STRONG>Usage:</STRONG> <CODE>asserta(+Clause)</CODE> <KBD> * ISO * </KBD> <UL> <LI><EM>Description:</EM> The current instance of <CODE>Clause</CODE> is interpreted as a clause and is added to the current program. The predicate concerned must be dynamic. The new clause becomes the <EM>first</EM> clause for the predicate concerned. Any uninstantiated variables in <CODE>Clause</CODE> will be replaced by new private variables. <LI><EM>The following properties hold globally:</EM> This predicate is understood natively by CiaoPP. (<CODE>basic_props:native/1</CODE>) </UL> </DL> <P> <A NAME="IDX2743"></A> <A NAME="IDX2744"></A> <DL> <DT><span class="define">PREDICATE:</span> <B>asserta/2:</B> <DD><A NAME="IDX2745"></A> <P> <EM>Meta-predicate</EM> with arguments: <CODE>asserta(clause,?)</CODE>. <P> <STRONG>Usage:</STRONG> <CODE>asserta(+Clause, -Ref)</CODE> <UL> <LI><EM>Description:</EM> Like <CODE>asserta/1</CODE>. <CODE>Ref</CODE> is a unique identifier of the asserted clause. <LI><EM>The following properties hold globally:</EM> This predicate is understood natively by CiaoPP. (<CODE>basic_props:native/1</CODE>) </UL> </DL> <P> <A NAME="IDX2746"></A> <A NAME="IDX2747"></A> <DL> <DT><span class="define">PREDICATE:</span> <B>assertz/1:</B> <DD><A NAME="IDX2748"></A> <P> <EM>Meta-predicate</EM> with arguments: <CODE>assertz(clause)</CODE>. <P> <STRONG>Usage:</STRONG> <CODE>assertz(+Clause)</CODE> <KBD> * ISO * </KBD> <UL> <LI><EM>Description:</EM> Like <CODE>asserta/1</CODE>, except that the new clause becomes the <EM>last</EM> clause for the predicate concerned. <LI><EM>The following properties hold globally:</EM> This predicate is understood natively by CiaoPP. (<CODE>basic_props:native/1</CODE>) </UL> </DL> <P> <A NAME="IDX2749"></A> <A NAME="IDX2750"></A> <DL> <DT><span class="define">PREDICATE:</span> <B>assertz/2:</B> <DD><A NAME="IDX2751"></A> <P> <EM>Meta-predicate</EM> with arguments: <CODE>assertz(clause,?)</CODE>. <P> <STRONG>Usage:</STRONG> <CODE>assertz(+Clause, -Ref)</CODE> <UL> <LI><EM>Description:</EM> Like <CODE>assertz/1</CODE>. <CODE>Ref</CODE> is a unique identifier of the asserted clause. <LI><EM>The following properties hold globally:</EM> This predicate is understood natively by CiaoPP. (<CODE>basic_props:native/1</CODE>) </UL> </DL> <P> <A NAME="IDX2752"></A> <A NAME="IDX2753"></A> <DL> <DT><span class="define">PREDICATE:</span> <B>assert/1:</B> <DD><A NAME="IDX2754"></A> <P> <EM>Meta-predicate</EM> with arguments: <CODE>assert(clause)</CODE>. <P> <STRONG>Usage:</STRONG> <CODE>assert(+Clause)</CODE> <UL> <LI><EM>Description:</EM> Identical to <CODE>assertz/1</CODE>. Included for compatibility. <LI><EM>The following properties hold globally:</EM> This predicate is understood natively by CiaoPP. (<CODE>basic_props:native/1</CODE>) </UL> </DL> <P> <A NAME="IDX2755"></A> <A NAME="IDX2756"></A> <DL> <DT><span class="define">PREDICATE:</span> <B>assert/2:</B> <DD><A NAME="IDX2757"></A> <P> <EM>Meta-predicate</EM> with arguments: <CODE>assert(clause,?)</CODE>. <P> <STRONG>Usage:</STRONG> <CODE>assert(+Clause, -Ref)</CODE> <UL> <LI><EM>Description:</EM> Identical to <CODE>assertz/2</CODE>. Included for compatibility. <LI><EM>The following properties hold globally:</EM> This predicate is understood natively by CiaoPP. (<CODE>basic_props:native/1</CODE>) </UL> </DL> <P> <A NAME="IDX2758"></A> <A NAME="IDX2759"></A> <DL> <DT><span class="define">PREDICATE:</span> <B>retract/1:</B> <DD><A NAME="IDX2760"></A> <P> <EM>Meta-predicate</EM> with arguments: <CODE>retract(clause)</CODE>. <P> <STRONG>Usage:</STRONG> <CODE>retract(+Clause)</CODE> <KBD> * ISO * </KBD> <UL> <LI><EM>Description:</EM> The first clause in the program that matches <CODE>Clause</CODE> is erased. The predicate concerned must be dynamic. The predicate <CODE>retract/1</CODE> may be used in a non-determinate fashion, i.e., it will successively retract clauses matching the argument through backtracking. If reactivated by backtracking, invocations of the predicate whose clauses are being retracted will proceed unaffected by the retracts. This is also true for invocations of <CODE>clause</CODE> for the same predicate. The space occupied by a retracted clause will be recovered when instances of the clause are no longer in use. <LI><EM>The following properties hold globally:</EM> This predicate is understood natively by CiaoPP. (<CODE>basic_props:native/1</CODE>) </UL> </DL> <P> <A NAME="IDX2761"></A> <A NAME="IDX2762"></A> <DL> <DT><span class="define">PREDICATE:</span> <B>retractall/1:</B> <DD><A NAME="IDX2763"></A> <P> <EM>Meta-predicate</EM> with arguments: <CODE>retractall(fact)</CODE>. <P> <STRONG>Usage:</STRONG> <CODE>retractall(+Head)</CODE> <UL> <LI><EM>Description:</EM> Erase all clauses whose head matches <CODE>Head</CODE>, where <CODE>Head</CODE> must be instantiated to an atom or a compound term. The predicate concerned must be dynamic. The predicate definition is retained. <LI><EM>The following properties hold globally:</EM> This predicate is understood natively by CiaoPP. (<CODE>basic_props:native/1</CODE>) </UL> </DL> <P> <A NAME="IDX2764"></A> <A NAME="IDX2765"></A> <DL> <DT><span class="define">PREDICATE:</span> <B>abolish/1:</B> <DD><A NAME="IDX2766"></A> <P> <EM>Meta-predicate</EM> with arguments: <CODE>abolish(spec)</CODE>. <P> <STRONG>Usage:</STRONG> <CODE>abolish(+Spec)</CODE> <KBD> * ISO * </KBD> <UL> <LI><EM>Description:</EM> Erase all clauses of the predicate specified by the predicate spec <CODE>Spec</CODE>. The predicate definition itself is also erased (the predicate is deemed undefined after execution of the abolish). The predicates concerned must all be user defined. <LI><EM>The following properties hold globally:</EM> This predicate is understood natively by CiaoPP. (<CODE>basic_props:native/1</CODE>) </UL> </DL> <P> <A NAME="IDX2767"></A> <A NAME="IDX2768"></A> <DL> <DT><span class="define">PREDICATE:</span> <B>clause/2:</B> <DD><A NAME="IDX2769"></A> <P> <EM>Meta-predicate</EM> with arguments: <CODE>clause(fact,?)</CODE>. <P> <STRONG>Usage:</STRONG> <CODE>clause(+Head, ?Body)</CODE> <KBD> * ISO * </KBD> <UL> <LI><EM>Description:</EM> The clause '<CODE>Head</CODE> <CODE>:-</CODE> <CODE>Body</CODE>' exists in the current program. The predicate concerned must be dynamic. <LI><EM>The following properties hold globally:</EM> This predicate is understood natively by CiaoPP. (<CODE>basic_props:native/1</CODE>) </UL> </DL> <P> <A NAME="IDX2770"></A> <A NAME="IDX2771"></A> <DL> <DT><span class="define">PREDICATE:</span> <B>clause/3:</B> <DD><A NAME="IDX2772"></A> <P> <CODE>clause(Head, Body, Ref)</CODE> <P> Like <CODE>clause(Head,Body)</CODE>, plus the clause is uniquely identified by <CODE>Ref</CODE>. <P> <EM>Meta-predicate</EM> with arguments: <CODE>clause(fact,?,?)</CODE>. <P> <STRONG>Usage 1:</STRONG> <CODE>clause(+Head, ?Body, ?Ref)</CODE> <UL> <LI><EM>Description:</EM> <CODE>Head</CODE> must be instantiated to an atom or a compound term. <LI><EM>The following properties hold globally:</EM> This predicate is understood natively by CiaoPP. (<CODE>basic_props:native/1</CODE>) </UL> <P> <STRONG>Usage 2:</STRONG> <CODE>clause(?Head, ?Body, +Ref)</CODE> <UL> <LI><EM>Description:</EM> <CODE>Ref</CODE> must be instantiated to a valid identifier. <LI><EM>The following properties hold globally:</EM> This predicate is understood natively by CiaoPP. (<CODE>basic_props:native/1</CODE>) </UL> </DL> <P> <A NAME="IDX2773"></A> <A NAME="IDX2774"></A> <DL> <DT><span class="define">PREDICATE:</span> <B>current_predicate/1:</B> <DD><A NAME="IDX2775"></A> <P> <STRONG>Usage:</STRONG> <CODE>current_predicate(?Spec)</CODE> <KBD> * ISO * </KBD> <UL> <LI><EM>Description:</EM> A predicate in the current module is named <CODE>Spec</CODE>. <LI><EM>The following properties hold globally:</EM> This predicate is understood natively by CiaoPP. (<CODE>basic_props:native/1</CODE>) </UL> </DL> <P> <A NAME="IDX2776"></A> <A NAME="IDX2777"></A> <DL> <DT><span class="define">PREDICATE:</span> <B>current_predicate/2:</B> <DD><A NAME="IDX2778"></A> <P> <STRONG>Usage:</STRONG> <CODE>current_predicate(?Spec, ?Module)</CODE> <UL> <LI><EM>Description:</EM> A predicate in <CODE>Module</CODE> is named <CODE>Spec</CODE>. <CODE>Module</CODE> never is an engine module. <LI><EM>The following properties hold globally:</EM> This predicate is understood natively by CiaoPP. (<CODE>basic_props:native/1</CODE>) </UL> </DL> <P> <A NAME="IDX2779"></A> <A NAME="IDX2780"></A> <DL> <DT><span class="define">PREDICATE:</span> <B>dynamic/1:</B> <DD><A NAME="IDX2781"></A> <P> <CODE>dynamic Spec</CODE> <P> <CODE>Spec</CODE> is of the form <CODE>F</CODE>/<CODE>A</CODE>. The predicate named <CODE>F</CODE> with arity <CODE>A</CODE> is made <A NAME="IDX2782"></A> dynamic in the current module at runtime (useful for predicate names generated on-the-fly). If the predicate functor name <CODE>F</CODE> is uninstatiated, a new, unique, predicate name is generated at runtime. </DL> <P> <A NAME="IDX2783"></A> <A NAME="IDX2784"></A> <DL> <DT><span class="define">PREDICATE:</span> <B>data/1:</B> <DD><A NAME="IDX2785"></A> <P> <CODE>data Spec</CODE> <P> <CODE>Spec</CODE> is of the form <CODE>F</CODE>/<CODE>A</CODE>. The predicate named <CODE>F</CODE> with arity <CODE>A</CODE> is made <A NAME="IDX2786"></A> data in the current module at runtime (useful for predicate names generated on-the-fly). If the predicate functor name <CODE>F</CODE> is uninstatiated, a new, unique, predicate name is generated at runtime. </DL> <P> <A NAME="IDX2787"></A> <A NAME="IDX2788"></A> <DL> <DT><span class="define">PREDICATE:</span> <B>wellformed_body/3:</B> <DD><A NAME="IDX2789"></A> <P> <CODE>wellformed_body(BodyIn, Env, BodyOut)</CODE> <P> <CODE>BodyIn</CODE> is a well-formed clause body. <CODE>BodyOut</CODE> is its counterpart with no single-variable meta-goals (i.e., with <CODE>call(X)</CODE> for <CODE>X</CODE>). <CODE>Env</CODE> denotes if global cuts are admissible in <CODE>BodyIn</CODE> (<CODE>+</CODE> if they are, <CODE>-</CODE> if they are not). </DL> <H2><A NAME="SEC199" HREF="ciao_toc.html#TOC199">Documentation on multifiles (<CODE>dynamic</CODE>)</A></H2> <P> <A NAME="IDX2790"></A> <A NAME="IDX2791"></A> <DL> <DT><span class="define">PREDICATE:</span> <B>do_on_abolish/1:</B> <DD><A NAME="IDX2792"></A> <P> <CODE>do_on_abolish(Head)</CODE> <P> A hook predicate which will be called when the definition of the predicate of <CODE>Head</CODE> is abolished. <P> The predicate is <EM>multifile</EM>. </DL> <P><HR><P> Go to the <A HREF="ciao_1.html">first</A>, <A HREF="ciao_36.html">previous</A>, <A HREF="ciao_38.html">next</A>, <A HREF="ciao_241.html">last</A> section, <A HREF="ciao_toc.html">table of contents</A>. </BODY> </HTML>
