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

Exception Handling

2016-11-08T16:31:20Z

EJP: Alll, Some times

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 = exception(string ClassName, string ExceptionName, string Description).</vip>

I.e. an exception is a functor term that contains three pieces of information:

; <vp>ClassName</vp>
: The name of the class that defines the exception
; <vp>ExceptionName</vp>
: Then name of the exception typically the name of a constant in the program
; <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
…
constants
cannotCreate : exception = exception(class_name(), constant_name(), "Cannot create or open the specified file").
…</vip>

[[Language_Reference/Built-in_entities/Predicates#class_name|<vp>class_name/0-></vp>]] and [[Language_Reference/Built-in_entities/Predicates#class_name|<vp>constant_name/0-></vp>]] are built-in predicate that returns the name if the class/constant in which the call occurs. So the line above is equivalent to this:
<vip>class fileSystem_api
…
constants
cannotCreate : exception = exception("fileSystem_api", "cannotCreate", "Cannot create or open the specified file").
…</vip>
}}

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. In most cases programmers will raise the exception <vp>internal_error</vp>.

=== Raising an exception ===

There are many predicates that explicitly raises exceptions, but most of them does it by calling a predicate in <vp>exception</vp>:

<vip>class exception
…
predicates
raise_exception : (exception Exception, ...) erroneous [programPoint].
raiseDetailes : (exception Exception, namedValue* ExtraInfo) erroneous [programPoint].
raise_definiteUser : (exception Exception, string Msg, namedValue* ExtraInfo) erroneous [programPoint].
...</vip>

In all cases the <vp>Exception</vp> is the exception to raise and the rest of the arguments provides additional information about the exception. See also [[Language Reference/Predicates#programPoint|programPoint in Language Reference]] for information about the programPoint attribute.

{{example|The <vp>cannotCreate</vp> exception from above is raised by the predicate <vp>fileSystem_api::raise_cannotCreate</vp>/<vp>fileSystem_api::raise_cannotCreate_explicit</vp>. The code looks like this:
<vip>clauses
raise_cannotCreate_explicit(ProgramPoint, FileName, LastError) :-
Desc = getLastErrorDescription(LastError),
Msg = string::format("Cannot create or open '%%%s'\nError = 0x%08x\n%%%s",
fileSystem_fileName_parameter, LastError, errorDescription_parameter),
raise_definiteUser_explicit(ProgramPoint, cannotCreate, Msg,
[namedValue(fileSystem_fileName_parameter, string(FileName)),
namedValue(fileSystem_path_parameter, string(directory::getCurrentDirectory())),
namedValue(errorCode_parameter, unsigned(LastError)),
namedValue(errorDescription_parameter, string(Desc))]).</vip>

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

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

<vp>exception::raise_definiteUser_explict</vp> is then used to raise the <vp>cannotCreate</vp> exception with the four pieces of extra information. The destinction between ''errors'', ''user errors'' and ''definite user errors'' are described below.
}}

It is very common to create helper predicates like <vp>fileSystem_api::raise_cannotCreate</vp> to do the actual raising rather that calling one of the predicates in <vp>exception</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 some defined in <vp>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

As explained above it is very common that an exception is continued one or more times after it has been raised, so an exception contains a complete ''trace'' of entries (raise, continue, continue, ---). Subsequently, you will need to search the trace to see if a certain exception is among the entries. This is done by calling <vp>exception::tryGetDescriptor</vp>:

<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) the 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(programPointDescriptor ProgramPoint, exception Exception,
kind Kind, namedValue* ExtraInfo, gmtTimeValue GMTTime, unsigned ThreadId).
</vip>

<vp>ProgramPoint</vp>
: A readable representation of the <vp>programPoint</vp> where the exception was raised/continued.
<vp>Exception</vp>
: The <vp>exception</vp> in question
<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 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, exception::errorDescription_parameter) then
stdio::writef("; %", Description)
end if,
stdio::write("\n")
else
exception::continue_unknown(TraceId, "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 a <vp>cannotCreate</vp> exception. For the continue call we add the filename as additional information. <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.
}}

=== 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> (see [[#Serializing exceptions]] below).

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 exception
: 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>exception::raise_user</vp>. Likewise you can continue exceptions with a user message using <vp>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) :-
exception::raise_user(fileSystem_api::cannotCreate,
"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>exception::definiteUserError_parameter</vp>. The preferred way to do this is by using the predicates:

* <vp>exception::raise_definiteUser</vp>
* <vp>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>exception::definiteUserError_parameter</vp>. The predicate <vp>exception::isDefiniteUserError</vp> will succeed for definite user errors.

=== 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.

==== Packed Exceptions ====

Sometimes, 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 error(TraceInfo) = Rtn then
exception::raise_packed(TraceInfo, "remoteCall returned an exception")
end if
...
</vip>

The predicate <vp>raise_packed</vp> works like a <vp>continue_unknown</vp> 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

2016-11-08T16:07:46Z

EJP: Typo (I to In)

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 = exception(string ClassName, string ExceptionName, string Description).</vip>

I.e. an exception is a functor term that contains three pieces of information:

; <vp>ClassName</vp>
: The name of the class that defines the exception
; <vp>ExceptionName</vp>
: Then name of the exception typically the name of a constant in the program
; <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
…
constants
cannotCreate : exception = exception(class_name(), constant_name(), "Cannot create or open the specified file").
…</vip>

[[Language_Reference/Built-in_entities/Predicates#class_name|<vp>class_name/0-></vp>]] and [[Language_Reference/Built-in_entities/Predicates#class_name|<vp>constant_name/0-></vp>]] are built-in predicate that returns the name if the class/constant in which the call occurs. So the line above is equivalent to this:
<vip>class fileSystem_api
…
constants
cannotCreate : exception = exception("fileSystem_api", "cannotCreate", "Cannot create or open the specified file").
…</vip>
}}

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. In most cases programmers will raise the exception <vp>internal_error</vp>.

=== Raising an exception ===

There are many predicates that explicitly raises exceptions, but most of them does it by calling a predicate in <vp>exception</vp>:

<vip>class exception
…
predicates
raise_exception : (exception Exception, ...) erroneous [programPoint].
raiseDetailes : (exception Exception, namedValue* ExtraInfo) erroneous [programPoint].
raise_definiteUser : (exception Exception, string Msg, namedValue* ExtraInfo) erroneous [programPoint].
...</vip>

In alll cases the <vp>Exception</vp> is the exception to raise and the rest of the arguments provides additional information about the exception. See also [[Language Reference/Predicates#programPoint|programPoint in Language Reference]] for information about the programPoint attribute.

{{example|The <vp>cannotCreate</vp> exception from above is raised by the predicate <vp>fileSystem_api::raise_cannotCreate</vp>/<vp>fileSystem_api::raise_cannotCreate_explicit</vp>. The code looks like this:
<vip>clauses
raise_cannotCreate_explicit(ProgramPoint, FileName, LastError) :-
Desc = getLastErrorDescription(LastError),
Msg = string::format("Cannot create or open '%%%s'\nError = 0x%08x\n%%%s",
fileSystem_fileName_parameter, LastError, errorDescription_parameter),
raise_definiteUser_explicit(ProgramPoint, cannotCreate, Msg,
[namedValue(fileSystem_fileName_parameter, string(FileName)),
namedValue(fileSystem_path_parameter, string(directory::getCurrentDirectory())),
namedValue(errorCode_parameter, unsigned(LastError)),
namedValue(errorDescription_parameter, string(Desc))]).</vip>

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

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

<vp>exception::raise_definiteUser_explict</vp> is then used to raise the <vp>cannotCreate</vp> exception with the four pieces of extra information. The destinction between ''errors'', ''user errors'' and ''definite user errors'' are described below.
}}

It is very common to create helper predicates like <vp>fileSystem_api::raise_cannotCreate</vp> to do the actual raising rather that calling one of the predicates in <vp>exception</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 some defined in <vp>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

As explained above it is very common that an exception is continued one or more times after it has been raised, so an exception contains a complete ''trace'' of entries (raise, continue, continue, ---). Subsequently, you will need to search the trace to see if a certain exception is among the entries. This is done by calling <vp>exception::tryGetDescriptor</vp>:

<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) the 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(programPointDescriptor ProgramPoint, exception Exception,
kind Kind, namedValue* ExtraInfo, gmtTimeValue GMTTime, unsigned ThreadId).
</vip>

<vp>ProgramPoint</vp>
: A readable representation of the <vp>programPoint</vp> where the exception was raised/continued.
<vp>Exception</vp>
: The <vp>exception</vp> in question
<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 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, exception::errorDescription_parameter) then
stdio::writef("; %", Description)
end if,
stdio::write("\n")
else
exception::continue_unknown(TraceId, "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 a <vp>cannotCreate</vp> exception. For the continue call we add the filename as additional information. <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.
}}

=== 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> (see [[#Serializing exceptions]] below).

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 exception
: 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>exception::raise_user</vp>. Likewise you can continue exceptions with a user message using <vp>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) :-
exception::raise_user(fileSystem_api::cannotCreate,
"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>exception::definiteUserError_parameter</vp>. The preferred way to do this is by using the predicates:

* <vp>exception::raise_definiteUser</vp>
* <vp>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>exception::definiteUserError_parameter</vp>. The predicate <vp>exception::isDefiniteUserError</vp> will succeed for definite user errors.

=== 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.

==== 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 error(TraceInfo) = Rtn then
exception::raise_packed(TraceInfo, "remoteCall returned an exception")
end if
...
</vip>

The predicate <vp>raise_packed</vp> works like a <vp>continue_unknown</vp> 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]]

Lists and Recursion

2016-11-03T10:26:24Z

EJP:

List processing – handling sequences of elements – is a powerful technique in Prolog. In this tutorial, we explain what lists are and how to declare them, and then give several examples that show how you might use list processing in your own applications. We also define two well known Prolog predicates – member and append – while looking at list processing from both a recursive and a procedural standpoint.

After that, we introduce findall, a Visual Prolog standard predicate that enables you to find and collect all solutions to a single goal. We round out this tutorial with a discussion of compound lists – combinations of different types of elements – and an example of parsing by difference lists.

==What Is a List?==

In Prolog, ''a list'' is an object that contains an arbitrary number of other objects within it. Lists correspond roughly to arrays in other languages, but, unlike an array, a list does not require you to declare how big it will be before you use it.

A list that contains the numbers 1, 2, and 3 is written as

<vip>[ 1, 2, 3 ]</vip>

The order of the elements in this list matters:

*Number "1" is the first element,

*"2" - the second,

*"3" - the third.

The list [ 1, 2, 3 ] is different from the list [ 1, 3, 2 ].

Each item contained in the list is known as an element. To form a list data structure, you separate the elements of a list with commas and then enclose them in square brackets. Here are some examples:

<vip>["dog", "cat", "canary"]
["valerie ann", "jennifer caitlin", "benjamin thomas"]</vip>

The same element can be present in the list several times, for example:

<vip>[ 1, 2, 1, 3, 1 ]</vip>

== Declaring Lists ==

To declare the domain for a list of integers, you use the domains declaration, like this:

<vip>domains
integer_list = integer*.</vip>

The asterisk means "list of"; that is, integer* means "list of integers."

Note that the word ''"list"'' has no special meaning in Visual Prolog. You could equally well have called your list domain ''zanzibar''. It is the asterisk, not the name that signifies a list domain.

The elements in a list can be anything, including other lists. However, all elements in a list must belong to the same domain, and in addition to the declaration of the list domain, there must be a '''domains''' declaration for the elements:

<vip>domains
element_list = elements*.
elements = ....</vip>

Here ''elements'' must be defined to a single domain type (for example, integer, real, or symbol) or to a set of alternatives marked with different functors. Visual Prolog does not allow you to mix standard types in a list. For example, the following declarations would not properly indicate a list made up of integers, reals, and symbols:

<vip>element_list = elements*.
elements =
integer; % Incorrect
real;
symbol.</vip>

The way to declare a list made up of integers, reals, and symbols is to define a single domain comprising all three types, with functors to show which type a particular element belongs to. For example:

<vip>element_list = elements*.
elements =
i(integer);
r(real);
s(symbol). % the functors are i, r, and s</vip>

(For more information about this, refer to "Compound Lists" later in this tutorial.)

== Heads and Tails ==

A list is really a recursive compound object. It consists of two parts: the head, of a list, which is the first element, and the tail, which is a list comprising all the subsequent elements.

'''''The tail of a list is always a list; the head of a list is an element.'''''

For example,

<vip>the head of [a, b, c] is a
the tail of [a, b, c] is [b, c]</vip>

What happens when you get down to a one-element list? The answer is that:

<vip>the head of [c] is c
the tail of [c] is []</vip>

'''''If you take the first element from the tail of a list enough times, you will eventually get down to an empty list ('''[ ]''').'''''

'''''The empty list cannot be broken into head and tail.'''''

This means that, conceptually, lists have a tree structure just like other compound objects. The tree structure of [a, b, c, d] is:

<pre> list
/ \
a list
/ \
b list
/ \
c list
/ \
d []</pre>Further, a one-element list such as [a] is not the same as the element that it contains, because [a] is really the compound data structure shown here:

<pre> list
/ \
a []</pre>

==List Processing==

Prolog provides a way to make a head and a tail of a list explicit. Instead of separating elements with commas, you can separate the head and tail with a vertical bar (|). For instance,
<vip>[a, b, c]</vip>
is equivalent to
<vip>[ a | [b, c] ]</vip>
which continuing the process is equivalent to
<vip>[ a | [ b | [ c ] ] ]</vip>
which is equivalent to
<vip>[ a | [ b | [ c | [] ] ] ]</vip>

You can even use both kinds of separators in the same list, provided the vertical bar is the last separator. So, if you really want to, you can write [a, b, c, d] as [a, b|[c, d]].

Table 1 gives more examples.
{|cellpadding="5" cellspacing="0" border="1"
|+'''Table 1: Heads and Tails of Lists'''
! List
! Head
! Tail
|-
| ['a', 'b', 'c']
| 'a'
| ['b', 'c']
|-
| [ 'a' ]
| 'a'
| []
|-
| []
| does not exist
| does not exist
|-
| [[1, 2, 3], [2, 3, 4], []]
| [1, 2, 3]
| [[2, 3, 4], []]
|}

Table 2 gives several examples of list unification.

{|cellpadding="5" cellspacing="0" border="1"
|+'''Table 2: Unification of Lists'''
!List 1
!List 2
!Variable Binding
|-
|[X, Y, Z]
|[egbert, eats, icecream]
|X=egbert, Y=eats, Z=icecream
|-
|[7]
|[X <nowiki>|</nowiki> Y]
|X=7, Y=[]
|-
|[1, 2, 3, 4]
|[X, Y <nowiki>|</nowiki> Z]
|X=1, Y=2, Z=[3,4]
|-
|[1, 2]
|[3 <nowiki>|</nowiki> X]
|fail
|}

==Using Lists==

Because a list is really a recursive compound data structure, you need recursive algorithms to process it. The most basic way to process a list is to work through it, doing something to each element until you reach the end.

An algorithm of this kind usually needs two clauses. One of them says what to do with an ordinary list (one that can be divided into a head and a tail). The other says what to do with an empty list.

===Writing Lists===

For example, if you just want to print out the elements of the list, here is what you do:

<vip>class my
predicates
write_a_list : (integer*).
end class

implement my
clauses
write_a_list([]).
/* If the list is empty, do nothing more. */
write_a_list([H|T]):-
/* Match the head to H and the tail to T, then... */
stdio::write(H),stdio::nl,
write_a_list(T).
end implement

goal
console::init(),
my::write_a_list([1, 2, 3]).</vip>

Here are the two write_a_list clauses described in natural language:

*To write an empty list, do nothing.

*Otherwise, to write a list, write its head (which is a single element), then write its tail (a list).

The first time through, the goal is:

<vip>my::write_a_list([1, 2, 3]).</vip>

This matches the second clause, with H=1 and T=[2, 3]; this writes 1 and then calls write_a_list recursively with the tail of the list:

<vip>my::write_a_list([2, 3]).
/* This is write_a_list(T). */</vip>

This recursive call matches the second clause, this time with H=2 and T=[3], so it writes 2 and again calls write_a_list recursively:

<vip>my::write_a_list([3]).</vip>

Now, which clause will this goal match? Recall that, even though the list [3] has only one element; it does have a head and tail; the head is 3 and the tail is []. So, again the goal matches the second clause, with H=3 and T=[]. Hence, 3 is written and write_a_list is called recursively like this:

<vip>my::write_a_list([]).</vip>

Now you see why this program needs the first clause. The second clause will not match this goal because [] cannot be divided into head and tail. So, if the first clause were not there, the goal would fail. As it is, the first clause matches and the goal succeeds without doing anything further.

===Counting List Elements===

Now consider how you might find out how many elements are in a list. What is the length of a list, anyway? Here is a simple logical definition:

The length of [] is 0. 
The length of any other list is 1 plus the length of its tail.

Can you implement this? In Prolog it is very easy. It takes just two clauses:

<vip>class my
predicates
length_of : (A*, integer) procedure(i,o).
end class

implement my
clauses
length_of([], 0).
length_of([_|T], L):-
length_of(T, TailLength),
L = TailLength + 1.
end implement

goal
console::init(),
my::length_of([1, 2, 3], L),
stdio::write(L).</vip>

Take a look at the second clause first. Crucially, [_|T] will match any nonempty list, binding T to the tail of the list. The value of the head is unimportant; as long as it exists, it can be counted it as one element.

So the goal:

<vip>my::length_of([1, 2, 3], L)</vip>

will match the second clause, with T=[2, 3]. The next step is to compute the length of T. When this is done (never mind how), TailLength will get the value 2, and the computer can then add 1 to it and bind L to 3.So how is the middle step executed? That step was to find the length of [2, 3] by satisfying the goal

<vip>my::length_of([2, 3], TailLength)</vip>

In other words, length_of calls itself recursively. This goal matches the second clause, binding

*[3] in the goal to T in the clause and

*TailLength in the goal to L in the clause.

Recall that TailLength in the goal will not interfere with TailLength in the clause, because '''''each recursive invocation of a clause has its own set of variables'''''.

So now the problem is to find the length of [3], which will be 1, and then add 1 to that to get the length of [2, 3], which will be 2. So far, so good.

Likewise, length_of will call itself recursively again to get the length of [3]. The tail of [3] is [], so T is bound to [], and the problem is to get the length of [], then add 1 to it, giving the length of [3].

This time it's easy. The goal:

<vip>my::length_of([], TailLength)</vip>

matches the ''first'' clause, binding TailLength to 0. So now the computer can add 1 to that, giving the length of [3], and return to the calling clause. This, in turn, will add 1 again, giving the length of [2, 3], and return to the clause that called it; this original clause will add 1 again, giving the length of [1, 2, 3].

Confused yet? We hope not. In the following brief illustration we'll summarize the calls. We've used subscripts to indicate that similarly named variables in different clauses – or different invocations of the same clause – are distinct. Please notice that you do not need to implement such predicate in your own code, you can use '''list::length''' predicate from PFC.

<vip>my::length_of([1, 2, 3], L1).
my::length_of([2, 3], L2).
my::length_of([3], L3).
my::length_of([], 0).
L3 = 0+1 = 1.
L2 = L3+1 = 2.
L1 = L2+1 = 3.</vip>

===Tail Recursion===

You probably noticed that length_of is not, and can't be, tail-recursive, because the recursive call is not the last step in its clause. Can you create a tail-recursive list-length predicate? Yes, but it will take some effort.

The problem with length_of is that you can't compute the length of a list until you've already computed the length of the tail. It turns out there's a way around this. You'll need a list-length predicate with three arguments.

*One is the list, which the computer will whittle away on each call until it eventually becomes empty, just as before.

*Another is a free argument that will ultimately contain the result (the length).

*The third is a counter that starts out as 0 and increments on each call.

When the list is finally empty, you'll unify the counter with the (up to then) unbound result.

<vip>class my
predicates
length_of : (A*, integer, integer)
procedure(i,o,i).
end class

implement my
clauses
length_of([], Result, Result).
length_of([_|T], Result, Counter):-
NewCounter = Counter + 1,
length_of(T, Result, NewCounter).
end implement

goal
console::init(),
my::length_of([1, 2, 3], L, 0), /* start with Counter = 0 */
stdio::write(" L = ", L).</vip>

This version of the length_of predicate is more complicated, and in many ways less logical, than the previous one. We've presented it merely to show you that, by devious means, '''''you can often find a tail-recursive algorithm for a problem that seems to demand a different type of recursion'''''.

=== Another Example – Modifying the List ===

Sometimes you want to take a list and create another list from it. You do this by working through the list element by element, replacing each element with a computed value. For example, here is a program that takes a list of numbers and adds 1 to each of them:

<vip>class my
predicates
add1 : (integer*, integer*) procedure(i,o).
end class

implement my
clauses
add1([], []).
/* boundary condition */
add1([Head|Tail],[Head1|Tail1]):-
/* separate the head */
/* from the rest of the list */
Head1 = Head+1,
/* add 1 to the first element */
add1(Tail, Tail1).
/* call element with the rest of the list */
end implement

goal
console::init(),
my::add1([1,2,3,4], NewList),
stdio::write(NewList)).</vip>

To paraphrase this in natural language:

To add 1 to all the elements of the empty list, 
just produce another empty list. 
 
To add 1 to all the elements of any other list, 
add 1 to the head and make it the head of the result, and then 
add 1 to each element of the tail and make that the tail of the result.

Load the program, and run the goal with the specified goal

<vip>add1([1,2,3,4], NewList).</vip>

The goal will return

<code language="text">NewList=[2,3,4,5]
1 Solution</code>

=== Tail Recursion Again ===

Is add1 tail-recursive? If you're accustomed to using Lisp or Pascal, you might think it isn't, because you think of it as performing the following operations:

*Split the list into ''Head'' and ''Tail''.

*Add 1 to ''Head'', giving ''Head1''.

*Recursively add 1 to all the elements of ''Tail'', giving ''Tail1''.

*Combine ''Head1'' and ''Tail1'', giving the resulting list.

This isn't tail-recursive, because the recursive call is not the last step.

But – and this is important – '''''that is not how Prolog does it'''''. In Visual Prolog, add1 is tail-recursive, because its steps are really the following:

*Bind the head and tail of the original list to ''Head'' and ''Tail''.

*Bind the head and tail of the result to ''Head1'' and ''Tail1''. (''Head1'' and ''Tail1'' do not have values yet.)

*Add 1 to ''Head'', giving ''Head1''.

*Recursively add 1 to all the elements of ''Tail'', giving ''Tail1''.

When this is done, ''Head1'' and ''Tail1'' are ''already'' the head and tail of the result; there is no separate operation of combining them. So the recursive call really is the last step.

=== More on Modifying Lists ===

Of course, you don't actually need to put in a replacement for every element. Here's a program that scans a list of numbers and copies it, leaving out the negative numbers:

<vip>class my
predicates
discard_negatives : (integer*, integer*) procedure(i,o).
end class

implement my
clauses
discard_negatives([], []).
discard_negatives([H|T], ProcessedTail):-
H < 0,
!, /* If H is negative, just skip it */
discard_negatives(T, ProcessedTail).
discard_negatives([H|T], [H|ProcessedTail]):-
discard_negatives(T, ProcessedTail).
end implement

goal
console::init(),
my::discard_negatives ([2, -45, 3, 468], X),
stdio::write(X).</vip>

For example, the goal

<vip>my::discard_negatives([2, -45, 3, 468], X)</vip>

gives

<vip>X=[2, 3, 468].</vip>

And here's a predicate that copies the elements of a list, making each element occur twice:

<vip>doubletalk([], []).
doubletalk([H|T], [H, H|DoubledTail]) :-
doubletalk(T, DoubledTail).</vip>

===List Membership===

Suppose you have a list with the names ''John'', ''Leonard'', ''Eric'', and ''Frank'' and would like to use Visual Prolog to investigate if a given name is in this list. In other words, you must express the relation "membership" between two arguments: a name and a list of names. This corresponds to the predicate

<vip>isMember : (name, name*).
/* "name" is a member of "name*" */</vip>

In the e01.pro program, the first clause investigates the head of the list. If the head of the list is equal to the name you're searching for, then you can conclude that Name is a member of the list. Since the tail of the list is of no interest, it is indicated by the anonymous variable. Thanks to this first clause, the goal

<vip>my::isMember("john", ["john", "leonard", "eric", "frank"])</vip>

is satisfied.

<vip>/* Program e01.pro */
class my
predicates
isMember : (A, A*) determ.
end class

implement my
clauses
isMember(Name, [Name|_]) :-
!.
isMember(Name, [_|Tail]):-
isMember(Name,Tail).
end implement

goal
console::init(),
my::isMember("john", ["john", "leonard", "eric", "frank"]),
!,
stdio::write("Success")
;
stdio::write("No solution").</vip>

If the head of the list is not equal to Name, you need to investigate whether Name can be found in the tail of the list.

In English:

Name is a member of the list if Name is the first element of the list, or 
Name is a member of the list if Name is a member of the tail.

The second clause of isMember relates to this relationship. In Visual Prolog:

<vip>isMember(Name, [_|Tail]) :-
isMember(Name, Tail).</vip>

===Appending One List to Another: Declarative and Procedural Programming===

As given, the member predicate of the e01.pro program works in two ways. Consider its clauses once again:

<vip>member(Name, [Name|_]).
member(Name, [_|Tail]) :-
member(Name, Tail).</vip>

You can look at these clauses from two different points of view: declarative and procedural.

*From a declarative viewpoint, the clauses say:Name is a member of a list if the head is equal to Name; 
if not, Name is a member of the list if it is a member of the tail.

*From a procedural viewpoint, the two clauses could be interpreted as saying:To find a member of a list, find its head; 
otherwise, find a member of its tail.

These two points of view correspond to the goals

<vip>member(2, [1, 2, 3, 4]).</vip>

and

<vip>member(X, [1, 2, 3, 4]).</vip>

In effect, the first goal asks Visual Prolog to check whether something is true; the second asks Visual Prolog to find all members of the list [1,2,3,4]. Don't be confused by this. The member predicate is the same in both cases, but its behavior may be viewed from different angles.

=== Recursion from a Procedural Viewpoint ===

The beauty of Prolog is that, often, when you construct the clauses for a predicate from one point of view, they'll work from the other. To see this duality, in this next example you'll construct a predicate to append one list to another. You'll define the predicate append with three arguments:

<vip>append(List1, List2, List3).</vip>

This combines List1 and List2 to form List3. Once again you are using recursion (this time from a procedural point of view).

If List1 is empty, the result of appending '' Lis''t''1'' and List2 will be the same as List2. In Prolog:

<vip>append([], List2, List2).</vip>

If List1 is not empty, you can combine List1 and List2 to form ''List3'' by making the head of List1 the head of List3. (In the following code, the variable H is used as the head of both List1 and List3.) The tail of List3 is L3, which is composed of the rest of List1 (namely, L1) and all of List2. In Prolog:

<vip>append([H|L1], List2, [H|L3]) :-
append(L1, List2, L3).</vip>

The append predicate operates as follows: While List1 is not empty, the recursive rule transfers one element at a time to List3. When List1 is empty, the first clause ensures that List2 hooks onto the back of List3.

=== One Predicate Can Have Different Uses ===

Looking at append from a declarative point of view, you have defined a relation between three lists. This relation also holds if List1 and List3 are known but List2 isn't. However, it also holds true if only List3 is known. For example, to find which two lists could be appended to form a known list, you could use a goal of the form

<vip>append(L1, L2, [1, 2, 4]).</vip>

With this goal, Visual Prolog will find these solutions:

<vip>1L1=[], L2=[1,2,4]
L1=[1], L2=[2,4]L1=[1,2], L2=[4]L1=[1,2,4], L2=[]4 Solutions</vip>

You can also use append to find which list you could append to [3,4] to form the list [1,2,3,4]. Try giving the goal

<vip>append(L1, [3,4], [1,2,3,4]).</vip>

Visual Prolog finds the solution

<vip>L1=[1,2].</vip>

This append predicate has defined a relation between an '' input set'' and an ''output set'' in such a way that the relation applies both ways. Given that relation, you can ask

Which output corresponds to this given input?

or

Which input corresponds to this given output?

The status of the arguments to a given predicate when you call that predicate is referred to as a ''flow pattern''. An argument that is bound or instantiated at the time of the call is an input argument, signified by (i); a free argument is an output argument, signified by (o).

The append predicate has the ability to handle any flow pattern you provide. However, not all predicates have the capability of being called with different flow patterns. When a Prolog clause is able to handle multiple flow patterns, it is known as an invertible clause. Many of list predicate can be found in the '''list''' class.

==Finding All the Solutions at Once==

Backtracking and recursion are two ways to perform repetitive processes. Recursion won out because, unlike backtracking, it can pass information (through arguments) from one recursive call to the next. Because of this, a recursive procedure can keep track of partial results or counters as it goes along.

But there's one thing backtracking can do that recursion can't do – namely, find all the alternative solutions to a goal. So you may find yourself in a quandary: You need all the solutions to a goal, but you need them all at once, as part of a single compound data structure. What do you do?

Fortunately, Visual Prolog provides a way out of this impasse. The built-in construction list comprehension takes a goal as one of its arguments and collects all of the solutions to that goal into an output single list. list comprehension takes two arguments:

*The first argument, VarName, specifies which argument in the specified predicate is to be collected into a list.

*The second, mypredicate, indicates the predicate from which the values will be collected.

*The output ListParam, is a variable that holds the list of values collected through backtracking.

The e02.pro program uses list comprehension to print the average age of a group of people.

<vip> /* Program e02.pro */
class my
domains
name = string.
address = string.
age = integer.

predicates
person : (name, address, age)
nondeterm anyflow.
sumlist : (age*, age, integer)
procedure(i,o,o).
end class

implement my
clauses
sumlist([],0,0).
sumlist([H|T], Sum, N):-
sumlist(T, S1, N1),
Sum=H+S1, N=1+N1.
person("Sherlock Holmes",
"22B Baker Street", 42).
person("Pete Spiers",
"Apt. 22, 21st Street", 36).
person("Mary Darrow",
"Suite 2, Omega Home", 51).
end implement

goal
console::init(),
L = [ Age || my::person(_, _, Age)],
my::sumlist(L, Sum, N),
Ave = Sum/N,
stdio::write("Average=", Ave, ". ").</vip>

The list comprehension clause in this program creates a list L, which is a collection of all the ages obtained from the predicate person. If you wanted to collect a list of all the people who are 42 years old, you could give the following subgoal:

<vip>List = [ Who || my::person(Who, _, 42) ]</vip>

The following code will create the list of positive items:

<vip>List = [ X || X = list::getMember_nd([2,-8,-3,6]), X > 0]</vip>

==Compound Lists==

A list of integers can be simply declared as

<vip>integer*</vip>

The same is true for a list of real numbers, a list of symbols, or a list of strings.

However, it is often valuable to store a combination of different types of elements within a list, such as:

<vip>[2, 3, 5.12, ["food", "goo"], "new"] % Not correct Visual Prolog</vip>

''Compound lists'' are lists that contain more than one type of element. You need special declarations to handle lists of multiple-type elements, because Visual Prolog requires that all elements in a list belong to the '''''same''''' domain. The way to create a list in Prolog that stores these different types of elements is to use functors, because a domain can contain '''''more than one''''' data type as arguments to functors.

The following is an example of a domain declaration for a list that can contain an integer, a character, a string, or a list of any of these:

<vip>domains
llist = l(list); i(integer); c(char); s(string).
% the functors are l, i, c, and s</vip>

The list

<vip>[ 2, 9, ["food", "goo"], "new" ] % Not correct Visual Prolog</vip>

would be written in Visual Prolog as:

<vip>[i(2), i(9), l([s("food"), s("goo")]), s("new")] % Correct Visual Prolog</vip>

The following example of append shows how to use this domain declaration in a typical list-manipulation program.

<vip>class my
domains
llist = l(list); i(integer); c(char); s(string).
predicates
test : ().
end class

implement my
class predicates
append : (A*,A*,A*) procedure (i,i,o).
clauses
append([], L, L).
append([X|L1], L2, [X|L3]):-
append(L1, L2, L3).

clauses
test() :-
append([s("likes"), l([s("bill"), s("mary")])], [s("bill"), s("sue")], Ans),
stdio::write("FIRST LIST: ", Ans,"\n\n"),
append([l([s("This"), s("is"),s("a"),s("list")]), s("bee")], [c('c')], Ans2),
stdio::write("SECOND LIST: ", Ans2, "\n\n").
end implement</vip>

== Parsing by Difference Lists ==

The ch07e10.pro program demonstrates [[wikipedia:parsing|parsing]] by ''difference lists''. The process of parsing by difference lists works by reducing the problem; in this example we transform a string of input into a Prolog structure that can be used or evaluated later.

The parser in this example is for a very primitive computer language. Although this example is very advanced for this point in the tutorial, we decided to put it here because parsing is one of the areas where Visual Prolog is very powerful. If you do not feel ready for this topic, you can skip this example and continue reading the tutorial without any loss of continuity.

<vip>#include @"pfc\list\list.ph"
#include @"pfc\string\string.ph"
#include @"pfc\application\exe\exe.ph"
#include @"pfc\console\console.ph"

/*******************************************
* Lexer
*******************************************/
class lexer
predicates
tokl : (string Input) -> string* TokenTL.
end class lexer

implement lexer
clauses
tokl(Input) = [Tok|tokl(Rest)] :-
string::fronttoken(Input, Tok, Rest),
!.
tokl(_) = [].
end implement

/*******************************************
* Parser
*******************************************/
class parser
domains
program = statement*.

domains
statement =
if_Then_Else(expression Condition, statement ThenPart, statement ElsePart);
if_Then(expression Condition, statement ThenPart);
while(expression Condition, statement Body);
assign(id Variable, expression Expression).

domains
expression =
plus(expression, expression);
minus(expression, expression);
var(id);
int(integer).

domains
id = string.

predicates
program : (string* TL) -> program ProgramTree determ.

end class

implement parser
clauses
program(TL) = Prog :-
Prog = statement_list(TL, TL0),
[] = TL0.

class predicates
statement_list : (string* TL1, string* TL0 [out]) -> program Program determ.
clauses
statement_list([], []) = [] :-
!.
statement_list(TL1, TL0) = [Statement|Program] :-
Statement = statement(TL1, TL2),
TL2=[";"|TL3],
Program = statement_list(TL3, TL0).

class predicates
statement : (string* TL1, string* TL0 [out]) -> statement Statement determ.
clauses
statement(["if"|TL1], TL0) = if_then_else(Condition, ThenPart, ElsePart) :-
Condition = expression(TL1, TL2),
TL2=["then"|TL3],
ThenPart = statement(TL3, TL4),
TL4=["else"|TL5],!,
ElsePart = statement(TL5, TL6),
TL6=["fi"|TL0].

statement(["if"|TL1], TL0) = if_then(Condition, Statement) :-
!,
Condition = expression(TL1, TL2),
TL2=["then"|TL3],
Statement = statement(TL3, TL4),
TL4=["fi"|TL0].

statement(["do"|TL1], TL0) = while(Condition, Statement) :-
!,
Statement = statement(TL1, TL2),
TL2=["while"|TL3],
Condition = expression(TL3, TL0).

statement([ID|TL1], TL0) = assign(Id,Exp) :-
string::isname(ID),
TL1=["="|TL2],
Exp = expression(TL2, TL0).

class predicates
expression : (string* TL1, string* TL0 [out]) -> expression Expression determ.
clauses
expression(TL1, TL0) = Exp:-
PreTerm = term(TL1, TL2),
Exp = termTail(TL2, TL0, PreTerm).

class predicates
termTail : (string* TL1, string* TL0 [out], expression PreExpr) -> expression Expr determ.
clauses
termTail(["+"|TL1], TL0, Exp1) = Exp :-
!,
Exp2 = term(TL1, TL2),
Exp = termTail(TL2, TL0, plus(Exp1, Exp2)).

termTail(["-"|TL1], TL0, Exp1) = Exp :-
!,
Exp2 = term(TL1, TL2),
Exp = termTail(TL2, TL0, minus(Exp1, Exp2)).

termTail(TL, TL, Exp) = Exp.

class predicates
term : (string* TL1, string* TL0 [out]) -> expression Expression determ.
clauses
term([Int|Rest], Rest) = int(I) :-
try
I = toTerm(Int)
catch _ do
fail
end try,
!.

term([Id|Rest], Rest) = var(Id) :-
string::isName(Id).
end implement parser

goal
console::init(),
TokenTL = lexer::tokl("b=2; if b then a=1 else a=2 fi; do a=a-1 while a;"),
if ProgramTree = parser::program(TokenTL) then
foreach Stmt = list::getMember_nd(ProgramTree) do
stdio::write(Stmt, "\n")
end foreach
else
stdio::write("Parse error\n")
end if.</vip>

The program will write:

<source lang="text">assign("b",int(2))
if_then_else(var("b"),assign("a",int(1)),assign("a",int(2)))
while(var("a"),assign("a",minus(var("a"),int(1))))</source>

The transformation in this example is divided into two stages: scanning and parsing. The tokl predicate is the scanner; it accepts a string and converts it into a list of tokens. In this example the input text is a Pascal-like program made up of Pascal-like statements. This programming language only understands certain statements: IF THEN ELSE, IF THEN, DO WHILE, and ASSIGNMENT. Statements are made up of expressions and other statements. Expressions are addition, subtraction, variables, and integers.

Here's how this example works:

*The '''program''' predicate takes a list of tokens call the '''statement_list''' predicate on that list. And then is test that all tokens was used in the parse process.
*The predicate '''statement_list''' takes a list of tokens and tests if the tokens can be divided up into individual statements, each ending with a semicolon.
*The predicate '''statement''' tests if the first tokens of the token list make up a legal statement. If so, the statement is returned in a structure and the remaining tokens are returned back to '''statement_list'''.
*The four clauses of the '''statement''' correspond to the four types of statements the parser understands.
**If the first '''statement''' clause is unable to transform the list of tokens into an ''IF THEN ELSE'' statement, the clause fails and backtracks to the next '''statement''' clause.
**The second clause tries to transform the list of tokens into an ''IF THEN'' statement.
**If that clause fails, the next clause tries to transform the list of tokens into a ''DO WHILE'' statement.
**And if all the first three '''statement''' clauses fail, the last clause for that predicate tests if the statement does assignment. This clause tests for assignment by testing if the first term is a symbol, the second term is "=", and the next terms make up a simple math expression.
*The '''expression''', '''term''', and '''termTail''' predicates work in simailar ways, by testing if the first terms are expressions and – if so – returning the remainder of the terms and an expression structure back to '''statement'''.

==Summary==

These are the important points covered in this tutorial:

*''Lists'' can contain an arbitrary number of elements; you declare them by adding an asterisk at the end of a previously defined domain.

*A list is a recursive compound object that consists of a head and a tail. The head is the first element and the tail is the rest of the list (without the first element). The tail of a list is always a list; the head of a list is an element. A list can contain zero or more elements; the empty list is written [].

*The elements in a list can be anything, including other lists; all elements in a list must belong to the same domain. The domain declaration for the elements must be of this form:

<vip>domains
element_list = elements*.
elements = ....</vip>

where elements = one of the standard domains (integer, real, etc.) or a set of alternatives marked with different functors (int(integer); rl(real); smb(symbol); etc.). You can only mix types in a list in Visual Prolog by enclosing them in compound objects/functors.

*You can use separators (commas, [, and |) to make the head and tail of a list explicit; for example, the list

<vip>[a, b, c, d]</vip>

can be written as:

<vip>[a|[b, c, d]] or[a, b|[c, d]] or[a, b, c|[d]] or[a|[b|[c, d]]] or[a|[b|[c|[d]]]] or even[a|[b|[c|[d|[]]]]]</vip>

*List processing consists of recursively removing the head of the list (and usually doing something with it) until the list is an empty list.

*The list predicates can be found in the '''list''' class.

*Visual Prolog provides a built-in construction, list comprehension, which takes a goal as one of its arguments and collects all of the solutions to that goal into a single list. It has the syntax

<vip>Result = [ Argument || myPredicate(Argument) ]</vip>

*Because Visual Prolog requires that all elements in a list belong to the same domain, you use functors to create a list that stores different types of elements.

*The process of ''parsing by difference lists'' works by reducing the problem; the example in this tutorial transforms a string of input into a Prolog structure that can be used or evaluated later.

[[ru:Списки и рекурсия]]
[[Category:Data types and handling]]

Fundamental Visual Prolog - the Data Layer

2016-11-03T09:40:04Z

EJP: Updated familyDL and familyData code snippets.

{{FundamentalPrologNavbar}}

In this tutorial, we will continue with the '''family''' example, where we would introduce one more layer - the Data layer - to handle the problem more efficiently. This tutorial will give you all the sophistication that is required to handle complex situations.

'''Download''' source files of the example project used in this tutorial:

* Visual Prolog 7.4 and 7.3 install examples in the IDE:
*:'''Help -> Install Examples...'''
* [http://download.pdc.dk/vip/72/tutorial/family4.zip Visual Prolog 7.2 version].
* [http://download.pdc.dk/vip/71/tutorial/family4.zip Visual Prolog 7.1 version].

==Concepts==

There is a Chinese proverb that goes like this: "Give a man a fish and you feed him for a day. Teach a man to fish and you feed him for a lifetime". There is a lesson in programming there. It is often better to substitute data (''a fish'') with a method (''the procedure of fishing'') that can lead to the data.

This concept can be extended further a bit more. For example, if before teaching the person fishing directly, the man is taught the principles of getting food from nature, then the person has a much better chance of getting food for his family.

But here is a caveat: explaining things using analogies can be a bit problematic, because, when you stretch an analogy too far, it breaks! In the above example, if you give the fisherman one more layer'','' then he may die of starvation before he can harvest the fruits of his fine education!

This manner of daisy-chaining together a set of activities to achieve the end goal can be done in programming also. But then, this has to be done intelligently, as per the demands posed by the complexity of the software problem you are trying to handle. Though it can be said that more the ''layers'' that are introduced, better is the control on reaching the eventual goal; one needs to setup the layers after careful foresight.

If you see the pattern that had evolved in through the entire '''family''' series of tutorials (Fundamental Visual Prolog, Fundamental Visual Prolog - GUI, Fundamental Visual Prolog - the Business Logical Layer), you would notice the same thing: more and more refined layers were introduced that finely controlled the behavior of the program. At the same time, there were no unnecessary layers - if it were so, it would have only increased the complexity and cumbersomeness of the program.

In this tutorial, we will introduce the Data layer. The core of the data layer is nothing but a class, and objects of that class would be used to access and set the actual data. In the earlier tutorial, please note that the Business Logical Layer (BLL) handled the data also. This time, the BLL would be handling ''only'' the logic.

==The Program==

But first of all, let us understand the various parts of the program with the help of the supplied family4.zip file. In this tutorial, we are not presenting the code that is needed (else this tutorial will become too lengthy). All the code is present in the example for the tutorial. You can read the code from the IDE, when you load the project there. Some partial code is, however, present here, for quick reference.

When you load the project ('''family4''') in the Visual Prolog IDE, you will notice four separate packages as seen below:

:[[Image:FundamentalVisualPrologData_01.png|Visual Prolog Project window]]

These packages are the FamilyBLL, FamilyData'','' FamilyDL and TaskWindow packages. The last package (i.e. TaskWindow) is automatically created by the IDE, when you create the project. The method to create the other packages was explained in a previous tutorial.

The project was created in a similar fashion that was explained in a previous tutorial. There are no surprises there. But here is a bit of explanation of something new.

There is one more dialog that is introduced in the '''TaskWindow''' package as compared to the previous tutorial. This is the '''NewPersonDialog''', which is shown below. (We've already included this dialog in the project. However, the explanation below pretends that you are creating this dialog on your own in the project.)

:[[Image:FundamentalVisualPrologData_02.png|New Person Dialog]]

This dialog is a modeless dialog, which is used to collect the information of a new person that is to be inserted into the current database. As you can see in the above image, there is a text-edit field (idc_name) for collecting the name, a radio button series (idc_male and idc_female) for finding the gender, and two further text edit fields (idc_parent1 and idc_parent2) to find the parents of the person being added into the database. A modeless dialog is one, which can remain open and active, without interfering in the workings of other parts of the GUI.

There is no difference between a ''modal'' and ''modeless'' dialog when it is being created. However, when you set its attributes you must be careful to specify that it is indeed a modeless one, as shown below:

:[[Image:FundamentalVisualPrologData_04.png|Specifying]]

Now just creating such a dialog is not of any use if there is no way by which the dialog can be invoked from TaskWindow. Hence we need to insert a new menu item in that and associate an event handler with that menu item. Once we create the appropriate menu item, the code wizard will allow us to create a handler into which we can fill in the requisite code. The image is shown below:

:[[Image:FundamentalVisualPrologData_03.png|Creating a handler in the Dialog and Window Expert (TaskWindow)]]

Please note that in an earlier tutorial (Fundamental Visual Prolog - GUI), we had shown how to create an event handler for a menu-item using the above code wizard.

==Modeless Dialog: Conceptual Issues==

This program uses a modeless dialog in order to insert information regarding new persons into the '''family''' database. As indicated in an earlier tutorial, coding for the events happening from a modeless dialog can sometimes be tricky. This can be understood if you know exactly why a modal dialog works the way it does. In a modal dialog, the operating system suspends events happening from all other GUI parts of the same application and concentrates only on those that emerge from the modal dialog. The logic required to be handled by the programmer at that point in time becomes quite simple, as the programmer is quite sure that there are no untoward events that are happening simultaneously in other parts of the same program.

On the other hand, when a modeless dialog is in use, the program is receptive to events even from parts of the program ''along with'' those occurring from within the said dialog. The permutations and combinations of event handling required need to be carefully thought through by the programmer. For example, the program could open a database, and then have a ''modeless'' dialog opened, which worked on the database. It would throw an error, when the dialog is put to use if in the background the database was closed without shutting down the dialog. Unless, of course, you had anticipated such a course of events and programmed for such situations.

If you see the source code that handles the events happening from this dialog in NewPersonDialog.pro, you would see that the code carefully catches a lot of error situations. It even has an integrity checker that attempts to trace what may cause a piece of code to cause an error.

Predicates that may lead to errors during runtime are called from within a <vp>try</vp>-construction. For example, see the following code:

<vip>clauses
onControlOK(_Ctrl, _CtrlType, _CtrlWin, _CtrlInfo) = handled(0) :-
Name = vpi::winGetText(vpi::winGetCtlHandle(thisWin, idc_name)),
Name "",
MaleBool = vpi::winIsChecked(vpi::winGetCtlHandle(thisWin, idc_male)),
Gender = maleFlagToGender(MaleBool),
OptParent1 = optParent(idc_parent1),
OptParent2 = optParent(idc_parent2),
try
bl:addPerson(Name, Gender, OptParent1, OptParent2)
catch TraceId do
integrityHandler(TraceId))
end try,
!,
stdIO::write("Inserted ", Name, "\n").
onControlOK(_Ctrl, _CtrlType, _CtrlWin, _CtrlInfo) = handled(0).</vip>

In the above code snippet, the programmer is not sure whether the addition of a person into the database is really possible (because it is not allowed to add an existing person). Thus the <vp>addPerson</vp> is not called directly, but inside a <vp>try</vp>-construction. The <vp>try</vp>-construction has three components ; the first is the code to be called to do the actual work at that point in the code, the second is the a variable (i.e. <vp>TraceId</vp>) bound to a <vp>traceId</vp> which is used to access information about the exception, and the third is the code that is called when the first part terminates with an exception. That component can be used by the programmer to bring the program safely back into control.

==The FamilyData Package==

In this example, we'll create one FamilyData package, which has all the required code for handling the domains that are needed by the program. The same domains would be available to the '''BLL''' (Business Logic Layer), when it communicates with the data layer.

In this class, we'll write the following code:

<vip>class familyData

domains
gender = female; male.

domains
person = string.

domains
optionalPerson =
noPerson;
person(person Person).

end class familyData</vip>

If you notice, the above class contains the domain definitions that are to be shared between multiple classes. Thus, the purpose of this package is to act as a meeting place between the ''Data Layer'' and the ''Business Layer''.

==Interfaces==

The layer'','' which will handle the data, will be via objects created from a class in the FamilyDL package. However, before we get to the actual contents of that package, we need to understand a concept called an interface''.''

An interface can be looked upon as a statement of intention on what to expect in the objects that would adhere to the said interface. It is written in a separate file using the IDE and it can contain predicates that can be expected to be found in the objects of a class.

An interface can also be used for some more definitions that are not explained in this tutorial. You can learn about those advance usage in a future tutorial.

The reason for writing the intentions separately into a different interface is an elegant one: A class can be written to adhere to the declarations found in an interface. The interface gives an abstract definition of the functionality provided by the objects of the class. The definition is "abstract" because it only expresses some of the functionality of the objects. In short, a class can declaratively state that its objects would be behaving in accordance to the interface.

Several classes can implement the same interface; each of them providing a specific, concrete (i.e. non-abstract) implementation of the abstraction. This reduces the burden of code maintenance tremendously. Later on, when more sophistication is to be introduced in the same program, the programmer/s can work on these interfaces and then work their way from there methodically.

==The FamilyDL Package==

This example also contains another package called the FamilyDL package. This package contains the main class, whose objects would handle the actual data.

This package contains an interface - the familydl interface. The main purpose of this interface is to define the predicates that are provided by the data layer to the business logic layer. As such it plays a major role in the data layer. This interface will be based on domains from the FamilyData package.

<vip>interface familyDL
open core, familyData

predicates
person_nd : (person Name [out]) nondeterm.

predicates
gender : (person Name) -> gender Gender.

predicates
parent_nd : (person Person, person Parent [out]) nondeterm.

predicates
addPerson : (person Person, gender Gender).

predicates
addParent : (person Person, person Parent).

predicates
personExists : (person Person) determ.

predicates
save : ().

end interface familyDL</vip>

In the above code, the open keyword is used to indicate that the declarations in both the core and the familyData packages are used in this interface.

The package contains two classes: family_exception and family_factfile. Most of the work will be done by family_factfile''.'' That file will contain the code, which brings in the fish (if one were to again use the metaphor of the Chinese proverb mentioned in the beginning of this tutorial). It systematically builds up the database that is used by the program, and, while doing, so checks for any error situation that may happen. In case there is an error, it would use predicates from the family_exception class to systematically signal the error.

==Code for the familyDL Package==

The familyDL package has one interface file familydl.i, which code was given earlier. The package also contains two .pro files containing the implementations of two .cl (class) files. The two classes in this package are familydl_exception and familydl_factfile. The code for familydl_factfile can be examined from the family4.zip file that can be downloaded separately for this tutorial. The predicates in that file are for handling the data, and we have covered that in our earlier tutorial.

The code for familydl_exception is also not presented here in this tutorial. Please read it from the family4.zip file. The predicates contain support utility predicates that are used to show correct error messages, when incorrect data and/or errors (known as exceptions in computerese) are caught by the program. Many of these error situations happen without the control of the programmer (for example, a drive door being open is an exception that cannot be predicted), but sometimes, it is required to make an error happen. That means, the programmer deliberately raises an error (to use some computer jargon here). Thus the error utility predicates start with the term '''raise_''' as you may notice in the code.

Note that familydl_exception does not contain the logic for handling the exceptions themselves. They are utility predicates that allow the program show the correct error dialog, when exceptions are to happen.

Here is an example how these raise_ predicates are deliberately invoked by the programmer to signal an error situation.

In the familydl_factfile.pro you would find a predicate for adding a parent. In the clause body, it first goes through two checks to see if both the Person as well as the Parent of the Person are existing. If anyone of them does not exist, then '''familyDL_exception::raise_personAlreadyExists''' is called. This raises the exception and the program would display a special error dialog at that point. Fortunately, that particular error dialog does not need to be constructed by the programmer. The dialog creation work is done by the libraries of Visual Prolog when it links your program. You would not be creating a separate error dialog the way we did for other dialogs.

<vip>%note: the following is only partial
% code from familydl_factfile.pro

clauses
addParent(Person, Parent) :-
check_personExists(Person),
check_personExists(Parent),
assertz(parent_fct(Person, Parent)).

clauses
personExists(Person) :-
person_fct(Person, _),
!.

predicates
check_personDoesNotExist : (string Person).
clauses
check_personDoesNotExist(Person) :-
personExists(Person),
!,
familyDL_exception::raise_personAlreadyExists(Person).
check_personDoesNotExist(_).

...</vip>

==Code for the familyBLL Package==

The code for the '''familyBL.i''' interface file is given below. This is quite similar to the interface for the business layer that was developed for the previous tutorial. But there are important differences: the domains have been shifted out of this package and are now commonly shared between the Data Layer and the Business Layer. This is an obvious move, because in the previous tutorial we had kept both the Business Layer and the Data Layer as one piece of code. When we separate these two layers, we would still need some common point through which these two layers can talk to one another, and the obvious decision would be to make the domains used by them common to each other.

The second change that can be noticed is that the predicates do not have multiple-flows. Each predicate does exactly one thing with the parameters that it handles. This makes the program move ''away'' from traditional Prolog and it becomes similar to programs written in other languages. Often, this strategy yields better results because it makes it easier to understand the program when one reads the source code. However, the former method of having multiple-flows does result in shorter source code and is often preferred by programmers who came in after using traditional Prolog.

<vip>interface familyBL
open core, familyData

predicates
personWithFather_nd : (person Person, person Father)
nondeterm (o,o).

predicates
personWithGrandfather_nd : (person Person, person GrandFather)
nondeterm (o,o).

predicates
ancestor_nd : (person Person, person Ancestor)
nondeterm (i,o).

predicates
addPerson : (person Person, gender Gender, optionalPerson Parent1, optionalPerson Parent2).

predicates
save : ().
end interface familyBL</vip>

The source code for the '''familyBL''' class is not presented here. You may read it once you load the code from the supplied example into your IDE. There should be no surprises there. It does the same activities that were carried out in the business layer of the previous tutorial (Fundamental Visual Prolog - the Business Logical Layer). However, there are two important differences: wherever data accessing or setting of data is needed, predicates from the familyDL class are used. Also, the predicates of this class check the validity of information and raise exceptions in the case logical errors are found.

The package contains one more class: '''familyBL_exception'''. This class is similar to the one that we found in the Data Layer. But this time, it contains utility predicates that are used to raise exceptions, when the Business Layer predicates are at work.

==Features of a Data Layer==

The main feature of a Data layer, is that it implements a set of predicates collectively referred to as data accessors in object-oriented languages. A ''Data accessor'' decouples data access from the underlying implementation. In simpler terms, you would use predicates to ''set'' and ''get'' the data used by the program. The actual data would remain private and inaccessible from the outside.

Data accessors can also provide a uniform interface to access attributes of the data, while leaving the concrete organization of the attributes hidden.

The advantage of using ''data accessors'' is that algorithms implemented in other areas of the program can be written independent of the knowledge regarding the exact data structure that was used in the Data layer.

There are hardly any pitfalls to this approach, but whatever they are, these pitfalls must be understood. The main one is that two sophisticated levels of understanding have to be reached by the programmer when writing the Data layer''.'' One would be to determine the internal data structures that will remain private within the Data layer. (The kind of thinking, required to develop data structures, was discussed in the Fundamental Visual Prolog tutorial regarding functors). But after that, the programmer will also have to spend time designing efficient ''data accessor'' predicates so that other layers can mate smoothly with the ''Data layer''. Incorrect design of the ''data accessor'' predicates can often create a lot of headache, when a team of programmers is at work. Especially, when the program is required to move from a simple one to a more complex one.

==Conclusion==

In this tutorial we used a strategy of "''teach the program fishing and not give it fish''" in our program. This is nothing but modularizing of the source code of the software intelligently so that code maintenance and extension of the code becomes extremely simple. We split the erstwhile Business Layer of the previous tutorial into two parts: one contained pure business logic and the other one handled just the data. This allows us to extend the program later on and replace just the data layer with other forms of data handling techniques (such as through data retrieved via an ODBC protocol, or via the Internet, etc.) This tutorial also covered exception handling and we discovered, how easy it is to write our own exception raising predicates, and use those to display intelligent error messages to the user.

==References==

[[Category:Fundamental Visual Prolog Tutorial]]