wiki.visual-prolog.com - User contributions [en]

Collection library

2010-05-26T09:37:22Z

Kehler: /* queue */

A collection is a value that contains a number (i.e. from zero to infinite) of other values.

Lists, sets, dictionaries, arrays, hash tables, (nondeterm) fact databases, etc are all collections.

A collection can also contain one value, but data types that by nature always contains exactly one value is not a collection. So a list with one element is a collection, but a variable which also contains one element is not a collection.

[[PFC]] contains an object oriented collection library with both persistent and modifiable collections. The collection library is based around a set of generic interfaces defining various conceptual collection types, and a number of classes implementing these interfaces.

== Persistent and Modifiable ==

Collections can be persistent or modifiable:

; Persistent
: A persistent collection never changes members. Meaning that when you insert or remove a member from persistent collection, you will receive a new collection and the old one will stay unchanged. Prolog lists is a characteristic example of persistent data types: When you match a list against a pattern to get the head and the tail, the original list stays intact; when you create a list from a new head and an existing list, both the new and the old list will exist.

; Modifiable
: Members can be added to and removed from a modifiable collection. Meaning that when you insert or remove a member from a modifiable collection, the old value of the collection is lost only the one exists. I.e. modifiable collections are updated destructively. Visual Prolog fact databases is a characteristic example of modifiable data types. When you assert or retract facts the database is modified and the original fact database is no longer accessible.

== Collection Interfaces & Classes ==

There is no fundamental difference in retrieving data from persistent and modifiable collection. The difference lies in the updating of the collections.

Therefore retrieval is done through interfaces that are shared by persistent and modifiable collections, whereas updating is done through separate persistent and modifiable interfaces.

<vp>collection</vp> is most fundamental interface for retrieving inspecting collections all collections supports this interface. It contains methods:
* <vp>isEmpty</vp> determining whether the collection is empty
* <vp>contains</vp> testing whether a certain element is in the collection
* <vp>tryGetFirst</vp> obtaining the first element in the collection.
* <vp>getAll_nd</vp> enumerating all elements in the collection.
* <vp>asList</vp> getting the collection in list form.

Notice that '''''first''''' means different things in different kinds of collections. In a hash table it may for example be the element with the first hash key.

Likewise, the order in which <vp>getAll_nd</vp> enumerates its elements depends on the collection kind.

Also notice that the performance of some operations may be very poor in some kind of collections. <vp>contains</vp> is for example a bad operation on a priority queue, because a priority queue not designed to determine membership.

All persistent collections also support the interface <vp>persistent</vp> and all modifiable collections supports the interface <vp>modifiable</vp>. <vp>persistent</vp> and <vp>modifiable</vp> have predicates with same names but different types, because the persistent version returns a new collection and the modifiable version doesn't return anything. These interfaces have methods:

* <vp>insert</vp>, <vp>insertList</vp> and <vp>insertCollection</vp> for inserting elements
* <vp>remove</vp>, <vp>removeList</vp> and <vp>removeCollection</vp> for removing elements
* <vp>tryRemoveFirst</vp> for removing the first element
* <vp>clear</vp> for removing all elements in the collection

=== set ===

A ''set'' is a collection of elements, which cannot contain duplicates. The fundamental set operation is test of membership. As such a set simply supports the <vp>collection</vp> interface and one of the interfaces <vp>persistent</vp> and <vp>modifiable</vp>.

* <vp>setP_redBlack</vp> implements persistent sets based on a red black tree representation.
* <vp>setM_redBlack</vp> implements modifiable sets based on a red black tree representation.

=== queue ===

A ''queue'' is a collection of elements which are ordered. The fundamental operation is getting the first element is the queue. Membership testing is typically inefficient. The interfaces of queues is similar to that of sets, supporting <vp>collection</vp> and one of the interfaces <vp>persistent</vp> and <vp>modifiable</vp>. The names are different to stress the difference in intension and efficeincy. And in future they may evolve differently. PFC contains two kinds of queues:

* ''queue'' is a "regular" FIFO (first-in-first-out) queue.
** <vp>queueP_fact</vp> implements a persistent FIFO queue based on a fact containing an algebraic queue
** <vp>queueM_fact</vp> implements a modifiable FIFO queue based on a nondeterm fact database

* ''priority queue'' is a queue where the first element is alwasy the element with hightst priority (i.e. the least, the greates or based on a custom comparison).
** <vp>priorityQueueP_leftist</vp> implements a persistent priority queue
** <vp>priorityQueueM_leftist</vp> implements a modifiable priority queue
Both are based on a leftist tree (see [[wikipedia:Leftist tree]]).

=== map ===

A '''map''' is a functionfrom ''keys'' to ''values''. Not all keys need have a value. The basic operations is setting, getting and try-getting the value associated with a certain key. When the value of a key is set the previous value of that key is "lost".

A map is a collection of (key,value)-tuples,so the <vp>collection</vp> predicates all deal with such tuples.

<vp>map</vp> is the basic interface for inspecting maps (persistent as well as modifiable). It supports <vp>collection</vp> of (key,value)-tuples and extends with predicates/properties:

* <vp>get</vp> and <vp>tryGet</vp> for getting the value associated with a key
* <vp>getKey_nd</vp> and <vp>getValue_nd</vp> for iterating the keys and values
* <vp>keyList</vp> and <vp>valueList</vp> for obtaining all the keys and values as lists.

<vp>mapP</vp> (persistent maps) and <vp>mapM</vp> (modifiable maps) supports <vp>map</vp> and either <vp>persistent</vp> or <vp>modifiable</vp>, and extends with:

* <vp>set</vp> for setting the value associated with a key (the previous value associated with that key is "lost")
* <vp>removeKey</vp> for removing a key and its associated value
* <vp>removeKeyList</vp> and <vp>removeKeyCollection</vp> for removing a number of keys and their associated values)

PFC contains persistent and modifiable map classes based on red-black trees:

* <vp>mapP_redBlack</vp>
* <vp>mapM_redBlack</vp>

== Usage examples ==

The examples in this section is inspired by the examples in ''The C5 Generic Collection Library for C# and CLI'', Niels Kokholm and Peter Sestoft, IT University Technical Report Series TR-2006-76, 2006.

=== Keyword recognition ===

It is often necessary to decide whether a word is member of some fixed collection of words. For example the keywords of a programming language, or frequent and therefore insignificant (so called stop-words) when indexing text.

Basically, we want to implement a class with a single deterministic predicate that can determine whether a word is a keyword:

<vip>class vipKeyword
predicates
isKeyword : (string Word) determ.
end class vipKeyword</vip>

It is a obvious choice to base the implementation on a set of keywords, because member-ship testing is the fundamantal operation of sets. The implementation can look like this:

<vip>implement vipKeyword
clauses
isKeyword(Word) :-
keywordSet:contains(Word).

class facts
keywordSet : setM{string Keyword} := initKeywordSet().

class predicates
initKeywordSet : () -> setM{string Keyword}.
clauses
initKeywordSet() = S :-
S = setM_redBlack::new(),
S:insertList(keywords).

constants
keywords : string* = ["as", "class", "clauses", ...].
end implement vipKeyword</vip>

<vp>isKeyword</vp> simply determines whether the the <vp>keywordSet</vp> <vp>contains</vp> the <vp>Word</vp> in question.

<vp>keywordSet</vp> is a (modifiable) set of strings, which is initialized to contain the actual keywords from the <vp>keywords</vp> constant.

Notice that you should be carefull when initializing class facts like it is done above. Such initialization is done in an unpredictable order before entering the goal of the program. So first of all it is difficult to know which other parts of the program that has already been initialized. Secondly, the exception system is not initialized properly so exceptions will be reported in a rather low-level fasion.

=== Text Concordance ===

A text concordance is a list of words in a text and the lines on which the word occurs, i.e. an index of text.

We will represent that concordance as a map from <vp>Word</vp> to a set of <vp>Linenumber</vp>'s, where word is a string and line is an integer. For convenience we will define a domain:

<vip>domains
concordance = mapM{string Word, setM{integer Linenumber}}.</vip>

To build a concordance from a stream (typically a file), we iterate the lines in the file, and the words of the line. For each word we insert it in the relevant line number set, which will have to be created if it does not already exist:

<vip>class predicates
build : (inputStream Input) -> concordance Concordance.
clauses
build(Input) = Concordance :-
Concordance = mapM_redBlack::new(),
foreach
tuple(Line, Linenumber) = getLine_nd(Input, 1),
Word = getWord_nd(Line)
do
if LinenumberSet = Concordance:tryGet(Word) then
else
LinenumberSet = setM_redBlack::new(),
Concordance:set(Word, LinenumberSet)
end if,
LinenumberSet:insert(Linenumber)
end foreach.</vip>

Though not important for the main topic the iteration predicates are here:

<vip>class predicates
getLine_nd : (inputStream Input, integer NextLine) -> tuple{string Line, integer Linenumber} nondeterm.
clauses
getLine_nd(Input, _NextLine) = _ :-
Input:endOfStream(),
!,
fail.

getLine_nd(Input, NextLine) = tuple(Line, NextLine) :-
Line = Input:readLine().

getLine_nd(Input, NextLine) = getLine_nd(Input, NextLine+1).

class predicates
getWord_nd : (string Line) -> string Word nondeterm.
clauses
getWord_nd(Line) = getWord2_nd(First, Rest) :-
string::frontToken(Line, First, Rest).

class predicates
getWord2_nd : (string First, string Rest) -> string Word nondeterm.
clauses
getWord2_nd(First, _Rest) = string::toLowerCase(First) :-
string::length(First) > 2, % only words with more than 2 letters
not(regexp::search("[^a-zA-Z]", First, _, _)). % not a word if it contains non-letters

getWord2_nd(_First, Rest) = getWord_nd(Rest).</vip>

From a concordance we can print an index, by iterating the <vp>(Word, LinenumberSet)</vp> tuples in the <vp>Concordance</vp>, and the <vp>Linenumber</vp>'s in the <vp>LinenumberSet</vp>'s. Since both the maps and the sets are based on red-black trees everything is automatically sorted for us:

<vip>class predicates
print : (outputStream Output, concordance Concordance).
clauses
print(Output, Concordance) :-
foreach tuple(Word, LinenumberSet) = Concordance:getAll_nd() do
Output:writef("%:\n", Word),
foreach Linenumber = LinenumberSet:getAll_nd() do
Output:writef(" %\n", Linenumber)
end foreach,
Output:write("\n")
end foreach.</vip>

== References ==

* [http://www.itu.dk/research/c5/ The C5 Generic Collection Library for C# and CLI]

[[Category:PFC]]
[[Category:Tutorials]]

Exception Handling

2010-01-23T11:51:00Z

Kehler: /* Defining an exception */

An exception is a deviation from the expected. What is an exception in one context may be expected in another context, and thus not an exception in that context.

In Visual Prolog programs exceptions are used to deal with deviations from what is expected in the given context. When a certain program part gets into a situation it cannot deal with it can '''''raise''''' an exception. When an exception is raised the program control is transferred to the nearest '''''exception handler'''''. If the exception handler cannot handle the exception it can either raise a new exception or '''''continue''''' the original exception.

The program will terminate with an error message if there is no exception handler to transfer the control to.

== Introduction to exception handling ==

There are many concepts and entities to understand when dealing with exceptions. This section will give an introduction by means of an example.

A certain program needs to write some information to a file. Therefore it has a predicate <vp>writeInfo</vp> that can write this information. <vp>writeInfo</vp> calls the PFC constructor <vp>outputStream_file::create</vp> to obtain a stream that it can write the information to:

<vip>clauses
writeInfo(Filename) :-
S = outputStream_file::create(Filename),
…</vip>

But if the file already exists and is write-protected it is impossible to create the stream.

In <vp>outputStream_file::create</vp> this situation is considered to be exceptional/unexpected and therefore it raises an exception.

When an exception is raised the program control is transferred to the nearest exception handler, which can hopefully handle the situation and thus bring the program back on track again.

In this case <vp>writeInfo</vp> is called after the user have entered the file name in a dialog and pressed a '''Save'''-button. So the handling we want is simply to tell the user that the information was not written because the file was write-protected. The user can choose a different filename, remove the write protection, delete the file, cancel the operation entirely or something else. But from the program's point of view the exceptional situation is handled.

To set a handler we use the {{lang2|Terms|try-catch|try-catch}} language construction:

<vip>clauses
saveInfo(Filename) :-
try
writeInfo(Filename)
catch TraceId do
% <<handle situation>>
end try.</vip>

The code works like this: <vp>writeInfo</vp> is called, if it succeeds the {{lang2|Terms|try-catch|try-catch}} construction will not do more and <vp>saveInfo</vp> will also succeed.

But in the write-protected case <vp>outputStream_file::create</vp> will raise an exception and therefore the following will take place:

# <vp>TraceId</vp> will be bound to the (so called) '''''trace id''''', which is a handle to information about the exception (described in more details below)
# The handler code (i.e. the code between <vp>do</vp> and <vp>end try</vp>) is evaluated
# The result of the handler code will be the result of the {{lang2|Terms|try-catch|try-catch}} construction, and thus of <vp>saveInfo</vp>.

So for the "write-protected" exception the handler code should write a message to the user.

If it is another kind of exception the handler will have to do something different. Especially, it may be an exception that the handler does not know how to handle. In this case the best thing the handler code can do is to continue the exception as an ''unknown'' exception (i.e. unknown to the handler).

When an exception is continued it consists of the original exception plus some continue information. If it has been continued by several handlers it will contain a lot of continue information in addition to the original exception information. The exception information describes a trace from the point of raise through all the handlers. The <vp>TraceId</vp> variable that is bound in the {{lang2|Terms|try-catch|try-catch}} construction gives access information about the entire trace (hence the name).

As mentioned above the program will terminate with en error message, if an exception is raised and no handler can be found. Therefore programs normally setup an outermost default exception handler. <vp>mainExe::run</vp> setup such a handler in a console program this is the fall-back handler. In a GUI program there is also a default hander in the GUI event loop which will catch exceptions arising from the handling of an event.

All in all, the lifecycle of an exception is as follows:

* It is raised
* It is caught and continued
* It is caught and continued
* …
* It is caught and handled (or the program terminates with an error message)

Each time the exception is caught the trace so far can be examined. When the exception is raised and each time it is continued extra information can be added to the exception trace. If nothing else handles an exception it will (normally) be handled by the fallback/default handler of the program.

== Defining an exception ==

An exception is a value of the type <vp>core::exception</vp>

<vip>domains
exception = (classInfo ClassInfo [out], string PredicateName [out], string Description [out]).</vip>

I.e. an exception is a predicate that returns three pieces of information:

; <vp>ClassInfo</vp>
: The <vp>classInfo</vp> of the class that defines the exception
; <vp>PredicateName</vp>
: The name of the exception predicate itself
; <vp>Description</vp>
: A description of the exception

{{example| The <vp>cannotCreate</vp> exception from the example above is declared in the class <vp>fileSystem_api</vp> like this:
<vip>class fileSystem_api
…
predicates
cannotCreate : exception.
…</vip>

The implementation looks like this:
<vip>implement fileSystem_api
…
clauses
cannotCreate(classInfo, predicate_name(), "Cannot create or open the specified file").
…</vip>
<vp>classInfo</vp> is the <vp>classInfo</vp> of the <vp>fileSystem_api</vp> class ; <vp>predicate_name</vp> is a built-in predicate that returns the name of the predicate in which it is called (i.e. in this case it will return <vp>"cannotCreate"</vp>). The last argument is the description of the exception.
}}

Many/most programmers will never need to define exceptions, because in many/most cases the exceptions to use are already defined. An exception definition is only needed when the exception must be distinguished from other kinds of exceptions, such that exception handlers can deal specially with that kind of exception. Typically exception definitions are only necessary for exceptions that are raised by library software. I most cases programmers will raise the exception <vp>internal_error</vp>.

== Raising an exception ==

Exceptions are raised using the predicate <vp>exception::raise</vp>:

<vip>class exception
…
predicates
raise : (classInfo ClassInfo, exception Exception) erroneous.
raise : (classInfo ClassInfo, exception Exception, namedValue_list ExtraInfo) erroneous.</vip>

<vp>ClassInfo</vp>
: The <vp>classInfo</vp> of the class that raise the excption
<vp>Exception</vp>
: The exception to raise
<vp>ExtraInfo</vp>
: Extra information about the raised exception.

{{example|The <vp>cannotCreate</vp> exception from above is raised by the predicate <vp>fileSystem_api::raise_cannotCreate</vp>. The code looks like this:
<vip>clauses
raise_cannotCreate(ClassInfo, FileName, LastError) :-
Desc = common_exception::getLastErrorDescription(LastError),
exception::raise(
ClassInfo,
cannotCreate,
[namedValue(fileSystem_exception::fileName_parameter, string(FileName)),
namedValue(common_exception::errorCode_parameter, unsigned(LastError)),
namedValue(common_exception::errorDescription_parameter, string(Desc))]).</vip>

<vp>raise_cannotCreate</vp> is called with the <vp>ClassInfo</vp> of the raising class the <vp>FileName</vp> and the windows error code <vp>LastError</vp> that the relevant low level Windows API predicate caused.

<vp>common_exception::getLastErrorDescription</vp> obtains the description corresponding to <vp>LastError</vp> from Windows.

<vp>exception::raise</vp> is then used to raise the <vp>cannotCreate</vp> exception with the three pieces of extra information. <vp>fileSystem_exception::fileName_parameter</vp>, <vp>common_exception::errorCode_parameter</vp> and <vp>common_exception::errorDescription_parameter</vp> are names (strings) used for the extra information.
}}

It is very common to create helper predicates like <vp>fileSystem_api::raise_cannotCreate</vp> to do the actual raising rather that calling <vp>exception::raise</vp> directly from the code that needs to raise the exception. That way it is certain that the extra info for this particular exception is handled in the same way in all cases.

Normally the helper raise predicate is created by the same programmer that declares the exception. And as mentioned above this is normally only programmers that create library software.

Application programmers will in most cases raise exceptions by calling appropriate raiser predicates, typically the ones defined in <vp>common_exception</vp>.

== Catching and handling exceptions ==

Exceptions are caught with the {{lang2|Terms|try-catch|try-catch}} construction:

<vipbnf>try <Body> catch <TraceId> do <Handler> end try</vipbnf>

If <vpbnf><Body></vpbnf> terminates with an exception <vpbnf><TraceId></vpbnf> is bound to the ''trace id'' and then <vpbnf><Handler></vpbnf> is evaluated.

<vpbnf><TraceId></vpbnf> is used to obtain information about the exception trace. This information can be used for at least two things:

* Determine which kind of exception that is caught, so that it can be decided if and how to handle it
* Obtain additional information to write to the user, in a log or use for something else

You will call <vp>exception::tryGetDescriptor</vp> to determine if a certain kind of exception is caught:

<vip>predicates
tryGetDescriptor : (traceId TraceID, exception Exception) -> descriptor Descriptor determ.</vip>

The exception trace corresponding to <vp>TraceId</vp> is searched for an exception of the kind <vp>Exception</vp>. If there is such an entry in the trace (raised or continued) a corresponding exception descriptor is returned in <vp>Descriptor</vp>.

The predicate fails if such an exception is not in the exception trace.

The <vp>Descriptor</vp> contains the extra information about that particular entry in the exception trace:

<vip>domains
descriptor = descriptor(classInfoDescriptor ClassInfo, exceptionDescriptor ExceptionInfo, kind Kind,
namedValue_list ExtraInfo, gmtTimeValue GMTTime, string ExceptionDescription, unsigned ThreadId).</vip>

; <vp>ClassInfo</vp>
: The <vp>classInfo</vp> of the class that raised the exception (in functor form)
; <vp>ExceptionInfo</vp>
: The <vp>exception</vp> in question (in functor form)
; <vp>Kind</vp>
: The entry kind (<vp>raise</vp> or <vp>continue</vp>)
; <vp>ExtraInfo</vp>
: The extra information provided with this entry in the trace
; <vp>GMTTime</vp>
: The time this exception trace entry was raised/continued
; <vp>ExceptionDescription</vp>
: The exception description of this entry (this information is also present in <vp>ExceptionInfo</vp>)
; <vp>ThreadId</vp>
: The thread id of the thread that raised/continued this entry

Much of this information is mainly interesting if the exception is not handled. The information that is most interesting when handling an exception is:

* The exception kind has been determined to be the one we expected
* The <vp>ExtraInfo</vp> for this entry is available for use in messages, etc

The predicate <vp>exception::tryGetExtraInfo</vp> is convenient for obtaining extra information:

<vip>predicates
tryGetExtraInfo : (descriptor Descriptor, string Name) -> value Value determ.</vip>

; <vp>Descriptor</vp>
: Is the description whose extra info we want to get something from.
; <vp>Name</vp>
: The name of the extra info parameter we want to obtain.
; <vp>Value</vp>
: The value that the mentioned parameter has.

{{example| Code for catching and handling the <vp>fileSystem_api::cannotCreate</vp> exception can look like this:

<vip>clauses
saveInfo(Filename) :-
try
writeInfo(Filename)
catch TraceId do
if D = exception::tryGetDescriptor(TraceId, fileSystem_api::cannotCreate) then
stdio::write("Cannot write to the file: ", Filename),
if string(Description) = exception::tryGetExtraInfo(D, common_exception::errorDescription_parameter) then
stdio::writef("; %", Description)
end if,
stdio::write("\n")
else
common_exception::continue_unknown(TraceId, classInfo, predicate_name(), "Filename = ", Filename)
end if
end try.</vip>

The code here don't need to obtain the <vp>fileSystem_exception::fileName_parameter</vp>, because the file name is already known in the <vp>Filename</vp> variable.

But we can obtain Window's description of the problem querying for <vp>common_exception::errorDescription_parameter</vp>

We '''continue''' the exception as unknown if it is not the <vp>cannotCreate</vp> kind . For the continue call we add the filename as. <vp>common_exception::continue_unknown</vp> will create a string of the extra arguments and add it as an <vp>common_exception::errorArguments_parameter</vp>. Such information is mainly for use in the default exception handler to be discussed below.
}}

== Serializing exceptions ==

In some situations the best way to handle an exception is by sending all the information about the exception somewhere else. A server might for example want to send the information to the client program that caused the exception, because then there is a user that can take action.

A <vp>traceId</vp> only have a meaning in the process that has created it, but the predicate <vp>exception::getTraceInfo</vp> can create a <vp>traceInfo</vp> structure (<vp>TraceInfo</vp>) from the <vp>traceId TraceId</vp>:

<vip>predicates
getTraceInfo : (traceId TraceId) -> traceInfo TraceInfo.</vip>

Such a structure is a functor structure that can be serialized/deserialized with <vp>toString</vp>/<vp>toTerm</vp>; <vp>write</vp>/<vp>read</vp>; nested in a fact database using <vp>save</vp>/<vp>consult</vp>; etc.

== Exception dumps ==

The class <vp>exceptionDump</vp> contains predicates for dumping exception traces to <vp>stdio</vp>, some other <vp>outputStream</vp> or a <vp>string</vp>.

An exception dump contains three major pieces of information:

* A dump of the call stack (with file names and line numbers) from the point where the exception was raised
* A dump of the exception-trace with all the information from the exception descriptors
* Information about the operating system that the program ran on

<vp>exceptionDump</vp> have predicates both for dumping exception traces both from a <vp>traceId</vp> and from a <vp>traceInfo</vp> obtained with <vp>exception::getTraceInfo</vp>.

Dumps for a certain program are in general only useful to the programmers of that program; the users of the program will find dumps cryptic and rather uninteresting. I.e. the purpose of dumps is to give the programmer means for improving the program.

== Default handling ==

A program should handle all exceptions, because if an exception is continued or raised at a point where there is no handler the program will terminate with a rather bad error message. The error message is bad because most exception handling is done in PFC; the language itself knows nothing about exception traces and the like.

To be sure that all exceptions are handled it is normal to set up a default (or fallback) exception handler.

<vp>mainExe::run</vp> (and <vp>mainExe::runCom</vp>) which is normally called in the goal setup such a default exception handler: It runs the <vp>main::run</vp> predicate inside a {{lang2|Terms|try-catch|try-catch}} construction that will handle any exception.

The handler in <vp>mainExe::run</vp> (and <vp>mainExe::runCom</vp>) dumps the entire exception trace to output stream in <vp>stdio</vp>. And then the program will terminate. The idea is that:

* Perhaps the user can see something from the dump (which may for example say that ''access is denied'' to ''xxx.txt'')
* Alternatively, the developer of the program may use the dump to improve the program

In addition to the handler in <vp>mainExe::run</vp> a GUI program also set a default handler in the event loop. This handler is set by calling <vp>applicationWindow::setErrorResponder</vp>:

<vip>domains
errorResponder = (applicationWindow Source, exception::traceId TraceId).

predicates
setErrorResponder : (errorResponder Responder).</vip>

By default the error responder <vp>errorPresentationDialog::present</vp> is used. The functioning of the <pv>errorPresentationDialog</vp> is closely related to a categorization of exceptions described in the next section.

PFC place exceptions in three major categories based on who is (believed to be) responsible:

; Internal errors
: An exceptional state which the programmer is responsible to deal with
; User exceptions
: An exception which can perhaps be solved by the end user of the program, but which may also call for a programmer solution. User exceptions carries a message for the end user of the program.
; Definite user errors
: An exception which is definitely one the end user should deal with, because the programmer cannot do anything about it anyway

You may notice that "error" is used to signal that a person is (believed to be) responsible for the problem, where as "exception" also covers situations with looser relation to specific persons (such as a network failure).

=== Internal errors ===

Internal errors are caused and/or should be prevented by the programmer of the program.

{{Example| A predicate takes two lists as argument and pair the elements of the lists. So the lists are expected to have the same length. If the lists have different lengths it is appropriate to raise an <vp>internal_error</vp>, because it is clearly the responsibility of the programmer to ensure that the lists have same length; the end-user of the program can at most influence this indirectly.
}}

=== User exceptions ===

User exceptions typically deal with problems related to external resources such as files, network, databases, web servers, etc. Often the user will become wiser by being informed about the problem and often the user may even solve the problem.

{{Example| The read-only file problem discussed above is a typical example of a user exception. It is the user rather than the programmer that can solve the problem with the read-only file.
}}

A user exception is distinguished by having extra information in a field with name <vp>common_exception::userMessage_parameter</vp>. This extra info should be a message with relevance for an end user of the program. The message can reference other extra info parameters using the format %PARAM. The preferred way to raise user exceptions is by means of the predicate <vp>common_exception::raise_user</vp>. Likewise you can continue exceptions with a user message using <vp>common_exception::continue_user</vp>.

{{Example| This predicate will raise a '''''user''''' <vp>fileSystem_api::cannotCreate</vp> exception

<vip>class predicates
raise_cannotCreate : (string Filename) erroneous.
clauses
raise_cannotCreate(Filename) :-
common_exception::raise_user(classInfo, fileSystem_api::cannotCreate, predicate_name(),
"It is not possible to create the file %Filename",
[namedValue("Filename", string(Filename))]).</vip>

The use of <vp>"%Filename"</vp> in the message corresponds to the extra info <vp>"Filename"</vp>.
}}

The predicate <vp>exceptionDump::tryGetUserMessage</vp> will return a user message from a <vp>traceId</vp> if possible. The message will consist of all user messages from the entire trace and will have parameters substituted.

{{Example| Given <vp>raise_cannotCreate</vp> from above and calling <vp>test</vp>:

<vip>clauses
test() :-
try
raise_cannotCreate("test.xxx")
catch TraceId do
if UserMsg = exceptionDump::tryGetUserMessage(TraceId) then
stdio::write(UserMsg)
end if
end try.</vip>

The following message is written to <vp>stdio</vp>:

<source lang="text">It is not possible to create the file test.xxx</source>
}}

=== Definite user errors ===

Definite user errors are exceptions that are solely the responsibility of the user of the program. For example wrong use of the program.

{{Example| A program can write out some information, but only if the user has specified which information to write. So if the user invoke the functionality without having specified which information to write, it is appropriate to raise a definite user error.
}}

A definite user exception is distinguished by adding <vp>true</vp> as extra info for the parameter <vp>common_exception::definiteUserError_parameter</vp>. The preferred way to do this is by using the predicates:

* <vp>common_exception::raise_definiteUser</vp>
* <vp>common_exception::continue_definiteUser</vp>

The use of these predicates is the same as the user of <vp>common_exception::raise_user</vp> and <vp>common_exception::continue_user</vp>.

An exception trace is considered a definite user error if one (or more) entries in the trace carries the <vp>common_exception::definiteUserError_parameter</vp>. The predicate <vp>common_exception::isDefiniteUserError</vp> will succeed for definite user errors.

=== Packed Exceptions ===

Some times, e.g., in a client/server application, you catch an exception on the server which you want to handle on the client. In that case you can serialize the exception on the server send it to the client and reraise it as a packed exception.

On the server
<vip>
try
...
catch E do
sendExceptionToClient(exception::getTraceInfo())
end try,
...
</vip>

On the client
<vip>
...
Rtn = remoteCall(...),
if Rtn = error(ExceptionInfo) then
common_exception::raise_packed(ExceptionInfo, classInfo, predicate_name(),"remoteCall returned an exception")
end if
...
</vip>

The predicate raise_packed works like a continue_unknown but continues a serialized exception instead of normal exception. It is meant to be used when the exception stem from another program and thus only is available in serialized form.

== The error presentation dialog ==

The error presentation dialog (in the class <vp>errorPresentationDialog</vp>) is by default used by the default exception handling in a GUI program. Its behavior is closely related to the classification of exceptions described above, as described by these two rules:

* If the exception trace carries a user message, this message will be presented to the user.
* If the exception trace is not a definite user error, there will be information for the programmer

So if the exception is an internal error there will only be information for the programmer; if it is a user exception there will both be information for the user and for the programmer; and if it is a user error there will only be information for the user.

If there is information to the programmer the exception dialog will have a details/less details button that can show/hide the programmer information. It will also have a "report error" button, which by default will copy the information to the clipboard so that the user can easily send it to the programmer.

[[Image:ErrorPresentationDialogDefault.png]]

The dialog is customizable by means of various properties:

<vip>properties
title : string. % := "Error".
callBackBtnText : string. % := "&Copy".
dontCallBackBtnText : string. % := "&OK".
showDetailsBtnText : string. % := "Show &Details".
hideDetailsBtnText : string. % := "Hide &Details".
closeApplicationBtnText : string. % := "Close &Application".
commentTextPromt : string. % := "Please describe what you were doing when the error occured:"
internalErrorMessage : string. % := "An internal error has occurred.\nPlease send a bug report to your vendor.".
feedbackMessage : string. % := "Please send your feedback.".
definiteUserErrorIcon : vpiDomains::resid.
userErrorIcon : vpiDomains::resid.
internalErrorIcon : vpiDomains::resid.
reportErrorDelegate : reportErrorDelegate.
extraInfoWriter : writer.</vip>

All texts and labels are controlled by properties.

The <vp>extraInfoWriter</vp> is a callback that can be set to include extra info for the programmer. This information will both be presented in the details window and reported back to the programmer if the user press the "report error" button (i.e. the button which is by default labeled '''Copy''').

The <vp>extraInfoWriter</vp> callback predicate must have this type:

<vip>domains
writer = (outputStream Stream).</vip>

The dialog will invoke the predicate and then it should simply write extra information to the received stream.

{{Example| The Visual Prolog IDE uses the <vp>extraInfoWriter</vp> to write version information, information about the open project and information about the last actions carried out in the IDE. This information will help the programmers to analyze the problem.
}}

The action performed by the "report error" button is customizable using the property <vp>reportErrorDelegate</vp>, which is a callback predicate of this type:

<vip>domains
reportErrorDelegate = (window Parent, string Comment, optional{exception::traceInfo} TraceInfo, string ExtraInfo).</vip>

; <vp>Parent</vp>
: The error presentation dialog which can be used as parent for additional dialogs.
; <vp>Comment</vp>
: The users comment from the comment box.
; <vp>TraceInfo</vp>
: If the dialog is invoked on an exception the trace info is here, if it is invoked for feedback this value is <vp>none</vp>
; <vp>ExtraInfo</vp>
: The extra info written by the <vp>extraInfoWriter</vp> callback

{{Example| In the Visual Prolog IDE the <vp>reportErrorDelegate</vp> will send the exception information to a WEB service which will insert the notification in a database. The notifications in the database will then be used to improve the IDE.
}}

[[Category:Tutorials]]

Calling C Sharp via COM

2009-02-20T10:55:33Z

Kehler: /* Further info about .Net COM integration */

== Howto call C# ==

This tutorial gives a description of one way of accessing C# from prolog.

We make the C# library COM visible and then we import the COM component in visual prolog.

=== Creating a C# COM component in Visual Studio ===

# Create a C# project. I just created one that was a class library.
# Open the project properties. Open the assembly information. Select ‘Make Assembly Com-Visible’.
# Make an interface that expose the functions you want to call and a class that implements that interface.

For the interface set the attributes InterfaceType ot InterfaceIsIUnknown and a GuidAttribute to some GUID (generated by tools\Create GUID in VS)

<source lang="csharp">
[InterfaceType(ComInterfaceType.InterfaceIsIUnknown),
GuidAttribute("0828DB14-1275-3926-813D-494F4FE771CF")]
public interface IMyInterface
{
string MyFunction(string Input);
}
</source>

The ClassInterface should be None and here should also be a GuidAttribute.

<source lang="csharp">
[ClassInterface(ClassInterfaceType.None),
GuidAttribute("95E62F78-55FF-4061-8238-6D3FCF88F5D0")]
public class MyClass : IMyInterface
{
…
}
</source>

Remember to add:

<source lang="csharp">
using System.Runtime.InteropServices;
</source>

Compile the program.

=== Importing the COM component in Visual Prolog ===

Copy assembly dll to your prolog projects exe folder.

If it has to be placed somewhere else there is some work with the registration which have to use /codebase, currently we expect it to be placed in the exe folder

Run tlbexp.exe on the dll to get a xxx.tbl file tlpexp.exe comes together with the windows SDK.

Register the dll using regasm.exe (this has to be done every time the program have to run on a new machine).

Import the COM component into the Visual Prolog project.
Select 'New in new package' in the project tree. Give the package a name and select COM package load the type library (that is the tlb file).

Now the program should be able to run.

=== Further info about .Net COM integration ===

You can find more information here: [http://msdn.microsoft.com/en-us/library/zsfww439.aspx]

[[Category:Tutorials]]

Calling C Sharp via COM

2009-02-20T10:54:52Z

Kehler: New page: == Howto call C# == This tutorial gives a description of one way of accessing C# from prolog. We make the C# library COM visible and then we import the COM component in visual prolog. =...

Exception Handling

2008-11-23T12:12:39Z

Kehler: /* Packed Exceptions */

An exception is a deviation from the expected. What is an exception in one context may be expected in another context, and thus not an exception in that context.

In Visual Prolog programs exceptions are used to deal with deviations from what is expected in the given context. When a certain program part gets into a situation it cannot deal with it can '''''raise''''' an exception. When an exception is raised the program control is transferred to the nearest '''''exception handler'''''. If the exception handler cannot handle the exception it can either raise a new exception or '''''continue''''' the original exception.

The program will terminate with an error message if there is no exception handler to transfer the control to.

== Introduction to exception handling ==

There are many concepts and entities to understand when dealing with exceptions. This section will give an introduction by means of an example.

A certain program needs to write some information to a file. Therefore it has a predicate <vp>writeInfo</vp> that can write this information. <vp>writeInfo</vp> calls the PFC constructor <vp>outputStream_file::create</vp> to obtain a stream that it can write the information to:

<vip>clauses
writeInfo(Filename) :-
S = outputStream_file::create(Filename),
…</vip>

But if the file already exists and is write-protected it is impossible to create the stream.

In <vp>outputStream_file::create</vp> this situation is considered to be exceptional/unexpected and therefore it raises an exception.

When an exception is raised the program control is transferred to the nearest exception handler, which can hopefully handle the situation and thus bring the program back on track again.

In this case <vp>writeInfo</vp> is called after the user have entered the file name in a dialog and pressed a '''Save'''-button. So the handling we want is simply to tell the user that the information was not written because the file was write-protected. The user can choose a different filename, remove the write protection, delete the file, cancel the operation entirely or something else. But from the program's point of view the exceptional situation is handled.

To set a handler we use the {{lang2|Terms|try-catch|try-catch}} language construction:

<vip>clauses
saveInfo(Filename) :-
try
writeInfo(Filename)
catch TraceId do
% <<handle situation>>
end try.</vip>

The code works like this: <vp>writeInfo</vp> is called, if it succeeds the {{lang2|Terms|try-catch|try-catch}} construction will not do more and <vp>saveInfo</vp> will also succeed.

But in the write-protected case <vp>outputStream_file::create</vp> will raise an exception and therefore the following will take place:

# <vp>TraceId</vp> will be bound to the (so called) '''''trace id''''', which is a handle to information about the exception (described in more details below)
# The handler code (i.e. the code between <vp>do</vp> and <vp>end try</vp>) is evaluated
# The result of the handler code will be the result of the {{lang2|Terms|try-catch|try-catch}} construction, and thus of <vp>saveInfo</vp>.

So for the "write-protected" exception the handler code should write a message to the user.

If it is another kind of exception the handler will have to do something different. Especially, it may be an exception that the handler does not know how to handle. In this case the best thing the handler code can do is to continue the exception as an ''unknown'' exception (i.e. unknown to the handler).

When an exception is continued it consists of the original exception plus some continue information. If it has been continued by several handlers it will contain a lot of continue information in addition to the original exception information. The exception information describes a trace from the point of raise through all the handlers. The <vp>TraceId</vp> variable that is bound in the {{lang2|Terms|try-catch|try-catch}} construction gives access information about the entire trace (hence the name).

As mentioned above the program will terminate with en error message, if an exception is raised and no handler can be found. Therefore programs normally setup an outermost default exception handler. <vp>mainExe::run</vp> setup such a handler in a console program this is the fall-back handler. In a GUI program there is also a default hander in the GUI event loop which will catch exceptions arising from the handling of an event.

All in all, the lifecycle of an exception is as follows:

* It is raised
* It is caught and continued
* It is caught and continued
* …
* It is caught and handled (or the program terminates with an error message)

Each time the exception is caught the trace so far can be examined. When the exception is raised and each time it is continued extra information can be added to the exception trace. If nothing else handles an exception it will (normally) be handled by the fallback/default handler of the program.

== Defining an exception ==

An exception is a value of the type <vp>core::exception</vp>

<vip>domains
exception = (classInfo ClassInfo [out], string PredicateName [out], string Description [out]).</vip>

I.e. an exception is a predicate that returns three pieces of information:

; <vp>ClassInfo</vp>
: The <vp>classInfo</vp> of the class that defines the exception
; <vp>PredicateName</vp>
: The name of the exception predicate itself
; <vp>Description</vp>
: A description of the exception

{{example| The <vp>cannotCreate</vp> exception from the example above is declared in the class <vp>fileSystem_api</vp> like this:
<vip>class fileSystem_api
…
predicates
cannotCreate : exception.
…</vip>

The implementation looks like this:
<vip>impement fileSystem_api
…
clauses
cannotCreate(classInfo, predicate_name(), "Cannot create or open the specified file").
…</vip>
<vp>classInfo</vp> is the <vp>classInfo</vp> of the <vp>fileSystem_api</vp> class ; <vp>predicate_name</vp> is a built-in predicate that returns the name of the predicate in which it is called (i.e. in this case it will return <vp>"cannotCreate"</vp>). The last argument is the description of the exception.
}}

Many/most programmers will never need to define exceptions, because in many/most cases the exceptions to use are already defined. An exception definition is only needed when the exception must be distinguished from other kinds of exceptions, such that exception handlers can deal specially with that kind of exception. Typically exception definitions are only necessary for exceptions that are raised by library software. I most cases programmers will raise the exception <vp>internal_error</vp>.

== Raising an exception ==

Exceptions are raised using the predicate <vp>exception::raise</vp>:

<vip>class exception
…
predicates
raise : (classInfo ClassInfo, exception Exception) erroneous.
raise : (classInfo ClassInfo, exception Exception, namedValue_list ExtraInfo) erroneous.</vip>

<vp>ClassInfo</vp>
: The <vp>classInfo</vp> of the class that raise the excption
<vp>Exception</vp>
: The exception to raise
<vp>ExtraInfo</vp>
: Extra information about the raised exception.

{{example|The <vp>cannotCreate</vp> exception from above is raised by the predicate <vp>fileSystem_api::raise_cannotCreate</vp>. The code looks like this:
<vip>clauses
raise_cannotCreate(ClassInfo, FileName, LastError) :-
Desc = common_exception::getLastErrorDescription(LastError),
exception::raise(
ClassInfo,
cannotCreate,
[namedValue(fileSystem_exception::fileName_parameter, string(FileName)),
namedValue(common_exception::errorCode_parameter, unsigned(LastError)),
namedValue(common_exception::errorDescription_parameter, string(Desc))]).</vip>

<vp>raise_cannotCreate</vp> is called with the <vp>ClassInfo</vp> of the raising class the <vp>FileName</vp> and the windows error code <vp>LastError</vp> that the relevant low level Windows API predicate caused.

<vp>common_exception::getLastErrorDescription</vp> obtains the description corresponding to <vp>LastError</vp> from Windows.

<vp>exception::raise</vp> is then used to raise the <vp>cannotCreate</vp> exception with the three pieces of extra information. <vp>fileSystem_exception::fileName_parameter</vp>, <vp>common_exception::errorCode_parameter</vp> and <vp>common_exception::errorDescription_parameter</vp> are names (strings) used for the extra information.
}}

It is very common to create helper predicates like <vp>fileSystem_api::raise_cannotCreate</vp> to do the actual raising rather that calling <vp>exception::raise</vp> directly from the code that needs to raise the exception. That way it is certain that the extra info for this particular exception is handled in the same way in all cases.

Normally the helper raise predicate is created by the same programmer that declares the exception. And as mentioned above this is normally only programmers that create library software.

Application programmers will in most cases raise exceptions by calling appropriate raiser predicates, typically the ones defined in <vp>common_exception</vp>.

== Catching and handling exceptions ==

Exceptions are caught with the {{lang2|Terms|try-catch|try-catch}} construction:

<vipbnf>try <Body> catch <TraceId> do <Handler> end try</vipbnf>

If <vpbnf><Body></vpbnf> terminates with an exception <vpbnf><TraceId></vpbnf> is bound to the ''trace id'' and then <vpbnf><Handler></vpbnf> is evaluated.

<vpbnf><TraceId></vpbnf> is used to obtain information about the exception trace. This information can be used for at least two things:

* Determine which kind of exception that is caught, so that it can be decided if and how to handle it
* Obtain additional information to write to the user, in a log or use for something else

You will call <vp>exception::tryGetDescriptor</vp> to determine if a certain kind of exception is caught:

<vip>predicates
tryGetDescriptor : (traceId TraceID, exception Exception) -> descriptor Descriptor determ.</vip>

The exception trace corresponding to <vp>TraceId</vp> is searched for an exception of the kind <vp>Exception</vp>. If there is such an entry in the trace (raised or continued) a corresponding exception descriptor is returned in <vp>Descriptor</vp>.

The predicate fails if such an exception is not in the exception trace.

The <vp>Descriptor</vp> contains the extra information about that particular entry in the exception trace:

<vip>domains
descriptor = descriptor(classInfoDescriptor ClassInfo, exceptionDescriptor ExceptionInfo, kind Kind,
namedValue_list ExtraInfo, gmtTimeValue GMTTime, string ExceptionDescription, unsigned ThreadId).</vip>

; <vp>ClassInfo</vp>
: The <vp>classInfo</vp> of the class that raised the exception (in functor form)
; <vp>ExceptionInfo</vp>
: The <vp>exception</vp> in question (in functor form)
; <vp>Kind</vp>
: The entry kind (<vp>raise</vp> or <vp>continue</vp>)
; <vp>ExtraInfo</vp>
: The extra information provided with this entry in the trace
; <vp>GMTTime</vp>
: The time this exception trace entry was raised/continued
; <vp>ExceptionDescription</vp>
: The exception description of this entry (this information is also present in <vp>ExceptionInfo</vp>)
; <vp>ThreadId</vp>
: The thread id of the thread that raised/continued this entry

Much of this information is mainly interesting if the exception is not handled. The information that is most interesting when handling an exception is:

* The exception kind has been determined to be the one we expected
* The <vp>ExtraInfo</vp> for this entry is available for use in messages, etc

The predicate <vp>exception::tryGetExtraInfo</vp> is convenient for obtaining extra information:

<vip>predicates
tryGetExtraInfo : (descriptor Descriptor, string Name) -> value Value determ.</vip>

; <vp>Descriptor</vp>
: Is the description whose extra info we want to get something from.
; <vp>Name</vp>
: The name of the extra info parameter we want to obtain.
; <vp>Value</vp>
: The value that the mentioned parameter has.

{{example| Code for catching and handling the <vp>fileSystem_api::cannotCreate</vp> exception can look like this:

<vip>clauses
saveInfo(Filename) :-
try
writeInfo(Filename)
catch TraceId do
if D = exception::tryGetDescriptor(TraceId, fileSystem_api::cannotCreate) then
stdio::write("Cannot write to the file: ", Filename),
if string(Description) = exception::tryGetExtraInfo(D, common_exception::errorDescription_parameter) then
stdio::writef("; %", Description)
end if,
stdio::write("\n")
else
common_exception::continue_unknown(TraceId, classInfo, predicate_name(), "Filename = ", Filename)
end if
end try.</vip>

The code here don't need to obtain the <vp>fileSystem_exception::fileName_parameter</vp>, because the file name is already known in the <vp>Filename</vp> variable.

But we can obtain Window's description of the problem querying for <vp>common_exception::errorDescription_parameter</vp>

We '''continue''' the exception as unknown if it is not the <vp>cannotCreate</vp> kind . For the continue call we add the filename as. <vp>common_exception::continue_unknown</vp> will create a string of the extra arguments and add it as an <vp>common_exception::errorArguments_parameter</vp>. Such information is mainly for use in the default exception handler to be discussed below.
}}

== Serializing exceptions ==

In some situations the best way to handle an exception is by sending all the information about the exception somewhere else. A server might for example want to send the information to the client program that caused the exception, because then there is a user that can take action.

A <vp>traceId</vp> only have a meaning in the process that has created it, but the predicate <vp>exception::getTraceInfo</vp> can create a <vp>traceInfo</vp> structure (<vp>TraceInfo</vp>) from the <vp>traceId TraceId</vp>:

<vip>predicates
getTraceInfo : (traceId TraceId) -> traceInfo TraceInfo.</vip>

Such a structure is a functor structure that can be serialized/deserialized with <vp>toString</vp>/<vp>toTerm</vp>; <vp>write</vp>/<vp>read</vp>; nested in a fact database using <vp>save</vp>/<vp>consult</vp>; etc.

== Exception dumps ==

The class <vp>exceptionDump</vp> contains predicates for dumping exception traces to <vp>stdio</vp>, some other <vp>outputStream</vp> or a <vp>string</vp>.

An exception dump contains three major pieces of information:

* A dump of the call stack (with file names and line numbers) from the point where the exception was raised
* A dump of the exception-trace with all the information from the exception descriptors
* Information about the operating system that the program ran on

<vp>exceptionDump</vp> have predicates both for dumping exception traces both from a <vp>traceId</vp> and from a <vp>traceInfo</vp> obtained with <vp>exception::getTraceInfo</vp>.

Dumps for a certain program are in general only useful to the programmers of that program; the users of the program will find dumps cryptic and rather uninteresting. I.e. the purpose of dumps is to give the programmer means for improving the program.

== Default handling ==

A program should handle all exceptions, because if an exception is continued or raised at a point where there is no handler the program will terminate with a rather bad error message. The error message is bad because most exception handling is done in PFC; the language itself knows nothing about exception traces and the like.

To be sure that all exceptions are handled it is normal to set up a default (or fallback) exception handler.

<vp>mainExe::run</vp> (and <vp>mainExe::runCom</vp>) which is normally called in the goal setup such a default exception handler: It runs the <vp>main::run</vp> predicate inside a {{lang2|Terms|try-catch|try-catch}} construction that will handle any exception.

The handler in <vp>mainExe::run</vp> (and <vp>mainExe::runCom</vp>) dumps the entire exception trace to output stream in <vp>stdio</vp>. And then the program will terminate. The idea is that:

* Perhaps the user can see something from the dump (which may for example say that ''access is denied'' to ''xxx.txt'')
* Alternatively, the developer of the program may use the dump to improve the program

In addition to the handler in <vp>mainExe::run</vp> a GUI program also set a default handler in the event loop. This handler is set by calling <vp>applicationWindow::setErrorResponder</vp>:

<vip>domains
errorResponder = (applicationWindow Source, exception::traceId TraceId).

predicates
setErrorResponder : (errorResponder Responder).</vip>

By default the error responder <vp>errorPresentationDialog::present</vp> is used. The functioning of the <pv>errorPresentationDialog</vp> is closely related to a categorization of exceptions described in the next section.

PFC place exceptions in three major categories based on who is (believed to be) responsible:

; Internal errors
: An exceptional state which the programmer is responsible to deal with
; User exceptions
: An exception which can perhaps be solved by the end user of the program, but which may also call for a programmer solution. User exceptions carries a message for the end user of the program.
; Definite user errors
: An exception which is definitely one the end user should deal with, because the programmer cannot do anything about it anyway

You may notice that "error" is used to signal that a person is (believed to be) responsible for the problem, where as "exception" also covers situations with looser relation to specific persons (such as a network failure).

=== Internal errors ===

Internal errors are caused and/or should be prevented by the programmer of the program.

{{Example| A predicate takes two lists as argument and pair the elements of the lists. So the lists are expected to have the same length. If the lists have different lengths it is appropriate to raise an <vp>internal_error</vp>, because it is clearly the responsibility of the programmer to ensure that the lists have same length; the end-user of the program can at most influence this indirectly.
}}

=== User exceptions ===

User exceptions typically deal with problems related to external resources such as files, network, databases, web servers, etc. Often the user will become wiser by being informed about the problem and often the user may even solve the problem.

{{Example| The read-only file problem discussed above is a typical example of a user exception. It is the user rather than the programmer that can solve the problem with the read-only file.
}}

A user exception is distinguished by having extra information in a field with name <vp>common_exception::userMessage_parameter</vp>. This extra info should be a message with relevance for an end user of the program. The message can reference other extra info parameters using the format %PARAM. The preferred way to raise user exceptions is by means of the predicate <vp>common_exception::raise_user</vp>. Likewise you can continue exceptions with a user message using <vp>common_exception::continue_user</vp>.

{{Example| This predicate will raise a '''''user''''' <vp>fileSystem_api::cannotCreate</vp> exception

<vip>class predicates
raise_cannotCreate : (string Filename) erroneous.
clauses
raise_cannotCreate(Filename) :-
common_exception::raise_user(classInfo, fileSystem_api::cannotCreate, predicate_name(),
"It is not possible to create the file %Filename",
[namedValue("Filename", string(Filename))]).</vip>

The use of <vp>"%Filename"</vp> in the message corresponds to the extra info <vp>"Filename"</vp>.
}}

The predicate <vp>exceptionDump::tryGetUserMessage</vp> will return a user message from a <vp>traceId</vp> if possible. The message will consist of all user messages from the entire trace and will have parameters substituted.

{{Example| Given <vp>raise_cannotCreate</vp> from above and calling <vp>test</vp>:

<vip>clauses
test() :-
try
raise_cannotCreate("test.xxx")
catch TraceId do
if UserMsg = exceptionDump::tryGetUserMessage(TraceId) then
stdio::write(UserMsg)
end if
end try.</vip>

The following message is written to <vp>stdio</vp>:

<source lang="text">It is not possible to create the file test.xxx</source>
}}

=== Definite user errors ===

Definite user errors are exceptions that are solely the responsibility of the user of the program. For example wrong use of the program.

{{Example| A program can write out some information, but only if the user has specified which information to write. So if the user invoke the functionality without having specified which information to write, it is appropriate to raise a definite user error.
}}

A definite user exception is distinguished by adding <vp>true</vp> as extra info for the parameter <vp>common_exception::definiteUserError_parameter</vp>. The preferred way to do this is by using the predicates:

* <vp>common_exception::raise_definiteUser</vp>
* <vp>common_exception::continue_definiteUser</vp>

The use of these predicates is the same as the user of <vp>common_exception::raise_user</vp> and <vp>common_exception::continue_user</vp>.

An exception trace is considered a definite user error if one (or more) entries in the trace carries the <vp>common_exception::definiteUserError_parameter</vp>. The predicate <vp>common_exception::isDefiniteUserError</vp> will succeed for definite user errors.

=== Packed Exceptions ===

Some times, e.g., in a client/server application, you catch an exception on the server which you want to handle on the client. In that case you can serialize the exception on the server send it to the client and reraise it as a packed exception.

On the server
<vip>
try
...
catch E do
sendExceptionToClient(exception::getTraceInfo())
end try,
...
</vip>

On the client
<vip>
...
Rtn = remoteCall(...),
if Rtn = error(ExceptionInfo) then
common_exception::raise_packed(ExceptionInfo, classInfo, predicate_name(),"remoteCall returned an exception")
end if
...
</vip>

The predicate raise_packed works like a continue_unknown but continues a serialized exception instead of normal exception. It is meant to be used when the exception stem from another program and thus only is available in serialized form.

== The error presentation dialog ==

The error presentation dialog (in the class <vp>errorPresentationDialog</vp>) is by default used by the default exception handling in a GUI program. Its behavior is closely related to the classification of exceptions described above, as described by these two rules:

* If the exception trace carries a user message, this message will be presented to the user.
* If the exception trace is not a definite user error, there will be information for the programmer

So if the exception is an internal error there will only be information for the programmer; if it is a user exception there will both be information for the user and for the programmer; and if it is a user error there will only be information for the user.

If there is information to the programmer the exception dialog will have a details/less details button that can show/hide the programmer information. It will also have a "report error" button, which by default will copy the information to the clipboard so that the user can easily send it to the programmer.

[[Image:ErrorPresentationDialogDefault.png]]

The dialog is customizable by means of various properties:

<vip>properties
title : string. % := "Error".
callBackBtnText : string. % := "&Copy".
dontCallBackBtnText : string. % := "&OK".
showDetailsBtnText : string. % := "Show &Details".
hideDetailsBtnText : string. % := "Hide &Details".
closeApplicationBtnText : string. % := "Close &Application".
commentTextPromt : string. % := "Please describe what you were doing when the error occured:"
internalErrorMessage : string. % := "An internal error has occurred.\nPlease send a bug report to your vendor.".
feedbackMessage : string. % := "Please send your feedback.".
definiteUserErrorIcon : vpiDomains::resid.
userErrorIcon : vpiDomains::resid.
internalErrorIcon : vpiDomains::resid.
reportErrorDelegate : reportErrorDelegate.
extraInfoWriter : writer.</vip>

All texts and labels are controlled by properties.

The <vp>extraInfoWriter</vp> is a callback that can be set to include extra info for the programmer. This information will both be presented in the details window and reported back to the programmer if the user press the "report error" button (i.e. the button which is by default labeled '''Copy''').

The <vp>extraInfoWriter</vp> callback predicate must have this type:

<vip>domains
writer = (outputStream Stream).</vip>

The dialog will invoke the predicate and then it should simply write extra information to the received stream.

{{Example| The Visual Prolog IDE uses the <vp>extraInfoWriter</vp> to write version information, information about the open project and information about the last actions carried out in the IDE. This information will help the programmers to analyze the problem.
}}

The action performed by the "report error" button is customizable using the property <vp>reportErrorDelegate</vp>, which is a callback predicate of this type:

<vip>domains
reportErrorDelegate = (window Parent, string Comment, optional{exception::traceInfo} TraceInfo, string ExtraInfo).</vip>

; <vp>Parent</vp>
: The error presentation dialog which can be used as parent for additional dialogs.
; <vp>Comment</vp>
: The users comment from the comment box.
; <vp>TraceInfo</vp>
: If the dialog is invoked on an exception the trace info is here, if it is invoked for feedback this value is <vp>none</vp>
; <vp>ExtraInfo</vp>
: The extra info written by the <vp>extraInfoWriter</vp> callback

{{Example| In the Visual Prolog IDE the <vp>reportErrorDelegate</vp> will send the exception information to a WEB service which will insert the notification in a database. The notifications in the database will then be used to improve the IDE.
}}

[[Category:Tutorials]]

Exception Handling

2008-11-23T12:07:54Z

Kehler: /* The error presentation dialog */

An exception is a deviation from the expected. What is an exception in one context may be expected in another context, and thus not an exception in that context.

In Visual Prolog programs exceptions are used to deal with deviations from what is expected in the given context. When a certain program part gets into a situation it cannot deal with it can '''''raise''''' an exception. When an exception is raised the program control is transferred to the nearest '''''exception handler'''''. If the exception handler cannot handle the exception it can either raise a new exception or '''''continue''''' the original exception.

The program will terminate with an error message if there is no exception handler to transfer the control to.

== Introduction to exception handling ==

There are many concepts and entities to understand when dealing with exceptions. This section will give an introduction by means of an example.

A certain program needs to write some information to a file. Therefore it has a predicate <vp>writeInfo</vp> that can write this information. <vp>writeInfo</vp> calls the PFC constructor <vp>outputStream_file::create</vp> to obtain a stream that it can write the information to:

<vip>clauses
writeInfo(Filename) :-
S = outputStream_file::create(Filename),
…</vip>

But if the file already exists and is write-protected it is impossible to create the stream.

In <vp>outputStream_file::create</vp> this situation is considered to be exceptional/unexpected and therefore it raises an exception.

When an exception is raised the program control is transferred to the nearest exception handler, which can hopefully handle the situation and thus bring the program back on track again.

In this case <vp>writeInfo</vp> is called after the user have entered the file name in a dialog and pressed a '''Save'''-button. So the handling we want is simply to tell the user that the information was not written because the file was write-protected. The user can choose a different filename, remove the write protection, delete the file, cancel the operation entirely or something else. But from the program's point of view the exceptional situation is handled.

To set a handler we use the {{lang2|Terms|try-catch|try-catch}} language construction:

<vip>clauses
saveInfo(Filename) :-
try
writeInfo(Filename)
catch TraceId do
% <<handle situation>>
end try.</vip>

The code works like this: <vp>writeInfo</vp> is called, if it succeeds the {{lang2|Terms|try-catch|try-catch}} construction will not do more and <vp>saveInfo</vp> will also succeed.

But in the write-protected case <vp>outputStream_file::create</vp> will raise an exception and therefore the following will take place:

# <vp>TraceId</vp> will be bound to the (so called) '''''trace id''''', which is a handle to information about the exception (described in more details below)
# The handler code (i.e. the code between <vp>do</vp> and <vp>end try</vp>) is evaluated
# The result of the handler code will be the result of the {{lang2|Terms|try-catch|try-catch}} construction, and thus of <vp>saveInfo</vp>.

So for the "write-protected" exception the handler code should write a message to the user.

If it is another kind of exception the handler will have to do something different. Especially, it may be an exception that the handler does not know how to handle. In this case the best thing the handler code can do is to continue the exception as an ''unknown'' exception (i.e. unknown to the handler).

When an exception is continued it consists of the original exception plus some continue information. If it has been continued by several handlers it will contain a lot of continue information in addition to the original exception information. The exception information describes a trace from the point of raise through all the handlers. The <vp>TraceId</vp> variable that is bound in the {{lang2|Terms|try-catch|try-catch}} construction gives access information about the entire trace (hence the name).

As mentioned above the program will terminate with en error message, if an exception is raised and no handler can be found. Therefore programs normally setup an outermost default exception handler. <vp>mainExe::run</vp> setup such a handler in a console program this is the fall-back handler. In a GUI program there is also a default hander in the GUI event loop which will catch exceptions arising from the handling of an event.

All in all, the lifecycle of an exception is as follows:

* It is raised
* It is caught and continued
* It is caught and continued
* …
* It is caught and handled (or the program terminates with an error message)

Each time the exception is caught the trace so far can be examined. When the exception is raised and each time it is continued extra information can be added to the exception trace. If nothing else handles an exception it will (normally) be handled by the fallback/default handler of the program.

== Defining an exception ==

An exception is a value of the type <vp>core::exception</vp>

<vip>domains
exception = (classInfo ClassInfo [out], string PredicateName [out], string Description [out]).</vip>

I.e. an exception is a predicate that returns three pieces of information:

; <vp>ClassInfo</vp>
: The <vp>classInfo</vp> of the class that defines the exception
; <vp>PredicateName</vp>
: The name of the exception predicate itself
; <vp>Description</vp>
: A description of the exception

{{example| The <vp>cannotCreate</vp> exception from the example above is declared in the class <vp>fileSystem_api</vp> like this:
<vip>class fileSystem_api
…
predicates
cannotCreate : exception.
…</vip>

The implementation looks like this:
<vip>impement fileSystem_api
…
clauses
cannotCreate(classInfo, predicate_name(), "Cannot create or open the specified file").
…</vip>
<vp>classInfo</vp> is the <vp>classInfo</vp> of the <vp>fileSystem_api</vp> class ; <vp>predicate_name</vp> is a built-in predicate that returns the name of the predicate in which it is called (i.e. in this case it will return <vp>"cannotCreate"</vp>). The last argument is the description of the exception.
}}

Many/most programmers will never need to define exceptions, because in many/most cases the exceptions to use are already defined. An exception definition is only needed when the exception must be distinguished from other kinds of exceptions, such that exception handlers can deal specially with that kind of exception. Typically exception definitions are only necessary for exceptions that are raised by library software. I most cases programmers will raise the exception <vp>internal_error</vp>.

== Raising an exception ==

Exceptions are raised using the predicate <vp>exception::raise</vp>:

<vip>class exception
…
predicates
raise : (classInfo ClassInfo, exception Exception) erroneous.
raise : (classInfo ClassInfo, exception Exception, namedValue_list ExtraInfo) erroneous.</vip>

<vp>ClassInfo</vp>
: The <vp>classInfo</vp> of the class that raise the excption
<vp>Exception</vp>
: The exception to raise
<vp>ExtraInfo</vp>
: Extra information about the raised exception.

{{example|The <vp>cannotCreate</vp> exception from above is raised by the predicate <vp>fileSystem_api::raise_cannotCreate</vp>. The code looks like this:
<vip>clauses
raise_cannotCreate(ClassInfo, FileName, LastError) :-
Desc = common_exception::getLastErrorDescription(LastError),
exception::raise(
ClassInfo,
cannotCreate,
[namedValue(fileSystem_exception::fileName_parameter, string(FileName)),
namedValue(common_exception::errorCode_parameter, unsigned(LastError)),
namedValue(common_exception::errorDescription_parameter, string(Desc))]).</vip>

<vp>raise_cannotCreate</vp> is called with the <vp>ClassInfo</vp> of the raising class the <vp>FileName</vp> and the windows error code <vp>LastError</vp> that the relevant low level Windows API predicate caused.

<vp>common_exception::getLastErrorDescription</vp> obtains the description corresponding to <vp>LastError</vp> from Windows.

<vp>exception::raise</vp> is then used to raise the <vp>cannotCreate</vp> exception with the three pieces of extra information. <vp>fileSystem_exception::fileName_parameter</vp>, <vp>common_exception::errorCode_parameter</vp> and <vp>common_exception::errorDescription_parameter</vp> are names (strings) used for the extra information.
}}

It is very common to create helper predicates like <vp>fileSystem_api::raise_cannotCreate</vp> to do the actual raising rather that calling <vp>exception::raise</vp> directly from the code that needs to raise the exception. That way it is certain that the extra info for this particular exception is handled in the same way in all cases.

Normally the helper raise predicate is created by the same programmer that declares the exception. And as mentioned above this is normally only programmers that create library software.

Application programmers will in most cases raise exceptions by calling appropriate raiser predicates, typically the ones defined in <vp>common_exception</vp>.

== Catching and handling exceptions ==

Exceptions are caught with the {{lang2|Terms|try-catch|try-catch}} construction:

<vipbnf>try <Body> catch <TraceId> do <Handler> end try</vipbnf>

If <vpbnf><Body></vpbnf> terminates with an exception <vpbnf><TraceId></vpbnf> is bound to the ''trace id'' and then <vpbnf><Handler></vpbnf> is evaluated.

<vpbnf><TraceId></vpbnf> is used to obtain information about the exception trace. This information can be used for at least two things:

* Determine which kind of exception that is caught, so that it can be decided if and how to handle it
* Obtain additional information to write to the user, in a log or use for something else

You will call <vp>exception::tryGetDescriptor</vp> to determine if a certain kind of exception is caught:

<vip>predicates
tryGetDescriptor : (traceId TraceID, exception Exception) -> descriptor Descriptor determ.</vip>

The exception trace corresponding to <vp>TraceId</vp> is searched for an exception of the kind <vp>Exception</vp>. If there is such an entry in the trace (raised or continued) a corresponding exception descriptor is returned in <vp>Descriptor</vp>.

The predicate fails if such an exception is not in the exception trace.

The <vp>Descriptor</vp> contains the extra information about that particular entry in the exception trace:

<vip>domains
descriptor = descriptor(classInfoDescriptor ClassInfo, exceptionDescriptor ExceptionInfo, kind Kind,
namedValue_list ExtraInfo, gmtTimeValue GMTTime, string ExceptionDescription, unsigned ThreadId).</vip>

; <vp>ClassInfo</vp>
: The <vp>classInfo</vp> of the class that raised the exception (in functor form)
; <vp>ExceptionInfo</vp>
: The <vp>exception</vp> in question (in functor form)
; <vp>Kind</vp>
: The entry kind (<vp>raise</vp> or <vp>continue</vp>)
; <vp>ExtraInfo</vp>
: The extra information provided with this entry in the trace
; <vp>GMTTime</vp>
: The time this exception trace entry was raised/continued
; <vp>ExceptionDescription</vp>
: The exception description of this entry (this information is also present in <vp>ExceptionInfo</vp>)
; <vp>ThreadId</vp>
: The thread id of the thread that raised/continued this entry

Much of this information is mainly interesting if the exception is not handled. The information that is most interesting when handling an exception is:

* The exception kind has been determined to be the one we expected
* The <vp>ExtraInfo</vp> for this entry is available for use in messages, etc

The predicate <vp>exception::tryGetExtraInfo</vp> is convenient for obtaining extra information:

<vip>predicates
tryGetExtraInfo : (descriptor Descriptor, string Name) -> value Value determ.</vip>

; <vp>Descriptor</vp>
: Is the description whose extra info we want to get something from.
; <vp>Name</vp>
: The name of the extra info parameter we want to obtain.
; <vp>Value</vp>
: The value that the mentioned parameter has.

{{example| Code for catching and handling the <vp>fileSystem_api::cannotCreate</vp> exception can look like this:

<vip>clauses
saveInfo(Filename) :-
try
writeInfo(Filename)
catch TraceId do
if D = exception::tryGetDescriptor(TraceId, fileSystem_api::cannotCreate) then
stdio::write("Cannot write to the file: ", Filename),
if string(Description) = exception::tryGetExtraInfo(D, common_exception::errorDescription_parameter) then
stdio::writef("; %", Description)
end if,
stdio::write("\n")
else
common_exception::continue_unknown(TraceId, classInfo, predicate_name(), "Filename = ", Filename)
end if
end try.</vip>

The code here don't need to obtain the <vp>fileSystem_exception::fileName_parameter</vp>, because the file name is already known in the <vp>Filename</vp> variable.

But we can obtain Window's description of the problem querying for <vp>common_exception::errorDescription_parameter</vp>

We '''continue''' the exception as unknown if it is not the <vp>cannotCreate</vp> kind . For the continue call we add the filename as. <vp>common_exception::continue_unknown</vp> will create a string of the extra arguments and add it as an <vp>common_exception::errorArguments_parameter</vp>. Such information is mainly for use in the default exception handler to be discussed below.
}}

== Serializing exceptions ==

In some situations the best way to handle an exception is by sending all the information about the exception somewhere else. A server might for example want to send the information to the client program that caused the exception, because then there is a user that can take action.

A <vp>traceId</vp> only have a meaning in the process that has created it, but the predicate <vp>exception::getTraceInfo</vp> can create a <vp>traceInfo</vp> structure (<vp>TraceInfo</vp>) from the <vp>traceId TraceId</vp>:

<vip>predicates
getTraceInfo : (traceId TraceId) -> traceInfo TraceInfo.</vip>

Such a structure is a functor structure that can be serialized/deserialized with <vp>toString</vp>/<vp>toTerm</vp>; <vp>write</vp>/<vp>read</vp>; nested in a fact database using <vp>save</vp>/<vp>consult</vp>; etc.

== Exception dumps ==

The class <vp>exceptionDump</vp> contains predicates for dumping exception traces to <vp>stdio</vp>, some other <vp>outputStream</vp> or a <vp>string</vp>.

An exception dump contains three major pieces of information:

* A dump of the call stack (with file names and line numbers) from the point where the exception was raised
* A dump of the exception-trace with all the information from the exception descriptors
* Information about the operating system that the program ran on

<vp>exceptionDump</vp> have predicates both for dumping exception traces both from a <vp>traceId</vp> and from a <vp>traceInfo</vp> obtained with <vp>exception::getTraceInfo</vp>.

Dumps for a certain program are in general only useful to the programmers of that program; the users of the program will find dumps cryptic and rather uninteresting. I.e. the purpose of dumps is to give the programmer means for improving the program.

== Default handling ==

A program should handle all exceptions, because if an exception is continued or raised at a point where there is no handler the program will terminate with a rather bad error message. The error message is bad because most exception handling is done in PFC; the language itself knows nothing about exception traces and the like.

To be sure that all exceptions are handled it is normal to set up a default (or fallback) exception handler.

<vp>mainExe::run</vp> (and <vp>mainExe::runCom</vp>) which is normally called in the goal setup such a default exception handler: It runs the <vp>main::run</vp> predicate inside a {{lang2|Terms|try-catch|try-catch}} construction that will handle any exception.

The handler in <vp>mainExe::run</vp> (and <vp>mainExe::runCom</vp>) dumps the entire exception trace to output stream in <vp>stdio</vp>. And then the program will terminate. The idea is that:

* Perhaps the user can see something from the dump (which may for example say that ''access is denied'' to ''xxx.txt'')
* Alternatively, the developer of the program may use the dump to improve the program

In addition to the handler in <vp>mainExe::run</vp> a GUI program also set a default handler in the event loop. This handler is set by calling <vp>applicationWindow::setErrorResponder</vp>:

<vip>domains
errorResponder = (applicationWindow Source, exception::traceId TraceId).

predicates
setErrorResponder : (errorResponder Responder).</vip>

By default the error responder <vp>errorPresentationDialog::present</vp> is used. The functioning of the <pv>errorPresentationDialog</vp> is closely related to a categorization of exceptions described in the next section.

PFC place exceptions in three major categories based on who is (believed to be) responsible:

; Internal errors
: An exceptional state which the programmer is responsible to deal with
; User exceptions
: An exception which can perhaps be solved by the end user of the program, but which may also call for a programmer solution. User exceptions carries a message for the end user of the program.
; Definite user errors
: An exception which is definitely one the end user should deal with, because the programmer cannot do anything about it anyway

You may notice that "error" is used to signal that a person is (believed to be) responsible for the problem, where as "exception" also covers situations with looser relation to specific persons (such as a network failure).

=== Internal errors ===

Internal errors are caused and/or should be prevented by the programmer of the program.

{{Example| A predicate takes two lists as argument and pair the elements of the lists. So the lists are expected to have the same length. If the lists have different lengths it is appropriate to raise an <vp>internal_error</vp>, because it is clearly the responsibility of the programmer to ensure that the lists have same length; the end-user of the program can at most influence this indirectly.
}}

=== User exceptions ===

User exceptions typically deal with problems related to external resources such as files, network, databases, web servers, etc. Often the user will become wiser by being informed about the problem and often the user may even solve the problem.

{{Example| The read-only file problem discussed above is a typical example of a user exception. It is the user rather than the programmer that can solve the problem with the read-only file.
}}

A user exception is distinguished by having extra information in a field with name <vp>common_exception::userMessage_parameter</vp>. This extra info should be a message with relevance for an end user of the program. The message can reference other extra info parameters using the format %PARAM. The preferred way to raise user exceptions is by means of the predicate <vp>common_exception::raise_user</vp>. Likewise you can continue exceptions with a user message using <vp>common_exception::continue_user</vp>.

{{Example| This predicate will raise a '''''user''''' <vp>fileSystem_api::cannotCreate</vp> exception

<vip>class predicates
raise_cannotCreate : (string Filename) erroneous.
clauses
raise_cannotCreate(Filename) :-
common_exception::raise_user(classInfo, fileSystem_api::cannotCreate, predicate_name(),
"It is not possible to create the file %Filename",
[namedValue("Filename", string(Filename))]).</vip>

The use of <vp>"%Filename"</vp> in the message corresponds to the extra info <vp>"Filename"</vp>.
}}

The predicate <vp>exceptionDump::tryGetUserMessage</vp> will return a user message from a <vp>traceId</vp> if possible. The message will consist of all user messages from the entire trace and will have parameters substituted.

{{Example| Given <vp>raise_cannotCreate</vp> from above and calling <vp>test</vp>:

<vip>clauses
test() :-
try
raise_cannotCreate("test.xxx")
catch TraceId do
if UserMsg = exceptionDump::tryGetUserMessage(TraceId) then
stdio::write(UserMsg)
end if
end try.</vip>

The following message is written to <vp>stdio</vp>:

<source lang="text">It is not possible to create the file test.xxx</source>
}}

=== Definite user errors ===

Definite user errors are exceptions that are solely the responsibility of the user of the program. For example wrong use of the program.

{{Example| A program can write out some information, but only if the user has specified which information to write. So if the user invoke the functionality without having specified which information to write, it is appropriate to raise a definite user error.
}}

A definite user exception is distinguished by adding <vp>true</vp> as extra info for the parameter <vp>common_exception::definiteUserError_parameter</vp>. The preferred way to do this is by using the predicates:

* <vp>common_exception::raise_definiteUser</vp>
* <vp>common_exception::continue_definiteUser</vp>

The use of these predicates is the same as the user of <vp>common_exception::raise_user</vp> and <vp>common_exception::continue_user</vp>.

An exception trace is considered a definite user error if one (or more) entries in the trace carries the <vp>common_exception::definiteUserError_parameter</vp>. The predicate <vp>common_exception::isDefiniteUserError</vp> will succeed for definite user errors.

=== Packed Exceptions ===

Some times, e.g., in a client/server application, you catch an exception on the server which you want to handle on the client. In that case you can serialize the exception on the server send it to the client and reraise it as a packed exception.

On the server
<vip>
try
...
catch E do
sendExceptionToClient(exception::getTraceInfo())
end try,
...
</vip>

On the client
<vip>
...
Rtn = remoteCall(...),
if Rtn = error(ExceptionInfo) then
common_exception::raise_packed(ExceptionInfo, classInfo, predicate_name(),"remoteCall returned an exception")
end if
...
</vip>

== The error presentation dialog ==

The error presentation dialog (in the class <vp>errorPresentationDialog</vp>) is by default used by the default exception handling in a GUI program. Its behavior is closely related to the classification of exceptions described above, as described by these two rules:

* If the exception trace carries a user message, this message will be presented to the user.
* If the exception trace is not a definite user error, there will be information for the programmer

So if the exception is an internal error there will only be information for the programmer; if it is a user exception there will both be information for the user and for the programmer; and if it is a user error there will only be information for the user.

If there is information to the programmer the exception dialog will have a details/less details button that can show/hide the programmer information. It will also have a "report error" button, which by default will copy the information to the clipboard so that the user can easily send it to the programmer.

[[Image:ErrorPresentationDialogDefault.png]]

The dialog is customizable by means of various properties:

<vip>properties
title : string. % := "Error".
callBackBtnText : string. % := "&Copy".
dontCallBackBtnText : string. % := "&OK".
showDetailsBtnText : string. % := "Show &Details".
hideDetailsBtnText : string. % := "Hide &Details".
closeApplicationBtnText : string. % := "Close &Application".
commentTextPromt : string. % := "Please describe what you were doing when the error occured:"
internalErrorMessage : string. % := "An internal error has occurred.\nPlease send a bug report to your vendor.".
feedbackMessage : string. % := "Please send your feedback.".
definiteUserErrorIcon : vpiDomains::resid.
userErrorIcon : vpiDomains::resid.
internalErrorIcon : vpiDomains::resid.
reportErrorDelegate : reportErrorDelegate.
extraInfoWriter : writer.</vip>

All texts and labels are controlled by properties.

The <vp>extraInfoWriter</vp> is a callback that can be set to include extra info for the programmer. This information will both be presented in the details window and reported back to the programmer if the user press the "report error" button (i.e. the button which is by default labeled '''Copy''').

The <vp>extraInfoWriter</vp> callback predicate must have this type:

<vip>domains
writer = (outputStream Stream).</vip>

The dialog will invoke the predicate and then it should simply write extra information to the received stream.

{{Example| The Visual Prolog IDE uses the <vp>extraInfoWriter</vp> to write version information, information about the open project and information about the last actions carried out in the IDE. This information will help the programmers to analyze the problem.
}}

The action performed by the "report error" button is customizable using the property <vp>reportErrorDelegate</vp>, which is a callback predicate of this type:

<vip>domains
reportErrorDelegate = (window Parent, string Comment, optional{exception::traceInfo} TraceInfo, string ExtraInfo).</vip>

; <vp>Parent</vp>
: The error presentation dialog which can be used as parent for additional dialogs.
; <vp>Comment</vp>
: The users comment from the comment box.
; <vp>TraceInfo</vp>
: If the dialog is invoked on an exception the trace info is here, if it is invoked for feedback this value is <vp>none</vp>
; <vp>ExtraInfo</vp>
: The extra info written by the <vp>extraInfoWriter</vp> callback

{{Example| In the Visual Prolog IDE the <vp>reportErrorDelegate</vp> will send the exception information to a WEB service which will insert the notification in a database. The notifications in the database will then be used to improve the IDE.
}}

[[Category:Tutorials]]

Main Page

2007-09-05T13:00:52Z

Kehler: Protected "Main Page": pdc's [edit=sysop:move=sysop]

==Welcome to the Visual Prolog wiki==

This wiki is dedicated to [http://www.visual-prolog.com/ Visual Prolog] and related tools and libraries.

We are proud that so many enthusiastic users put such a great effort into Visual Prolog. We hope and trust that this wiki will serve as a significant platform for knowledge exchange in the community.

===Prolog Development Center===

[http://www.pdc.dk/ Prolog Development Center] (PDC) is the company behind Visual Prolog.

PDC will contribute where it can, but the real value of the wiki comes from your contributions. PDC will also monitor the wiki for SPAM and other malicious use, but not otherwise control the contents of the wiki.

===Contribution===

To contribute to this wiki you must register yourself and have your email address validated (see [[wiki.visual-prolog.com:Privacy_policy|Privacy Policy]]). You are encouraged to provide your real life name as user name.

===Wiki software and help===

The wiki is based on [http://www.mediawiki.org/wiki/MediaWiki MediaWiki] software, which is also used for [http://www.wikipedia.org/ Wikipedia]. If you seek help about the wiki itself and cannot find it here, you may search in [http://www.mediawiki.org/wiki/Help:Contents MediaWiki help pages] and [http://en.wikipedia.org/wiki/Help:Contents Wikipedea help pages].

==Contents==

Currently the main contains is a number of Visual Prolog [[:Category:Tutorials|Tutorials]].

==See Also==

* Visual Prolog [http://www.visual-prolog.com homepage]
* Visual Prolog [http://discuss.visual-prolog.com discussion forum]
* [http://www.pdc.dk/ Prolog Development Center]

__NOTOC__ __NOEDITSECTION__

Main Page

2007-09-04T15:50:35Z

Kehler:

Main Page

2007-07-17T07:48:32Z

Kehler: /* Visual Prolog Token Coloring */

This is the Visual Prolog Wiki. Currently, this is only for test puposes. There is still many configurations that need to be done.

'''Notice''': The underlying database is '''not yet backed-up'''.

The Wiki is based on MediaWiki software (IIS+PHP+MySQL).

=== Visual Prolog Token Coloring ===

The Wiki has a special Visual Prolog extension. If you write:

<nowiki><vip></nowiki>some Visual Prolog code</vip>

The code will be token colered according to Visual Prolog rules (more or less). For example:

<nowiki><vip>predicates
isMember : (Elem Value, Elem* List) determ.
%@short Succeds is #Value is member of #List.
%@end
clauses
isMember(V, [V|_L]) :- !.
isMember(V, [_X|L]) :- isMember(V, L).</vip></nowiki>

The result will look like this:

<vip>predicates
isMember : (Elem Value, Elem* List) determ.
%@short Succeds is #Value is member of #List.
%@end
clauses
isMember(V, [V|_L]) :- !.
isMember(V, [_X|L]) :- isMember(V, L).</vip>

== Tutorials ==

[[Fundamental Prolog Part 1]]

== Media Wiki Getting started ==

Consult the [http://meta.wikimedia.org/wiki/Help:Contents User's Guide] for information on using the wiki software.

* [http://www.mediawiki.org/wiki/Help:Configuration_settings Configuration settings list]
* [http://www.mediawiki.org/wiki/Help:FAQ MediaWiki FAQ]
* [http://mail.wikimedia.org/mailman/listinfo/mediawiki-announce MediaWiki release mailing list]