<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 - Printing status and error messages</TITLE> </HEAD> <BODY> Go to the <A HREF="ciao_1.html">first</A>, <A HREF="ciao_69.html">previous</A>, <A HREF="ciao_71.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="SEC304" HREF="ciao_toc.html#TOC304">Printing status and error messages</A></H1> <P> <A NAME="IDX4353"></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#282 (2004/2/13, 15:20:28 CET) <P> This is a very simple library for printing status and error messages to the console. <UL> <LI><A HREF="ciao_70.html#SEC305">Usage and interface (messages)</A> <LI><A HREF="ciao_70.html#SEC306">Documentation on exports (messages)</A> <LI><A HREF="ciao_70.html#SEC307">Documentation on multifiles (messages)</A> <LI><A HREF="ciao_70.html#SEC308">Documentation on internals (messages)</A> <LI><A HREF="ciao_70.html#SEC309">Known bugs and planned improvements (messages)</A> </UL> <H2><A NAME="SEC305" HREF="ciao_toc.html#TOC305">Usage and interface (<CODE>messages</CODE>)</A></H2> <div class="cartouche"> <UL> <LI><STRONG>Library usage:</STRONG> <CODE>:- use_module(library(messages)).</CODE> <LI><STRONG>Exports:</STRONG> <UL> <LI><EM>Predicates:</EM> <A NAME="IDX4354"></A> <CODE>error_message/1</CODE>, <A NAME="IDX4355"></A> <CODE>error_message/2</CODE>, <A NAME="IDX4356"></A> <CODE>error_message/3</CODE>, <A NAME="IDX4357"></A> <CODE>warning_message/1</CODE>, <A NAME="IDX4358"></A> <CODE>warning_message/2</CODE>, <A NAME="IDX4359"></A> <CODE>warning_message/3</CODE>, <A NAME="IDX4360"></A> <CODE>note_message/1</CODE>, <A NAME="IDX4361"></A> <CODE>note_message/2</CODE>, <A NAME="IDX4362"></A> <CODE>note_message/3</CODE>, <A NAME="IDX4363"></A> <CODE>simple_message/1</CODE>, <A NAME="IDX4364"></A> <CODE>simple_message/2</CODE>, <A NAME="IDX4365"></A> <CODE>optional_message/2</CODE>, <A NAME="IDX4366"></A> <CODE>optional_message/3</CODE>, <A NAME="IDX4367"></A> <CODE>debug_message/1</CODE>, <A NAME="IDX4368"></A> <CODE>debug_message/2</CODE>, <A NAME="IDX4369"></A> <CODE>debug_goal/2</CODE>, <A NAME="IDX4370"></A> <CODE>debug_goal/3</CODE>. <LI><EM>Multifiles:</EM> <A NAME="IDX4371"></A> <CODE>issue_debug_messages/1</CODE>. </UL> <LI><STRONG>Other modules used:</STRONG> <UL> <LI><EM>System library modules:</EM> <A NAME="IDX4372"></A> <CODE>format</CODE>, <A NAME="IDX4373"></A> <CODE>lists</CODE>, <A NAME="IDX4374"></A> <CODE>filenames</CODE>. </UL> </UL> </div class="cartouche"> <H2><A NAME="SEC306" HREF="ciao_toc.html#TOC306">Documentation on exports (<CODE>messages</CODE>)</A></H2> <P> <A NAME="IDX4375"></A> <A NAME="IDX4376"></A> <DL> <DT><span class="define">PREDICATE:</span> <B>error_message/1:</B> <DD><A NAME="IDX4377"></A> <P> <EM>Meta-predicate</EM> with arguments: <CODE>error_message(addmodule)</CODE>. <P> <STRONG>Usage:</STRONG> <CODE>error_message(Text)</CODE> <UL> <LI><EM>Description:</EM> The text provided in <CODE>Text</CODE> is printed as an ERROR message. <LI><EM>The following properties should hold at call time:</EM> <CODE>Text</CODE> is a string (a list of character codes). (<CODE>basic_props:string/1</CODE>) </UL> </DL> <P> <A NAME="IDX4378"></A> <A NAME="IDX4379"></A> <DL> <DT><span class="define">PREDICATE:</span> <B>error_message/2:</B> <DD><A NAME="IDX4380"></A> <P> <EM>Meta-predicate</EM> with arguments: <CODE>error_message(?,addmodule)</CODE>. <P> <STRONG>Usage:</STRONG> <CODE>error_message(Text, ArgList)</CODE> <UL> <LI><EM>Description:</EM> The text provided in <CODE>Text</CODE> is printed as an ERROR message, using the arguments in <CODE>ArgList</CODE> to interpret any variable-related formatting commands embedded in <CODE>Text</CODE>. <LI><EM>The following properties should hold at call time:</EM> <CODE>Text</CODE> is an atom or string describing how the arguments should be formatted. If it is an atom it will be converted into a string with <CODE>name/2</CODE>. (<CODE>format:format_control/1</CODE>) <CODE>ArgList</CODE> is a list. (<CODE>basic_props:list/1</CODE>) </UL> </DL> <P> <A NAME="IDX4381"></A> <A NAME="IDX4382"></A> <DL> <DT><span class="define">PREDICATE:</span> <B>error_message/3:</B> <DD><A NAME="IDX4383"></A> <P> <EM>Meta-predicate</EM> with arguments: <CODE>error_message(?,?,addmodule)</CODE>. <P> <STRONG>Usage:</STRONG> <CODE>error_message(Lc, Text, ArgList)</CODE> <UL> <LI><EM>Description:</EM> The text provided in <CODE>Text</CODE> is printed as an ERROR message, using the arguments in <CODE>ArgList</CODE> to interpret any variable-related formatting commands embedded in <CODE>Text</CODE>, and reporting error location <CODE>Lc</CODE> (file and line numbers). <LI><EM>The following properties should hold at call time:</EM> Identifies a program source line. (<CODE>messages:location/1</CODE>) <CODE>Text</CODE> is an atom or string describing how the arguments should be formatted. If it is an atom it will be converted into a string with <CODE>name/2</CODE>. (<CODE>format:format_control/1</CODE>) <CODE>ArgList</CODE> is a list. (<CODE>basic_props:list/1</CODE>) </UL> </DL> <P> <A NAME="IDX4384"></A> <A NAME="IDX4385"></A> <DL> <DT><span class="define">PREDICATE:</span> <B>warning_message/1:</B> <DD><A NAME="IDX4386"></A> <P> <EM>Meta-predicate</EM> with arguments: <CODE>warning_message(addmodule)</CODE>. <P> <STRONG>Usage:</STRONG> <CODE>warning_message(Text)</CODE> <UL> <LI><EM>Description:</EM> The text provided in <CODE>Text</CODE> is printed as a WARNING message. <LI><EM>The following properties should hold at call time:</EM> <CODE>Text</CODE> is a string (a list of character codes). (<CODE>basic_props:string/1</CODE>) </UL> </DL> <P> <A NAME="IDX4387"></A> <A NAME="IDX4388"></A> <DL> <DT><span class="define">PREDICATE:</span> <B>warning_message/2:</B> <DD><A NAME="IDX4389"></A> <P> <EM>Meta-predicate</EM> with arguments: <CODE>warning_message(?,addmodule)</CODE>. <P> <STRONG>Usage:</STRONG> <CODE>warning_message(Text, ArgList)</CODE> <UL> <LI><EM>Description:</EM> The text provided in <CODE>Text</CODE> is printed as a WARNING message, using the arguments in <CODE>ArgList</CODE> to interpret any variable-related formatting commands embedded in <CODE>Text</CODE>. <LI><EM>The following properties should hold at call time:</EM> <CODE>Text</CODE> is an atom or string describing how the arguments should be formatted. If it is an atom it will be converted into a string with <CODE>name/2</CODE>. (<CODE>format:format_control/1</CODE>) <CODE>ArgList</CODE> is a list. (<CODE>basic_props:list/1</CODE>) </UL> </DL> <P> <A NAME="IDX4390"></A> <A NAME="IDX4391"></A> <DL> <DT><span class="define">PREDICATE:</span> <B>warning_message/3:</B> <DD><A NAME="IDX4392"></A> <P> <EM>Meta-predicate</EM> with arguments: <CODE>warning_message(?,?,addmodule)</CODE>. <P> <STRONG>Usage:</STRONG> <CODE>warning_message(Lc, Text, ArgList)</CODE> <UL> <LI><EM>Description:</EM> The text provided in <CODE>Text</CODE> is printed as a WARNING message, using the arguments in <CODE>ArgList</CODE> to interpret any variable-related formatting commands embedded in <CODE>Text</CODE>, and reporting error location <CODE>Lc</CODE> (file and line numbers). <LI><EM>The following properties should hold at call time:</EM> Identifies a program source line. (<CODE>messages:location/1</CODE>) <CODE>Text</CODE> is an atom or string describing how the arguments should be formatted. If it is an atom it will be converted into a string with <CODE>name/2</CODE>. (<CODE>format:format_control/1</CODE>) <CODE>ArgList</CODE> is a list. (<CODE>basic_props:list/1</CODE>) </UL> </DL> <P> <A NAME="IDX4393"></A> <A NAME="IDX4394"></A> <DL> <DT><span class="define">PREDICATE:</span> <B>note_message/1:</B> <DD><A NAME="IDX4395"></A> <P> <EM>Meta-predicate</EM> with arguments: <CODE>note_message(addmodule)</CODE>. <P> <STRONG>Usage:</STRONG> <CODE>note_message(Text)</CODE> <UL> <LI><EM>Description:</EM> The text provided in <CODE>Text</CODE> is printed as a NOTE. <LI><EM>The following properties should hold at call time:</EM> <CODE>Text</CODE> is a string (a list of character codes). (<CODE>basic_props:string/1</CODE>) </UL> </DL> <P> <A NAME="IDX4396"></A> <A NAME="IDX4397"></A> <DL> <DT><span class="define">PREDICATE:</span> <B>note_message/2:</B> <DD><A NAME="IDX4398"></A> <P> <EM>Meta-predicate</EM> with arguments: <CODE>note_message(?,addmodule)</CODE>. <P> <STRONG>Usage:</STRONG> <CODE>note_message(Text, ArgList)</CODE> <UL> <LI><EM>Description:</EM> The text provided in <CODE>Text</CODE> is printed as a NOTE, using the arguments in <CODE>ArgList</CODE> to interpret any variable-related formatting commands embedded in <CODE>Text</CODE>. <LI><EM>The following properties should hold at call time:</EM> <CODE>Text</CODE> is an atom or string describing how the arguments should be formatted. If it is an atom it will be converted into a string with <CODE>name/2</CODE>. (<CODE>format:format_control/1</CODE>) <CODE>ArgList</CODE> is a list. (<CODE>basic_props:list/1</CODE>) </UL> </DL> <P> <A NAME="IDX4399"></A> <A NAME="IDX4400"></A> <DL> <DT><span class="define">PREDICATE:</span> <B>note_message/3:</B> <DD><A NAME="IDX4401"></A> <P> <EM>Meta-predicate</EM> with arguments: <CODE>note_message(?,?,addmodule)</CODE>. <P> <STRONG>Usage:</STRONG> <CODE>note_message(Lc, Text, ArgList)</CODE> <UL> <LI><EM>Description:</EM> The text provided in <CODE>Text</CODE> is printed as a NOTE, using the arguments in <CODE>ArgList</CODE> to interpret any variable-related formatting commands embedded in <CODE>Text</CODE>, and reporting error location <CODE>Lc</CODE> (file and line numbers). <LI><EM>The following properties should hold at call time:</EM> Identifies a program source line. (<CODE>messages:location/1</CODE>) <CODE>Text</CODE> is an atom or string describing how the arguments should be formatted. If it is an atom it will be converted into a string with <CODE>name/2</CODE>. (<CODE>format:format_control/1</CODE>) <CODE>ArgList</CODE> is a list. (<CODE>basic_props:list/1</CODE>) </UL> </DL> <P> <A NAME="IDX4402"></A> <A NAME="IDX4403"></A> <DL> <DT><span class="define">PREDICATE:</span> <B>simple_message/1:</B> <DD><A NAME="IDX4404"></A> <P> <STRONG>Usage:</STRONG> <CODE>simple_message(Text)</CODE> <UL> <LI><EM>Description:</EM> The text provided in <CODE>Text</CODE> is printed. <LI><EM>The following properties should hold at call time:</EM> <CODE>Text</CODE> is a string (a list of character codes). (<CODE>basic_props:string/1</CODE>) </UL> </DL> <P> <A NAME="IDX4405"></A> <A NAME="IDX4406"></A> <DL> <DT><span class="define">PREDICATE:</span> <B>simple_message/2:</B> <DD><A NAME="IDX4407"></A> <P> <STRONG>Usage:</STRONG> <CODE>simple_message(Text, ArgList)</CODE> <UL> <LI><EM>Description:</EM> The text provided in <CODE>Text</CODE> is printed as a message, using the arguments in <CODE>ArgList</CODE>. <LI><EM>The following properties should hold at call time:</EM> <CODE>Text</CODE> is an atom or string describing how the arguments should be formatted. If it is an atom it will be converted into a string with <CODE>name/2</CODE>. (<CODE>format:format_control/1</CODE>) <CODE>ArgList</CODE> is a list. (<CODE>basic_props:list/1</CODE>) </UL> </DL> <P> <A NAME="IDX4408"></A> <A NAME="IDX4409"></A> <DL> <DT><span class="define">PREDICATE:</span> <B>optional_message/2:</B> <DD><A NAME="IDX4410"></A> <P> <STRONG>Usage:</STRONG> <CODE>optional_message(Text, Opts)</CODE> <UL> <LI><EM>Description:</EM> The text provided in <CODE>Text</CODE> is printed as a message, but only if the atom <CODE>-v</CODE> is a member of <CODE>Opts</CODE>. These predicates are meant to be used for optional messages, which are only to be printed when <EM>verbose</EM> output is requested explicitly. <LI><EM>The following properties should hold at call time:</EM> <CODE>Text</CODE> is a string (a list of character codes). (<CODE>basic_props:string/1</CODE>) <CODE>Opts</CODE> is a list of <CODE>atm</CODE>s. (<CODE>basic_props:list/2</CODE>) </UL> </DL> <P> <A NAME="IDX4411"></A> <A NAME="IDX4412"></A> <DL> <DT><span class="define">PREDICATE:</span> <B>optional_message/3:</B> <DD><A NAME="IDX4413"></A> <P> <STRONG>Usage:</STRONG> <CODE>optional_message(Text, ArgList, Opts)</CODE> <UL> <LI><EM>Description:</EM> The text provided in <CODE>Text</CODE> is printed as a message, using the arguments in <CODE>ArgList</CODE>, but only if the atom <CODE>-v</CODE> is a member of <CODE>Opts</CODE>. These predicates are meant to be used for optional messages, which are only to be printed when <EM>verbose</EM> output is requested explicitly. <LI><EM>The following properties should hold at call time:</EM> <CODE>Text</CODE> is an atom or string describing how the arguments should be formatted. If it is an atom it will be converted into a string with <CODE>name/2</CODE>. (<CODE>format:format_control/1</CODE>) <CODE>ArgList</CODE> is a list. (<CODE>basic_props:list/1</CODE>) <CODE>Opts</CODE> is a list of <CODE>atm</CODE>s. (<CODE>basic_props:list/2</CODE>) </UL> </DL> <P> <A NAME="IDX4414"></A> <A NAME="IDX4415"></A> <DL> <DT><span class="define">PREDICATE:</span> <B>debug_message/1:</B> <DD><A NAME="IDX4416"></A> <P> <EM>Meta-predicate</EM> with arguments: <CODE>debug_message(addmodule)</CODE>. <P> <STRONG>Usage:</STRONG> <CODE>debug_message(Text)</CODE> <UL> <LI><EM>Description:</EM> The text provided in <CODE>Text</CODE> is printed as a debugging message. These messages are turned <CODE>on</CODE> by defining a fact of <A NAME="IDX4417"></A> <CODE>issue_debug_messages/1</CODE> with the module name as argument. <LI><EM>The following properties should hold at call time:</EM> <CODE>Text</CODE> is an atom or string describing how the arguments should be formatted. If it is an atom it will be converted into a string with <CODE>name/2</CODE>. (<CODE>format:format_control/1</CODE>) </UL> </DL> <P> <A NAME="IDX4418"></A> <A NAME="IDX4419"></A> <DL> <DT><span class="define">PREDICATE:</span> <B>debug_message/2:</B> <DD><A NAME="IDX4420"></A> <P> <EM>Meta-predicate</EM> with arguments: <CODE>debug_message(?,addmodule)</CODE>. <P> <STRONG>Usage:</STRONG> <CODE>debug_message(Text, ArgList)</CODE> <UL> <LI><EM>Description:</EM> The text provided in <CODE>Text</CODE> is printed as a debugging message, using the arguments in <CODE>ArgList</CODE> to interpret any variable-related formatting commands embedded in <CODE>Text</CODE>. These messages are turned <CODE>on</CODE> by defining a fact of <A NAME="IDX4421"></A> <CODE>issue_debug_messages/1</CODE> which the module name as argument. <LI><EM>The following properties should hold at call time:</EM> <CODE>Text</CODE> is an atom or string describing how the arguments should be formatted. If it is an atom it will be converted into a string with <CODE>name/2</CODE>. (<CODE>format:format_control/1</CODE>) <CODE>ArgList</CODE> is a list. (<CODE>basic_props:list/1</CODE>) </UL> </DL> <P> <A NAME="IDX4422"></A> <A NAME="IDX4423"></A> <DL> <DT><span class="define">PREDICATE:</span> <B>debug_goal/2:</B> <DD><A NAME="IDX4424"></A> <P> <EM>Meta-predicate</EM> with arguments: <CODE>debug_goal(goal,addmodule)</CODE>. <P> <STRONG>Usage:</STRONG> <CODE>debug_goal(Goal, Text)</CODE> <UL> <LI><EM>Description:</EM> <CODE>Goal</CODE> is called. The text provided in <CODE>Text</CODE> is then printed as a debugging message. The whole process (including running <CODE>Goal</CODE>) is turned <CODE>on</CODE> by defining a fact of <A NAME="IDX4425"></A> <CODE>issue_debug_messages/1</CODE> with the module name as argument. </UL> </DL> <P> <A NAME="IDX4426"></A> <A NAME="IDX4427"></A> <DL> <DT><span class="define">PREDICATE:</span> <B>debug_goal/3:</B> <DD><A NAME="IDX4428"></A> <P> <EM>Meta-predicate</EM> with arguments: <CODE>debug_goal(goal,?,addmodule)</CODE>. <P> <STRONG>Usage:</STRONG> <CODE>debug_goal(Goal, Text, ArgList)</CODE> <UL> <LI><EM>Description:</EM> <CODE>Goal</CODE> is called. The text provided in <CODE>Text</CODE> is then printed as a debugging message, using the arguments in <CODE>ArgList</CODE> to interpret any variable-related formatting commands embedded in <CODE>Text</CODE>. Note that the variables in <CODE>ArgList</CODE> can be computed by <CODE>Goal</CODE>. The whole process (including running <CODE>Goal</CODE>) is turned <CODE>on</CODE> by defining a fact of <A NAME="IDX4429"></A> <CODE>issue_debug_messages/1</CODE> with the module name as argument. </UL> </DL> <H2><A NAME="SEC307" HREF="ciao_toc.html#TOC307">Documentation on multifiles (<CODE>messages</CODE>)</A></H2> <P> <A NAME="IDX4430"></A> <A NAME="IDX4431"></A> <DL> <DT><span class="define">PREDICATE:</span> <B>issue_debug_messages/1:</B> <DD><A NAME="IDX4432"></A> <P> The predicate is <EM>multifile</EM>. <P> The predicate is of type <EM>data</EM>. <P> <STRONG>Usage:</STRONG> <CODE>issue_debug_messages(Module)</CODE> <UL> <LI><EM>Description:</EM> Printing of debugging messages is enabled for module <CODE>Module</CODE>. <LI><EM>The following properties should hold upon exit:</EM> <CODE>Module</CODE> is currently instantiated to an atom. (<CODE>term_typing:atom/1</CODE>) </UL> </DL> <H2><A NAME="SEC308" HREF="ciao_toc.html#TOC308">Documentation on internals (<CODE>messages</CODE>)</A></H2> <P> <A NAME="IDX4433"></A> <A NAME="IDX4434"></A> <DL> <DT><span class="define">REGTYPE:</span> <B>location/1:</B> <DD><A NAME="IDX4435"></A> <P> <STRONG>Usage:</STRONG> <UL> <LI><EM>Description:</EM> Identifies a program source line. </UL> </DL> <H2><A NAME="SEC309" HREF="ciao_toc.html#TOC309">Known bugs and planned improvements (<CODE>messages</CODE>)</A></H2> <UL> <LI> Debug message switching should really be done with an expansion, for performance. </UL> <P><HR><P> Go to the <A HREF="ciao_1.html">first</A>, <A HREF="ciao_69.html">previous</A>, <A HREF="ciao_71.html">next</A>, <A HREF="ciao_241.html">last</A> section, <A HREF="ciao_toc.html">table of contents</A>. </BODY> </HTML>
