/usr/share/mozart/doc/system/node77.html is in mozart-doc 1.4.0-8ubuntu1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML><HEAD><TITLE>24 Error Formatting: Error</TITLE><LINK href="ozdoc.css" rel="stylesheet" type="text/css"></HEAD><BODY><TABLE align="center" border="0" cellpadding="6" cellspacing="6" class="nav"><TR bgcolor="#DDDDDD"><TD><A href="node58.html#chapter.property"><< Prev</A></TD><TD><A href="index.html">- Up -</A></TD><TD><A href="node78.html#chapter.errorformatters">Next >></A></TD></TR></TABLE><DIV id="chapter.error"><H1><A name="chapter.error">24 Error Formatting: <CODE>Error</CODE></A></H1><P> The <CODE>Error</CODE> module is concerned with various tasks related to error reporting. This encompasses the following: </P><UL><LI><P>Reporting errors as represented by data-structures called <A name="label840"></A><EM>error messages</EM>. </P></LI><LI><P>Constructing error messages from run-time error conditions in the form of exceptions. </P></LI><LI><P>Registering error formatters in the <A name="label841"></A><EM>error registry</EM>. </P></LI></UL><P> At boot time, the system installs a default exception handler processing all uncaught exceptions. This involves printing out the exception with the mechanisms mentioned above and executing a handler as given by the properties <CODE><SPAN class="string">'errors.toplevel'</SPAN></CODE> and <CODE><SPAN class="string">'errors.subordinate'</SPAN></CODE>, which see. </P><H2><A name="label842">24.1 Data Structures</A></H2><P> The central data structure used in this module is the error message. The general format is as follows: </P><BLOCKQUOTE><TABLE border="0" cellpadding="0" cellspacing="0"><TR valign="top"><TD><<I>message</I>></TD><TD align="center"> ::= </TD><TD><<I>message label</I>><CODE>(</CODE></TD></TR><TR valign="top"><TD></TD><TD align="center"></TD><TD><CODE> </CODE>[<CODE>kind: </CODE><<I>extended virtual string</I>>] </TD><TD align="left"><I> % origin subsystem or component</I></TD></TR><TR valign="top"><TD></TD><TD align="center"></TD><TD><CODE> </CODE>[<CODE>msg: </CODE><<I>extended virtual string</I>>] </TD><TD align="left"><I> % main message</I></TD></TR><TR valign="top"><TD></TD><TD align="center"></TD><TD><CODE> </CODE>[<CODE>items: [</CODE><<I>line</I>><CODE>]</CODE>] </TD><TD align="left"><I> % additional information</I></TD></TR><TR valign="top"><TD></TD><TD align="center"></TD><TD><CODE> </CODE>...<CODE>)</CODE> </TD><TD align="left"><I> % internal fields</I></TD></TR></TABLE></BLOCKQUOTE><P> All fields of the record are optional and specify information as indicated by the comments (wherever applicable). It is recommended that both <CODE>kind</CODE> and <CODE>msg</CODE> start with a lower-case letter and do not end in a period. </P><P> The label of the record is currently ignored by the procedures from the <CODE>Error</CODE> module, but other system modules expect it to be either <CODE>error</CODE> or <CODE>warn</CODE>, depending on the severity of the condition. </P><BLOCKQUOTE><TABLE border="0" cellpadding="0" cellspacing="0"><TR valign="top"><TD><<I>message label</I>></TD><TD align="center"> ::= </TD><TD><CODE>error</CODE> | <CODE>warn</CODE></TD></TR></TABLE></BLOCKQUOTE><P> </P><P> The <CODE>items</CODE> describe a sequence of lines meant to give additional hints about the error, but one should make sure that the error message is comprehensible without this information. All keys should start with a capital letter. </P><BLOCKQUOTE><TABLE border="0" cellpadding="0" cellspacing="0"><TR valign="top"><TD><<I>line</I>></TD><TD align="center"> ::= </TD><TD><CODE>hint(</CODE>[<CODE>l: </CODE><<I>extended virtual string</I>>]</TD></TR><TR valign="top"><TD></TD><TD align="center"></TD><TD><CODE> </CODE>[<CODE>m: </CODE><<I>extended virtual string</I>>]) </TD><TD align="left"><I> % key/value pair</I></TD></TR><TR valign="top"><TD></TD><TD align="center"> | </TD><TD><<I>coordinates</I>> </TD><TD align="left"><I> % source code error relates to</I></TD></TR><TR valign="top"><TD></TD><TD align="center"> | </TD><TD><CODE>line(</CODE><<I>extended virtual string</I>><CODE>)</CODE> </TD><TD align="left"><I> % full line of text</I></TD></TR><TR valign="top"><TD></TD><TD align="center"> | </TD><TD><CODE><SPAN class="keyword">unit</SPAN></CODE> </TD><TD align="left"><I> % empty line (separator)</I></TD></TR></TABLE></BLOCKQUOTE><P> </P><BLOCKQUOTE><TABLE border="0" cellpadding="0" cellspacing="0"><TR valign="top"><TD><<I>coordinates</I>></TD><TD align="center"> ::= </TD><TD><CODE>pos(</CODE><<I>atom</I>> </TD><TD align="left"><I> % file name; <CODE><SPAN class="string">''</SPAN></CODE> if not known</I></TD></TR><TR valign="top"><TD></TD><TD align="center"></TD><TD><CODE> </CODE><<I>int</I>> </TD><TD align="left"><I> % line number; required</I></TD></TR><TR valign="top"><TD></TD><TD align="center"></TD><TD><CODE> </CODE><<I>int</I>><CODE>)</CODE> </TD><TD align="left"><I> % column number; <CODE><SPAN class="keyword">~</SPAN>1</CODE> if not known</I></TD></TR></TABLE></BLOCKQUOTE><P> </P><P> An <<I>extended virtual string</I>> is a virtual string that may contain, for convenience, embedded records with special interpretation. </P><BLOCKQUOTE><TABLE border="0" cellpadding="0" cellspacing="0"><TR valign="top"><TD><<I>extended virtual string</I>></TD><TD align="center"> ::= </TD><TD><<I>atom</I>> | <<I>int</I>> | <<I>float</I>> | <<I>string</I>></TD></TR><TR valign="top"><TD></TD><TD align="center"> | </TD><TD><CODE><SPAN class="string">'#'</SPAN>(</CODE><<I>extended virtual string</I>> ... <<I>extended virtual string</I>><CODE>)</CODE></TD></TR><TR valign="top"><TD></TD><TD align="center"> | </TD><TD><CODE>oz(</CODE><<I>value</I>><CODE>)</CODE></TD></TR><TR valign="top"><TD></TD><TD align="center"> | </TD><TD><CODE>pn(</CODE><<I>atom</I>><CODE>)</CODE></TD></TR><TR valign="top"><TD></TD><TD align="center"> | </TD><TD><<I>coordinates</I>></TD></TR><TR valign="top"><TD></TD><TD align="center"> | </TD><TD><CODE>apply(</CODE><<I>procedure or print name</I>><CODE> [</CODE><<I>value</I>><CODE>])</CODE></TD></TR><TR valign="top"><TD></TD><TD align="center"> | </TD><TD><CODE>list([</CODE><<I>value</I>><CODE>] </CODE><<I>extended virtual string</I>><CODE>)</CODE></TD></TR></TABLE></BLOCKQUOTE><P> </P><BLOCKQUOTE><TABLE border="0" cellpadding="0" cellspacing="0"><TR valign="top"><TD><<I>procedure or print name</I>></TD><TD align="center"> ::= </TD><TD><<I>procedure</I>> | <<I>atom</I>></TD></TR></TABLE></BLOCKQUOTE><P> The embedded records are translated to virtual strings as follows: </P><DL><DT><CODE>oz(</CODE><CODE><I>X</I></CODE><CODE>)</CODE></DT><DD><P>transforms <CODE><I>X</I></CODE> using <CODE>Value<SPAN class="keyword">.</SPAN>toVirtualString</CODE>, using the print depth and width given by the system properties <CODE><SPAN class="string">'errors.depth'</SPAN></CODE> and <CODE><SPAN class="string">'errors.width'</SPAN></CODE>, respectively. </P></DD><DT><CODE>pn(</CODE><CODE>+<I>A</I></CODE><CODE>)</CODE></DT><DD><P>considers <CODE><I>A</I></CODE> to be a variable print name, i. e., escapes non-printable characters according to variable concrete syntax if <CODE><I>A</I></CODE> is enclosed in backquotes. </P></DD><DT><CODE>pos(</CODE><CODE>+<I>A</I></CODE><CODE> </CODE><CODE>+<I>I</I></CODE><CODE> </CODE><CODE>+<I>I</I></CODE><CODE>)</CODE></DT><DD><P>prints out source coordinates, e. g., <CODE>in file </CODE><CODE><I>A</I></CODE><CODE>, line </CODE><CODE><I>I</I></CODE><CODE>, column </CODE><CODE><I>I</I></CODE> with the unspecified parts omitted. </P></DD><DT><CODE>apply(</CODE><CODE>+<I>X</I></CODE><CODE> </CODE><CODE>+<I>Ys</I></CODE><CODE>)</CODE></DT><DD><P>represents an Oz application of <CODE><I>X</I></CODE> to <CODE><I>Ys</I></CODE>. Output uses the usual brace notation. </P></DD><DT><CODE>list(</CODE><CODE>+<I>Xs</I></CODE><CODE> </CODE><CODE>+<I>ExtendedVirtualString</I></CODE><CODE>)</CODE></DT><DD><P>outputs the values in <CODE><I>Xs</I></CODE> as if each was wrapped inside <CODE>oz(</CODE>...<CODE>)</CODE>, inserting <CODE><I>ExtendedVirtualString</I></CODE> between every pair of elements. </P></DD></DL><P> </P><H2><A name="label843">24.2 The Error Registry</A></H2><P> The <A name="label844"></A><EM>error registry</EM> has the purpose of storing so-called <A name="label845"></A><EM>error formatters</EM> under specific keys of type ``literal''. An error formatter <I>P</I> is a procedure with the signature </P><BLOCKQUOTE class="code"><CODE>{</CODE><I>P</I><CODE> </CODE><CODE>+<I>ExceptionR</I></CODE><CODE> </CODE><CODE>?<I>MessageR</I></CODE><CODE>}</CODE></BLOCKQUOTE><P> <I>P</I> must be capable of processing any exception having as label any of the keys under which <I>P</I> has been entered into the error registry and must return a <<I>message</I>> as defined above describing the condition. In the case of error or system exceptions, only the record found in the dispatch field of the exception is handed to the formatter. </P><P> Error formatters may be invoked by the default exception handler installed at boot time. Possibly dealing with serious conditions, formatters are required to be robust. In particular, the handler flags the thread executing the formatter to be <A name="label846"></A><EM>non-blocking</EM>, i. e., if it ever blocks on a logic variable, an exception is raised in this thread. This increases chances of any message being output at all. Note that it is allowed to block on futures though and that this flag is not inherited by any created child thread. </P><H2><A name="label847">24.3 Example Error Formatter</A></H2><P> The following piece of code illustrates how an error formatter might be registered and how it could behave. Assume a system component called <CODE>compiler</CODE>, which is given ``queries'' to process. If any query is ill-typed, an exception is raised, containing the query, the number of the ill-typed argument, and the expected argument type. Furthermore, an <CODE>internal</CODE> exception is raised when an internal programming assertion is violated. For robustness, an <CODE><SPAN class="keyword">else</SPAN></CODE> case is included to handle any other exceptions. The formatter simply prints out the exception record, since this might help more than no output at all. </P><BLOCKQUOTE class="code"><CODE>{Error<SPAN class="keyword">.</SPAN>registerFormatter compiler<BR> <SPAN class="keyword">fun</SPAN><SPAN class="variablename"> </SPAN>{<SPAN class="functionname">$</SPAN> E}<BR> T = <SPAN class="string">'compiler engine error'</SPAN> <BR> BugReport = <SPAN class="string">'please send a bug report to mozart-bugs@ps.uni-sb.de'</SPAN> <BR> <SPAN class="keyword">in</SPAN> <BR> <SPAN class="keyword">case</SPAN> E <SPAN class="keyword">of</SPAN> compiler(internal X) <SPAN class="keyword">then</SPAN> <BR> error(kind: T<BR> msg: <SPAN class="string">'Internal compiler error'</SPAN> <BR> items: [hint(l: <SPAN class="string">'Additional information'</SPAN> m: oz(X))<BR> line(BugReport)])<BR> <SPAN class="keyword">elseof</SPAN> compiler(invalidQuery M I A) <SPAN class="keyword">then</SPAN> <BR> error(kind: T<BR> msg: <SPAN class="string">'Ill-typed query argument'</SPAN> <BR> items: [hint(l: <SPAN class="string">'Query'</SPAN> m: oz(M))<BR> hint(l: <SPAN class="string">'At argument'</SPAN> m: I)<BR> hint(l: <SPAN class="string">'Expected type'</SPAN> m: A)])<BR> </CODE>...<CODE> <BR> <SPAN class="keyword">else</SPAN> <BR> error(kind: T<BR> items: [line(oz(E))])<BR> <SPAN class="keyword">end</SPAN> <BR> <SPAN class="keyword">end</SPAN>}</CODE></BLOCKQUOTE><P> </P><H2><A name="label848">24.4 The Module</A></H2><P> </P><DL><DT><CODE>exceptionToMessage</CODE> <A name="label850"></A> </DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{Error<SPAN class="keyword">.</SPAN>exceptionToMessage </CODE><CODE>+<I>Exception</I></CODE><CODE> </CODE><CODE>?<I>Message</I></CODE><CODE>}</CODE> </P></BLOCKQUOTE></DD><DD><P>constructs a <<I>message</I>> from an exception, using the formatters defined in the error registry or a generic formatter if none is defined for the exception. The message returned by the formatter is enriched with additional fields copied from the exception. </P></DD><DT><CODE>messageToVirtualString</CODE> <A name="label852"></A> </DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{Error<SPAN class="keyword">.</SPAN>messageToVirtualString </CODE><CODE>+<I>Message</I></CODE><CODE> </CODE><CODE>?<I>V</I></CODE><CODE>}</CODE> </P></BLOCKQUOTE></DD><DD><P>converts a <<I>message</I>> to a virtual string using the standard layout. This can span several lines and includes the final newline. </P></DD><DT><CODE>extendedVSToVS</CODE> <A name="label854"></A> </DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{Error<SPAN class="keyword">.</SPAN>extendedVSToVS </CODE><CODE>+<I>ExtendedVirtualString</I></CODE><CODE> </CODE><CODE>?<I>V</I></CODE><CODE>}</CODE> </P></BLOCKQUOTE></DD><DD><P>converts an <<I>extended virtual string</I>> to a <<I>virtual string</I>>. </P></DD><DT><CODE>printException</CODE> <A name="label856"></A> </DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{Error<SPAN class="keyword">.</SPAN>printException </CODE><CODE>+<I>Exception</I></CODE><CODE>}</CODE> </P></BLOCKQUOTE></DD><DD><P>converts an exception to a message and this to a virtual string, printing the result on standard error (using <CODE>System<SPAN class="keyword">.</SPAN>printError</CODE>). </P></DD><DT><CODE>registerFormatter</CODE> <A name="label858"></A> </DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{Error<SPAN class="keyword">.</SPAN>registerFormatter </CODE><CODE>+<I>L</I></CODE><CODE> </CODE><CODE>+<I>P</I></CODE><CODE>}</CODE> </P></BLOCKQUOTE></DD><DD><P>enters a formatter for exceptions with label <CODE><I>L</I></CODE> into the error registry, quietly replacing a possibly existing formatter for <CODE><I>L</I></CODE>. </P></DD></DL><P></P></DIV><TABLE align="center" border="0" cellpadding="6" cellspacing="6" class="nav"><TR bgcolor="#DDDDDD"><TD><A href="node58.html#chapter.property"><< Prev</A></TD><TD><A href="index.html">- Up -</A></TD><TD><A href="node78.html#chapter.errorformatters">Next >></A></TD></TR></TABLE><HR><ADDRESS><A href="http://www.ps.uni-sb.de/~duchier/">Denys Duchier</A>, <A href="http://www.ps.uni-sb.de/~kornstae/">Leif Kornstaedt</A>, <A href="http://www.ps.uni-sb.de/~homik/">Martin Homik</A>, <A href="http://www.ps.uni-sb.de/~tmueller/">Tobias Müller</A>, <A href="http://www.ps.uni-sb.de/~schulte/">Christian Schulte</A> and <A href="http://www.info.ucl.ac.be/~pvr">Peter Van Roy</A><BR><SPAN class="version">Version 1.4.0 (20110908185330)</SPAN></ADDRESS></BODY></HTML>
|