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

Visual Prolog 10 Upgrade Notes

2026-03-31T08:17:09Z

Thomas Linder Puls: predicate name spelling

This document describes how to upgrade Visual Prolog 9 projects to Visual Prolog 10, for older projects you should also read the [[Visual Prolog 9 Upgrade Notes]].

If you have problems with upgrading your projects and need additional information, you are welcome to ask questions in [http://discuss.visual-prolog.com/viewforum.php?f=2 Visual Prolog Discussion Forum].

By default, the installation of Visual Prolog 10 will not replace any previously installed versions. It is possible to work with several versions on a single computer.
* The Commercial Edition will by default be installed in '''C:\Program Files (x86)\Visual Prolog 10''' or '''C:\Program Files\Visual Prolog 10'''.
* The Personal Edition will by default be installed to '''C:\Program Files (x86)\Visual Prolog 10PE''' or '''C:\Program Files\Visual Prolog 10PE'''.

Visual Prolog 10 projects are backward-compatible with Visual Prolog 9 projects.
If you are going to use different versions of Visual Prolog installed at one computer, avoid opening projects by double-clicking on vipprj files.

'''Notice''' it is highly advisable to have a backup of a project before updating.

=== Superfluos files ===

The following files are superfluous and should be deleted:

* '''.frm''' related to forms
* '''.win''' related to e.g. the task window
* '''.ctl''' related to controls
* '''.dlg''' related to dialogs; '''except''' if it corresponds to "aincient" Visual Prolog 5 resource dialog that has been "inherited" into the project. If in doubt: the code in the corresponding '''.pro''' file of such a dialog will not contain a <vp>generatedInitialize</vp> predicate.

=== Binary memory representation ===

Binaries have changed representation. In the old representation a binary was a pointer to the actual data, and immediately before the data the size of the binary was written. Windows API and other external APIs does not use this representation and as a consequence binaries was often had to be copied from the buffer that cntains it to another "buffer" that can hold the size infront of the data. A <vp>binary</vp> is now represented as a pointer to a memory cell containing a pointer to a data-buffer and the size. So the size is no longer placed in a specific place relative to the actual data. With the old representation <vp>uncheckedConvert</vp> of a binary to the <vp>pointer</vp> domain would result in a pointer to the data. With the new representation this is no longer the case and therefore it has been made illegal to <vp>uncheckedConvert</vp> from <vp>binary</vp> to <vp>pointer</vp>, instead you must use <vp>convert</vp> which will both in old and new representation give a pointer to the data. Alternatively, you can use the extension predicate <vp>binary::data()</vp> instead, e.g. <vp>Pointer = MyBinary:data()</vp>.

=== List comprehension ===

In a list comprehension <vp>[ Exp || Gen ]</vp> the <vp>Exp</vp> must be a procedure (language reference has always required that, but the compiler has accepted <vp>determ</vp> expressions). In cases where <vp>Exp</vp> is determ the following rewrite can be applied <vp>[ V || Gen, V = Exp ]</vp>.

=== <>_list domains deprecated ===

The domains <vp>integer_list</vp>, <vp>integer_list_list</vp>, etc. has been deprecated. In declarations the *-form should be used, but in predicate calls like <vp>tryToTerm</vp> it is necessary to uses the <vp>list{...}</vp> type constructor, e.g. <vp>tryToTerm(list{integer}, String)</vp>. An old program can require a significant amount of updates.

=== Erroneous predicates as values ===

<vp>erroneous</vp> predicates can now be used as a value, for example in <vp>X otherwise raise_error()</vp>. Hereby <vp>erroneous</vp> functions have become superfluous, and subsequently it is now illegal to declare <vp>erroneous</vp> functions (a corresponding <vp>erroneous</vp> predicate must be used instead).

== See also ==

* [[Visual Prolog 10 New Features]]
* [[Visual Prolog 9 Upgrade Notes]]

[[Category:Release Notes|10 Upgrade Notes]]

Getting Started

2026-01-26T12:02:50Z

Thomas Linder Puls: PDC is on com domain

== Tutorials ==

No matter what prerequisites you have, it is a good idea to read the [[:Category:Tutorials|tutorials]].

The tutorials in the [[Fundamental Visual Prolog]] section describe differences between Visual Prolog and traditional Prolog, and introduce a program that is developed in Visual Prolog.

Other tutorials discuss the [[Ide/Environment Overview|Visual Prolog Integrated Environment]] (IDE) and various Visual Prolog language features.

== Video Tutorials ==

* [http://www.visual-prolog.com/video/HelloWorld/default.htm Hello World! Video Tutorial] covers basic IDE functionality
* [http://www.visual-prolog.com/video/IntelliSpeed/default.htm IntelliSpeed Video Tutorial] demonstrates the context sensitive keyboard accelerator and browse system.

== Online Help System ==

Once you are familiar with the concepts and principles, you also can use reference material from the following sections of the Help system:

*The [[Language Reference]] that describes the syntax and semantics of the Visual Prolog language.
*Integrated Development Environment (IDE) Help.
*Prolog Foundation Classes (PFC) reference documentation.

This Help is reference material rather than tutorial, meaning that it is not a good place to learn Visual Prolog, but it is a very good place to seek answers to specific questions.

The Help system is available from the Integrated Development Environment.

== Discussion forum ==

You are also welcome to join Visual Prolog discussion forum and seek assistance or share your knowledge in the [https://discuss.visual-prolog.com Visual Prolog Discussion forums].

You will find a lot of interesting information in the [https://discuss.visual-prolog.com/viewforum.php?f=3 Visual Prolog Tips, How To's, Code Samples, etc]. And, of course, you are also invited to contribute your own tips, etc.

== Examples ==

You can download a number of [http://www.visual-prolog.com/link/demo.php demo examples] for Visual Prolog.

Notice that the Microsoft Edge browser may say that the download is not safe, which is not true. Click on the three dots and choose "Keep".

== PDC ==

Visual Prolog is made by the company PDC. We invite you to visit the [https://www.pdc.com PDC homepage] to find descriptions of real-world commercial projects written entirely in Visual Prolog for:

* Staff Planning
* Hospital Booking
* Airport Decision Support
* Airline Decision Support
* Shop Floor Scheduling

We hope, you will enjoy Visual Prolog!

[[Category:Basic Information]]

Getting Started

2026-01-26T11:59:48Z

Thomas Linder Puls: Download examples

== Tutorials ==

No matter what prerequisites you have, it is a good idea to read the [[:Category:Tutorials|tutorials]].

The tutorials in the [[Fundamental Visual Prolog]] section describe differences between Visual Prolog and traditional Prolog, and introduce a program that is developed in Visual Prolog.

Other tutorials discuss the [[Ide/Environment Overview|Visual Prolog Integrated Environment]] (IDE) and various Visual Prolog language features.

== Video Tutorials ==

* [http://www.visual-prolog.com/video/HelloWorld/default.htm Hello World! Video Tutorial] covers basic IDE functionality
* [http://www.visual-prolog.com/video/IntelliSpeed/default.htm IntelliSpeed Video Tutorial] demonstrates the context sensitive keyboard accelerator and browse system.

== Online Help System ==

Once you are familiar with the concepts and principles, you also can use reference material from the following sections of the Help system:

*The [[Language Reference]] that describes the syntax and semantics of the Visual Prolog language.
*Integrated Development Environment (IDE) Help.
*Prolog Foundation Classes (PFC) reference documentation.

This Help is reference material rather than tutorial, meaning that it is not a good place to learn Visual Prolog, but it is a very good place to seek answers to specific questions.

The Help system is available from the Integrated Development Environment.

== Discussion forum ==

You are also welcome to join Visual Prolog discussion forum and seek assistance or share your knowledge in the [https://discuss.visual-prolog.com Visual Prolog Discussion forums].

You will find a lot of interesting information in the [https://discuss.visual-prolog.com/viewforum.php?f=3 Visual Prolog Tips, How To's, Code Samples, etc]. And, of course, you are also invited to contribute your own tips, etc.

== Examples ==

You can download a number of [http://www.visual-prolog.com/link/demo.php demo examples] for Visual Prolog.

Notice that the Microsoft Edge browser may say that the download is not safe, which is not true. Click on the three dots and choose "Keep".

== PDC ==

Visual Prolog is made by the company PDC. We invite you to visit the [https://www.pdc.dk PDC homepage] to find descriptions of real-world commercial projects written entirely in Visual Prolog for:

* Staff Planning
* Hospital Booking
* Airport Decision Support
* Airline Decision Support
* Shop Floor Scheduling

We hope, you will enjoy Visual Prolog!

[[Category:Basic Information]]

Lists and Recursion

2025-10-06T13:10:33Z

Thomas Linder Puls: format bug

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 <vp>1</vp>, <vp>2</vp>, and <vp>3</vp> 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 <vp>[1, 2, 3]</vp> is different from the list <vp>[1, 3, 2]</vp>.

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>

== Lists Domains ==

It <vp>T</vp> is a type/domain then <vp>T*</vp> is the domain of lists containing <vp>T</vp> elements. I.e. an asterisk after a domain means "List of that domain".

The elements in a list can be anything, including other lists. However, all elements in a list must belong to the '''''same''''' domain.

== 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 (<vp>[]</vp>).

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="50" 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>implement main

clauses
run() :-
write_a_list([1, 2, 3]).

class predicates
write_a_list : (integer* List).
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 main

goal
console::runUtf8(main::run).</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 <vp>write_a_list</vp> predicate is called from <vp>run</vp> clause:

<vip>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>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>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>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 an empty list, <vp>[]</vp>, is <vp>0</vp>.<br />
*The length of any other list is the length of its tail plus <vp>1</vp>.

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

<vip>class main

predicates
length_of : (A* List) -> integer Length.

end class

implement main

clauses
length_of([]) = 0.
length_of([_ | T]) = Length :-
TailLength = length_of(T),
Length = TailLength + 1.

end implement main

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

Take a look at the second clause first. Crucially, <vp>[_ | T]</vp> will match any nonempty list, binding <vp>T</vp> 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>Length = main::length_of([1, 2, 3])</vip>

will match the second clause, with <vp>T</vp> = <vp>[2, 3]</vp>. The next step is to compute the length of <vp>T</vp>. When this is done (never mind how), <vp>TailLength</vp> will get the value <vp>2</vp>, and the computer can then add <vp>1</vp> to it and bind <vp>Length</vp> to <vp>3</vp>.

So how is the middle step executed? That step was to find the length of <vp>[2, 3]</vp> by satisfying the goal

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

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

*<vp>[3]</vp> in the goal to <vp>T</vp> in the clause and
*<vp>TailLength</vp> in the goal to <vp>Length</vp> in the clause.

Recall that <vp>TailLength</vp> in the goal will not interfere with <vp>TailLength</vp> 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 <vp>[3]</vp>, which will be <vp>1</vp>, and then add <vp>1</vp> to that to get the length of <vp>[2, 3]</vp>, which will be <vp>2</vp>. So far, so good.

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

This time it's easy. The goal:

<vip>TailLength = main::length_of([])</vip>

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

Confused yet? We hope not. In the following brief illustration we'll summarize the calls. We've used suffixes 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>Length_1 = main::length_of([1, 2, 3]).
TailLength_1 = main::length_of([2, 3]).
TailLength_2 = main::length_of([3]).
TailLength_3 = main::length_of([]).
TailLength_3 = 0.
Length_3 = TailLength_3 + 1 = 1.
Length_2 = Length_3 + 1 = 2.
Length_1 = Length_2 + 1 = 3.</vip>

Notice that the code above can be written more compact without the use of intermediate variables like this:

<vip>
clauses
length_of([]) = 0.
length_of([_ | T]) = length_of(T) + 1.
</vip>

These clauses more or less directly states the original specification:

*The length of an empty list, <vp>[]</vp>, is <vp>0</vp>.<br />
*The length of any other list is the length of its tail plus <vp>1</vp>.

===Tail Recursion===

You probably noticed that <vp>length_of</vp> 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 <vp>length_of</vp> 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 two arguments.

* The first is the list, which the computer will whittle away on each call until it eventually becomes empty, just as before.
* The second is an counter that starts out as <vp>0</vp> and increments on each call.

When the list is finally empty, you'll return the counter as the list length.

<vip>class main

predicates
length_of : (A* List, integer Counter) -> integer Result.

end class

implement main

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

end implement main

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

This version of the <vp>length_of</vp> 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 main

predicates
add1 : (integer* NumberList) -> integer* IncrList.

end class

implement main

clauses
add1([]) = []. % boundary condition
add1([Head | Tail]) = Result :-
% separate the head from the rest of the list
Head1 = Head + 1, % add 1 to the first element
Tail1 = add1(Tail), % call element with the rest of the list
Result = [Head1 | Tail1]. % Put the new head infront of the new tail

end implement main

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

To paraphrase this in natural language:

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

Runnig the the predicate with <vp>[1, 2, 3, 4]</vp>:

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

Will result in

<code>NewList = [2, 3, 4, 5]</code>

=== Tail Recursion Again ===

Is <vp>add1</vp> 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 <vp>Head</vp> and <vp>Tail</vp>.
*Add <vp>1</vp> to <vp>Head</vp>, giving <vp>Head1</vp>.
*Recursively add 1 to all the elements of <vp>Tail</vp>, giving <vp>Tail1</vp>.
*Combine <vp>Head1</vp> and <vp>Tail1</vp>, 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, <vp>add1</vp> is tail-recursive, because its steps are really the following:

*Bind the head and tail of the original list to <vp>Head</vp> and <vp>Tail</vp>.
*Bind the head and tail of <vp>Result</vp> to <vp>Head1</vp> and <vp>Tail1</vp>. (<vp>Head1</vp> and <vp>Tail1</vp> do not have values yet.)
*Add <vp>1</vp> to <vp>Head</vp>, giving <vp>Head1</vp>.
*Recursively add <vp>1</vp> to all the elements of <vp>Tail</vp>, giving <vp>Tail1</vp>.

When this is done, <vp>Head1</vp> and <vp>Tail1</vp> are ''already'' the head and tail of <vp>Result</vp>; 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 main

predicates
discard_negatives : (integer*, integer* [out]).

end class

implement main

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 main

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

For example, the goal

<vip>main::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>clauses
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 program below, 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>main::isMember("john", ["john", "leonard", "eric", "frank"])</vip>

is satisfied.

<vip>class main

predicates
isMember : (A, A*) determ.

end class

implement main

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

end implement main

goal
console::init(),
main::isMember("john", ["john", "leonard", "eric", "frank"]),
!,
stdio::write("Success")
or
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<br />
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 program works in two ways. Consider its clauses once again:

<vip>clauses
isMember(Name, [Name | _]) :-
!.
isMember(Name, [_ | Tail]) :-
isMember(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;<br />
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;<br />
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.

This program uses list comprehension to print the average age of a group of people.

<vip>class main

domains
name = string.
address = string.
age = integer.

predicates
person : (name Name [out], address Address [out], age Age [out]) multi.
sumlist : (age* AgeList, age Age [out], integer Count [out]).

end class

implement main

clauses
sumlist([], 0, 0).
sumlist([H | T], Sum, N) :-
sumlist(T, S1, N1),
Sum = H + S1,
N = 1 + N1.

clauses
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 main

goal
console::init(),
L = [Age || main::person(_, _, Age)],
main::sumlist(L, Sum, N),
Average = Sum / N,
stdio::writef("Average = %.", Average).</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 || main::person(Who, _, 42)]</vip>

The following code will create the list of positive items:

<vip>List = [X || X in [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
list = elem*.
elem = l(list List); i(integer Integer); c(char Char); s(string 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 main

domains
list = elem*.
elem = l(list List); i(integer Integer); c(char Char); s(string String).

predicates
test : ().

end class

implement main

class predicates
append : (A*, A*, A* [out]).
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 main

goal
console::init(),
main::test().
</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>/*******************************************
* 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 lexer

/*******************************************
* 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 in 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
[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]]

Lists and Recursion

2025-10-06T13:09:25Z

Thomas Linder Puls: add goal

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 <vp>1</vp>, <vp>2</vp>, and <vp>3</vp> 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 <vp>[1, 2, 3]</vp> is different from the list <vp>[1, 3, 2]</vp>.

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>

== Lists Domains ==

It <vp>T</vp> is a type/domain then <vp>T*</vp> is the domain of lists containing <vp>T</vp> elements. I.e. an asterisk after a domain means "List of that domain".

The elements in a list can be anything, including other lists. However, all elements in a list must belong to the '''''same''''' domain.

== 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 (<vp>[]</vp>).

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="50" 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>implement main

clauses
run() :-
write_a_list([1, 2, 3]).

class predicates
write_a_list : (integer* List).
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 main

goal
console::runUtf8(main::run).</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 <vp>write_a_list</vp> predicate is called from <vp>run</vp> clause:

<vip>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>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>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>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 an empty list, <vp>[]</vp>, is <vp>0</vp>.<br />
*The length of any other list is the length of its tail plus <vp>1</vp>.

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

<vip>class main

predicates
length_of : (A* List) -> integer Length.

end class

implement main

clauses
length_of([]) = 0.
length_of([_ | T]) = Length :-
TailLength = length_of(T),
Length = TailLength + 1.

end implement main

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

Take a look at the second clause first. Crucially, <vp>[_ | T]</vp> will match any nonempty list, binding <vp>T</vp> 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>Length = main::length_of([1, 2, 3])</vip>

will match the second clause, with <vp>T</vp> = <vp>[2, 3]</vp>. The next step is to compute the length of <vp>T</vp>. When this is done (never mind how), <vp>TailLength</vp> will get the value <vp>2</vp>, and the computer can then add <vp>1</vp> to it and bind <vp>Length</vp> to <vp>3</vp>.

So how is the middle step executed? That step was to find the length of <vp>[2, 3]</vp> by satisfying the goal

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

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

*<vp>[3]</vp> in the goal to <vp>T</vp> in the clause and
*<vp>TailLength</vp> in the goal to <vp>Length</vp> in the clause.

Recall that <vp>TailLength</vp> in the goal will not interfere with <vp>TailLength</vp> 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 <vp>[3]</vp>, which will be <vp>1</vp>, and then add <vp>1</vp> to that to get the length of <vp>[2, 3]</vp>, which will be <vp>2</vp>. So far, so good.

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

This time it's easy. The goal:

<vip>TailLength = main::length_of([])</vip>

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

Confused yet? We hope not. In the following brief illustration we'll summarize the calls. We've used suffixes 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>Length_1 = main::length_of([1, 2, 3]).
TailLength_1 = main::length_of([2, 3]).
TailLength_2 = main::length_of([3]).
TailLength_3 = main::length_of([]).
TailLength_3 = 0.
Length_3 = TailLength_3 + 1 = 1.
Length_2 = Length_3 + 1 = 2.
Length_1 = Length_2 + 1 = 3.</vip>

Notice that the code above can be written more compact without the use of intermediate variables like this:

<vip>
clauses
length_of([]) = 0.
length_of([_ | T]) = length_of(T) + 1.
</vip>

These clauses more or less directly states the original specification:

*The length of an empty list, <vp>[]</vp>, is <vp>0</vp>.<br />
*The length of any other list is the length of its tail plus <vp>1</vp>.

===Tail Recursion===

You probably noticed that <vp>length_of</vp> 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 <vp>length_of</vp> 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 two arguments.

* The first is the list, which the computer will whittle away on each call until it eventually becomes empty, just as before.
* The second is an counter that starts out as <vp>0</vp> and increments on each call.

When the list is finally empty, you'll return the counter as the list length.

<vip>class main

predicates
length_of : (A* List, integer Counter) -> integer Result.

end class

implement main

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

end implement main

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

This version of the <vp>length_of</vp> 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 main

predicates
add1 : (integer* NumberList) -> integer* IncrList.

end class

implement main

clauses
add1([]) = []. % boundary condition
add1([Head | Tail]) = Result :-
% separate the head from the rest of the list
Head1 = Head + 1, % add 1 to the first element
Tail1 = add1(Tail), % call element with the rest of the list
Result = [Head1 | Tail1]. % Put the new head infront of the new tail

end implement main

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

To paraphrase this in natural language:

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

Runnig the the predicate with <vp>[1, 2, 3, 4]</vp>:

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

Will result in

<code>NewList = [2, 3, 4, 5]</code>

=== Tail Recursion Again ===

Is <vp>add1</vp> 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 <vp>Head</vp> and <vp>Tail</vp>.
*Add <vp>1</vp> to <vp>Head</vp>, giving <vp>Head1</vp>.
*Recursively add 1 to all the elements of <vp>Tail</vp>, giving <vp>Tail1</vp>.
*Combine <vp>Head1</vp> and <vp>Tail1</vp>, 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, <vp>add1</vp> is tail-recursive, because its steps are really the following:

*Bind the head and tail of the original list to <vp>Head</vp> and <vp>Tail</vp>.
*Bind the head and tail of <vp>Result</vp> to <vp>Head1</vp> and <vp>Tail1</vp>. (<vp>Head1</vp> and <vp>Tail1</vp> do not have values yet.)
*Add <vp>1</vp> to <vp>Head</vp>, giving <vp>Head1</vp>.
*Recursively add <vp>1</vp> to all the elements of <vp>Tail</vp>, giving <vp>Tail1</vp>.

When this is done, <vp>Head1</vp> and <vp>Tail1</vp> are ''already'' the head and tail of <vp>Result</vp>; 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 main

predicates
discard_negatives : (integer*, integer* [out]).

end class

implement main

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 main

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

For example, the goal

<vip>main::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>clauses
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 program below, 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>main::isMember("john", ["john", "leonard", "eric", "frank"])</vip>

is satisfied.

<vip>class main

predicates
isMember : (A, A*) determ.

end class

implement main

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

end implement main

goal
console::init(),
main::isMember("john", ["john", "leonard", "eric", "frank"]),
!,
stdio::write("Success")
or
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<br />
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 program works in two ways. Consider its clauses once again:

<vip>clauses
isMember(Name, [Name | _]) :-
!.
isMember(Name, [_ | Tail]) :-
isMember(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;<br />
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;<br />
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.

This program uses list comprehension to print the average age of a group of people.

<vip>class main

domains
name = string.
address = string.
age = integer.

predicates
person : (name Name [out], address Address [out], age Age [out]) multi.
sumlist : (age* AgeList, age Age [out], integer Count [out]).

end class

implement main

clauses
sumlist([], 0, 0).
sumlist([H | T], Sum, N) :-
sumlist(T, S1, N1),
Sum = H + S1,
N = 1 + N1.

clauses
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 main

goal
console::init(),
L = [Age || main::person(_, _, Age)],
main::sumlist(L, Sum, N),
Average = Sum / N,
stdio::writef("Average = %.", Average).</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 || main::person(Who, _, 42)]</vip>

The following code will create the list of positive items:

<vip>List = [X || X in [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
list = elem*.
elem = l(list List); i(integer Integer); c(char Char); s(string 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 main

domains
list = elem*.
elem = l(list List); i(integer Integer); c(char Char); s(string String).

predicates
test : ().

end class

implement main

class predicates
append : (A*, A*, A* [out]).
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 main</vip>

goal
console::init(),
main::test().

== 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>/*******************************************
* 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 lexer

/*******************************************
* 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 in 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
[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]]

Language Reference/Terms/Anonymous Predicates

2025-08-22T11:05:54Z

Thomas Linder Puls: Review

==== Anonymous Predicates ====

An anonymous predicate is an expression that evaluates to a predicate value. The value can be bound to a variable, passed as an argument, or returned as a result, but it has no name in any class, interface, or implementation.

Anonymous predicates have the ability to capture values from the context in which the expression occurs; this is a powerful ability that can be used to avoid a rather excessive amount of strange/unpleasant code.

===== Syntax =====

Anonymous predicates are terms:

<vipbnf><Term> : one of
...
<AnonymousPredicate>
...</vipbnf>

An anonymous predicate is a nameless clause in curly brackets. Certain parts are optional, giving these forms:

<vipbnf><AnonymousPredicate> : one of
{ ( <Arg>-comma-sep-list ) = <Term> }
{ ( <Arg>-comma-sep-list ) = <Term> :- <Term> }
{ ( <Arg>-comma-sep-list ) :- <Term> }
{ = <Term> }
{ = <Term> :- <Term> }
{ :- <Term> }</vipbnf>

Leaving out the argument list means "the required number of arguments" and can be used whenever the arguments are not used inside the predicate expression.

===== Semantics =====

An anonymous predicate expression evaluates to a predicate value.
Consider this code:

<vip>clauses
run() :-
Inc = { (X) = X+1 },
A = Inc(4),
B = Inc(23),
stdio::writef("A = %, B = %", A, B).</vip>

Inc becomes an increment predicate, so the program will write:

<source lang="text">A = 5, B = 24</source>

The code in this example corresponds to this code:

<vip>clauses
run() :-
Inc = inc,
A = Inc(4),
B = Inc(23),
stdio::writef("A = %, B = %", A, B).

class predicates
inc : (integer X) -> integer R.
clauses
inc(X) = X+1.</vip>

Where the clause <vp>(X) = X+1</vp> can be found in the last line; i.e., this time in a named predicate.

Variables that are bound outside (i.e., before the occurrence of) an anonymous predicate can be used inside the anonymous predicate. The value of the variable will be captured by the anonymous predicate.

Variables that are bound in an anonymous predicate are local variables in the anonymous predicate.

===== Capturing context =====

An anonymous predicate can capture context, which means that it can refer to things that are defined in its context, especially facts and variables from the clause.

===== Capturing variables =====

An anonymous predicate occurs in a clause, and this clause may contain variables. Those variables that are bound before the anonymous predicate is met can be used inside the anonymous predicate.
This code illustrates how a variable is captured:

<vip>domains
pred = (integer) -> integer.

class predicates
createAdder : (integer A) -> pred Adder.
clauses
createAdder(A) = { (X) = X+A }.

clauses
run() :-
Add17 = createAdder(17),
A = Add17(4),
B = Add17(20),
stdio::writef("A = %, B = %", A, B).</vip>

We call <vp>createAdder</vp> with <vp>17</vp> as argument. So in the <vp>createAdder</vp> clause <vp>A</vp> is <vp>17</vp>, and therefore the result is <vp>{ (X) = X+17 }</vp>. We say that the anonymous predicate has captured the variable <vp>A</vp>.

Since <vp>Add17</vp> is a predicate that adds <vp>17</vp> to its argument, the output of the code will be:

<source lang="text">A = 21, B = 37</source>

===== Capturing ellipsis (...) =====

An anonymous predicate can capture the ellipsis variable (i.e., <vp>...</vp>):

<vip>clauses
ppp(...) :-
W = { () :- stdio::write(...) },
qqq(W).</vip>

<vp>W</vp> captures the ellipsis variable. <vp>qqq</vp> receives a nullary predicate; when this predicate is invoked the captured ellipsis variable will be written to the standard output device.

===== Capturing facts =====

An anonymous predicate can access facts. If it is created by a class predicate it can access class facts. If it is created by an object predicate it can access both object and class facts.
Consider this code that captures a class fact:

<vip>class facts
count : integer := 0.
clauses
seq() = { () = count :- count := count+1 }.
clauses
run() :-
A = seq(),
B = seq(),
stdio::writef("A1 = %, ", A()),
stdio::writef("B1 = %, ", B()),
stdio::writef("A2 = %, ", A()),
stdio::writef("B2 = %", B()).</vip>

Both <vp>A</vp> and <vp>B</vp> increment the class fact <vp>count</vp>, so the result is:

<source lang="text">A1 = 1, B1 = 2, A2 = 3, B2 = 4</source>

In object predicates we can capture object facts. So assuming that <vp>seq</vp> is an object predicate in <vp>myClass</vp>, this code illustrates the capture of an object fact:

<vip>facts
count : integer := 0.
clauses
seq() = { () = count :- count := count+1 }.
clauses
run() :-
A = myClass::new():seq(),
B = myClass::new():seq(),
stdio::writef("A1 = %, ", A()),
stdio::writef("B1 = %, ", B()),
stdio::writef("A2 = %, ", A()),
stdio::writef("B2 = %", B()).</vip>

In this case <vp>A</vp> and <vp>B</vp> come from two different objects, which each have a <vp>count</vp> fact, so the output will be:

<source lang="text">A1 = 1, B1 = 1, A2 = 2, B2 = 2</source>

Technically, the class version actually does not capture anything; it merely has access to the fact. Likewise, the object version does not actually capture the fact; instead it captures <vp>This</vp> and through <vp>This</vp> it obtains access to the object facts.

===== Capturing This =====

As described above it is possible to capture <vp>This</vp> and thereby gain access to object facts. The same mechanism gives access to calling object predicates.

<vip>clauses
seq() = { () = count :- inc() }.

clauses
inc() :- count := count+1.</vip>

<vp>This</vp> can also be used directly:

<vip>clauses
ppp() = { () = aaa::rrr(This) }.</vip>

===== Nesting =====

Anonymous predicates can be nested:

<vip>clauses
run() :-
P = { (A) = { (B) = A+B } },
Q = P(3300),
R = P(2200),
stdio::writef("Q(11) = %, ", Q(11)),
stdio::writef("R(11) = %", R(11)).</vip>

To obtain <vp>Q</vp> we call <vp>P</vp> with <vp>3300</vp>, so <vp>A</vp> is <vp>3300</vp> and <vp>Q</vp> therefore becomes <vp>{ (B) = 3300+B }</vp>; likewise <vp>R</vp> becomes <vp>{ (B) = 2200+B }</vp>. So the output is:

<source lang="text">Q(11) = 3311, R(11) = 2211</source>

===== Syntactic Sugar =====

If you do not need the arguments they can be skipped.
So this code fragment:

<vip>
P = { (_) :- succeed },
Q = { (_, _) = 0 },
R = { (_, _, _) = _ :- fail }.
</vip>

can be shortened to:

<vip>
P = { :- succeed },
Q = { = 0 },
R = { = _ :- fail }.
</vip>

Notice that the arguments are completely skipped. If you write <vp>()</vp> it means zero arguments, whereas skipping the arguments means "a suitable amount" of arguments.

==== Examples of practical usage ====

The examples assume that the PFC scopes <vp>core</vp>, <vp>std</vp>, <vp>stdio</vp>, <vp>list</vp> and <vp>string</vp> are open.

===== Dummy predicates =====

Anonymous predicates are good for creating dummy predicate values:

<vip>
ppp( { = true } ), % do not filter (boolean)
qqq( { :- succeed } ), % do not filter (determ)
rrr( { = 17 } ). % all rows must have height 17
</vip>

===== Adaptation =====

In cases where you need a predicate and have one that is almost suitable, you can make the adaptation using an anonymous predicate.

====== Index adaptation ======

Consider the predicate write3:

<vip>class predicates
write3 : (function{integer, string} Indexer).
clauses
write3(Indexer) :-
foreach I = std::fromTo(0,2) do
write(Indexer(I), "\n")
end foreach.</vip>

Indexer implements an "array" of strings; <vp>write3</vp> will write the three strings found at the indexes <vp>0</vp>, <vp>1</vp> and <vp>2</vp>. So <vp>write3</vp> assumes that the "array" index is zero-based.

However, the "array" we have uses a one-based index:

<vip>class predicates
myArray : (integer N) -> string Value.
clauses
myArray(1) = "First" :- !.
myArray(2) = "Second" :- !.
myArray(3) = "Third" :- !.
myArray(_) = _ :-
raiseError().</vip>

Using an anonymous predicate we can easily adapt the one-based array to the zero-based usage:

<vip>% myArray is 1-based, write3 requires 0-based
Arr = { (N) = myArray(N+1) },
write3(Arr).</vip>

So we get the expected output:

<source lang="text">First
Second
Third</source>

====== Parameter adaptation ======

In this code <vp>listChildren</vp> will call a <vp>ChildWriter</vp> predicate for each "C is the child of P"-pair:

<vip>class predicates
listChildren :
(predicate{string,string} ChildWriter).
clauses
listChildren(CW) :-
CW("Son1", "Father"),
CW("Son2", "Father").</vip>

We will however prefer to list the "P is the parent of C" using the predicate <vp>wParent</vp>:

<vip>class predicates
wParent : (string Parent, string Child).
clauses
wParent(P, C) :-
writef("% is the parent of %\n", P, C).</vip>

<vp>wParent</vp> takes the arguments in the opposite order, but we can easily adapt using an anonymous predicate:

<vip>Swap = { (A,B) :- wParent(B,A) },
listChildren(Swap).</vip>

And then the output becomes the expected:

<source lang="text">Father is the parent of Son1
Father is the parent of Son2</source>

We can also throw away arguments, for example when calling this predicate that only needs a <vp>Child</vp>:

<vip>class predicates
wKnowParent : (string Child).
clauses
wKnowParent(C) :-
writef("We know a parent of %\n", C).</vip>

The adaptation looks like this:

<vip>Fewer = { (C,P) :- wKnowParent(C) },
listChildren(Fewer).</vip>

The output will be:

<source lang="text">We know a parent of Son1
We know a parent of Son2</source>

We can also supply dummy arguments:

<vip>More = { (_,P) :- addChildren(P, 1) },
listChildren(More).</vip>

Here <vp>addChildren</vp> will "add a count of children to P". Since each invocation corresponds to one child we will call <vp>addChildren</vp> supplying <vp>1</vp> as a "dummy" argument. The <vp>More</vp> is thus an adaptor that both throws away an argument and supplies a dummy argument.

===== Filters =====

Assume this predicate:

<vip>class predicates
writeFiltered :
(string L, predicate_dt{integer} Filter).
clauses
writeFiltered(Label, Filter) :-
List = [1,2,3,4,5,6,7,8,9],
FilteredList = filter(List, Filter),
writef("%\t%\n", Label, FilteredList).</vip>

<vp>Filter</vp> is used to filter the list <vp>[1,2,3,4,5,6,7,8,9]</vp>; the filtered list and the <vp>Label</vp> are written to the standard output.

First we use the allow-all filter:

<vip>All = { :- succeed },
writeFiltered("All", All).</vip>

This filter simply succeeds for any element, so the output is the entire list:

<source lang="text">All [1,2,3,4,5,6,7,8,9]</source>

It is just as easy to create a filter that fails for all elements and thus allow-none:

<vip>None = { :- fail },
writeFiltered("None", None).</vip>

The output from this is the empty list:

<source lang="text">None []</source>

We can also create filters for elements greater than <vp>3</vp> and elements divisible by <vp>3</vp>:

<vip>GreaterThan3 = { (X) :- X > 3 },
writeFiltered("> 3", GreaterThan3),
Rem3 = { (X) :- 0 = X rem 3 },
writeFiltered("Rem3", Rem3).</vip>

The output from this is:

<source lang="text">> 3 [4,5,6,7,8,9]
Rem3 [3,6,9]</source>

===== Sorting =====

The list package has a sort predicate. But sometimes the default order is not what you need. Therefore the list package also has a predicate <vp>sortBy</vp>, which sorts the elements using a programmer-defined compare operation.
Let us first consider string sorting, using this predicate:

<vip>class predicates
writeStringsSorted :
(string Label, comparator{string} Comp).
clauses
writeStringsSorted(Label, C) :-
List = ["John Wayne", "Uma Thurman",
"Harrison Ford", "Nicolas Cage",
"Elizabeth Taylor", "Cary Grant",
"Jerry Lewis", "Robert De Niro"],
Sorted = sortBy(C, List),
write(Label, "\n"),
foreach S = list::getMember_nd(Sorted) do
writef(" %\n", S)
end foreach.</vip>

We can call the predicate with the "normal" comparator, and using an anonymous predicate we can easily sort it descending as well:

<vip>Normal = compare,
writeStringsSorted("Normal", Normal),
Descending = { (A,B) = compare(B,A) },
writeStringsSorted("Descending", Descending).</vip>

The output looks like this:

<source lang="text">Normal
Cary Grant
Elizabeth Taylor
Harrison Ford
Jerry Lewis
John Wayne
Nicolas Cage
Robert De Niro
Uma Thurman
Descending
Uma Thurman
Robert De Niro
Nicolas Cage
John Wayne
Jerry Lewis
Harrison Ford
Elizabeth Taylor
Cary Grant</source>

Let us also sort some more complex elements. Here a person has a first name and a last name, using this domain:

<vip>domains
person = p(string First, string Last).</vip>

For the demonstration we will use this test predicate:

<vip>class predicates
writePersonsSorted :
(string Label, comparator{person} Comparator).
clauses
writePersonsSorted(Label, C) :-
List = [p("John","Wayne"),
p("Uma","Thurman"),
p("Harrison","Ford"),
p("Nicolas","Cage"),
p("Elizabeth","Taylor"),
p("Cary","Grant"),
p("Jerry","Lewis"),
p("Robert","De Niro")],
Sorted = sortBy(C, List),
write(Label, "\n"),
foreach p(F,L) = list::getMember_nd(Sorted) do
writef(" % %\n", F, L)
end foreach.</vip>

Again we can sort using the normal and a descending comparator:

<vip>Normal = compare,
writePersonsSorted("Normal", Normal),
Descending = { (A,B) = compare(B,A) },
writePersonsSorted("Descending", Descending).</vip>

Since the <vp>compare</vp> predicate uses left-to-right lexicographic order on the <vp>p</vp>-functor, the result is the same as before:

<source lang="text">Normal
Cary Grant
Elizabeth Taylor
Harrison Ford
Jerry Lewis
John Wayne
Nicolas Cage
Robert De Niro
Uma Thurman
Descending
Uma Thurman
Robert De Niro
Nicolas Cage
John Wayne
Jerry Lewis
Harrison Ford
Elizabeth Taylor
Cary Grant</source>

But with the more complex domain we can create a comparator that will sort on last name:

<vip>LN = { (p(_,L1), p(_, L2)) = compare(L1,L2) },
writePersonsSorted("LastName", LN).</vip>

The result is what we expect:

<source lang="text">LastName
Nicolas Cage
Robert De Niro
Harrison Ford
Cary Grant
Jerry Lewis
Elizabeth Taylor
Uma Thurman
John Wayne</source>

===== Capturing context (threads & callbacks) =====

As mentioned a very powerful feature of anonymous predicates is the ability to capture context. The examples in this section show some ways you can use this.

====== Background threads ======

The routine for starting a thread takes a nullary predicate and runs it in the new thread. But you nearly always need to pass some input data to the job in the new thread.
This is possible in several ways, but the absolutely simplest way is to use anonymous predicates.
The project <vp>bgDemo</vp> from the Visual Prolog example collection (that can be installed from the IDE) uses this method.
The project has a form that can start a background job and display status information from the job in a <vp>jobControl</vp> that is added to the form.
A background job is a predicate that will receive a <vp>jobLog</vp>, which it can use to report status and completion degree:

<vip>domains
job = (jobLog Log).</vip>

A <vp>jobLog</vp> looks like this:

<vip>interface jobLog

properties
completion : real (i).

properties
status : string (i).

end interface jobLog</vip>

The job can report completion degree by setting the <vp>completion</vp> property (range <vp>0</vp> to <vp>1</vp>). Likewise, the <vp>status</vp> property can be used to reflect the current status of the job.

The status and completion will be shown in the form together with a job name.
A job is started by calling the form's <vp>addJob</vp> predicate:

<vip>clauses
addJob(JobName, Job) :-
JobCtrl = jobControl::new(This),
JobCtrl:name := JobName,
JobCtrl:show(),
assert(jobCtrl_fact(JobCtrl)),
arrange(),
JobLog = jobLog::new(JobCtrl),
Action = { :- Job(JobLog) },
_ = thread::start(Action).</vip>

In this context it is the last three lines that are interesting. <vp>thread::start</vp> takes a nullary predicate as argument, but a job is a predicate that takes a <vp>jobLog</vp> as argument. Therefore we create an anonymous predicate <vp>Action</vp>, which takes no arguments but invokes <vp>Job</vp> on the <vp>JobLog</vp>. The anonymous predicate has captured both <vp>Job</vp> and <vp>JobLog</vp> from the context, and subsequently both these values are transferred to the new thread even though this thread only receives a nullary predicate.

The jobs in the <vp>bgDemo</vp> project are merely dummy jobs that only manipulate their <vp>jobLog</vp>. One of them looks like this:

<vip>clauses
job(Log, From, To) :-
Log:status := "Step 1",
foreach N1 = std::fromTo(From, To) do
Log:completion :=
(N1-From) / (To-From) / 2,
programControl::sleep(3)
end foreach,
Log:status := "Step 2",
foreach N2 = std::fromTo(From, To) do
Log:completion :=
(N2-From) / (To-From) / 2 + 0.5,
programControl::sleep(3)
end foreach,
Log:status := "finished".</vip>

It has two loops which run from <vp>From</vp> to <vp>To</vp> and calculates the completion and sets it on the <vp>Log</vp>. It also sets the status text before, between and after the loops.

You may notice that the job does not have the proper job type, because a proper job only has one argument (the <vp>jobLog</vp>); this job has three arguments.
Again it is anonymous predicates that help us. The code that adds the jobs to the form looks like this:

<vip>predicates
onFileNew : window::menuItemListener.
clauses
onFileNew(_Source, _MenuTag) :-
JF = jobForm::display(This),
Job11 = {(L) :- job1::job(L, 1, 1000)},
Job12 = {(L) :- job1::job(L, 200, 600)},
Job13 = {(L) :- job1::job(L, 1200, 3000)},
Job14 = {(L) :- job1::job(L, 1, 1000)},
JF:addJob("job1.1", Job11),
JF:addJob("job1.2", Job12),
JF:addJob("job1.3", Job13),
JF:addJob("job1.4", Job14),
...</vip>

In a more realistic program, it is most likely that <vp>From</vp> and <vp>To</vp> would not be constants, but rather parameters passed from some outer place. In that case these anonymous predicates would also capture variables from the context.

The <vp>jobLog</vp> in the <vp>bgDemo</vp> illustrates one more usage of anonymous predicates. The <vp>jobLog</vp> passes the completion and the status information to a <vp>jobControl</vp>. The <vp>jobControl</vp> is a GUI control on the <vp>jobForm</vp> capable of doing a suitable rendering of the information. This however gives a synchronization problem, because GUI controls are not thread safe and here we want to update some controls from a background thread. This can lead to conflicts, because it is the main thread that draws the controls.

The solution is to transfer the update of the control to the GUI thread. We do this by posting actions to the control.
The implementation of the status update looks like this:

<vip>clauses
status(Status) :-
Action = { :- jobCtrl:status := Status },
jobCtrl:postAction(Action).</vip>

<vp>Action</vp> is a nullary predicate that will set the status in the <vp>jobCtrl</vp>. We post this action to the <vp>jobCtrl</vp>. When the <vp>jobCtrl</vp> receives the action it invokes it and is thus updated. This way, the actual update of the control will be performed by the GUI thread.
This anonymous predicate not only captures the <vp>Status</vp> variable it also captures the <vp>jobCtrl</vp> fact.

====== Asynchronous callbacks ======

Assume that we send commands to a remote service. The command execution is asynchronous, so when we execute a command we also give a callback action which will be invoked when the execution of the command is finished. To execute a command we must call this predicate:

<vip>predicates
executeCommand :
(command Cmd, predicate{} OnDone).</vip>

Based on this predicate we want to create a similar predicate that can execute a list of commands. A certain command should be executed when the previous command completes.
We will also make our list executor asynchronous, so we supply an action that will be invoked when the entire script of commands is finished.
Our script executor will have the form:

<vip>predicates
executeScript :
(command* Script, predicate{} OnDone).</vip>

If the script is empty we simply invoke the <vp>OnDone</vp> action.
If the script has a command <vp>H</vp> and a rest script <vp>T</vp>, we must first execute <vp>H</vp>, and when it is finished we must execute the rest of the script <vp>T</vp>. So the <vp>OnDone</vp> action we supply when executing <vp>H</vp> must execute <vp>T</vp>.
All in all, the implementation can look like this:

<vip>clauses
executeScript([], OnDone) :-
OnDone().
executeScript([H|T], OnDone) :-
DoneH = { :- executeScript(T, OnDone) },
executeCommand(H, DoneH).</vip>

We have used an anonymous predicate to perform the execution of the rest of the script. This anonymous predicate captures <vp>T</vp> and <vp>OnDone</vp>.

<noinclude>{{LanguageReferenceSubarticle|Terms/Anonymous Predicates}}</noinclude>

Language Reference/Built-in entities/Domains

2025-08-21T09:13:05Z

Thomas Linder Puls: string8 literals

{|{{prettytable}}
|-
|[[#any|any]]
|Universal term type
|-
|[[#char|char]]
|Unicode character (16-bit)
|-
|[[#string|string]]
|UTF-16 zero-terminated string
|-
|[[#string8|string8]]
|Zero-terminated 8-bit string typically in UTF-8 encoding
|-
|[[#symbol|symbol]]
|Interned UTF-16 string (global symbol table)
|-
|[[#binary|binary]]
|Byte sequence (non-scanned)
|-
|[[#binaryNonAtomic|binaryNonAtomic]]
|Byte sequence (GC-scanned; may contain pointers)
|-
|[[#integer|integer]]
|32-bit signed integer
|-
|[[#integer64|integer64]]
|64-bit signed integer
|-
|[[#integerNative|integerNative]]
|Platform-sized signed integer (32/64-bit)
|-
|[[#unsigned|unsigned]]
|32-bit unsigned integer
|-
|[[#unsigned64|unsigned64]]
|64-bit unsigned integer
|-
|[[#unsignedNative|unsignedNative]]
|Platform-sized unsigned integer (32/64-bit)
|-
|[[#real|real]]
|Floating-point number (64-bit)
|-
|[[#real32|real32]]
|Floating-point number (32-bit)
|-
|[[#pointer|pointer]]
|Pointer value
|-
|[[#pointerTo|pointerTo]]
|Pointer to a value of a given type
|-
|[[#handle|handle]]
|Operating system handle (e.g., Windows)
|-
|[[#boolean|boolean]]
|Boolean values
|-
|[[#factDB|factDB]]
|Descriptor of a named internal database
|-
|[[#compareResult|compareResult]]
|Result of a comparison
|}

==== any ====

Universal term type.

<vip>any</vip>

Values of this domain can hold any term. Such a value contains a reference to the type library of the term and the term itself.

==== char ====

Unicode character.

<vip>char</vip>

Values of this domain are Unicode characters implemented as two unsigned bytes.

Only assignment and comparison (lexicographical) are defined. The image of a character has the following syntax:

<vipbnf><Char_image> :
' Char_value '
<Char_value> :
<Letter>
<Digit>
<Graphical_symbol>
<Escape_seq>
<Escape_seq>:
\t
\n
\r
\\
\'
\"
\u<HHHH></vipbnf>

In the syntax above <vpbnf><HHHH></vpbnf> corresponds to four hexadecimal digits. The backslash and single quote can only be represented by escape sequences.

==== compareResult ====

The result domain for comparisons (e.g., {{lang2|Built-in entities|compare|compare/2->}}).

<vip>domains
compareResult = less; equal; greater.
</vip>

==== string ====

UTF-16 strings.

<vip>string</vip>

A string is a pointer to a zero-terminated sequence of UTF-16 code units. Elements are 16-bit values; certain characters are encoded using surrogate pairs. Strings are immutable.

In source code a string literal is one or more parts surrounded by double quotes:

<vipbnf><StringLiteral>:
<StringLiteralPart>-list</vipbnf>

<vipbnf><StringLiteralPart> :
@" AnyCharacter-list-opt "
" CharacterValue-list-opt "</vipbnf>

Parts starting with <vp>@</vp> do not use escape sequences; parts without <vp>@</vp> use the following escapes:

* <vp>\\</vp> representing <vp>\</vp>
* <vp>\t</vp> representing a tab character
* <vp>\n</vp> representing a newline character
* <vp>\r</vp> representing a carriage return
* <vp>\'</vp> representing a single quote
* <vp>\"</vp> representing a double quote
* <vp>\u</vp> followed by exactly four <vpbnf><HexadecimalDigit></vpbnf> values representing the Unicode character

Double quotes in strings must be written using the escape sequence (single quotes may be written directly or escaped).

==== string8 ====

A built-in domain whose elements are sequences of one-byte characters (bytes). Implemented as a pointer to a zero-terminated array of bytes.

'''Literals.''' The same string literal syntax (`"..."`) can be used both as a <vp>string</vp> literal and as a <vp>string8</vp> literal, depending on context:
* When a <vp>string8</vp> value is expected, the literal is compiled as UTF-8 bytes with a trailing zero
* When a <vp>string</vp> value is expected, the literal is compiled as UTF-16 code units with a trailing zero

If the context is ambiguous, disambiguate by using a typed context (e.g., a predicate parameter of type <vp>string8</vp>) or by explicit conversion.

{{Example|
<vip>
predicates
use8 : (string8 S8).
use16 : (string S).

clauses
demo() :-
use8("Hello"), % literal used as string8 (UTF-8)
use16("Hello"). % the same literal used as string (UTF-16)
</vip>
}}

==== symbol ====

UTF-16 strings with the same representation as <vp>string</vp>, but also stored in a global symbol table.

<vip>symbol</vip>

A <vp>symbol</vp> is interned in a global symbol table; identical symbols share the same pointer value. Symbols are never reclaimed, so they should not be used for large, short-lived text.

<vp>symbol</vp> is a subtype of <vp>string</vp>, so a symbol can be used wherever a string is expected. The opposite is not automatic; to obtain a symbol from a string, explicitly <vp>convert</vp> to the symbol domain (or a subtype).

Equality is efficient for <vp>symbol</vp> values (pointer equality). Other comparisons behave like the corresponding <vp>string</vp> operations.

==== binary ====

Sequence of bytes.

<vip>binary</vip>

Used for holding binary data. A value is a pointer to the byte sequence that represents the contents of the binary term.

The length of a binary term is stored in the four bytes immediately preceding the sequence:

<vip>TotalNumberOfBytesOccupiedByBinary = ByteLen + 4</vip>

where <vp>ByteLen</vp> is the length of the sequence and <vp>4</vp> is the size field.

Only assignment and comparison are defined.

Two binaries are compared as follows:

* If sizes differ, the larger size is greater
* Otherwise, compare bytes (as unsigned) until a difference is found; equal if sizes match and all bytes are equal

The text syntax for binary images is determined by <vpbnf><Binary></vpbnf>:

<vipbnf><Binary> :
$ [ <Byte_value>-comma-sep-list-opt ]
<Byte_value> :
<Expression></vipbnf>

Each expression must be computable at compile time and have a value in the range <vp>0</vp>.. <vp>255</vp>.

==== binaryNonAtomic ====

Sequence of bytes.

<vip>binaryNonAtomic</vip>

Same as [[#binary|binary]], but may contain pointers and is scanned by the garbage collector.

==== integer ====

32-bit signed integer.

<vip>integer</vip>

Values occupy 4 bytes. Arithmetic (<vp>+</vp>, <vp>-</vp>, <vp>/</vp>, <vp>*</vp>, <vp>^</vp>), comparison, assignment, {{lang2|Built-in entities|Operators|div/2->}}, {{lang2|Built-in entities|Operators|mod/2->}}, {{lang2|Built-in entities|Operators|quot/2->}}, and {{lang2|Built-in entities|Operators|rem/2->}} are defined.

Range: <vp>-2147483648</vp> .. <vp>2147483647</vp>.

Literals follow <vpbnf><Integer></vpbnf>:

<vipbnf><Integer> :
<Add_operation>-opt 0o <Oct_number>
<Add_operation>-opt <Dec_number>
<Add_operation>-opt 0x <Hex_number>
<Add_operation> :
+
-
<Oct_number> :
<Oct_digit>-list
<Oct_digit> : one of
0 1 2 3 4 5 6 7
<Dec_number> :
<Dec_digit>-list
<Dec_digit> : one of
<Oct_digit> 8 9
<Hex_number> :
<Hex_digit>-list
<Hex_digit> : one of
<Dec_digit> a b c d e f A B C D E F</vipbnf>

==== integer64 ====

64-bit signed integer.

<vip>integer64</vip>

Values occupy 8 bytes.

Range: <vp>-2^63 = -9223372036854775808</vp> .. <vp>2^63-1 = 9223372036854775807</vp>.

Literals use the same syntax as <vpbnf><Integer></vpbnf>. The available operations mirror those for <vpbnf><Integer></vpbnf>.

==== integerNative ====

Platform-sized signed integer (32-bit in 32-bit programs; 64-bit in 64-bit programs).

<vip>integerNative</vip>

==== unsigned ====

32-bit unsigned integer.

<vip>unsigned</vip>

Values occupy 4 bytes. Arithmetic (<vp>+</vp>, <vp>-</vp>, <vp>/</vp>, <vp>*</vp>, <vp>^</vp>), comparison, assignment, {{lang2|Built-in entities|Operators|div/2->}}, {{lang2|Built-in entities|Operators|mod/2->}}, {{lang2|Built-in entities|Operators|rem/2->}}, and {{lang2|Built-in entities|Operators|quot/2->}} are defined.

Range: <vp>0</vp> .. <vp>4294967295</vp>.

Literals use the same syntax as <vp>integer</vp> numbers. A leading minus (<vpbnf><UnaryMinus></vpbnf>) is not allowed for an <vp>unsigned</vp> literal.

==== unsigned64 ====

64-bit unsigned integer.

<vip>unsigned64</vip>

Values occupy 8 bytes.

Range: <vp>0</vp> .. <vp>2^64-1 = 18,446,744,073,709,551,615</vp>.

Literals use the same syntax as <vp>integer64</vp> numbers. A leading minus (<vpbnf><UnaryMinus></vpbnf>) is not allowed for an <vp>unsigned64</vp> literal.

Operations mirror those for <vpbnf><Unsigned></vpbnf>.

==== unsignedNative ====

Platform-sized unsigned integer (32-bit in 32-bit programs; 64-bit in 64-bit programs).

<vip>unsignedNative</vip>

==== real ====

Floating-point number.

<vip>real</vip>

Values occupy 8 bytes. All arithmetic, comparison, and assignment operations are defined.

Range: approximately <vp>-1.7e+308</vp> .. <vp>1.7e+308</vp>. Integral values are implicitly converted to <vp>real</vp> when needed.

Floating-point literals follow <vpbnf><Real></vpbnf>:

<vipbnf><Real> :
<Add_operation>-opt <Fraction> <Exponent>-opt
<Fraction> :
<Dec_number> <Fractional_part>-opt
<Fractional_part> :
. <Dec_number>
<Exponent> :
<Exp> <Add_operation>-opt <Dec_number>
<Exp> :
e
E
<Add_operation> :
+
-
<Dec_number> :
<Dec_digit>-list
<Dec_digit> : one of
0 1 2 3 4 5 6 7 8 9</vipbnf>

==== real32 ====

Floating-point number.

<vip>real32</vip>

Values occupy 4 bytes. All arithmetic, comparison, and assignment operations are defined.

Range: approximately <vp>-3.4e+38</vp> .. <vp>3.4e+38</vp>.

The syntax of <vp>real32</vp> literals is the same as for <vp>real</vp> literals.

==== pointer ====

A pointer to a memory address.

<vip>pointer</vip>

Corresponds directly to memory addresses. Only equality comparison is defined. There is a built-in '''null''' constant for this type.

==== pointerTo ====

<vp>pointerTo{Type}</vp> represents a pointer to a value of type <vp>Type</vp>. Conceptually (it is built-in), it can be viewed as:

<vip>domains
pointerTo{Type} = pointerTo(Type Value).</vip>

==== handle ====

Used for Windows API calls. Values have the same size as a pointer (4 bytes on 32-bit, 8 bytes on 64-bit platforms).

No operations are defined for this domain, and values cannot be converted to/from other domains (except via <vp>uncheckedConvert</vp>).

There are built-in constants: [[#nullHandle|nullHandle]] and [[#invalidHandle|invalidHandle]].

==== boolean ====

Boolean values.

<vip>boolean</vip>

This domain is provided for convenience and is treated as a normal compound domain:

<vip>domains
boolean = false; true.</vip>

==== factDB ====

Descriptors of named internal databases.

<vip>factDB</vip>

This domain has the following hidden meta-declaration:

<vip>domains
factDB = struct @factdb( named_internal_database_domain, object ).</vip>

All user-defined names of facts sections are constants of this domain. The compiler automatically builds the corresponding compound terms when needed. At runtime, the first field holds the address of the corresponding domain descriptor, and the second holds either zero (for class facts sections) or a pointer to an object (e.g., <vp>This</vp> for object facts sections).
<noinclude>{{LanguageReferenceSubarticle|Built-in entities/Domains}}</noinclude>

Language Reference/Built-in entities/Constants

2025-08-20T13:34:27Z

Thomas Linder Puls: Review

{|{{prettytable}}
|-
|[[#compilation_date|compilation_date]]
|Compilation date
|-
|[[#compilation_time|compilation_time]]
|Compilation time
|-
|[[#compiler_buildDate|compiler_buildDate]]
|Build date of the compiler
|-
|[[#compiler_version|compiler_version]]
|Compiler version number
|-
|[[#maxFloatDigits|maxFloatDigits]]
|Maximum supported <vp>digits</vp> for <vp>real</vp> domains
|-
|[[#null|null]]
|The default NULL pointer
|-
|[[#nullHandle|nullHandle]]
|A constant of type handle with value 0
|-
|[[#invalidHandle|invalidHandle]]
|A constant of type handle with value −1 (invalid)
|-
|[[#platform_bits|platform_bits]]
|Bitness of the compilation platform (32 or 64)
|-
|[[#platform_name|platform_name]]
|Target platform name
|}

==== compilation_date ====

Compilation date in the format ''YYYY-MM-DD''.

<vip>compilation_date : string = "YYYY-MM-DD".</vip>

==== compilation_time ====

Compilation time in the format ''HH:MM:SS'' (24-hour clock).

<vip>compilation_time : string = "HH:MM:SS".</vip>

==== compiler_buildDate ====

Build date of the compiler in the format ''YYYY-MM-DD HH:MM''.

<vip>compiler_buildDate : string = "YYYY-MM-DD HH:MM".</vip>

==== compiler_version ====

Compiler version number (value depends on the compiler).

<vip>compiler_version = 1100.</vip>

==== maxFloatDigits ====

Maximum supported value of <vp>digits</vp> for <vp>real</vp> domains.

<vip>maxFloatDigits = 16.</vip>

==== null ====

A constant of type <vp>pointer</vp> with the value <vp>0</vp>.

<vip>null : pointer = uncheckedConvert(pointer, 0).</vip>

<vp>null</vp> is also implicitly defined on all interfaces as a null pointer of the interface type. If it were defined '''explicitly''', it would look like this:

<vip>
interface xxx
...
constants
null : xxx = uncheckedConvert(xxx, null). % already implicitly defined
...
end interface xxx
</vip>

{{Example|This example shows how the constant can be used in a clause.
<vip>
interface xxx
end interface xxx

...
clauses
isNullXxx(X) :-
xxx::null = X.
</vip>
}}

==== nullHandle ====

A constant of type <vp>handle</vp> with the value <vp>0</vp>.

<vip>nullHandle : handle = uncheckedConvert(handle, 0).</vip>

==== invalidHandle ====

A constant of type <vp>handle</vp> with the value <vp>-1</vp> (invalid for a handle).

<vip>invalidHandle : handle = uncheckedConvert(handle, -1).</vip>

==== platform_bits ====

Bitness of the compilation platform.

<vip>platform_bits = 32.
or
platform_bits = 64.</vip>

==== platform_name ====

Target platform name.

<vip>platform_name : string = "Windows 32bits".
or
platform_name : string = "Windows 64bits".</vip>
<noinclude>{{LanguageReferenceSubarticle|Built-in entities/Constants}}</noinclude>

Language Reference/Basic Concepts/Scoping and Visibility

2025-08-20T13:19:16Z

Thomas Linder Puls: review

==== Name Categories ====

All names (identifiers) in Visual Prolog are syntactically divided into two major groups:

* Constant names (starting with a lowercase letter)
* Variable names (starting with an uppercase letter or an underscore)

Constant names (identifiers) are divided into the following categories:

* Type names (i.e., domains and interfaces)
* Domain carriers (i.e., classes and interfaces)
* Names without parentheses (i.e., constants, fact variables of non-function type, and nullary-functors)
* Value-returning names of arity N (i.e., functions, functors, and fact variables of function type)
* Non-value-returning names of arity N (i.e., predicates, facts, and fact variables of predicate type)

Visual Prolog requires that names do not conflict at the point of declaration; otherwise, conflicts cannot be resolved at the point of use. Declarations can only conflict if they are in the same scope, because scope qualification can resolve conflicts. A name in one category can never conflict with a name in another category, but a single declaration can place a name in several categories.

==== Packages ====

Packages are the basic units of code organization in Visual Prolog. They group related interfaces and classes.

Each declaration or implementation of an interface or class in a package is placed in a separate file. Each filename matches the interface or class that it declares or implements. All package files are stored in the package directory; subpackages are stored in subdirectories of that directory.

Packages can act as class libraries. You can include packages in your program instead of placing all used interfaces and classes directly in the program.

How packages are structured and included in projects is described in the IDE documentation (see '''Creating a Package''' in '''Creating New Project Items''').

==== Visibility, Shadowing, and Qualification ====

Most scoping rules were introduced above; this section completes the picture.

An interface definition, a class declaration, and a class implementation are scopes (scopes cannot be nested). An implementation (privately) extends the scope of the corresponding class declaration. Visibility is the same '''everywhere''' in a scope; i.e., '''no matter where''' something is declared in the scope, it is visible in the '''whole''' scope.

Public names from supported interfaces and super-classes are directly (i.e., without qualification) available inside a scope when their origin is unambiguous. It is illegal to use a name whose origin is ambiguous. Ambiguities in predicate calls can be removed by qualifying the predicate name with the class name (e.g., <vp>cc::p</vp>).

This qualification is also used to qualify calls to object member predicates of super-classes on the ''current'' object.

Visual Prolog has the following shadowing hierarchy:

* Local
* Opened scopes and super-classes

Opened scopes have the same status as super-classes. Local declarations shadow declarations in opened scopes. If two or more opened scopes contain conflicting declarations, you can only access them by using qualification.

{{Example|Assume the interface <vp>ixx</vp> and the classes <vp>aa</vp> and <vp>bb</vp>:
<vip>
interface ixx

predicates
p1 : ().
p2 : ().
p3 : ().

end interface ixx

%========================

class aa : ixx
end class aa

%========================

class bb

predicates
p3 : ().
p4 : ().
p5 : ().

end class bb
</vip>

The class <vp>aa</vp> creates objects of type <vp>ixx</vp>, whereas the class <vp>bb</vp> does not create objects at all.

In this context consider the implementation of a class <vp>cc</vp>:

<vip>
implement cc inherits aa
open bb

clauses
p2(). % reimplementation of ixx::p2

predicates
p5 : ().
clauses
p5().

clauses
new() :-
p1(), % aa::p1
p2(), % cc::p2 (shadows aa::p2)
aa::p2(), % aa::p2
p3(), % Illegal ambiguous call: aa::p3 or bb::p3
aa::p3(), % aa::p3
bb::p3(), % bb::p3
p4(), % bb::p4
p5(). % cc::p5 (shadows bb::p5)

end implement cc
</vip>
Since <vp>cc</vp> inherits <vp>aa</vp>, all predicates in the interface <vp>ixx</vp> are visible in <vp>cc</vp>. Likewise, the <vp>open bb</vp> directive makes all predicates in <vp>bb</vp> visible in <vp>cc</vp>.}}
<noinclude>{{LanguageReferenceSubarticle|Basic Concepts/Scoping & Visibility}}</noinclude>

Language Reference/Basic Concepts/Object System

2025-08-20T12:26:53Z

Thomas Linder Puls: review

==== External View ====

This section clarifies the class-related notions in Visual Prolog at a conceptual level. It does not discuss syntax or implementation details.

The class concept in Visual Prolog is based on three semantic entities:
* objects
* interfaces
* classes

===== Object =====

An ''object'' is a set of named ''object member predicates'' together with a set of ''supported'' interfaces. Objects also have state, but this state can only be observed and changed through member predicates; the state is therefore ''encapsulated'' in the object.

===== Interface =====

An ''interface'' is an object type. It has a name and defines a set of named object predicates.

Interfaces form a ''supports'' hierarchy (a [[wikipedia:semilattice|semi-lattice]]) rooted at the <vp>object</vp> interface. If an object has a type denoted by some interface, it also has the types of all supported interfaces. Thus the supports hierarchy is a type hierarchy: an interface is a subtype of each interface it supports.

===== Class =====

A ''class'' is a named object factory; it constructs objects that correspond to a given interface. If a class constructs objects of interface <vp>iii</vp>, then its objects are "<vp>iii</vp> objects". All objects constructed by the same class share the same definitions of the object member predicates, but each object has its own state; the predicate definitions belong to the class, while the state belongs to each object.

The set of object member predicates a class ''defines'' is the '''union''' of the predicates ''declared'' (transitively) in its interfaces. If the same predicate is declared in multiple interfaces, the class provides '''one''' common definition; this is only valid if the intended semantics coincide. Interface support must be specified explicitly.

===== Module =====

A class need not construct objects. A class without a construction type acts as a module: it may have only class members and class state.

===== Identity =====

Every object is unique. Even if two objects currently have identical state, they are not identical: one can be changed without affecting the other. We never access object state directly; we access it through references, and many references may denote the same object. Classes and interfaces are also unique and identified by name (with namespace); duplicate names are not allowed within a program. Structural equality does '''not''' imply identity for objects, classes, or interfaces.

==== Internal View ====

This section complements the external view with internal aspects: how declarations and implementations are organized. From a programmatic point of view, classes are central (they contain the code). Interfaces have mainly static importance and have no direct runtime representation; objects are dynamic and exist only when the program runs.

A class has a declaration and an implementation. The declaration states the ''public'' accessible parts of the class and of the objects it constructs; the implementation ''defines'' what the declaration introduces (predicates are implemented by clauses, by inheritance, or resolved to external libraries). A class declaration is purely declarative.

An implementation can declare additional private entities (domains, predicates, etc.). Object state is stored as facts in the implementation; such facts are per-object, while ''class'' facts are shared across all objects of the class. Facts are declared only in implementations and are not directly accessible from outside. Implementations may also (privately) support more interfaces than stated in the declaration.

===== Code Inheritance =====

Code inheritance occurs only in class implementations. Visual Prolog supports multiple inheritance via an ''inherits'' section in the implementation. The classes you inherit from are ''parent'' (''super'') classes; the inheriting class is the ''child'' (''sub'') class. A child class can only access its parent classes through their public interfaces; it receives no special privileges.

<noinclude>{{LanguageReferenceSubarticle|Basic Concepts/Object System}}</noinclude>

Language Reference/Basic Concepts/Types and Subtypes

2025-08-20T08:47:13Z

Thomas Linder Puls: Review

==== Types ====

Visual Prolog types are divided into object types and value types. Objects
have mutable state, whereas values are immutable.

Object types are defined by interface definitions.

The value types include {{lang2|Domains|Integral_Domains|numerical types}}, {{lang2|Built-in_entities|string|strings}}, {{lang2|Built-in_entities|char|character types}}, and {{lang2|Domains|Compound_Domains|compound domains}} (also known as algebraic data types). Simpler forms
of compound domains are structure and enumeration types, whereas more
complex forms represent tree structures.

==== Subtypes ====

Types are organized in a subtype hierarchy. Subtypes provide subsumption polymorphism: any context that expects a value of some type will also accept a value of any subtype. Equivalently, values of a given type are implicitly converted to any super-type where needed; no explicit cast is required.

Subtypes can be derived from any value type, except from algebraic data types. Types derived from algebraic data types are synonym types rather than subtypes (i.e., they denote the same type).

The notion of subtypes relates to the notion of subsets. However, even if a type is "mathematically" a subset of another type, it is not a subtype unless declared as such.

<vip>domains
t1 = [1..17].
t2 = [5..13].
t3 = t1 [5..13].</vip>

<vp>t1</vp> is an integral type whose values are the integers from <vp>1</vp> to <vp>17</vp> (inclusive). Likewise, <vp>t2</vp> contains the values from <vp>5</vp> to <vp>13</vp>. So <vp>t2</vp> is a subset of <vp>t1</vp>, but <vp>t2</vp> is '''not''' a subtype of <vp>t1</vp>. By contrast, <vp>t3</vp> (which contains the same values as <vp>t2</vp>) is a subtype of <vp>t1</vp>, because it is declared to be so.

The language contains a few implicit subtype relations; otherwise, subtype relations are stated explicitly in type definitions.

Object types are organized in a subtype hierarchy rooted in the predefined object type <vp>object</vp>, i.e., any object type is a subtype of <vp>object</vp>. Object subtypes are formed by stating that one interface <vp>supports</vp> another. If an object has an interface/object type that <vp>supports</vp> another interface, the object also has that type and can be used as such without further changes.

See also: {{lang2|Domains|Universal_and_Root_Types|Universal and Root Types}}
<noinclude>{{LanguageReferenceSubarticle|Basic Concepts/Types and Subtypes}}</noinclude>

Language Reference/Basic Concepts/Scoping and Visibility

2025-08-19T15:10:15Z

Thomas Linder Puls: Header level

==== Name Categories ====

All names (identifiers) in Visual Prolog are syntactically divided into two major groups:

*Constant names (starting with a lowercase letter)
*Variable names (starting with an uppercase letter or an underscore)

Constant names (identifiers) are divided into the following categories:

* Type names (i.e. domains and interfaces).
* Domain carriers (i.e. classes and interfaces).
* Names without parentheses (i.e. constants, fact variables of non-function type and nullary-functors).
* Value returning names of arity N (i.e. functions, functors and fact-variables of function type).
* Non-value-returning names of arity N (i.e. predicates, facts and fact variables of predicate type).

Visual Prolog demands that names do not conflict at the point of declaration, because then it would be impossible to solve the conflict at point of usage. Declarations can only conflict if they are in the same scope, because qualification with scope can be used to solve the conflict. A name in one category can never be in conflict with a name in another category, but as we shall see a single declaration might place a name in several categories.

==== Packages ====

The basic units of code organization accepted in Visual Prolog are packages. We use packages in Visual Prolog to organize and structuring things. The use of packages ensures homogeneity in structuring principles among different projects. Packages define the standard for tool structuring and ease sharing source code among projects.

The package is a collection of several grouped together interfaces and classes. The package provides some common name to all these interfaces and classes. Each declaration or implementation of each interface or class from a package is placed in a separate file. Each filename (of these files) coincides with the name of a class or an interface that is declared or implemented in this file. All package files are stored in the same separate package directory. (If a package contains sub-packages, then they are placed in subdirectories of the package directory.)

The concept of packages is used for grouping together several linked interfaces and classes. Packages can play a role of some class library. Packages can be used in your program instead of direct placing all used interfaces and classes into your program.

The accepted in Visual Prolog structure of packages and how packages should be included into projects are described in the VDE part of this help. (See '''Creating a Package''' in '''Creating New Project Items'''.)

==== Visibility, Shadowing, and Qualification ====

Most of the scoping rules are already mentioned above. This section will complete the picture.

An interface definition, a class declaration and a class implementation are scopes (scopes cannot be nested). An implementation (privately) extends the scope of the corresponding class declaration. The visibility is the same '''everywhere''' in a scope. This does especially mean that '''no matter where''' in a scope something is declared, it is visible in the '''whole''' scope.

Public names from supported interfaces and super-classes are directly (i.e. without qualification) available inside a scope, if it is unambiguous where they come from. It is illegal to use a name whose origin is ambiguous. All ambiguities in predicate calls can be removed by qualifying the predicate name with the class name (e.g. <vp>cc::p</vp>).

This qualification is also used to qualify calls of object member predicates of super-classes on the ''current'' object.

Visual Prolog has the following shadowing hierarchy:

* Local
* Super-class & opened scopes

Opened scopes have the same status as super-classes, so in the sequel we will just say super-classes.

The hierarchy means that a local declaration will shadow a super-class declaration. But there is no shadowing between super-classes; all super-classes have equal preference. If two or more super classes contain conflicting declarations then these declarations can only be accessed by means of qualification.

{{Example|Assume the interface <vp>ixx</vp> and the classes <vp>aa</vp> and <vp>bb</vp>:
<vip>
interface ixx

predicates
p1 : ().
p2 : ().
p3 : ().

end interface ixx

%========================

class aa : ixx
end class aa

%========================

class bb

predicates
p3 : ().
p4 : ().
p5 : ().

end class bb
</vip>

The class <vp>aa</vp> creates objects of type <vp>ixx</vp>, whereas the class <vp>bb</vp> does not create objects at all.

In this context consider the implementation of a class <vp>cc</vp>:

<vip>
implement cc inherits aa
open bb

clauses
p2(). % reimplementation of ixx::p2

predicates
p5 : ().
clauses
p5().

clauses
new() :-
p1(), % aa::p1
p2(), % cc::p2 (shadows aa::p2)
aa::p2(), % aa::p2
p3(), % Illegal ambiguous call: aa::p3 or bb::p3
aa::p3(), % aa::p3
bb::p3(), % bb::p3
p4(), % bb::p4
p5(). % cc::p5 (shadows bb::p5)

end implement cc
</vip>
Since <vp>cc</vp> inherits <vp>aa</vp> all the predicates in the interface <vp>ixx</vp> are also visible in <vp>cc</vp>. Likewise the <vp>open bb</vp> qualification will make all predicates in <vp>bb</vp> visible in <vp>cc</vp>.}}
<noinclude>{{LanguageReferenceSubarticle|Basic Concepts/Scoping & Visibility}}</noinclude>

Language Reference/Basic Concepts/Scoping and Visibility

2025-08-19T15:09:56Z

Thomas Linder Puls: Header level

==== Name Categories ====

All names (identifiers) in Visual Prolog are syntactically divided into two major groups:

*Constant names (starting with a lowercase letter)
*Variable names (starting with an uppercase letter or an underscore)

Constant names (identifiers) are divided into the following categories:

* Type names (i.e. domains and interfaces).
* Domain carriers (i.e. classes and interfaces).
* Names without parentheses (i.e. constants, fact variables of non-function type and nullary-functors).
* Value returning names of arity N (i.e. functions, functors and fact-variables of function type).
* Non-value-returning names of arity N (i.e. predicates, facts and fact variables of predicate type).

Visual Prolog demands that names do not conflict at the point of declaration, because then it would be impossible to solve the conflict at point of usage. Declarations can only conflict if they are in the same scope, because qualification with scope can be used to solve the conflict. A name in one category can never be in conflict with a name in another category, but as we shall see a single declaration might place a name in several categories.

==== Packages ====

The basic units of code organization accepted in Visual Prolog are packages. We use packages in Visual Prolog to organize and structuring things. The use of packages ensures homogeneity in structuring principles among different projects. Packages define the standard for tool structuring and ease sharing source code among projects.

The package is a collection of several grouped together interfaces and classes. The package provides some common name to all these interfaces and classes. Each declaration or implementation of each interface or class from a package is placed in a separate file. Each filename (of these files) coincides with the name of a class or an interface that is declared or implemented in this file. All package files are stored in the same separate package directory. (If a package contains sub-packages, then they are placed in subdirectories of the package directory.)

The concept of packages is used for grouping together several linked interfaces and classes. Packages can play a role of some class library. Packages can be used in your program instead of direct placing all used interfaces and classes into your program.

The accepted in Visual Prolog structure of packages and how packages should be included into projects are described in the VDE part of this help. (See '''Creating a Package''' in '''Creating New Project Items'''.)

===== Visibility, Shadowing, and Qualification =====

Most of the scoping rules are already mentioned above. This section will complete the picture.

An interface definition, a class declaration and a class implementation are scopes (scopes cannot be nested). An implementation (privately) extends the scope of the corresponding class declaration. The visibility is the same '''everywhere''' in a scope. This does especially mean that '''no matter where''' in a scope something is declared, it is visible in the '''whole''' scope.

Public names from supported interfaces and super-classes are directly (i.e. without qualification) available inside a scope, if it is unambiguous where they come from. It is illegal to use a name whose origin is ambiguous. All ambiguities in predicate calls can be removed by qualifying the predicate name with the class name (e.g. <vp>cc::p</vp>).

This qualification is also used to qualify calls of object member predicates of super-classes on the ''current'' object.

Visual Prolog has the following shadowing hierarchy:

* Local
* Super-class & opened scopes

Opened scopes have the same status as super-classes, so in the sequel we will just say super-classes.

The hierarchy means that a local declaration will shadow a super-class declaration. But there is no shadowing between super-classes; all super-classes have equal preference. If two or more super classes contain conflicting declarations then these declarations can only be accessed by means of qualification.

{{Example|Assume the interface <vp>ixx</vp> and the classes <vp>aa</vp> and <vp>bb</vp>:
<vip>
interface ixx

predicates
p1 : ().
p2 : ().
p3 : ().

end interface ixx

%========================

class aa : ixx
end class aa

%========================

class bb

predicates
p3 : ().
p4 : ().
p5 : ().

end class bb
</vip>

The class <vp>aa</vp> creates objects of type <vp>ixx</vp>, whereas the class <vp>bb</vp> does not create objects at all.

In this context consider the implementation of a class <vp>cc</vp>:

<vip>
implement cc inherits aa
open bb

clauses
p2(). % reimplementation of ixx::p2

predicates
p5 : ().
clauses
p5().

clauses
new() :-
p1(), % aa::p1
p2(), % cc::p2 (shadows aa::p2)
aa::p2(), % aa::p2
p3(), % Illegal ambiguous call: aa::p3 or bb::p3
aa::p3(), % aa::p3
bb::p3(), % bb::p3
p4(), % bb::p4
p5(). % cc::p5 (shadows bb::p5)

end implement cc
</vip>
Since <vp>cc</vp> inherits <vp>aa</vp> all the predicates in the interface <vp>ixx</vp> are also visible in <vp>cc</vp>. Likewise the <vp>open bb</vp> qualification will make all predicates in <vp>bb</vp> visible in <vp>cc</vp>.}}
<noinclude>{{LanguageReferenceSubarticle|Basic Concepts/Scoping & Visibility}}</noinclude>

Language Reference/Basic Concepts/Scoping and Visibility

2025-08-19T15:09:42Z

Thomas Linder Puls: Header level

==== Name Categories ====

All names (identifiers) in Visual Prolog are syntactically divided into two major groups:

*Constant names (starting with a lowercase letter)
*Variable names (starting with an uppercase letter or an underscore)

Constant names (identifiers) are divided into the following categories:

* Type names (i.e. domains and interfaces).
* Domain carriers (i.e. classes and interfaces).
* Names without parentheses (i.e. constants, fact variables of non-function type and nullary-functors).
* Value returning names of arity N (i.e. functions, functors and fact-variables of function type).
* Non-value-returning names of arity N (i.e. predicates, facts and fact variables of predicate type).

Visual Prolog demands that names do not conflict at the point of declaration, because then it would be impossible to solve the conflict at point of usage. Declarations can only conflict if they are in the same scope, because qualification with scope can be used to solve the conflict. A name in one category can never be in conflict with a name in another category, but as we shall see a single declaration might place a name in several categories.

===== Packages =====

The basic units of code organization accepted in Visual Prolog are packages. We use packages in Visual Prolog to organize and structuring things. The use of packages ensures homogeneity in structuring principles among different projects. Packages define the standard for tool structuring and ease sharing source code among projects.

The package is a collection of several grouped together interfaces and classes. The package provides some common name to all these interfaces and classes. Each declaration or implementation of each interface or class from a package is placed in a separate file. Each filename (of these files) coincides with the name of a class or an interface that is declared or implemented in this file. All package files are stored in the same separate package directory. (If a package contains sub-packages, then they are placed in subdirectories of the package directory.)

The concept of packages is used for grouping together several linked interfaces and classes. Packages can play a role of some class library. Packages can be used in your program instead of direct placing all used interfaces and classes into your program.

The accepted in Visual Prolog structure of packages and how packages should be included into projects are described in the VDE part of this help. (See '''Creating a Package''' in '''Creating New Project Items'''.)

===== Visibility, Shadowing, and Qualification =====

Most of the scoping rules are already mentioned above. This section will complete the picture.

An interface definition, a class declaration and a class implementation are scopes (scopes cannot be nested). An implementation (privately) extends the scope of the corresponding class declaration. The visibility is the same '''everywhere''' in a scope. This does especially mean that '''no matter where''' in a scope something is declared, it is visible in the '''whole''' scope.

Public names from supported interfaces and super-classes are directly (i.e. without qualification) available inside a scope, if it is unambiguous where they come from. It is illegal to use a name whose origin is ambiguous. All ambiguities in predicate calls can be removed by qualifying the predicate name with the class name (e.g. <vp>cc::p</vp>).

This qualification is also used to qualify calls of object member predicates of super-classes on the ''current'' object.

Visual Prolog has the following shadowing hierarchy:

* Local
* Super-class & opened scopes

Opened scopes have the same status as super-classes, so in the sequel we will just say super-classes.

The hierarchy means that a local declaration will shadow a super-class declaration. But there is no shadowing between super-classes; all super-classes have equal preference. If two or more super classes contain conflicting declarations then these declarations can only be accessed by means of qualification.

{{Example|Assume the interface <vp>ixx</vp> and the classes <vp>aa</vp> and <vp>bb</vp>:
<vip>
interface ixx

predicates
p1 : ().
p2 : ().
p3 : ().

end interface ixx

%========================

class aa : ixx
end class aa

%========================

class bb

predicates
p3 : ().
p4 : ().
p5 : ().

end class bb
</vip>

The class <vp>aa</vp> creates objects of type <vp>ixx</vp>, whereas the class <vp>bb</vp> does not create objects at all.

In this context consider the implementation of a class <vp>cc</vp>:

<vip>
implement cc inherits aa
open bb

clauses
p2(). % reimplementation of ixx::p2

predicates
p5 : ().
clauses
p5().

clauses
new() :-
p1(), % aa::p1
p2(), % cc::p2 (shadows aa::p2)
aa::p2(), % aa::p2
p3(), % Illegal ambiguous call: aa::p3 or bb::p3
aa::p3(), % aa::p3
bb::p3(), % bb::p3
p4(), % bb::p4
p5(). % cc::p5 (shadows bb::p5)

end implement cc
</vip>
Since <vp>cc</vp> inherits <vp>aa</vp> all the predicates in the interface <vp>ixx</vp> are also visible in <vp>cc</vp>. Likewise the <vp>open bb</vp> qualification will make all predicates in <vp>bb</vp> visible in <vp>cc</vp>.}}
<noinclude>{{LanguageReferenceSubarticle|Basic Concepts/Scoping & Visibility}}</noinclude>

Language Reference/Attributes

2025-08-19T15:08:25Z

Thomas Linder Puls: link

{{languageReferenceNavbar|Attributes}}

Various definitions and declarations can be annotated with attributes. This section describes the general syntax of attributes and where they can be placed. It also describes the meaning of the specific attributes.

=== Syntax ===

<vipbnf><Attributes> :
[ <Attribute>-comma-sep-list ]</vipbnf>

<vipbnf><Attribute> : one of
<LowerCaseIdentifier>
<LowerCaseIdentifier> ( <Literal>-comma-sep-list )</vipbnf>

where the literals must either be numbers or string literals.

=== Insertion Points ===

The attributes of interfaces, classes and implementations are right after the scope qualifications.

<vipbnf><InterfaceDeclaration> :
interface <IinterfaceName>
<ScopeQualifications>
<Attributes>-opt
<Sections>
end interface <IinterfaceName>-opt</vipbnf>

<vipbnf><ClassDeclaration> :
class <ClassName> <ConstructionType>-opt
<ScopeQualifications>
<Attributes>-opt
<Sections>
end class <ClassName>-opt</vipbnf>

<vipbnf><ClassImplementation> :
implement <ClassName>
<ScopeQualifications>
<Attributes>-opt
<Sections>
end implement <ClassName>-opt</vipbnf>

The attributes of constants, domains, predicates, properties and facts are at the end (i.e. right before the terminating dot).

<vipbnf><ConstantDefinition>: one of
<ConstantName> = <ConstantValue> <Attributes>-opt
<ConstantName> : <TypeName> = <ConstantValue> <Attributes>-opt</vipbnf>

<vipbnf><DomainDefinition>:
<DomainName> <FormalTypeParameterList>-opt = <TypeExpression> <Attributes>-opt</vipbnf>

<vipbnf><PredicateDeclaration> :
<PredicateName> : <PredicateDomain> <LinkName>-opt <Attributes>-opt
<PredicateName> : <PredicateDomainName> <LinkName>-opt <Attributes>-opt</vipbnf>

<vipbnf><PropertyDeclaration> :
<PropertyName> : <PropertyType> <FlowPattern>-list-opt <Attributes>-opt</vipbnf>

<vipbnf><FactDeclaration> :
<FactVariableDeclaration> <Attributes>-opt
<FactFunctorDeclaration> <Attributes>-opt</vipbnf>

The attributes of formal arguments are at the end.

<vipbnf><FormalArgument> :
<TypeExpression> <ArgumentName>-opt <Attributes>-opt</vipbnf>

=== Specific Attributes ===

==== attribute ====

This attribute is used on a functor domain to indicate that the functors in the domain can be used as attributes elsewhere in the program.
{{Example|
<vip>
domains
meta =
meta;
metaDisplayAs(string DisplayAs) [attribute].
</vip>
}}

See [[Program Defined Attributes]].

==== byVal ====

An argument is transferred directly on the stack rather than using a pointer. Valid for formal predicate arguments provided the <vp>language</vp> is <vp>stdcall</vp>, <vp>apicall</vp> or <vp>c</vp>.

{{Example|
<vip>
domains
point = point(integer X, integer Y).
predicates
externalP : (point Point [byVal]) language apicall.
</vip>}}

The attribute can also be used in combination with the <vp>out</vp> attribute:

{{Example|
<vip>
predicates
externalP2 : (point Point [byVal, out]) language apicall.
</vip>}}

In that case a <vp>point</vp> structure will be allocated before the call then a pointer to that structure is transferred handed to the external predicate which can then fill the structure with relevant data.

==== classInitializer ====

This attribute indicates that a predicate should be invoked as a class initializer. It can be applied to a class predicate that does not take any arguments. The predicate will be invoked when the initialization code invokes the <vp>runtime_api::runProgramInitialization</vp>. A class can have any number of class initializer which will be invoked in an undetermined order. Notice that other classes may not have been initialized.

The predicate <vp>xxx::initialize</vp> is registered as a class initializer:

<vip>
implement xxx

class predicates
initialize : () [classInitializer].
clauses
initialize() :-
…

end class xxx
</vip>

==== constant ====

The <vp>constant</vp> attribute is used to declare fact variables that cannot be changed once they have been initialized.

See {{lang2|Facts|Constant fact variable|Constant fact variable}}.

==== compiletimeSetting ====

The <vp>compiletimeSetting</vp> attribute indicates that a constant should be considered a compiletime setting. As a result the compiler will suppress warnings about always failing/succeding code and about unreachable code that may be caused by this constant. The warning suppession is an approximation, because it a may be impossible/difficult to determine the cause of a warning.

<vip>
implement xxx

constants
debugOutput : boolean = false [compiletimeSetting].

clauses
pppp(...) :-
...
if true = debugOutput then
% do not give a warning about unreachable code
log::write(...)
end if,
...

end implement xxx
</vip>

==== default ====

It is problematic to update functor domains, if terms have been persisted in serialized form. Because new programs cannot deal with old serializations.

The two attributes <vp>default/1</vp> and <vp>retiredFunctor/1</vp> can help dealing with this problem.

The last arguments of a functor can have default values:

<vip>
domains
ppp =
fct(
integer A,
real B,
ddd C,
integer* New [default([])],
real New2 [default(0)]
).
</vip>

The default attribute does not change anything within the program; it only affects the deserialization. If during deserialization we meet the closing parenthesis too soon we supply default values for the remaining arguments.

'''Notice''' that this will only work for '''text''' deserialization.

See also [[Functor Domain Versioning]].

==== deprecated ====

The declared entity is deprecated. The string literal describes how to migrate from it. The entity still exists, but usage will cause a warning.
The entity will not exist in future versions of Visual Prolog. Valid for member declarations and scopes.

{{Example|
<vip>predicates
oldFashioned : (string Arg) [deprecated("Use newFashion instead")].</vip>
}}

==== explicitTag ====

This predicate can be used on a functor domain to ensure that the memory representation of all terms have a functor. Without this attribute the compiler optimizes the representation such that some alternatives doesn't have a functor in the term, and such that functors with arguments are represented as a pointer value. The main purpose of this attribute is to ensure compatibility with foreign code.

{{Example|
<vip>domains
menu =
resMenu(resid Resid);
dynMenu(menuItem* SubMenu);
noMenu
[explicitTag].</vip>
}}

==== formatString ====

The argument is a format string for a subsequent ellipsis argument (i.e. <vp>...</vp>). Valid for one string argument of a predicate with an ellipsis argument. The use of <vp>formatString</vp> will make the compiler check the validity of actual arguments with respect to actual format strings (where possible).

{{Example|
<vip>predicates
writef : (string Format [formatString], ...).</vip>
}}

The format string can contain ordinary characters which are printed without modification, and format fields, that begins with the percent <vp>%</vp> sign. If the percent sign is followed by some unknown character (not the format specifier) - then this character will be printed without modifications. To output a <vp>%</vp> character you must write <vp>%%</vp> in the format string.

<vip>predicates
writef : (string Format [formatstring], ...).</vip>

The format fields specification is:

[-][0][width][.precision][type]

All fields are optional.

[-] Hyphen indicates that the field is to be left justified; right justified is the default. Having no effect when width value is not set, or the number of characters in the actual value is greater than width value.

[0] Zero before width means for values that zeros will be added until the minimum width is reached. If 0(zero) and -(hyphen) appear, the 0 is ignored

[width] Positive decimal number specifying a minimum field size. If the number of characters in the actual value is less than width value - then the required number of space ' ' characters will be added before the value (or after it, if '-' field was set). No changes occurs if number of characters in the actual value is greater than the width value.

[.precision] The point '.' with the following unsigned decimal number can specify either the precision of a floating-point image or the maximum number of characters to be printed from a string.

[type] Specifies other format then the default for the given. For example, in the type field, you can give a specifier that says an integer will be formatted as an unsigned. The possible values are:

:{|{{prettytable}}
|-
| f || Format real's in fixed-decimal notation (such as 123.4 or 0.004321). This is the default for real's.
|-
| e || Format real's in exponential notation (such as 1.234e+002 or 4.321e-003).
|-
| g || Format real's in the shortest of f and e format, but always in e format if exponent of the value is less than -4 or greater than or equal to the precision. Trailing zeros are truncated.
|-
| d or D || Format as a signed decimal number.
|-
| u or U || Format as an unsigned integer.
|-
| x or X || Format as a hexadecimal number.
|-
| o or O || Format as an octal number.
|-
| c || Format as a char.
|-
| B || Format as the Visual Prolog binary type.
|-
| R || Format as a database reference number.
|-
| p || Format as the presented value.
|-
| P || Format as a procedure parameter.
|-
| s || Format as a string.
|}

==== generated ====
This attribute can be placed on interfaces, classes and implementation to indicate that the code is generated by some tool. As result the compiler will issue less warnings about the code.

{{Example|
<vip>
interface iSomething supports iUnknown
[generated]
...
</vip>
}}

==== immediate ====

The attribute immediate enforces immediate (i.e. non-late) initialization of a fact variable:

{{Example|
<vip>
facts
current : integer := initializeCurrent() [immediate].
</vip>
}}

See also {{Lang2|Facts|Fact Variable Declarations|Fact Variable Declarations}}.

==== in ====

The argument is an input argument. Valid for a formal predicate argument.

{{Example|
<vip>predicates
pred : (string InputArg [in]).
</vip>
}}

==== in_iterate ====

Defines an in-iterator predicate for a domain or interface. See the description of the {{lang2|Terms|in|in}} operator.

==== in_test ====

Defines an in-test for a domain or interface. See the description of the {{lang2|Terms|in|in}} operator.

==== inline ====

<vp>inline</vp> alters the memory layout of a struct (i.e. a single alternative functor domain with an align qualification). The purpose of the attribute is to ease interfacing to foreign languages and should normally not be used for pure Visual Prolog.

<vp>inline</vp> can be used in three cases:

* inlining a struct rather than having a pointer to the struct
* inlining a fixed size string
* inlining a fixed number of bytes
* inlining a prolog predicate type (as a struct with two fields)

When using <vp>inline</vp> on struct field in another struct its data will be inlined instead of having a pointer to the struct

{{Example|
<vip>domains
point =p(integer X, integer Y).

domains
rectangle =
r(
point UpperLeft [inline],
point LowerRight [inline]
).</vip>
Since <vp>UpperLeft</vp> and <vp>LowerRight</vp> are inlined the struct have the same memory layout as this one:
<vip>domains
rectangle2 =
r2(
integer UpperLeft_X,
integer UpperLeft_Y,
integer LowerRight_X,
integer LowerRight_Y
).</vip>
}}

When using <vp>inline(<size>)</vp> on a <vp>string</vp> or a <vp>string8</vp> field in a struct, the struct will contain a fixed size string with <vp><size></vp> characters (i.e. <vp>char</vp> or <vp>char8</vp>, respectively). The strings will be zero terminated if they are shorter than <vp><size></vp>, but not if they have <vp><size></vp> characters.

{{Example|
<vip>domains
device =
device(
integer Id,
string DeviceName [inline(12)]
).</vip>
<vp>DeviceName</vp> is an inlined Unicode string of length 12.
The struct have the same layout as:
<vip>domains
device =
device(
integer Id,
char DeviceName_01,
char DeviceName_02,
char DeviceName_03,
char DeviceName_04,
char DeviceName_05,
char DeviceName_06,
char DeviceName_07,
char DeviceName_08,
char DeviceName_09,
char DeviceName_10,
char DeviceName_11,
char DeviceName_12
).</vip>
}}

When using <vp>inline(<size>)</vp> on the <vp>pointer</vp> type the struct will contain <vp><size></vp> bytes, and the pointer will become a pointer to that field:

{{Example|
<vip>domains
mark =
mark(
integer Position,
pointer Data [inline(8)]
).</vip>
<vp>Data</vp> is pointer to 8 inlined bytes
The struct have the same layout as:
<vip>domains
mark2 =
mark2(
integer Position,
byte Data_1,
byte Data_2,
byte Data_3,
byte Data_4,
byte Data_5,
byte Data_6,
byte Data_7,
byte Data_8
).</vip>
And <vp>Data</vp> will point to <vp>Data_1</vp>.
}}

==== intrinsic ====

A declaration which has special meaning and handling in the compiler (semi-built-in).

==== mandatoryOut ====

Used to prevent a predicate from having optional output parameters (see {{Lang2|Terms|Optional parameters|Optional parameters}}).

{{Example|This predicate does not have optional output paramters
<vip>
predicates
ppp : (integer X [out]) [mandatoryOut]. % The output parameter is mandatory
</vip>
}}

==== noDefaultConstructor ====

Used for a class to indicate that it should not have an implicit default constructor, and can thus be used to a class that does not have any public constructors at all. Valid for an object creating class declaration.

{{Example|
<vip>class classWithoutPublicConstructors : myInterface
open core
[noDefaultConstructor]
...
end class classWithoutPublicConstructors</vip>
}}

==== out ====

The argument is an output argument. Valid for a formal predicate argument.

{{Example|
<vip>predicates
pred : (string OutputArg [out]).</vip>
}}

==== pack ====

The <vp>[pack(n)]</vp> attribute (where <vp>n</vp> is a number) instructs the compiler to use <vp>n</vp> as packing size for a functor domains. By default the packing size is <vp>4</vp> in 32 bit programs and <vp>8</vp> in 64 bit programs. This attribute is mainly intended for compatibility with C/C++ api's.

{{Example|
<vip>
domains
packed = packed(integer8, pointer) [pack(2)].
</vip>
}}

The attribute can used on a <vp>class</vp> declaration to cover all domains in that class.

{{Example|The domains used with the RichEdit control must all be packed with 4:
<vip>
class richEdit_native
open core, gui_native
[pack(4)]

% pack all domains with packing size 4

end class richEdit_native
</vip>
}}

==== programPoint ====

<vp>programPoint</vp>'s are used by the exception mechanism to indicate where exceptions are raised and continued, but the usage is not limited to that purpose.

The <vp>programPoint</vp> attribute is used predicate or constructor declaration to indicate that it receives an extra input argument which describes the place in a program (program point) where this predicate was called. This additional argument has <vp>programPoint</vp> type which is declared in the PFC core class like:

<vip>domains
programPoint = programPoint(hScopeDescriptor ClassDescriptor, string PredicateName, sourceCursor Cursor).
</vip>

The <vp>programPoint</vp> attribute can be added to a predicate declaration like this:

<vip>predicates
raiseAnException : (integer X) erroneous [programPoint].</vip>

Adding this attribute actually means that two predicates are declared, the one you have mentioned and an another one with name <vp>raiseAnException_explicit</vp> which in addition to the arguments of <vp>raiseAnException</vp> takes a <vp>programPoint</vp> as first argument:

<vip>predicates
raiseAnException : (integer X) erroneous.

predicates
raiseAnException_explicit : (programPoint ProgramPoint, integer X) erroneous.</vip>

When you call <vp>raiseAnException</vp> the compiler will create a program point and call <vp>raiseAnException_explicit</vp> instead.

{{example|
<vip>clauses
test() :-
raiseAnException(17).</vip>
will actually correspond to:
<vip>clauses
test() :-
raiseAnException_explicit(programPoint(...), 17).
</vip>
where the program point corresponds to the point where <vp>raiseAnException</vp> is called in the <vp>test</vp> predicate.}}

If you have a programPoint you can directly call the explicit predicate with it.

{{example|
<vip>clauses
raiseAnExceptio17_explicit(ProgramPoint) :-
raiseAnException_explicit(ProgramPoint, 17).
</vip>

Typically, as in this example, explicit predicates will call other explicit predicates with the programPoint they receive in order to use an "original" call point in a nested explicit predicate.}}

Such code is treated in the usual way. I.e. when calling <vp>raiseAnException</vp> or <vp>raiseAnException_explicit</vp> will in both cases result in calling <vp>raiseAnException_explicit</vp>, so this is the only predicate that needs an implementation. In fact, it is illegal to state clauses for the non-explicit predicate that will never be called.

There is also a built-in predicate, [[Language Reference/Built-in entities#programPoint|<vp>programPoint/0-></vp>]], which returns a <vp>programPoint</vp> corresponding to the place where it is called.

To summarize:
* A predicate declaration with <vp>programPoint</vp> attribute actually declares two predicates. A non-explicit and an explicit predicate.
* Calling the non-explicit predicate actually results in calling the explicit predicate with the call point as additional argument.
* Only the explicit predicate should be implemented.

==== presenter ====

Used to specify the presenter of a domain.

{{Example|
<vip>domains
someDomain = ... [presenter(presenter_someDomain)].
</vip>
}}

Also used without argument to specify that an interface has a presenter.

{{Example|
<vip>interface something [presenter]
...
end interface something</vip>
}}

See [[Presenters]].

==== queryable ====

Makes an entity 'queryable', so that it is available for reflextion using the class <vp>predicateExtractor</vp>.

==== retired ====

The declared entity is retired. The string literal describes how to migrate from it. The entity does not exist anymore.

{{Example|
<vip>predicates
veryOldFashioned : (string Arg) [retired("Use newFashion instead")].</vip>
}}

==== retiredFunctor ====

Functor alternatives can be retired.

<vip>domains
ppp =
fct(integer A, real B, ddd C) [retiredFunctor(aaa::fct_ppp)];
fct2(integer A, ddd C, integer* New).</vip>

<vp>aaa::fct_ppp</vp> must be a predicate with this type (it can be an anonymous predicate):

<vip>predicates
fct_ppp : (integer A, real B, ddd C) -> ppp NewValue.</vip>

I.e. it takes the arguments of the old functor and returns a value in the functor domain.

In the program fct is does not exist at all, it is retired. But in the deserialization fct terms can still be handled: The arguments are parsed according to the types, and then the value is created by invoking <vp>aaa::fct_ppp</vp>.

This method will also work for binary serializations, provided:

* The old domain had more than one alternative (so there are functor numbers in the serialization)
* New alternatives are added last (to retain functor numbers)

It is however not recommend using binary serialization for inter-session persistence.

See also [[Functor Domain Versioning]].

==== sealed ====

Used for an interface to indicate that it cannot be supported by any other interface. This allows to create more efficient codes, because the compiler provides some optimization when using the objects of such type. Valid for an object creating class declaration as a construction interface.

{{Example|
<vip>interface myInterface
[sealed]
...
end interface myInterface

class myClass : myInterface
...
end class myClass</vip>
}}

==== this ====

Used for declaring {{lang2|Predicates|Extension Predicates|extension predicates}}.

{{Example|
<vip>
class predicates
extension : (unsigned V [this]).
</vip>
}}

==== union ====

Used for creating functor domains with several alternatives but no real functors. This should only be used to mimic C/C++ union structs in low-level interfacing. Valid for functor domain with several alternatives and alignment.

{{Example|
<vip>domains
u64var = align 4
u64(unsigned64 Value64);
u64_struct(unsigned Low32, unsigned High32)
[union].</vip>
}}

==== used ====

An unused local member can be marked <vp>used</vp> to prevent the compiler to issue a warning and remove the corresponding code. Valid for members.

{{Example|
<vip>predicates
seeminglyUnused : () [used].</vip>
}}

Language Reference/Terms

2025-08-19T15:05:11Z

Thomas Linder Puls: Casing

{{languageReferenceNavbar|Terms}}

This section describes terms and how execution/evaluation of terms and clauses proceeds.

Semantically, there are two kinds of terms: '''''formulas''''' and '''''expressions'''''.

*Expressions represent values, like the number 7.
*Formulas represent logical statements, like "the number 7 is greater than the number 3".

Syntactically the two kinds have a huge overlap and therefore the syntax unites the two kinds into ''terms''.

The following definition of <vpbnf><Term></vpbnf> is simplified, in the sense that it includes syntactic constructions that are not legal. For example, one cannot legally write <vp>! + !</vp>. We do however believe that using this simple syntax description in combination with intuitive understanding of language concepts, the type system, and the operator hierarchy described below is better for most purposes.

<vipbnf><Term>:
( <Term> )
<Literal>
<Variable>
<Identifier>
<MemberAccess>
<PredicateCall>
<PredicateExpression>
<UnaryOperator> <Term>
<Term> <Operator> <Term>
<Cut>
<Ellipsis>
<FactvariableAssignment></vipbnf>

=== Backtracking ===

The evaluation of a Prolog program is a search for a "solution" to the goal. Each step in the search for a solution can either '''''succeed''''' or '''''fail'''''. At certain points in the program execution there are more than one possible choices for finding a solution. When such a choice point is met a so called '''''backtrack point''''' is created. A backtrack point is a recording of the program state plus a pointer to the choice that was not executed. If it turn out that the original choice could not provide the solution (i.e. if it '''''fails'''''), then the program will '''''backtrack''''' to the recorded backtrack point. Thereby restoring the program state and pursuing the other choice. The mechanism will be described and exemplified in details in the following sections.

=== Literals ===

Literals have {{lang2|Domains|Universal_Types|universal type}}.

<vipbnf><Literal>:
<IntegerLiteral>
<RealLiteral>
<CharacterLiteral>
<StringLiteral>
<BinaryLiteral>
<ListLiteral>
<CompoundDomainLiteral></vipbnf>

See also {{lang2|Lexical Elements|Literals|Literals (in Lexical Elements)}}

=== Variables ===

Variables in Visual Prolog are immutable: once they are bound to a value they retain that value, but backtracking can unbind the variable again during the process of restoring a previous program state.

A variable can thus be bound (during unification and matching), if it is already bound then it evaluates to the value that it is bound to.

Variables are names starting with an upper-case letter or with an underscore (_), followed by a sequence of letters (both uppercase and lowercase), digits, and underscore characters (all in all called an UppercaseIdentifier):

<vipbnf><Variable>:
<UppercaseIdentifer></vipbnf>

The following are examples of valid variable names:

<vip>My_first_correct_variable_name
_
_Sales_10_11_86</vip>

while the next two are invalid:

<vip>1stattempt
second_attempt</vip>

The variable consisting of single underscore character (i.e. <vp>_</vp>) is known as the ''anonymous variable''. The anonymous variable is used in patterns and bindings where the corresponding value is of no interest and should be ignored. Every occurrence of the anonymous variable is an independent anonymous variable, i.e. even though the anonymous variable is used several times in a single clause they have no relation to each other.

If variables that starts with an underscore are not anonymous, but they are still intended for values of no interest that should be ignored. The compiler will issue a warning if the value of such a warning is actually not ignored.

Prolog variables are local to the clause in which it occurs. That is, if two clauses each contain a variable called <vp>X</vp>, these <vp>X</vp>-s are two distinct variables.

A variable is said to be ''free'' when it is not yet associated with a term and to be ''bound'' or instantiated when it is unified with a term.

The Visual Prolog compiler does not make a distinction between upper and lower case letters in names, except for the first letter. This means that the two variables <vp>SourceCode</vp> and <vp>SOURCECODE</vp> are the same.

=== Identifier ===

<vipbnf><Identifier>: one of
<MemberName>
<GlobalScopeMembername>
<ScopeQualifiedMemberName>

<MemberName>:
<LowerCaseIdentifier>
</vipbnf>

Identifiers are used to refer to named entities (i.e. classes, interfaces, constants, domains, predicates, facts, ...).

An identifier can just be a lower case identifier (i.e. a lowercase letter followed by a sequence of letters, numbers and underscore characters).

Many entities can have the same name. So it may be necessary or desirable to qualify the lowercase identifier the name of the particular scope of interest, or to state that the name is in the global namespace.

{{Example| These are examples of unqualified identifiers:

<vip>integer
mainExe
myPredicate</vip>
}}

==== Global Entities Access ====

The only global entities, which exist in Visual Prolog, are built-in domains, predicates, and constants. Global names are directly accessible in any scope. There might however exist situations where a global name is shadowed by a local or imported name. In that case the global entity can be qualified with a double colon '<vp>::</vp>' (without a prefixed class/interface name). The double colon can be used everywhere, but the most important place is where an interface name is used as formal parameter type specifier.

<vipbnf><GlobalScopeMemberName>:
:: <MemberName></vipbnf>

{{Example| The built-in domain <vp>integer</vp> is defined in the global scope, to avoid ambiguity or stress that it is this particular domains you can use the global scope member name:

<vip>::integer</vip>
}}

==== Class/Interface Member Access ====

Static members of classes and interfaces are accessed by means of qualification with the class name (and optionally a namespace prefix):

<vipbnf><ScopeQualifiedMemberName>
<NamespacePrefix>-opt <ScopeName> :: <MemberName>

<NamespacePrefix>:
<NamespaceIdentifier>-opt \

<ScopeName>:
<LowercaseIdentifier></vipbnf>

The ScopeName is the name of the class or interface that defines/declares the name.

Namespace prefixing is explained in: {{lang2|Namespaces|Referencing names in namespaces|Referencing names in namespaces}}.

Some names can be accessed without qualification, see {{lang2|Basic_Concepts|Scoping_&_Visibility|scoping & visibility}}.

=== Predicate Call ===

A predicate call have the form

<vipbnf><PredicateCall>:
<Term> ( <Term>-comma-sep-list-opt )</vipbnf>

The first term must be an expression that evaluates to a value with predicate type. Typically, it is either the name of a predicate in a class, or an expression that evaluates to a predicate member of an object.

Notice that some predicates return values, whereas other predicates do not. A predicate that returns a value is an expression, and the predicate call is often referred to as a '''function''' call. A predicate that does return a value is a formula.

A predicate is invoked by applying arguments to the predicate. The predicate must have a flow-pattern that matches the free/bound state of the arguments.

Most predicates are defined by a set of clauses, but some predicates are built into the language and some are defined externally in a DLL (perhaps in a foreign programming language).

When a predicate is invoked by a predicate call, each clause is executed in turn until one of them '''''succeeds''''', or there are no more clauses left to execute. If no clause succeeds the predicate '''''fails'''''.

If a clause succeeds and there are more relevant clauses left, a '''backtrackpoint''' is created to the next relevant clause.

Thus, a predicate can '''''fail''''', '''''succeed''''', and even '''''succeed''''' multiple times.

Each clause has a head and optionally a body.

When a predicate is called the clauses are tried in turn (from top to bottom). For each clause the arguments in the head is unified with the arguments from the call. If this unification succeeds then the body of the clause (if present) is executed. The clause '''''succeeds,''''' if the match of the head '''''succeeds''''' and the body '''''succeeds'''''. Otherwise it '''''fails'''''.

{{Example|
<vip>clauses
ppp() :- qqq(X), write(X), fail.

qqq(1).
qqq(2).
qqq(3).</vip>

When <vp>ppp</vp> is called it in turn calls <vp>qqq</vp>. When <vp>qqq</vp> is called, it first creates a backtrack point pointing to the second clause. Then the first clause is executed. Hereby the free variable <vp>X</vp> from <vp>ppp</vp> is matched against the number <vp>1</vp>, whereby <vp>X</vp> is bound to <vp>1</vp>.

In <vp>ppp</vp> <vp>X</vp> (i.e. <vp>1</vp>) is written and then <vp>fail</vp> cause backtracking to the backtrackpoint. Hereby program control is set to the second clause in <vp>qqq</vp> and the program state is set back to the state it was in when <vp>qqq</vp> was first entered, i.e. <vp>X</vp> in <vp>ppp</vp> is unbound again.

Before the actual execution of the second clause in <vp>qqq</vp> begins a backtrack point to the third clause is created. The execution then proceeds as it did for <vp>1</vp>
}}

=== Unification ===

When a predicate is called the arguments from the call is '''''unified''''' with the terms in the head of each clause.

Unification is the process of binding variables in such a way that two terms become equal, making as few bindings as possible (i.e. leaving as much as possible open for further binding).

Variables can be bound to any kind of terms, including variables or terms containing variables.

Unification is either possible or impossible, i.e. it can '''''succeed''''' or '''''fail'''''.

Variables and terms to which they are unified have types, a variable can only be bound to a term of the same type as the variable, or a subtype. When two variables are bound to each other they must therefore have exactly the same type.

Unification takes place (as mentioned) between a predicate call and the clause head. It also takes place when two terms are compared for equality.

{{Example| Consider two terms (of the same type):

<vip>T1 = f1(g(), X, 17, Y, 17)
T2 = f1(Z, Z, V, U, 43)</vip>

We will attempt to unify these two terms from left to right (i.e. a left-to-right pre-traversal).

Both <vp>T1</vp> and <vp>T2</vp> are <vp>f1/5</vp> terms, this match. Therefore we attempt to unify each of the arguments from <vp>T1</vp> with each correspondent argument of <vp>T2</vp>. First we must unify <vp>Z</vp> and <vp>g()</vp>, this can be unified if we bind <vp>Z</vp> to <vp>g()</vp>. So far everything is fine and we have the first binding in our unifier:

<vip>Z = g()</vip>

The next two arguments are <vp>X</vp> and <vp>Z</vp>, which already has been bound to <vp>g()</vp>. These two arguments can also be unified if we also bind <vp>X</vp> to <vp>g()</vp>. So we now have the following contributions to our unifier:

<vip>X = Z = g()</vip>

Next we must bind <vp>V</vp> to <vp>17</vp> and then we must bind <vp>Y</vp> to <vp>U</vp>. So far everything unifies with the following unifier:

<vip>X = Z = g()
V = 17
Y = U</vip>

The two unified terms are now equivalent to these terms:

<vip>T1 = f1(g(), g(), 17, Y, 17)
T2 = f1(g(), g(), 17, Y, 43)</vip>

But we have not yet unified the two last arguments, which are <vp>17</vp> and <vp>43</vp>. No variable binding can make these terms equal, so all in all the unification '''''fails'''''.

<vp>T1</vp> and <vp>T2</vp> cannot be unified.
}}

In the example above <vp>T1</vp> could have been a predicate call and <vp>T2</vp> a clause head. But they could also have been two terms that were compared with equal "<vp>=</vp>".

=== Matching ===

'''''Matching''''' is the same as unification except that variables can only be bound to grounded terms. A '''''grounded''''' term is a term that does not contain any unbound variables.

It is the flow-patterns that are stated for predicates, that make it possible to use matching rather than full-blown unification.

{{Example|
<vip>clauses
ppp(Z, Z, 17).
qqq() :-
ppp(g(), X, 17).</vip>

Unification of the <vp>ppp</vp>-call with the <vp>ppp</vp>-clause is possible with the following unifier:

<vip>Z = X = g()</vip>

If <vp>ppp</vp> have the flow <vp>(i,o,i)</vp> then the unification is just a match:

*<vp>g()</vp> is input as the first argument, this is bound to <vp>Z</vp>
*The second argument in the clause is therefore bound and can thus be output to <vp>X</vp>, which therefore becomes bound to ''<vp>g()</vp>''.
*finally the third argument is <vp>17</vp> used as input this number is simply compared to the third argument in the clause.

It is the flow-pattern that makes it possible to predict that the clause does not need real unification.
}}

=== Nested Function Calls ===

Terms that have to be unified or matched with each other are allowed to contain sub-terms that are actually expressions or function calls that have to be evaluated before the unification/matching can be completed.

The evaluation of such sub-terms is done on a by-need basis.

In a predicate call all input arguments are evaluated before the predicate is called, all output arguments are variables, which does not need evaluation.

Clause heads can also contain terms that have to be evaluated, before matching/unification can be determined.

*all matching/unification that does not require any evaluation is performed before any evaluation is performed;
*then evaluation corresponding to input arguments is performed one by one left-to-right. Comparing each value to the corresponding input after each evaluation;
*then the clause body is evaluated;
*then the output arguments are evaluated (left-to-right);
*then the return value (if the predicate is a function) is evaluated.

If any of these '''''fail''''' then the rest of the evaluation is not carried out.

All in all the base principles are:

*input after other match, before body evaluation
*output after body evaluation
*left-to-right

=== Arguments ===
{{:Language Reference/Terms/Arguments}}
=== Fact Variable Assignment ===

Assign operator <vp>:=</vp> is used to assign a new value for a {{lang2|Facts|Fact_Variable_Declarations|fact variable}} <vpbnf><FactVariable></vpbnf>. The <vpbnf><Term></vpbnf> must be evaluated to a value of suitable type (i.e. the same type as the fact variable, or a subtype).

<vipbnf><FactVariableAssignment>:
<FactVariable> := <Term></vipbnf>

=== Facts ===

A fact database contains a number of fully instantiated (grounded) predicate heads corresponding to the facts from the facts section declaration. The facts can be accessed by a predicate call, using the fact name as the predicate name. The predicate call is matched against each fact in turn; succeeding with a possible backtrack point to the next fact each time the predicate call match the fact. When there are no more facts in the fact database then the predicate call fails.

New facts can be '''''asserted''''' using the predicates {{lang2|Built-in_entities|assert|assert/1}}, {{lang2|Built-in_entities|asserta|asserta/1}}, and {{lang2|Built-in_entities|assertz|assertz/1}}. {{lang2|Built-in_entities|assert|assert/1}} is the same as {{lang2|Built-in_entities|assertz|assertz/1}} and it asserts a new fact to the end of the list of facts, whereas {{lang2|Built-in_entities|asserta|asserta/1}} asserts a new fact to the start of the list.

Existing facts can be '''''retracted''''' with the predicate {{lang2|Built-in_entities|retract|retract/1}} and {{lang2|Built-in_entities|retractall|retractAll/1}}. {{lang2|Built-in_entities|retract|retract/1}} retracts the first fact that match the argument binding variables in the argument and leaving a backtrack point so that more facts will potentially be retracted when backtracking.

{{lang2|Built-in_entities|retractall|retractAll/1}} retracts all facts that matches the arguments and succeeds without any binding.

=== Operators ===

Operators are organized in a precedence hierarchy. In the rule below operators in each group have same precedence, which is higher than those below. I.e. the power operator has higher precedence than unary minus and plus, which in turn has higher precedence than the multiplication operators, etc. Parenthesis can be used to circumvent the precedence (and for clarification).

<vipbnf><Operator>: one of
<PowerOperator>
<UnaryOperator>
<MultiplicationOperator>
<AdditionOperator>
<OtherwiseOperator>
<RelationOperator>
<MustUnifyOperator>
<InOperator>
<AndOperator>
<OrOperator></vipbnf>

<vipbnf><UnaryOperator>: one of
- +</vipbnf>

All operators except the <vpbnf><UnaryOperator></vpbnf>'s are binary. The power operator is right associative, all other operators are left associative.

<vpbnf><RelationOperator></vpbnf>, <vpbnf><MustUnifyOperator></vpbnf> and <vpbnf><InOperator></vpbnf> have same precedence.

'''Notice''' that the placement <vpbnf><UnaryOperator></vpbnf> is not consistent with mathematics, where these operators are at the same level as the <vpbnf><AdditionalOperator></vpbnf>'s. The difference has no influence of the calculated value, but it allows writing <vp>2*-2</vp>, where mathematics would require a parenthesis around the second operator <vp>2*(-2)</vp>. It also means that <vp>-2*2</vp> is mmeans (-2)*2 where it would be <vp>-(2*2)</vp> in mathematics (the resulting value is the same).

{{Example|
<vp>-2^2</vp> is the same as <vp>-(2^2)</vp> because ^ has higher precedence than unary minus.
}}

{{Example|
<vp>3^2^2</vp> is the same as <vp>3^(2^2)</vp> because ^ is right associative.
}}

{{Example|
<vp>-2*-3^-4+5</vp> is the same as <vp>((-2) * (-(3 ^ (-4)))) + 5</vp>.
}}

{{Example| The following term:

<vip>7 + 3 * 5 * 13 + 4 + 3 = X / 6 ; A < 7, p(X)</vip>

has the same meaning as this term:

<vip>((((7 + ((3 * 5) * 13)) + 4) + 3) = (X / 6)) ; ((A < 7) , p(X))</vip>

I.e. at outermost level the term is an "<vp>or</vp>" of two terms, the first of these is a relational (<vp>=</vp>) term, the second is an "<vp>and</vp>" term, etc.
}}

=== Arithmetic Operators ===

The arithmetic operators are used for arithmetic operations on numbers. They are expressions, which takes expressions as arguments. They have root types as arguments and return universal types as result. (See {{lang2|Domains|Universal_and_Root_Types|Universal and Root types}}.)

<vipbnf><PowerOperator>:
^</vipbnf>

<vipbnf><MultiplicationOperator>: one of
* / div mod quot rem</vipbnf>

<vipbnf><AdditionOperator>: one of
+ -</vipbnf>

=== Relational Operators ===

The relational operators are formulas, which takes expressions as arguments. Given this nature they are non-associative.

<vipbnf><RelationOperator>: one of
= > < >= <= <> ><</vipbnf>

First the left term is evaluated, then the right term is evaluated and then the results are compared.

'''Notice''' that <vp><></vp> (different) is not the dual operation of = (equal). <vp><></vp> compares two values, whereas <vp>=</vp> tries to unify two terms (in the general case at least).

The dual to expression <vp>A = B</vp> is <vp>not (A = B)</vp>.

==== Must Unify Operator ====

The must unify operator is a procedure, which takes expressions as arguments. It is non-associative.

<vipbnf><MustUnifyOperator>:
==</vipbnf>

<vpbnf>A == B</vpbnf> unifies <vpbnf>A</vpbnf> and <vpbnf>B</vpbnf>; if the unification fails an exception is raised, otherwise the predicate succeeds. Therefore <vpbnf>A == B</vpbnf> always succeeds.

{{Example|
<vip>clauses
p(L) :-
[H|T] == L,
...</vip>
<vp>p</vp> is a procedure. An exception will be raised if it is called with an empty list, because <vp>[H|T]</vp> and <vp>L</vp> cannot unify.}}

=== Bitwise and boolean operators ===

The following operators for bitwise operations on <vp>unsigned</vp>, <vp>unsigned64</vp> and <vp>unsignedNative</vp>.

<vip>
A ** B % A and B
A ++ B % A or B
A -- B % A and not B
A ^^ B % A exclusive or B
~~ A % not A
A << N % Shifts the bits in A N times to the left.
A >> N % Shifts the bits in A N times to the right.
</vip>

The logical operations (<vp>**</vp>, <vp>++</vp>, <vp>^^</vp> and <vp>~~</vp>) can also be used on <vp>boolean</vp> values.

The shift operations discard bits that is shifted out of the number, and shift-in zero bits in the opposite end.

=== Logical Operators ===

The <vpbnf><AndOperator></vpbnf>(s) and <vpbnf><OrOperator></vpbnf>(s) are formulas, which takes formulas as arguments. They are all left associative. The <vp>,</vp> and <vp>and </vp> are synonyms and so are <vp>; </vp> and <vp>or</vp>.

<vipbnf><AndOperator>: one of
, and</vipbnf>

<vipbnf><OrOperator>: one of
; or orelse</vipbnf>

==== and (,) ====

The evaluation of an <vp>and</vp> term <vp>A, B</vp> proceeds as follows. First the left sub-term <vp>A</vp> is evaluated. If this evaluation fails, the whole <vp>and</vp> term fails. If <vp>A</vp> succeeds then the right sub-term <vp>B</vp> is evaluated. If this evaluation fails, the whole <vp>and</vp> term fails, otherwise the <vp>and</vp> term succeeds.

Thus the second sub-term <vp>B</vp> is only evaluated, if the first sub-term <vp>A</vp> succeeds.

{{Example|
<vip>clauses
ppp() :-
qqq(), rrr().</vip>

When <vp>ppp</vp> is called it will first call <vp>qqq</vp> and if <vp>qqq</vp> succeeds, then it will call <vp>rrr</vp>. If <vp>rrr</vp> succeeds, then the <vp>and</vp> term and subsequently the whole clause succeeds.
}}

==== or (;) ====

The evaluation of an <vp>or</vp> term <vp>A</vp>; <vp>B</vp> proceeds as follows. First a backtrack point to the second term <vp>B</vp> is created and then the first term <vp>A</vp> is evaluated. If the evaluation of the first term succeeds, then the whole <vp>or</vp> term succeeds and is left with a backtrack to the second term <vp>B</vp>. If the evaluation of the first term fails, the backtrack point to the second term is activated.

If the backtrack point to the second term <vp>B</vp> is activated (either because the first term fails, or because something later in the execution invokes the backtrack point), then the second term <vp>B</vp> is evaluated and the whole <vp>or</vp> term will succeed if <vp>B</vp> succeeds.

Thus an <vp>or</vp> term can succeed with a backtrack point and the second sub-term <vp>B</vp> is only evaluated on backtrack.

{{Example|
<vip>clauses
ppp() :-
(V = 3 or V = 7), write(V), fail.</vip>

Here we have used the keyword <vp>or</vp>, but you can also use semi-colon <vp>;</vp>.

When <vp>ppp</vp> is called we first create a backtrack point to the term <vp>V = 7</vp> and then we evaluate <vp>V = 3</vp>. Thereby <vp>V</vp> will be bound to <vp>3</vp> we then continue to the <vp>write(V)</vp> after <vp>3</vp> has been written <vp>fail</vp> is met. <vp>fail</vp> always fails so we effectuate the backtrack point leading us to the term <vp>V = 7</vp>.

Backtracking also undo all bindings made since the backtrack point was created. In this case it means that <vp>V</vp> is unbound.

Then <vp>V = 7</vp> is evaluated and <vp>V</vp> becomes bound to <vp>7</vp> and er continue to the term <vp>write(V)</vp>, and then <vp>fail</vp> is met again, this time there are no more backtrack points <vp>ppp</vp> fails.
}}

Using parentheses <vp>or</vp> can be nested deeply in clauses.

<vip>clauses
p(X) = Y :-
(X = 1, !, Z = 3 or Z = 7), Y = 2*Z.</vip>

We recommend careful usage of <vp>or</vp>. It is mainly intended for usage in test-conditions:

<vip>clauses
isOutside(X) :-
(X < 10 or X > 90), !.</vip>

<vp>or</vp> is a nondeterministic construction, but <vp>orelse</vp> can be used as a deterministic pendant:

<vip>clauses
isOutside(X) :-
X < 10 orelse X > 90.</vip>

==== orelse ====

<vp>orelse</vp> is a deterministic pendant to the nondeterministic <vp>or</vp>. <vp>A orelse B</vp> will succeed if <vp>A</vp> succeeds or if <vp>B</vp> succeeds, but it will '''''not''''' leave a backtrack point to <vp>B</vp> if <vp>A</vp> succeeds.

The evaluation of an <vp>orelse</vp> term <vp>A orelse B</vp> proceeds as follows: First a backtrack point to the second term <vp>B</vp> is created and then the first term <vp>A</vp> is evaluated. If the evaluation of the first term succeeds then the backtrack to the second term (and any backtrack point within it) <vp>B</vp> are removed again and the whole <vp>orelse</vp> term succeeds. If the evaluation of the first term <vp>A</vp> fails, the backtrack point to the second term <vp>B</vp> is evaluated.

So an <vp>orelse</vp> term does not leave a backtrack point.

{{Example|
<vip>clauses
ppp(V) :-
(V = 3 orelse V = 7), write(V).</vip>

Whenever <vp>ppp</vp> is called we first create a backtrack point to the term <vp>V = 7</vp> and then we evaluate the term <vp>V = 3</vp>, if <vp>V = 3</vp> succeeds we remove the backtrack point to <vp>V = 7</vp> again and then continue to <vp>write(V)</vp>. If <vp>V = 3</vp> fails the backtrack point to <vp>V = 7</vp> is effectuated. If <vp>V = 7</vp> succeeds we continue to <vp>write(V)</vp>, if <vp>V = 7</vp> fails the entire <vp>ppp</vp> predicate will fail.
}}

==== otherwise ====

<vp>otherwise</vp> is an expression operator; though it has control flow that makes it resemble the logical operators.

<vip>A otherwise B</vip>

is an expression (<vp>A</vp> and <vp>B</vp> must be expressions). If the evaluation of <vp>A</vp> succeeds by evaluating to the value VA then <vp>A otherwise B</vp> evaluates to VA, otherwise (i.e. if the evaluation of <vp>A</vp> fails) then <vp>A otherwise B</vp> will be the result of evaluating <vp>B</vp>.

<vp>otherwise</vp> is right associative:

<vip>A otherwise B otherwise C
=>
A otherwise (B otherwise C)</vip>

It has lower precedence than all other expression operators, but higher than relational operators:

<vip>V < A + tryGet() otherwise 9
=>
V < ((A + tryGet()) otherwise 9)</vip>

<vp>core</vp> have been enriched with a predicate <vp>isSome</vp> for providing default values for <vp>core::optional</vp> matching:

{{Example|
<vip>V = isSome(Optional) otherwise 0</vip>
If <vp>Optional</vp> have the form <vp>some(X)</vp> then <vp>V</vp> will get the value <vp>X</vp> otherwise <vp>V</vp> will get the value <vp>0</vp>.}}

==== not ====

The {{lang2|Built-in_entities|not|not/1}} takes a term as the argument. The evaluation of <vp>not(A)</vp> first evaluates <vp>A</vp>. If <vp>A</vp> succeeds, then <vp>not(A)</vp> fails, if <vp>A</vp> fails, then <vp>not(A)</vp> succeeds.

Notice that <vp>not(A)</vp> will never bind any variables, because if <vp>not(A)</vp> succeeds then <vp>A</vp> has failed, and a failed term does not bind anything. If <vp>not(A)</vp> on the other hand fails, it cannot bind any variables either, because then the term itself failed.

Also notice that <vp>not(A)</vp> can never succeed with backtrack points, because if <vp>not(A)</vp> succeeds then <vp>A</vp> have failed, and a failed term cannot contain any backtrack points. This in turn means that all possibilities of success in <vp>A</vp> have been exhausted.

==== cut (!) ====

Cut "<vp>!</vp>" removes all backtrack points created since the entrance to the current predicate, this means all backtrack points to subsequent clauses, plus backtrack points in predicate calls made in the current clause before the "<vp>!</vp>".

<vipbnf><Cut>:
!</vipbnf>

{{Example|
<vip>clauses
ppp(X) :-
X > 7,
!,
write("Greater than seven").
ppp(_X) :-
write("Not greater than seven").</vip>

When <vp>ppp</vp> is executed, there is first created a backtrack point to the second clause, and then the first clause is executed. If the test "<vp>X > 7</vp>" succeeds then the cut "<vp>!</vp>" is reached. This cut "<vp>!</vp>" will remove the backtrack point to the second clause.
}}

{{Example|

<vip>clauses
ppp() :-
qqq(X),
X > 7,
!,
write("Found one").
ppp() :-
write("Did not find one").
clauses
qqq(3).
qqq(12).
qqq(13).</vip>

When <vp>ppp</vp> is executed it first creates a backtrack point to the second <vp>ppp</vp> clause and then <vp>qqq</vp> is called. The <vp>qqq</vp> will create a backtrack point to the second <vp>qqq</vp> clause and execute the first clause, thereby returning the value <vp>3</vp>. In <vp>ppp</vp> variable <vp>X</vp> is bound to this value and then compared to <vp>7</vp>. This test fails and, therefore, the control backtracks to the second clause of <vp>qqq</vp>.

Before executing the second clause a new backtrack point to the third clause of <vp>qqq</vp> is created and then the second clause returns <vp>12</vp>.

This time the test against <vp>7</vp> succeeds and, therefore, the cut is executed. This cut will remove both the backtrack point left in <vp>qqq</vp> as well as the backtrack point to the second clause of <vp>ppp</vp>.
}}

===== cut scopes =====

A cut scope is a scope to which the effect of a <vp>cut</vp> is limited. Meaning that if a <vp>cut</vp> is met within a cut scope then only backtrack points within that scope are discarded, while backtrack points outside (i.e. prior to) the cut scope remains.

The clauses of a predicate is a cut scope. Meeting a <vp>cut</vp> will (at most) discard the backtrack points that was created after entrance to the predicate. Backtrack points created before entrance to the predicate will remain.

{{Example|
<vip>clauses
aaa() :- p1_nd(), qqq().
qqq() :- p2_nd(), !.</vip>

<vp>aaa</vp> calls <vp>p1_nd</vp>, which leaves a backtrack point, and then it calls <vp>qqq</vp>. <vp>qqq</vp> calls <vp>p2_nd</vp>, which also leaves a backtrack point. Then we meet a <vp>cut</vp>. This <vp>cut</vp> is in the <vp>cut</vp>-scope of the <vp>qqq</vp> predicate, so it is only the backtrack point in <vp>p2_nd</vp> which is discarded, the one in <vp>p1_nd</vp> remains.
}}

Several terms introduce cut scopes (see the respective terms: {{lang2|Terms|List_Comprehension|list comprehension}}, {{lang2|Terms|if-then-else|if-then-else}}, {{lang2|Terms|foreach|foreach}}). Here we will use <vp>if-then-else</vp> to illustrate the effect of cut scopes. Consider the schematic <vp>if-then-else</vp> term:

<vip>if Cond then T1 else T2 end if</vip>

The condition <vp>Cond</vp> is a cut-scope, meaning that a <vp>cut</vp> inside <vp>Cond</vp> will only have effect inside <vp>Cond</vp>. <vp>Cut</vp>s inside <vp>T1</vp> and <vp>T2</vp>, on the other hand, have effect outside the <vp>if-then-else</vp> statement.

Consider this code fragment:

<vip>X = getMember_nd([3,1,2]),
if X = getMember_nd([3,3]), ! then
write(X)
else
!
end if,
fail</vip>

<vp>getMember_nd</vp> is a nondeterministic predicate. The evaluation of this code will go as follows. First <vp>X</vp> is bound to <vp>3</vp> and <vp>getMember_nd</vp> leaves a backtrack point (so that <vp>X</vp> can later become <vp>1</vp> and then even <vp>2</vp>).

Then we evaluate the condition in the <vp>if-then-else</vp> term. The first part of this condition succeeds as <vp>3</vp> is a member of <vp>[3,3]</vp>. The first part also leaves a backtrack point, so that it can be examined whether <vp>X</vp> is a member several times.

Now we meet a <vp>cut</vp>. This <vp>cut</vp> is inside the condition part of an <vp>if-then-else</vp> statement, so it only has local effect, meaning that it only discards the backtrack point in the second <vp>getMember_nd</vp>, but leaves the backtrack point in the first <vp>getMember_nd</vp> predicate.

The whole condition succeeds and we enter the then-part and write out "<vp>3</vp>".

After the <vp>if-then-else</vp> we meet <vp>fail</vp>, which backtracks us to the first <vp>getMember_nd</vp>.

<vp>getMember_nd</vp> then binds <vp>X</vp> to <vp>1</vp>, and leaves a backtrack point (so that <vp>X</vp> can later become <vp>2</vp>).

Then we evaluate the condition in the <vp>if-then-else</vp> term. The first part of this condition fails as <vp>1</vp> is not a member of <vp>[3,3]</vp>. So we enter the <vp>else</vp>-part.

Here we meet a <vp>cut</vp>. This <vp>cut</vp> is in the <vp>else</vp>-part of a conditional term so it has effect outside the <vp>if-then-else</vp> term and subsequently it discards the backtrack point in the first <vp>getMember_nd</vp>.

When we meet the <vp>fail</vp> after the <vp>if-then-else</vp> term there are no more backtrack points in the code and it will fail. So all in all <vp>X</vp> never becomes <vp>2</vp>.

==== fail/0 and succeed/0 ====

{{lang2|Built-in_entities|fail|fail/0}} and {{lang2|Built-in_entities|succeed|succeed/0}} are two built-in nullary predicates. {{lang2|Built-in_entities|fail|fail/0}} always fails and {{lang2|Built-in_entities|succeed|succeed/0}} always succeeds, besides this the predicates have no effect.

=== in ===
{{:Language Reference/Terms/in}}
=== List Comprehension ===

<vipbnf><ListComprehensionTerm> :
[ <Term> || <Term> ]</vipbnf>

The list comprehension term is a list expression. Consider this schematic term:

<vip>[ Exp || Gen ]</vip>

<vp>Gen</vp> is (typically) a <vp>nondeterm</vp> term. <vp>Exp</vp> is evaluated for each solution of <vp>Gen</vp>, and the resulting <vp>Exp</vp>'s are collected in a list. The <vp>Exp</vp> corresponding to the first solution of <vp>Gen</vp> is the first element in the list, etc. This list is the result of the list comprehension term. <vp>Exp</vp> must be procedure (or erroneous). Both <vp>Exp</vp> and <vp>Gen</vp> are {{lang2|Terms|Cut_Scopes|cut scopes}}.

The list comprehension (normally) reads: The list of <vp>Exp</vp>'s such that <vp>Gen</vp>.

{{Example|
<vip>[ X || X = getMember_nd(L), X mod 2 = 0 ]</vip>

This reads the list of <vp>X</vp>'s such that <vp>X</vp> is in <vp>L</vp> and <vp>X</vp> is even. So this expression is the even numbers of <vp>L</vp>.
}}

{{Example|
<vip>[ X + 1 || X = getMember_nd(L), X mod 2 = 0 ]</vip>

Here the collected expression is more complex. This makes say the term more awkward:

:"the list of (X+1)'s such that ..."

This expression again finds the even elements in <vp>L</vp>, but the resulting list contains all these values incremented.

This term is completely equivalent to this term:

<vip>[ Y || X = getMember_nd(L), X mod 2 = 0 , Y = X+1 ]</vip>

This term is easier to say:

:"The list of Y's such that (there exists an) X which is member of L, and which is even, and Y is X+1."
}}

=== Anonymous Predicates ===
{{:Language Reference/Terms/Anonymous Predicates}}
=== Object Member Access ===
Whenever we have a reference to an object, we can access the object member predicates of that object.
<vipbnf><MemberAccess>:
<Term> : <Identifier></vipbnf>

(Currently, the {{lang|Terms|term}} must be a variable or a fact variable).

The {{lang2|Lexical_Elements|Identifiers|identifier}} must have the type of the {{lang|Terms|term}}.

Inside an implementation object member predicates can be invoked without reference to an object, because "<vp>This</vp>" is subsumed, see {{lang2|Basic_Concepts|Scoping_&_Visibility|Scoping}}.

=== Object Expressions ===

An object expressions is an expressions that evaluates to an object. Like anonymous predicates it can capture values from and access facts in the context it appears in.

The syntax is like a regular class implementation without a name, but with a construction interface:

{{Example|<vip>Object =
implement : observer
clauses
onNext(A) :- F(toString(A)).
onCompletion() :- F("\n").
end implement</vip>
}}

the <vp>implement ... end implement</vp> part is an object expression.
To make object expressions a lightweight construction the keyword <vp>clauses</vp> is implicit/optional at the beginning of the scope (unless the scope has <vp>open</vp>, <vp>supports</vp> or <vp>inherits</vp> qualifications).

<vipbnf><ObjectExpression>: one of
<FullObjectExpression>
<SimpleObjectExpression>

<FullObjectExpression>:
implement : <ConstructionType>
<ScopeQualifications>
<Sections>
end implement

<SimpleObjectExpression>:
implement : <ConstructionType>
<Clause>-dot-term-list-opt
<Sections>
end implement</vipbnf>

There will be exactly one constructor <vp>new\0</vp>. Like for other objects you don't need to supply an implementation if the constructor is 'trivial'.

<vp>inherits</vp>, <vp>supports</vp>, <vp>open</vp>, <vp>delegate</vp> and <vp>resolve</vp> works in the same way as in regular implementations.

=== Scoping ===

The predicates can refer to the context like anonymous predicates but can also refer to facts and inherited classes inside the object.

Object expressions are nested within other scopes, these scopes are all visible from the object expression. If a name is defined in more than one surrounding scope then the reference is to the closest level. Names from named scopes can be resolved with the scope name, but names from surrounding object expressions must be resolved by means of a variable as described in the "This" section.

=== This ===

In a predicate in an object expression the variable <vp>This</vp> represent the object of the object expression. There are no predefined names for surrounding <vp>This</vp> variables. So if you want to refer to an outer <vp>This</vp> you will have to put it in another variable e.g. <vp>Outer = This</vp> and then use that variable inside the object expression.

<vip>...
Outer = This,
Object =
implement : observer
onNext(A) :- F(Outer, toString(A))).
onCompletion() :- F(Outer, "\n")).
end implement</vip>

=== Polymorphism (limitation) ===

Occasionally there will be situations where we will need a type variable. An example would be a predicate <vp>p : () -> observer{A}</vp> implemented using an object expression. Unfortunately, this is not possible until we get access to the type variables of polymorphic constructions.

<vip>
clauses
p(Value) =
implement : observer{A} % A is unknown/unbound
facts
v : A = Value. % A is unknown/unbound
clauses
onNext(V) :- v := V.
onCompleted():- write(v).
end implement.
</vip>

=== Examples ===

The examples below will be based on <vp>iterator</vp> object.

<vip>interface iterator
predicates
hasNext : () determ.
next : () -> integer.
end interface iterator</vip>

Which we will write using this predicate:

<vip>class predicates
writeAll : (iterator It).
clauses
writeAll(It) :-
if It:hasNext() then
writef("%\n", It:next()),
writeAll(It)
else
write("<<<end>>>\n")
end if.</vip>

==== Simple object ====

{{Example|We can write a simple "null" <vp>iterator</vp> that is finished immediately.

<vip>class predicates
test1 : ().
clauses
test1() :-
It =
implement : iterator
hasNext() :-
fail.
next() = _ :-
exception::raise_error().
end implement,
writeAll(It).</vip>

Calling <vp>test1</vp> will produce
<<<end>>>
}}

==== Own state====

{{Example|In this example we create an iterator object that har its own fact <vp>n</vp> which is used to count down from <vp>3</vp>

<vip>class predicates
test2 : ().
clauses
test2() :-
It =
implement : iterator
hasNext() :-
n > 0.
next() = N :-
N = n,
n := n - 1.
facts
n : integer := 3.
end implement,
writeAll(It).</vip>

Calling <vp>test2</vp> will produce
3
2
1
<<<end>>>
}}

==== Capturing values ====

{{Example|The count down object from above can be placed in its own predicate, and we can capture the value to count down <vp>From</vp> in the context:

<vip>class predicates
countDown : (integer From) -> iterator It.
clauses
countDown(From) =
implement : iterator
hasNext() :-
n > 0.
next() = N :-
N = n,
n := n - 1.
facts
n : integer := From.
end implement.

class predicates
test3 : ().
clauses
test3() :-
It = countDown(2),
writeAll(It).</vip>

Calling <vp>test3</vp> will produce
2
1
<<<end>>>
}}

{{Example|Here <vp>map</vp> create an iterator that maps the values returned <vp>iterator</vp> just like it would have modified the values of a list. Notice how the object expression captures the variables <vp>F</vp> and <vp>It</vp> and accesses them in its member predicates.

<vip>class predicates
map : (function{integer, integer} Function, iterator It) -> iterator Mapped.
clauses
map(F, It) =
implement : iterator
hasNext() :-
It:hasNext().
next() = F(It:next()).
end implement.

class predicates
test4 : ().
clauses
test4() :-
It1 = countDown(2),
It2 = map({ (V) = V + 7 }, It1),
writeAll(It2).</vip>

Calling <vp>test4</vp> will produce
9
8
<<<end>>>
}}

==== Capturing a fact ====

{{Example|Here the fact <vp>count</vp> from the context is captured and manipulated from within the object expression.

<vip>class facts
count : integer := 3.

class predicates
test5 : ().
clauses
test5() :-
It =
implement : iterator
hasNext() :-
count > 0.
next() = N :-
N = count,
count := count - 1.
end implement,
writeAll(It).
</vip>

Calling <vp>test5</vp> will produce
3
2
1
<<<end>>>
}}

==== inherits ====

{{Example|Suppose we have a class <vp>randomIterator</vp> which generates random numbers and supports the <vp>iterator</vp> iterator.
We can inherit from this iterator to create a iterator that "throws a dice":

<vip>class predicates
test6 : ().
clauses
test6() :-
Dice =
implement : iterator inherits randomIterator
clauses
next() = randomIterator::next() mod 6 + 1.
end implement,
foreach _ = std::cIterate(5) do
writef("Dice : %\n", Dice:next())
end foreach.</vip>

By inheriting <vp>randomIterator</vp> we get the implementation of <vp>hasNext</vp> and only need to implement <vp>next</vp>.

Notice that it is necessary to use the <vp>clauses</vp> keyword in this case because the class has an <vp>inherits</vp> qualification.

Assuming that <vp>randomIterator</vp> will never end, we just iterate <vp>5</vp> times.

Calling <vp>test5</vp> will produce (something like):
Dice : 1
Dice : 2
Dice : 4
Dice : 2
Dice : 3
}}

=== Domain, Functor, and Constant Access ===

Domains, functors, and constants are all accessed as if they are class members. Even if they are declared in an interface. This means that when they are qualified, then they are always qualified with class/interface name and a double colon.

=== foreach ===
{{:Language Reference/Terms/Foreach}}
=== if-then-else ===
{{:Language Reference/Terms/If-then-else}}
=== try-catch-finally ===
{{:Language Reference/Terms/Try-catch-finally}}

Language Reference/Interfaces

2025-06-23T11:54:10Z

Thomas Linder Puls: /* The interface: object */ object::null

{{languageReferenceNavbar|Interfaces}}

An interface definition defines a named object type. Interfaces can support other interfaces. See {{lang2|Interfaces|Supports_Qualification|Supports Qualification}} for further details.

All predicates declared in an interface are object members in objects of the interface type.

An interface is also a global scope, in which constants and domains can be defined. Thus constants and domains defined in an interface are not part of the type that the interface denotes (or of objects having this type).

Such domains and constants can be referenced from other scopes by qualification with the interface name: <vp>interfaceName::constant</vp>, or by using an open qualification. (See {{lang2|Interfaces|Open_Qualification|Open Qualification}}.)

<vipbnf><InterfaceDefinition> :
interface <InterfaceName>
<ScopeQualifications>
<Sections>
end interface <IinterfaceName>-opt</vipbnf>

<vipbnf><InterfaceName> :
<LowerCaseIdentifier></vipbnf>

See also {{lang|Generic Interfaces and Classes|Generic Interfaces and Classes}} and {{lang|Monitors|Monitors}}.

The <vpbnf><InterfaceName></vpbnf> in the end of the construction must (if present) be identical to the one in the beginning of the construction.

The <vpbnf><ScopeQualifications></vpbnf> must be of the kinds:

*{{lang2|Interfaces|Supports_Qualification|Supports Qualification}}
*{{lang2|Interfaces|Open_Qualification|Open Qualification}}

The <vpbnf><Sections></vpbnf> must be of the kinds:

*{{lang2|Constants|Constants_Sections|ConstantsSection}}
*{{lang2|Domains|Domains_Sections|DomainsSection}}
*{{lang2|Predicates|Predicates_Sections|PredicatesSection}}
*{{lang2|Predicates|Predicates_from_Interface|PredicatesFromInterface}}
*{{lang2|Properties|Properties_Sections|PropertiesSection}}
*{{lang2|Directives|Conditional_Compilation|ConditionalSection}}

All sections contained (transitively) in conditional sections must also be of those kinds.

=== The interface: object ===

If an interface does not explicitly support any interfaces, then it implicitly supports the build-in interface ''object.''

The ''object'' is an empty interface, i.e. it contains no predicates etc. The constant [[Language_Reference/Built-in_entities#null|null]] is however defined for the interface.

The purpose of ''object'' is to be a universal base-type of all objects.

=== Open Qualification ===

Open qualifications are used to make references to class level entities more convenient. The open section brings the names of one scope into another scope, so that these can be referenced without qualification.

Open has no effect on the names of object members as these can only be accessed by means of an object anyway. But names of class members, domains, functors and constants can be accessed without qualification.

When names are brought into a scope in this way it may happen that some names becomes ambiguous (see {{lang2|Basic_Concepts|Scoping_&_Visibility|Scoping}}).

Open sections have only effect in the scope in which they occur. Especially this means that an open section in a class declaration has no effect on the class implementation.

<vipbnf><OpenQualification> :
open <ScopeName>-comma-sep-list</vipbnf>

=== Supports Qualification ===

Supports qualifications can only be used in {{lang2|Interfaces|Interfaces|<vpbnf><InterfaceDefinition></vpbnf>}} and {{lang|Implementations|<vpbnf><ClassImplementation></vpbnf>}}.

Supports qualifications are used for two things:

*specifying that one interface <vp>A</vp> extends another interface <vp>B</vp> and, thereby, that the object type <vp>A</vp> is a subtype of the object type <vp>B</vp>
*declaring that the objects of a certain class "privately" have more object types, than the one specified as construction type.

<vp>supports</vp> is a transitive relation: if an interface <vp>A</vp> <vp>supports</vp> an interface <vp>B</vp> and <vp>B</vp> in turn <vp>supports</vp> <vp>C</vp>, then <vp>A</vp> also <vp>supports</vp> <vp>C</vp>.

If an interface does not explicitly support any interfaces, then it implicitly supports the predefined interface ''object''.

Functionally, it makes no difference whether an interface supports a certain interface more that once (directly and/or indirectly), but it might make a representational difference for the objects.

When <vp>supports</vp> is used in the implementation of a class, the result is that "<vp>This</vp>" not only can be used with the construction type, but also with any privately supported object type.

<vipbnf><SupportsQualification> :
supports <InterfaceName>-comma-sep-list</vipbnf>

<vpbnf><SupportsQualification></vpbnf> can only be used in {{lang2|Interfaces|Interfaces|<vpbnf><InterfaceDefinition></vpbnf>}} and {{lang|Implementations|<vpbnf><ClassImplementation></vpbnf>}}.

'''Notice''' interfaces cannot be used together in a supports qualification, if they have conflicting predicates.

Predicates are conflicting if they have the same name and the arity but different origin interfaces.

The '''''origin''''' interface of a predicate is the interface in which the predicate is literally declared, as opposed to interfaces where it is indirectly declared by a supports qualification.

So it does not give conflicts, if the same interface is met twice or more in the supports chains.

{{Example| Consider the following definitions and declarations:

<vip>interface aaa
predicates
insert : (integer X).
end interface

interface bbb
supports aaa
predicates
insert : (integer X, string Comment).
end interface

interface cc
supports aaa
predicates
extract : () -> integer.
end interface

interface dd
supports aaa, bbb, cc
predicates
extract : (string Comment) -> integer.
end interface</vip>

Here is a list of all predicates found in <vp>dd</vp> (found by a depth traversal):

<vip>predicates
insert : (integer). % dd -> aaa
insert : (integer). % dd -> bbb -> aaa
insert : (integer, string). % dd -> bbb
insert : (integer). % dd -> cc -> aaa
extract : () -> integer. % dd -> cc
extract: : (string) -> integer. % dd</vip>

Some of the predicates are the same, so all in all, <vp>dd</vp> will contain the following members:

<vip>predicates
insert : (integer). % origin interface: aaa
insert : (integer, string). % origin interface: bbb
extract : () -> integer. % origin interface: cc
extract : (string) -> integer. % origin interface: dd</vip>
}}

{{Example| Consider the following interfaces:

<vip>interface aaa
predicates
insert : (integer X).
end interface

interface bbb
predicates
insert : (integer X).
end interface

interface cc
supports aaa, bbb % conflicting interfaces
end interface</vip>

The interface <vp>cc</vp> is '''illegal''', because <vp>insert/1</vp> supported in <vp>aaa</vp> has <vp>aaa</vp> as origin, whereas <vp>insert/1</vp> supported in <vp>bbb</vp> has <vp>bbb</vp> as origin.
}}

Language Reference/Built-in entities/Constants

2025-06-23T11:50:18Z

Thomas Linder Puls: interface::null

{|{{prettytable}}
|-
|[[#compilation_date|compilation_date]]
|Compilation date.
|-
|[[#compilation_time|compilation_time]]
|Compilation time.
|-
|[[#compiler_buildDate|compiler_buildDate]]
|Build date of a compiler.
|-
|[[#compiler_version|compiler_version]]
|A compiler version.
|-
|[[#maxFloatDigits|maxFloatDigits]]
|Defines the maximal value of "digits", which is supported by the compiler.
|-
|[[#null|null]]
|The default NULL pointer.
|-
|[[#nullHandle|nullHandle]]
|A special constant of a handle type with the zero value.
|-
|[[#invalidHandle|invalidHandle]]
|A special constant of a handle type with the invalid (-1) value.
|-
|[[#platform_bits|platform_bits]]
|Defines the digital capacity of compilation platform.
|-
|[[#platform_name|platform_name]]
|Defines the target platform name.
|}

==== compilation_date ====

Compilation date. Here ''YYYY'' means the number of a year, ''MM'' means a month number, and ''DD'' means a day number.

<vip>compilation_date : string = "YYYY-MM-DD".</vip>

==== compilation_time ====

Compilation time. Here ''HH'' means hours, ''MM'' means minutes, and ''SS ''means seconds.

<vip>compilation_time : string = "HH:MM:SS".</vip>

==== compiler_buildDate ====

Build date of the compiler.

<vip>compiler_buildDate : string = "YYYY-MM-DD HH:MM".</vip>

==== compiler_version ====

A compiler version. This value depends upon the compiler version.

<vip>compiler_version = 6003.</vip>

==== maxFloatDigits ====

Defines the maximal value of "digits", which is supported by the compiler.

<vip>maxFloatDigits = 16.</vip>

==== null ====

A constant of type <vp>pointer</vp> with the value <vp>0</vp>.

<vip>null : pointer = uncheckedConvert(pointer, 0).</vip>

<vp>null</vp> is also implicitly defined on all interfaces. It is a null pointer of the type the interface has. This is how it would look if the constant was defined '''explicitly''':

<vip>
interface xxx
...
constants
null : xxx = uncheckedConvert(xxx, null). % this constant is already implicitly defined
...
end interface xxx
</vip>

{{Example|This example shows how the constant can be used in a clause.
<vip>
interface xxx
end interface xxx

...
clauses
isNullXxx(X) :-
xxx::null = X.
</vip>
}}

==== nullHandle ====

A constant of type <vp>handle</vp> with the value <vp>0</vp>.

<vip>nullHandle : handle = uncheckedConvert(handle, 0).</vip>

==== invalidHandle ====

A constant of type <vp>handle</vp> with the invalid (for a handle) value <vp>-1</vp>.

<vip>invalidHandle : handle = uncheckedConvert(handle, -1).</vip>

==== platform_bits ====

Defines the digital capacity of compilation platform.

<vip>platform_bits = 32.
or
platform_bits = 64.</vip>

==== platform_name ====

Defines the target platform name.

<vip>platform_name : string = "Windows 32bits".
or
platform_name : string = "Windows 64bits".</vip>
<noinclude>{{LanguageReferenceSubarticle|Built-in entities/Constants}}</noinclude>

Visual Prolog 11 New Features

2025-03-06T12:32:29Z

Thomas Linder Puls: /* Language */ spelling

Visual Prolog 11 has been extended with {{lang|Suspending Predicates|Suspending Predicates}}.

The development system can only run on 64 bit Windows, but can still build programs for both 32 and 64 bit Windows.

New utility "[[vipLaunch]]" for launching projects in correct IDE. The installer is included in the Visual Prolog 11 installer, but you can also install the latest version directly here [https://www.visual-prolog.com/link/vipLaunch.php vipLaunch installer].

Download Visual Prolog 11 [https://www.visual-prolog.com/link/examples.php?version=11 Demo Examples].

== Build 1105 ==

=== Language ===

* {{lang|Suspending Predicates|Suspending Predicates}}
* {{lang2|Attributes|feature|feature}} attribute, built-in predicate <vp>is_feature_available</vp>, compiler option '''/ENABLEFEature:feature_name'''
* Built-in predicates <vp>convertAllowNull</vp> and <vp>tryConvertAllowNull</vp>
* Built-in constants <interface><vp>::null</vp> for all interfaces
* Warning: explicit <vp>programmingPoint</vp> available
* Embedded string8 (utf8) support (literals and conversions)
* Warning c665 for a fact which is always initialized with a constant and is not changed (switched off by the default)
* Digit separator support (syntax only) <vp>1_000_000</vp> and <vp>0x_1A2B_3C4D</vp>

=== PFC ===

* Support for asynchronous programming by means of suspending predicates:
** New: <vp>executionContext_pool</vp> a multi threaded pool for asynchronous and background work
** New: <vp>executionContext_single</vp> a single threaded worker for asynchronous work
** New: Suspending predicates can be executed in a GUI thread (using <vp>future::submit</vp>)
** New: Diverse suspending predicate domains in <vp>core</vp>
** Updated: <vp>asyncSocket</vp> & <vp>asyncSocketListener</vp>
** Updated: master/slave support
** Updated: <vp>future</vp>/<vp>promise</vp>
** Updated: HTTP server & JSON RPC & <vp>webSocket</vp>
** Updated: <vp>webView2</vp>
** Updated: <vp>watchDirectory</vp>
** Removed: <vp>continuation</vp> class and inteface due to redundancy.
** Removed: <vp>threadpool</vp> and all related classes and interfaces due to redundancy.
** New support class: <vp>resumable</vp> class for internal support of suspending predicates
** New support classes: <vp>tp</vp> (etc) internal win32 threadpool interface for dealing with asynchronous io, timers, syncObject waiting, etc
** Deprecated/removed diverse continuation based stuff
* MSXML import free threaded xmlhttp: including <vp>iXMLHTTPRequest3</vp>
* Predicate <vp>messageBox::displayWarningYesNo_dt</vp> replacement for <vp>displayWarning_dt</vp>
* Deprecate <vp>messageBox::displayWarning_dt</vp>: UX: It is reccomended to use Yes/No warnings instead of OK/Cancel
* Color predicates <vp>blendColor</vp>, <vp>darken</vp> and <vp>lighten</vp> in <vp>gdiplus</vp>.
* <vp>fetchString8asString</vp> and <vp>useLocalTimeValue</vp> properties on <vp>odbcConnection</vp> and <vp>odbcStatement</vp>.
* <vp>delayCallLimit</vp> predicate on <vp>window</vp> for delay calls with a MaxDelay.
* <vp>inputStream_binary</vp> and <vp>outputStream_binary</vp> supports/allows ansi(utf8) mode.
* Improved <vp>outputStream</vp> performance for <vp>messageControl</vp>.
* <vp>event0</vp>, <vp>event1</vp>, ... classes: lock free threadsafe.
* 'Sergoe Fluent Icons'/'Segoe MDL2 Assets' glyph icons in ribbonControl/commands
* Explorer theme is applied to <vp>treeControl</vp> by default.
* <vp>monitorQueue</vp> and <vp>monitorQueue_length</vp> are updated with <vp>close</vp> functionality. As a result the <vp>dequeue</vp> operation has become determ.
* Console projects supports [https://docs.microsoft.com/en-us/windows/console/console-virtual-terminal-sequences Console Virtual Terminal Sequences] (by off default).
* flag <vp>jsonRpcApi{@Context}::exceptionTraceLevel</vp> controlling which/when exception dumps that are send to the client side.

=== IDE ===

* Main IDE is now always 64bit
* [[Ide/Debugger#Debug_Adapter|Debug Adapter]] makes cross-debugging to 32bit possible
* Dynamic Help (based on browse information and syntax parsing results)
* New toolbar
* vipId support
* Use new Sergoe Fluent Icons
* Default SDI project includes 'Sergoe Fluent Icons'/'Segoe MDL2 Assets' glyph icons the ribbonControl/commands
* Add variable $(node_modules)
* New Menu item handlers (move code expert to properties window)
* Alt+X converts (unicode) hex to char
* changes.htm and appData\doc\vip.chm handling
* Updated Welcome window
* splitterControl in welcome page
* Build system: pre-build command
* Automatic parallel obj/deb directories

=== Debugger ===

* Debugging now uses a [[Ide/Debugger#Debug_Adapter|Debug Adapter]]

=== Other ===

* Remove superfluous webRpc demo & update webServiceDemo to dispose the session.
* The <vp>webServiceDemo</vp> is updated to demonstrate usage of the flag <vp>jsonRpcApi{@Context}::exceptionTraceLevel</vp>.

== Build 1106 ==

=== Language ===

* Fix: Subtype presenter problem
* Fix: Stack overflow exception on binary constant allocation
* Fix: Wrong debug info for unbound variable (functor component)
* Fix: Debugger/presenters: false objects

=== PFC ===

* webView2
** Fix: Windows 7 and Windows 8 compatibility./li>
** Additional CompleteHandler handling (suspending predicates).
* Fix: <vp>ribbonControl</vp>: Release native graphics context.
* odbc: add column/parameter number for results longer than the buffer.
* <vp>window::centerTo</vp>: map to Windows parent (not pfc parent).

=== IDE ===

* <vp>webView2</vp> control show on Windows 7/8 & update build number
* show correct build number

=== Other ===

* <vp>comWrap</vp>: Handle more winRT CompleteHandlers (for webView2)
* Fix: Runtime debugger/presenters: false objects

== Build 1107 ==

=== PFC ===

* New class <vp>gcUcBuffer</vp>: for buffers that cannot be caught by false pointers.
* odbc: utilize <vp>gcUcBuffer</vp> to avoid that odbc buffers are caught by false pointers.
* New predicate <vp>clipBoard::putFileList</vp> for putting files on the clipboard in the pre-defined hDrop format.
* <vp>command</vp> and <vp>ribbonControl</vp>: new responder <vp>queryBadgeState</vp>.
* Prevent <vp>vpi::processEvents</vp> from interfering with <vp>postAction</vp> order.

=== IDE ===

* Personal edition supports 64 bit targets.
* Open external browser for registration, wiki-help and forum links.
* '''Help -> Prolog Foundation Classes (PFC)''' opens vip.chm.

=== Other ===

Fix: MemoryProfiler wrong scaling of total graph.

== Build 1108 ==

=== PFC ===

* New property <vp>remoteAddress</vp> on interface <vp>httpRequest</vp>.
* New predicate <vp>memory::mkCopy_atomic</vp> for copying structs.
* New predicates <vp>formatSocketAddress</vp> and <vp>formatSockAddr</vp> in class <vp>winSock2_api</vp>.
* <vp>winSock2_api</vp> correct and simplify various domains.

=== IDE ===

* Fix: Exceptions when git is not installed.

== Build 1110 ==

=== Language ===

* <vp>match</vp> and <vp>case</vp> has been reserved as keywords in next major release.

=== PFC ===

* Fix: Wrong type of parameter type in predicate <vp>winHttp_native::winHttpSetOption</vp> declaration.
* Fix: Eliminate race condition for <vp>postAction</vp>.
* Deprecate <vp>time::getTickCount</vp> in favour of <vp>performanceCounter</vp>'s.
* Deprecate <vp>regEx::match</vp> because <vp>match</vp> will become a keyword.

== Build 1111 ==

=== PFC ===

* Fix: time_api::getTimeZoneOffset hours -> minutes
* Fix: odbcStatement::free: allow to be called more than once
* Fix: stringFormat (gdiplus): nullary constructor must create a fresh object

=== Debugger ===

Fix: Dictionary loading timeout for large programs in debug adaptor

== Build 1112 ==

=== Language ===

* Fix: Access violation for suspending <vp>getMember_susp_nd</vp> predicate.
* Fix: Syntax error for <vp>language as</vp> with subtype bounds
* Fix: 32 bit code problem for bounded polymorphism: <vp>where Key supports unsigned64</vp>
* Fix: unification of two patterns <vp>[As, [X]] = [[X], Bs] </vp>
* Fix: Optional out for predicate defined by predicate domain
* Fix: default argument functor from domain in generic interface
* Fix: Problem locating correct predicate with arity (from different scopls)
* Fix: code generation bug for backtracking handling.

The fixes above solves the problems mentioned in [https://discuss.visual-prolog.com/viewtopic.php?f=2&t=20231 Some minor details in VIP 11 build 1111].

=== PFC ===

* Fix: window::delayCall wrong handling of Id.
* Fix: Better presenter for core::timeout.

=== Other ===

* New: More relaxed commas in parser for vipPP to auto-correct (change in vip parser)

== See also ==

See also [[Visual Prolog 11 Upgrade Notes]].

[[Category:Release Notes|11 New Features]]

Visual Prolog 11 New Features

2025-03-06T12:18:12Z

Thomas Linder Puls: Remove zip/unzip

Visual Prolog 11 has been extended with {{lang|Suspending Predicates|Suspending Predicates}}.

The development system can only run on 64 bit Windows, but can still build programs for both 32 and 64 bit Windows.

New utility "[[vipLaunch]]" for launching projects in correct IDE. The installer is included in the Visual Prolog 11 installer, but you can also install the latest version directly here [https://www.visual-prolog.com/link/vipLaunch.php vipLaunch installer].

Download Visual Prolog 11 [https://www.visual-prolog.com/link/examples.php?version=11 Demo Examples].

== Build 1105 ==

=== Language ===

* {{lang|Suspending Predicates|Suspending Predicates}}
* {{lang2|Attributes|feature|feature}} attribute, built-in predicate <vp>is_feature_available</vp>, compiler option '''/ENABLEFEature:feature_name'''
* Built-in predicates <vp>convertAllowNull</vp> and <vp>tryConvertAllowNull</vp>
* Built-in constants <interface><vp>::null</vp> for all interfaces
* Warning: explicit <vp>programmingPoint</vp> available
* Embedded string8 (utf8) support (literals and conversions)
* Warning c665 for a fact which is always initialized with a constant and is not changed (switched off by the default)
* Digit separator support (syntax only) <vp>1_000_000</vp> and <vp>0x_1A2B_3C4D</vp>

=== PFC ===

* Support for asynchronous programming by means of suspending predicates:
** New: <vp>executionContext_pool</vp> a multi threaded pool for asynchronous and background work
** New: <vp>executionContext_single</vp> a single threaded worker for asynchronous work
** New: Suspending predicates can be executed in a GUI thread (using <vp>future::submit</vp>)
** New: Diverse suspending predicate domains in <vp>core</vp>
** Updated: <vp>asyncSocket</vp> & <vp>asyncSocketListener</vp>
** Updated: master/slave support
** Updated: <vp>future</vp>/<vp>promise</vp>
** Updated: HTTP server & JSON RPC & <vp>webSocket</vp>
** Updated: <vp>webView2</vp>
** Updated: <vp>watchDirectory</vp>
** Removed: <vp>continuation</vp> class and inteface due to redundancy.
** Removed: <vp>threadpool</vp> and all related classes and interfaces due to redundancy.
** New support class: <vp>resumable</vp> class for internal support of suspending predicates
** New support classes: <vp>tp</vp> (etc) internal win32 threadpool interface for dealing with asynchronous io, timers, syncObject waiting, etc
** Deprecated/removed diverse continuation based stuff
* MSXML import free threaded xmlhttp: including <vp>iXMLHTTPRequest3</vp>
* Predicate <vp>messageBox::displayWarningYesNo_dt</vp> replacement for <vp>displayWarning_dt</vp>
* Deprecate <vp>messageBox::displayWarning_dt</vp>: UX: It is reccomended to use Yes/No warnings instead of OK/Cancel
* Color predicates <vp>blendColor</vp>, <vp>darken</vp> and <vp>lighten</vp> in <vp>gdiplus</vp>.
* <vp>fetchString8asString</vp> and <vp>useLocalTimeValue</vp> properties on <vp>odbcConnection</vp> and <vp>odbcStatement</vp>.
* <vp>delayCallLimit</vp> predicate on <vp>window</vp> for delay calls with a MaxDelay.
* <vp>inputStream_binary</vp> and <vp>outputStream_binary</vp> supports/allows ansi(utf8) mode.
* Improved <vp>outputStream</vp> performance for <vp>messageControl</vp>.
* <vp>event0</vp>, <vp>event1</vp>, ... classes: lock free threadsafe.
* 'Sergoe Fluent Icons'/'Segoe MDL2 Assets' glyph icons in ribbonControl/commands
* Explorer theme is applied to <vp>treeControl</vp> by default.
* <vp>monitorQueue</vp> and <vp>monitorQueue_length</vp> are updated with <vp>close</vp> functionality. As a result the <vp>dequeue</vp> operation has become determ.
* Console projects supports [https://docs.microsoft.com/en-us/windows/console/console-virtual-terminal-sequences Console Virtual Terminal Sequences] (by off default).
* flag <vp>jsonRpcApi{@Context}::exceptionTraceLevel</vp> controlling which/when exception dumps that are send to the client side.

=== IDE ===

* Main IDE is now always 64bit
* [[Ide/Debugger#Debug_Adapter|Debug Adapter]] makes cross-debugging to 32bit possible
* Dynamic Help (based on browse information and syntax parsing results)
* New toolbar
* vipId support
* Use new Sergoe Fluent Icons
* Default SDI project includes 'Sergoe Fluent Icons'/'Segoe MDL2 Assets' glyph icons the ribbonControl/commands
* Add variable $(node_modules)
* New Menu item handlers (move code expert to properties window)
* Alt+X converts (unicode) hex to char
* changes.htm and appData\doc\vip.chm handling
* Updated Welcome window
* splitterControl in welcome page
* Build system: pre-build command
* Automatic parallel obj/deb directories

=== Debugger ===

* Debugging now uses a [[Ide/Debugger#Debug_Adapter|Debug Adapter]]

=== Other ===

* Remove superfluous webRpc demo & update webServiceDemo to dispose the session.
* The <vp>webServiceDemo</vp> is updated to demonstrate usage of the flag <vp>jsonRpcApi{@Context}::exceptionTraceLevel</vp>.

== Build 1106 ==

=== Language ===

* Fix: Subtype presenter problem
* Fix: Stack overflow exception on binary constant allocation
* Fix: Wrong debug info for unbound variable (functor component)
* Fix: Debugger/presenters: false objects

=== PFC ===

* webView2
** Fix: Windows 7 and Windows 8 compatibility./li>
** Additional CompleteHandler handling (suspending predicates).
* Fix: <vp>ribbonControl</vp>: Release native graphics context.
* odbc: add column/parameter number for results longer than the buffer.
* <vp>window::centerTo</vp>: map to Windows parent (not pfc parent).

=== IDE ===

* <vp>webView2</vp> control show on Windows 7/8 & update build number
* show correct build number

=== Other ===

* <vp>comWrap</vp>: Handle more winRT CompleteHandlers (for webView2)
* Fix: Runtime debugger/presenters: false objects

== Build 1107 ==

=== PFC ===

* New class <vp>gcUcBuffer</vp>: for buffers that cannot be caught by false pointers.
* odbc: utilize <vp>gcUcBuffer</vp> to avoid that odbc buffers are caught by false pointers.
* New predicate <vp>clipBoard::putFileList</vp> for putting files on the clipboard in the pre-defined hDrop format.
* <vp>command</vp> and <vp>ribbonControl</vp>: new responder <vp>queryBadgeState</vp>.
* Prevent <vp>vpi::processEvents</vp> from interfering with <vp>postAction</vp> order.

=== IDE ===

* Personal edition supports 64 bit targets.
* Open external browser for registration, wiki-help and forum links.
* '''Help -> Prolog Foundation Classes (PFC)''' opens vip.chm.

=== Other ===

Fix: MemoryProfiler wrong scaling of total graph.

== Build 1108 ==

=== PFC ===

* New property <vp>remoteAddress</vp> on interface <vp>httpRequest</vp>.
* New predicate <vp>memory::mkCopy_atomic</vp> for copying structs.
* New predicates <vp>formatSocketAddress</vp> and <vp>formatSockAddr</vp> in class <vp>winSock2_api</vp>.
* <vp>winSock2_api</vp> correct and simplify various domains.

=== IDE ===

* Fix: Exceptions when git is not installed.

== Build 1110 ==

=== Language ===

* <vp>match</vp> and <vp>case</vp> has been reserved as keywords in next major release.

=== PFC ===

* Fix: Wrong type of parameter type in predicate <vp>winHttp_native::winHttpSetOption</vp> declaration.
* Fix: Eliminate race condition for <vp>postAction</vp>.
* Deprecate <vp>time::getTickCount</vp> in favour of <vp>performanceCounter</vp>'s.
* Deprecate <vp>regEx::match</vp> because <vp>match</vp> will become a keyword.

== Build 1111 ==

=== PFC ===

* Fix: time_api::getTimeZoneOffset hours -> minutes
* Fix: odbcStatement::free: allow to be called more than once
* Fix: stringFormat (gdiplus): nullary constructor must create a fresh object

=== Debugger ===

Fix: Dictionary loading timeout for large programs in debug adaptor

== Build 1112 ==

=== Language ===

* Fix: Access violation for suspending <vp>getMember_susp_nd</vp> predicate.
* Fix: Syntax error for <vp>language as</vp> with subtype bounds
* Fix: 32 bit code problem for bounded polymorphism: <vp>where Key supports unsigned64</vp>
* Fix: unification of two patters <vp>[As, [X]] = [[X], Bs] </vp>
* Fix: Optional out for predicate defined by predicate domain
* Fix: default argument functor from domain in generic interface
* Fix: Problem locating correct predicate with arity (from different scopls)
* Fix: code generation bug for backtracking handling.

The fixes above solves the problems mentioned in [https://discuss.visual-prolog.com/viewtopic.php?f=2&t=20231 Some minor details in VIP 11 build 1111].

=== PFC ===

* Fix: window::delayCall wrong handling of Id.
* Fix: Better presenter for core::timeout.

=== Other ===

* New: More relaxed commas in parser for vipPP to auto-correct (change in vip parser)

== See also ==

See also [[Visual Prolog 11 Upgrade Notes]].

[[Category:Release Notes|11 New Features]]

Shadowing PFC files

2025-02-11T16:15:46Z

Thomas Linder Puls: initial version

Sometimes you wan't to '''shadow''' one or more of the official PFC files with your own files.

Here is a way to do this in a "gentle" way.

Let us for the example assume that I want to use my own version of the <vp>list</vp> package.

Before doing anything my project tree looks like this:

[[File:Initial project tree.png|center|Initial project tree]]

My project is named '''shadow_demo''' and is located in '''D:\demo\projects\shadow_demo''' and I want to place my shadow version of the list package inside the directory '''D:\demo\shadow'''.

This original files are located in the <vp>$(ProDir)\list</vp> directory where <vp>$(ProDir)</vp> is where where my Visual Prolog is installed.

Notice that you can open a file explorer in this directory by selecting the <vp>$(ProDir)</vp> node in the project tree and select '''Explore ... (Ctrl+E)''' in its context menu.

For this "shadow" method it is important that my own files are placed in the same structure as in the original '''pfc''' directory (including the '''pfc''' level). So I copy the original '''list''' files to my the directory '''D:\demo\shadow\pfc\list'''.

I want my copied files to shadow the original pfc files and therefore I add the '''D:\demo\shadow''' directory as an '''Include Directory''' in my project (it will appear with a relative path):

[[File:Include directories shadow added.png|center|Include directories: shadow directory added]]

It is important that the '''shadow''' include directory is placed '''''above''''' the <vp>$(ProDir)</vp>, so that files found here are used instead of filed found in <vp>$(ProDir)</vp>. I.e. that they ''shadow'' the original pfc files.

At this point it is important to delete the original <vp>$(ProDir)\pfc\list\list.pack</vp> from the project otherwise you may easily end up with "Symbol redefinition" link errors:

[[File:Symbol redefinition errors.png|center|Symbol redefinition link errors]]

After I have deleted the <vp>$(ProDir)\pfc\list\list.pack</vp> file from the project and rebuild the project I was met by an "Add required " dialog:

[[File:Add required shadow list.png|center|Add required shadow list package]]

And I added the package. Now the project tree (actually, after closing and reopening the project in the IDE) looks like this:

[[File:After rebuild.png|center|After rebuild (shadow appearing in project tree)]]

The list package no longer appears in the <vp>$(ProDir)</vp> directory. But now I have a list package in '''..\..\shadow\pfc\list''' and these files will then be used instead of the original pfc files in the project. And I can modify them as I want.

[[Category:Tutorials]]

File:After rebuild.png

2025-02-11T16:14:59Z

Thomas Linder Puls: Thomas Linder Puls uploaded a new version of File:After rebuild.png

After rebuild (shadow list appearing)

File:Add required shadow list.png

2025-02-11T16:13:19Z

Thomas Linder Puls: Thomas Linder Puls uploaded a new version of File:Add required shadow list.png

Add required shadow list package

File:Symbol redefinition errors.png

2025-02-11T16:11:28Z

Thomas Linder Puls: Thomas Linder Puls uploaded a new version of File:Symbol redefinition errors.png

Symbol redefinition errors

File:Include directories shadow added.png

2025-02-11T16:09:04Z

Thomas Linder Puls: Thomas Linder Puls uploaded a new version of File:Include directories shadow added.png

Include directories shadow directory added

File:Initial project tree.png

2025-02-11T16:06:52Z

Thomas Linder Puls: Thomas Linder Puls uploaded a new version of File:Initial project tree.png

Initial project tree

File:Include directories shadow added.png

2025-02-11T16:01:33Z

Thomas Linder Puls: Thomas Linder Puls uploaded a new version of File:Include directories shadow added.png

Include directories shadow directory added

File:Symbol redefinition errors.png

2025-02-11T15:34:24Z

Thomas Linder Puls:

Symbol redefinition errors

File:After rebuild.png

2025-02-11T15:18:51Z

Thomas Linder Puls:

After rebuild (shadow list appearing)

File:Add required shadow list.png

2025-02-11T15:16:51Z

Thomas Linder Puls:

Add required shadow list package

File:Include directories shadow added.png

2025-02-11T15:13:25Z

Thomas Linder Puls:

Include directories shadow directory added

File:Initial project tree.png

2025-02-11T15:10:02Z

Thomas Linder Puls:

Initial project tree

Visual Prolog 11 New Features

2025-02-03T12:07:43Z

Thomas Linder Puls: Build 1112

Visual Prolog 11 has been extended with {{lang|Suspending Predicates|Suspending Predicates}}.

The development system can only run on 64 bit Windows, but can still build programs for both 32 and 64 bit Windows.

New utility "[[vipLaunch]]" for launching projects in correct IDE. The installer is included in the Visual Prolog 11 installer, but you can also install the latest version directly here [https://www.visual-prolog.com/link/vipLaunch.php vipLaunch installer].

Download Visual Prolog 11 [https://www.visual-prolog.com/link/examples.php?version=11 Demo Examples].

== Build 1105 ==

=== Language ===

* {{lang|Suspending Predicates|Suspending Predicates}}
* {{lang2|Attributes|feature|feature}} attribute, built-in predicate <vp>is_feature_available</vp>, compiler option '''/ENABLEFEature:feature_name'''
* Built-in predicates <vp>convertAllowNull</vp> and <vp>tryConvertAllowNull</vp>
* Built-in constants <interface><vp>::null</vp> for all interfaces
* Warning: explicit <vp>programmingPoint</vp> available
* Embedded string8 (utf8) support (literals and conversions)
* Warning c665 for a fact which is always initialized with a constant and is not changed (switched off by the default)
* Digit separator support (syntax only) <vp>1_000_000</vp> and <vp>0x_1A2B_3C4D</vp>

=== PFC ===

* Support for asynchronous programming by means of suspending predicates:
** New: <vp>executionContext_pool</vp> a multi threaded pool for asynchronous and background work
** New: <vp>executionContext_single</vp> a single threaded worker for asynchronous work
** New: Suspending predicates can be executed in a GUI thread (using <vp>future::submit</vp>)
** New: Diverse suspending predicate domains in <vp>core</vp>
** Updated: <vp>asyncSocket</vp> & <vp>asyncSocketListener</vp>
** Updated: master/slave support
** Updated: <vp>future</vp>/<vp>promise</vp>
** Updated: HTTP server & JSON RPC & <vp>webSocket</vp>
** Updated: <vp>webView2</vp>
** Updated: <vp>watchDirectory</vp>
** Removed: <vp>continuation</vp> class and inteface due to redundancy.
** Removed: <vp>threadpool</vp> and all related classes and interfaces due to redundancy.
** New support class: <vp>resumable</vp> class for internal support of suspending predicates
** New support classes: <vp>tp</vp> (etc) internal win32 threadpool interface for dealing with asynchronous io, timers, syncObject waiting, etc
** Deprecated/removed diverse continuation based stuff
* MSXML import free threaded xmlhttp: including <vp>iXMLHTTPRequest3</vp>
* Predicate <vp>messageBox::displayWarningYesNo_dt</vp> replacement for <vp>displayWarning_dt</vp>
* Deprecate <vp>messageBox::displayWarning_dt</vp>: UX: It is reccomended to use Yes/No warnings instead of OK/Cancel
* Color predicates <vp>blendColor</vp>, <vp>darken</vp> and <vp>lighten</vp> in <vp>gdiplus</vp>.
* <vp>fetchString8asString</vp> and <vp>useLocalTimeValue</vp> properties on <vp>odbcConnection</vp> and <vp>odbcStatement</vp>.
* <vp>delayCallLimit</vp> predicate on <vp>window</vp> for delay calls with a MaxDelay.
* <vp>inputStream_binary</vp> and <vp>outputStream_binary</vp> supports/allows ansi(utf8) mode.
* Improved <vp>outputStream</vp> performance for <vp>messageControl</vp>.
* <vp>event0</vp>, <vp>event1</vp>, ... classes: lock free threadsafe.
* 'Sergoe Fluent Icons'/'Segoe MDL2 Assets' glyph icons in ribbonControl/commands
* Explorer theme is applied to <vp>treeControl</vp> by default.
* <vp>monitorQueue</vp> and <vp>monitorQueue_length</vp> are updated with <vp>close</vp> functionality. As a result the <vp>dequeue</vp> operation has become determ.
* Console projects supports [https://docs.microsoft.com/en-us/windows/console/console-virtual-terminal-sequences Console Virtual Terminal Sequences] (by off default).
* flag <vp>jsonRpcApi{@Context}::exceptionTraceLevel</vp> controlling which/when exception dumps that are send to the client side.

=== IDE ===

* Main IDE is now always 64bit
* [[Ide/Debugger#Debug_Adapter|Debug Adapter]] makes cross-debugging to 32bit possible
* Dynamic Help (based on browse information and syntax parsing results)
* New toolbar
* vipId support
* Use new Sergoe Fluent Icons
* Default SDI project includes 'Sergoe Fluent Icons'/'Segoe MDL2 Assets' glyph icons the ribbonControl/commands
* Add variable $(node_modules)
* New Menu item handlers (move code expert to properties window)
* Alt+X converts (unicode) hex to char
* changes.htm and appData\doc\vip.chm handling
* Updated Welcome window
* splitterControl in welcome page
* Build system: pre-build command
* Automatic parallel obj/deb directories

=== Debugger ===

* Debugging now uses a [[Ide/Debugger#Debug_Adapter|Debug Adapter]]

=== Other ===

* Remove superfluous webRpc demo & update webServiceDemo to dispose the session.
* The <vp>webServiceDemo</vp> is updated to demonstrate usage of the flag <vp>jsonRpcApi{@Context}::exceptionTraceLevel</vp>.
* Add zip / unzip functionality

== Build 1106 ==

=== Language ===

* Fix: Subtype presenter problem
* Fix: Stack overflow exception on binary constant allocation
* Fix: Wrong debug info for unbound variable (functor component)
* Fix: Debugger/presenters: false objects

=== PFC ===

* webView2
** Fix: Windows 7 and Windows 8 compatibility./li>
** Additional CompleteHandler handling (suspending predicates).
* Fix: <vp>ribbonControl</vp>: Release native graphics context.
* odbc: add column/parameter number for results longer than the buffer.
* <vp>window::centerTo</vp>: map to Windows parent (not pfc parent).

=== IDE ===

* <vp>webView2</vp> control show on Windows 7/8 & update build number
* show correct build number

=== Other ===

* <vp>comWrap</vp>: Handle more winRT CompleteHandlers (for webView2)
* Fix: Runtime debugger/presenters: false objects

== Build 1107 ==

=== PFC ===

* New class <vp>gcUcBuffer</vp>: for buffers that cannot be caught by false pointers.
* odbc: utilize <vp>gcUcBuffer</vp> to avoid that odbc buffers are caught by false pointers.
* New predicate <vp>clipBoard::putFileList</vp> for putting files on the clipboard in the pre-defined hDrop format.
* <vp>command</vp> and <vp>ribbonControl</vp>: new responder <vp>queryBadgeState</vp>.
* Prevent <vp>vpi::processEvents</vp> from interfering with <vp>postAction</vp> order.

=== IDE ===

* Personal edition supports 64 bit targets.
* Open external browser for registration, wiki-help and forum links.
* '''Help -> Prolog Foundation Classes (PFC)''' opens vip.chm.

=== Other ===

Fix: MemoryProfiler wrong scaling of total graph.

== Build 1108 ==

=== PFC ===

* New property <vp>remoteAddress</vp> on interface <vp>httpRequest</vp>.
* New predicate <vp>memory::mkCopy_atomic</vp> for copying structs.
* New predicates <vp>formatSocketAddress</vp> and <vp>formatSockAddr</vp> in class <vp>winSock2_api</vp>.
* <vp>winSock2_api</vp> correct and simplify various domains.

=== IDE ===

* Fix: Exceptions when git is not installed.

== Build 1110 ==

=== Language ===

* <vp>match</vp> and <vp>case</vp> has been reserved as keywords in next major release.

=== PFC ===

* Fix: Wrong type of parameter type in predicate <vp>winHttp_native::winHttpSetOption</vp> declaration.
* Fix: Eliminate race condition for <vp>postAction</vp>.
* Deprecate <vp>time::getTickCount</vp> in favour of <vp>performanceCounter</vp>'s.
* Deprecate <vp>regEx::match</vp> because <vp>match</vp> will become a keyword.

== Build 1111 ==

=== PFC ===

* Fix: time_api::getTimeZoneOffset hours -> minutes
* Fix: odbcStatement::free: allow to be called more than once
* Fix: stringFormat (gdiplus): nullary constructor must create a fresh object

=== Debugger ===

Fix: Dictionary loading timeout for large programs in debug adaptor

== Build 1112 ==

=== Language ===

* Fix: Access violation for suspending <vp>getMember_susp_nd</vp> predicate.
* Fix: Syntax error for <vp>language as</vp> with subtype bounds
* Fix: 32 bit code problem for bounded polymorphism: <vp>where Key supports unsigned64</vp>
* Fix: unification of two patters <vp>[As, [X]] = [[X], Bs] </vp>
* Fix: Optional out for predicate defined by predicate domain
* Fix: default argument functor from domain in generic interface
* Fix: Problem locating correct predicate with arity (from different scopls)
* Fix: code generation bug for backtracking handling.

The fixes above solves the problems mentioned in [https://discuss.visual-prolog.com/viewtopic.php?f=2&t=20231 Some minor details in VIP 11 build 1111].

=== PFC ===

* Fix: window::delayCall wrong handling of Id.
* Fix: Better presenter for core::timeout.

=== Other ===

* New: More relaxed commas in parser for vipPP to auto-correct (change in vip parser)

== See also ==

See also [[Visual Prolog 11 Upgrade Notes]].

[[Category:Release Notes|11 New Features]]

Thread safety in Visual Prolog

2024-11-05T09:45:09Z

Thomas Linder Puls: mapM/setM

Thread safe:

* Access facts

'''Not''' thread safe:

* GUI
* Streams
* odbcConnection/odbcStatement

=== Facts ===

See [[Threadsafe facts]].

=== GUI ===

Windows GUI is not thread safe, only the thread that runs the message pump of a window should accees that window. In Visual Prolog all windows (except modal dialogs) belong to the thread that have executed the <vp>vpi::init</vp> call.

Synchronization back to the GUI thread can be done using '''window::postAction''', because the posted action will be executed by the GUI thread.

Modal dialogs run their own message pump and they are therefore owned by the thread that displays them.

=== Streams ===

Streams are in general not thread safe, but specific streams can be.

From Visual Prolog 7.4 the thread on <vp>messageControl</vp>s are thread safe. In a GUI application stdio will thus be thread safe while it is redirected to a <vp>messageControl</vp>/<vp>messageForm</vp>, but if it is redirected to some other stream it will "inherit" the thread safety from that stream.

=== ODBC ===

An <vp>odbcConnection</vp>/<vp>odbcStatement</vp> is not thread safe, but different <vp>odbcConnection</vp>'s/<vp>odbcStatement</vp>'s can be accessed in parallel.

=== mapM and setM ===

<vp>mapM</vp> and <vp>setM</vp> each exist in two threadsafe versions. Here we will just consider the mapM versions (the setM behaves completely similarly). Most operations on red-black trees are already threadsafe. The classes mentioned here ensures that updates are "sound": If you set/add/delete something it will in fact be set/added/deleted.

<vp>mapM_redBlack_cas</vp> uses <vp>compareAndSwap</vp> (see also [https://learn.microsoft.com/en-us/windows/win32/api/winnt/nf-winnt-interlockedcompareexchange InterlockedCompareExchange]). If two threads are updating the map simultaneously there is a chance that one of the <vp>compareAndSwap</vp> will fail (the swap only takes place if the current tree is the same that this thread updated). If that happens the operation will be performed once more on what is now the current tree.

<vp>mapM_redBlack_block</vp> uses a <vp>multiThread_native::srwLock</vp> (see also [https://learn.microsoft.com/en-us/windows/win32/sync/slim-reader-writer--srw--locks Slim Reader/Writer (SRW) Locks]) to block threads that tries to update the map while another thread is already updating the thread.

So in case of collisions the <vp>mapM_redBlack_cas</vp> will use extra resources (CPU, memory allocations, etc) whereas the <vp>mapM_redBlack_block</vp> will block a thread instead. If there are few collision then the <vp>_cas</vp> version will not waste much time and no threads will be blocked and involve the operating systems thread scheduling mechanism. If there are many collisions then the <vp>_block</vp> version will go easy on CPU, memory and instead involve the task scheduling mechanism.

Notice that if you have really many collisions then you have a problem in any case, because then your threads will either spend resources or wait all the time. In the first case there will be a large load on you computer, in the second case the benefit you hoped for using many threads will disappear in waiting.

[[Category:Multi-threading]]
[[Category:GUI]]
[[Category:ODBC]]

Master/slave processes

2024-10-15T11:32:21Z

Thomas Linder Puls: review

The PFC master/slave process concept can be used for a number of reasons:

* To make computations in parallel
* To isolate computations from each other
* To manage independent subprocesses

=== Master/slave concepts ===

Master/slave processes are organized hierarchically:

* A master process can have several slave processes
* Each slave process has exactly one master process.
* A slave process can be master process of other slave processes.

The '''master''' process spawns and owns the '''slave''' processes.

A master and slave process can communicate with each other using remote procedure calls and notifications. All communication is serialized on pipes that are established between the master and the slave.

The communication is (quite) transparent to the programs, in the master process the slave is represented by a proxy object; calls and notifications from the master to the slave is performed by invoking methods on the proxy object. Likewise the master is represented by a proxy object in the slave and calls and notifications from slave to master are made on the proxy object.

All methods are asynchronous (using an <vp>executionContext_pool</vp> as execution context), so {{lang|Suspending Predicates|suspending predicates}} must be applied. And synchronization to non-threadsafe structures must be used. <vp>postAction</vp> will have to be used to switch execution context to the GUI thread for GUI operations (and in many applications for safe access to program state).

The master/slave process concept is illustrated by a demo project. In the demo project the master is a builder similar to the '''vipBuilder'''. This master spawns a number of compiler/slave processes.

The demo is academic in the sense that nothing is really build; the "compilers" merely simulate that they do something.

Notice that the demo program uses the name space <vp>compiler_ms</vp> for interfaces and classes used in the process interface. For simplicity the name space declarations are not included in this article.

The compiler/slave has this interface:

<vip>
interface slave
open core
[pfc\masterSlaveProcess::slave]

domains
compile_rsp = compile_rsp(integer LineCount, integer Errors, durationValue CompilationTime).

predicates
compile : (string Filename) -> compile_rsp CompileResult suspending.

predicates
setSettings : (string Settings) -> unit suspending.

end interface slave
</vip>

Notice that in this academic example the interface name is <vp>slave</vp>. In a real program it would be more natural to call it e.g. <vp>compiler_slave</vp>.

We will consider the details of this interface below, currently the interesting thing is that it defines procedures <vp>compile</vp> and <vp>setSettings</vp>. Notice that they are {{lang|Suspending Predicates|suspending predicates}}.

When the master spawn this slave it will call the <vp>setSettings</vp> to inform the slave about settings (i.e. corresponding to the command line flags , etc of a regular compiler). And then it will call <vp>compile</vp> on a file and when that operation completes it will (potentially) call <vp>compile</vp> again on another file. The master will continue this until there are no more files to compile and then it will terminate the slave.

Actually, the master will spawn a number of slaves, so that several files can be compiled in parallel.

The master has this interface towards the slave:

<vip>
interface master
[pfc\masterSlaveProcess::master]

domains
compilerMessage_ntf = compilerMessage_ntf(string File, integer Line, string Message).

predicates
compilerMessage : (compilerMessage_ntf Message).

end interface master
</vip>

This interface only contains a single notification <vp>compilerMessage</vp> through which the compiler can notify the master with messages from the compilation, while the compilation takes place. Notice that this predicate is not a suspending predicate, this is because notifications completely asynchronous in the sense that no result is returned to the slave and the slave does not wait for the notification to be handled. Be aware that additional notifications and final results can arrive before other notifications has been handled. This may lead to race conditions, and if they are not acceptable you should use a suspending predicate/function instead.

There are restrictions on these interfaces:

* They can contain one-input-one-output {{lang|Suspending Predicates|suspending function}}
* They can contain one-input notification predicates
* They cannot contain any other kind of predicates
* The input and output of the procedures and notifications must be serializable

These two interfaces describes the master/slave process interface.

To make the system complete the following things must be implemented:

* A proxy class must be implemented for each of these interfaces
* The slave must implement the <vp>slave</vp> interface
* The master must implement the <vp>master</vp> interface as a context to the slave proxy

The following is also necessary, but that is handled by PFC classes:

* The subprocess creation
* The creation of communication pipes
* The serialization/deserialization, communication and dispatching of data/messages

The implementation of the proxy classes are quite simple as described in the next sections.

=== slaveProcess ===

For the master process we will need a proxy representing the slave process, the interface of this proxy looks like this:

<vip>
interface slaveProcess supports slave, useExe

predicates from pfc\masterSlaveProcessSupport
terminate_toRemote

end interface slaveProcess
</vip>

It supports the <vp>slave</vp> interface (which is the main proxy facility). It also supports <vp>useExe</vp> which is the PFC standard interface for subprocesses and finally it also contains the predicate <vp>terminate_toRemote</vp> which is used internally to terminate the slave process.

The class declaration of the <vp>slaveProcess</vp> looks like this:

<vip>
class slaveProcess : slaveProcess

constructors
new : (string SlaveProgram, master Master, string CmdLine).

end class slaveProcess
</vip>

The <vp>Master</vp> is the implementation of the <vp>master</vp> interface that the slave will communicate with. I.e. it is the master's implementation of the <vp>master</vp> interface.

The implementation of the <vp>slaveProcess</vp> looks like this:

<vip>
implement slaveProcess inherits slaveProcessSupport
open pfc\

clauses
new(SlaveProgram, Master, CmdLine) :-
slaveProcessSupport::new(SlaveProgram, CmdLine),
register_notify("compilerMessage", Master:compilerMessage).

clauses
compile(Filename) = call_toRemote(predicate_name(), Filename).

clauses
setSettings(Settings) = call_toRemote(predicate_name(), Settings).

end implement slaveProcess
</vip>

The implementation inherits from <vp>slaveProcessSupport</vp> which is initialized with a "path" to the <vp>SlaveProgram</vp>.

The implementation must also register all calls and notifications of the <vp>master</vp> interface. In this case it is just the <vp>compilerMessage</vp> notification.

Finally, the implementation contains a proxy method for each of the calls and notifications in the <vp>slave</vp> interface.

You will notice that registration as well as proxy methods is trivial code.

=== masterProxy ===

For the slave process we will need a proxy representing the <vp>master</vp> interface provided by the master. The interface of this proxy looks like this:

<vip>
interface masterProxy supports master

properties from pfc\masterSlaveProcessSupport
fromLoop

end interface masterProxy
</vip>

It simply supports the <vp>master</vp> interface and provides a <vp>fromLoop</vp> predicate that must be invoked to receive communication from the master. We will return to this predicate below.

The class declaration of the <vp>masterProxy</vp> looks like this:

<vip>
class masterProxy : masterProxy

constructors
new : (slave Slave, string MsPipe).

end class masterProxy
</vip>

The constructor takes the implementation of the <vp>slave</vp> interface as argument and the name of a <vp>MsPipe</vp> to use for communication. The implementation of the <vp>masterProxy</vp> looks like this:

<vip>
implement masterProxy inherits masterProxySupport
open pfc\

clauses
new(Slave, MsPipe) :-
register_call("compile", Slave:compile),
register_call("setSettings", Slave:setSettings),
masterProxySupport::new(MsPipe).

clauses
compilerMessage(Message) :-
notify_wait_toRemote(predicate_name(), Message).

end implement masterProxy
</vip>

It inherits from <vp>masterProxySupport</vp> and contains registration of all <vp>slave</vp> calls and notifications, and proxy implantations of all <vp>master</vp> calls and notifications.

=== The master program ===

The master program (i.e. the builder) is a console program that

* compiles a set of files
* using a number of slave-compilers and
* writes the messages from the compilers to the console.

Finally after all compilation is completed it will write some statistics to the console.

This is done by the <vp>compiler::compileFiles</vp> predicate

<vip>
class compiler : compiler
open core
[noDefaultConstructor]

predicates
compileFiles : (string SlaveProgram, string Settings, setM{string} Files, positive ProcessCount, boolean Debug)
-> pfc\asynchronous\future{string} Result.

end class compiler
</vip>

As you can see the <vp>compiler</vp> class can actually (privately) create objects of type <vp>compiler</vp>. Each of these objects represents a compiler subprocess, but the management of these are kept privately in the implementation of the <vp>compiler</vp> class.

The <vp>compiler</vp> interface declares a <vp>compileFiles2</vp> predicate:

<vip>
interface compiler

predicates
compileFiles2 : (string Settings, setM{string} Files) -> pfc\asynchronous\future{compiler_ms\slave::compile_rsp} Result.

end interface compiler
</vip>

As you can see it uses a <vp>future</vp>, which is an important part of submitting suspending predicates for execution. The implementation looks like this:

<vip>
implement compiler
supports master
open core, compiler_ms\, slave, pfc\asynchronous\

class facts
cs : criticalSection := criticalSection::new(1000) [constant, immediate].

clauses
compileFiles(SlaveProgram, Settings, Files, ProcessCount, Debug) = R :-
ProcessCount2 = math::min(list::length(Files:asList), ProcessCount),
CL =
[ new(SlaveProgram, D) ||
C = std::cIterate(ProcessCount2),
D = Debug ** toBoolean(C = 0)
],
RL = [ C:compileFiles2(Settings, Files) || C in CL ],
FC = future::fold(RL, plus, compilerResult_zero),
R = FC:futureExtension::map(asString).

facts
slave : slaveProcess.

constructors
new : (string SlaveProgram, boolean Debug).
clauses
new(SlaveProgram, Debug) :-
CmdLine = if true = Debug then "-debug" else "" end if,
slave := slaveProcess::new(SlaveProgram, This, CmdLine),
slave:setNativeCreationFlags(multiThread_native::idle_priority_class),
slave:run().

clauses
compileFiles2(Settings, Files) =
future::submit(
{ = R :-
setSettings(Settings),
R = doCompileFiles(Files, compilerResult_zero)
}).

predicates
setSettings : (string Settings) suspending.
clauses
setSettings(Settings) :-
_ = slave:setSettings(Settings).

predicates
doCompileFiles : (setM{string} Files, compile_rsp Acc) -> compile_rsp OnCompileResult suspending.
clauses
doCompileFiles(Files, Acc) = CompileResult :-
if File = Files:tryRemoveFirst() then
CR = slave:compile(File),
cs:synchronize({ :- stdio::writef(" %s %s\n", File, CR:asString()) }),
CompileResult = doCompileFiles(Files, Acc:plus(CR))
else
slave:terminate_toRemote(),
CompileResult = Acc
end if.

constants
compilerResult_zero : compile_rsp = compile_rsp(0, 0, 0).

class predicates
asString : (compile_rsp CompileResponse [this]) -> string.
clauses
asString(compile_rsp(LineCount, Errors, CompilationTime)) =
string::format("% lines in %p % erros", LineCount, duration::new(CompilationTime), Errors).

class predicates
plus : (compile_rsp A [this], compile_rsp B) -> compile_rsp C.
clauses
plus(compile_rsp(AL, BL, CL), compile_rsp(AR, BR, CR)) = compile_rsp(AL + AR, BL + BR, CL + CR).

% master
clauses
compilerMessage(compilerMessage_ntf(File, Line, Message)) :-
cs:synchronize({ :- stdio::writef(" %s(%d): %s\n", File, Line, Message) }).

end implement compiler
</vip>

The asynchronous method in the master/slave concept is based on suspending predicates. It is outside the scope of this article to go fully into details about asynchronous programming, suspending predicates and <vp>future</vp>s/<vp>promise</vp>s.
Here we want the main thread to wait for the result of a number of compilers it has started, and for such combined waiting and result summing, we will use <vp>future</vp>s.

The main predicate (<vp>compileFiles</vp>) will start a number of <vp>slave</vp> programs, and submit compilation "job" (<vp>compileFiles2</vp>) for each of these <vp>slave</vp>s. The submission of such a job is represented by a <vp>future</vp> which will return the result some time in the "future". The results of all these <vp>future</vp>s are folded into a single future, which in turn is "mapped" to a string.

<vip>
clauses
compileFiles(SlaveProgram, Settings, Files, ProcessCount, Debug) = R :-
ProcessCount2 = math::min(list::length(Files:asList), ProcessCount),
CL =
[ new(SlaveProgram, D) ||
C = std::cIterate(ProcessCount2),
D = Debug ** toBoolean(C = 0)
],
RL = [ C:compileFiles2(Settings, Files) || C in CL ],
FC = future::fold(RL, plus, compilerResult_zero),
R = FC:futureExtension::map(asString).
</vip>

As you can see simple processing is a bit more complicated when futures are involved. But predicates like <vp>future::fold</vp> deals with a number of things: First of all it combines the results, but it also deals with asynchronous (as well as synchronous) waiting on the individual results, and in case some of the involved sub jobs completes with an exception it will also handle cancellation of the remaining sub jobs.

The predicate <vp>compileFiles2</vp> submits a compilation "job" to be executed in the default <vp>executionContext</vp>; which in this case will be <vp>executionContext_pool::defaultPool</vp>:

<vip>
clauses
compileFiles2(Settings, Files) =
future::submit(
{ = R :-
setSettings(Settings),
R = doCompileFiles(Files, compilerResult_zero)
}).
</vip>

The result is a <vp>future</vp>.

The suspending predicate <vp>doCompileFiles</vp> contains the heart loop of the compilation. Each started compiler will be controlled with a <vp>doCompileFiles</vp> loop:

<vip>
predicates
doCompileFiles : (setM{string} Files, compile_rsp Acc) -> compile_rsp OnCompileResult suspending.
clauses
doCompileFiles(Files, Acc) = CompileResult :-
if File = Files:tryRemoveFirst() then
CR = slave:compile(File),
cs:synchronize({ :- stdio::writef(" %s %s\n", File, CR:asString()) }),
CompileResult = doCompileFiles(Files, Acc:plus(CR))
else
slave:terminate_toRemote(),
CompileResult = Acc
end if.
</vip>

The loop will try to remove a <vp>File</vp> to compile from the <vp>Files</vp> to compile. Since several loops will do this in parallel it is important that <vp>tryRemoveFirst</vp> is thread safe. In this example this is ensured by using a <vp>setM_redBlack_cas</vp> (i.e. a ''compare and swap'' red black set; see the <vp>main::run</vp> implementation).

If a <vp>File</vp> can be removed from the set the <vp>slave</vp> is asked to <vp>compile</vp> it (asynchronous using a <vp>continuation</vp>). When the compilation is completed, we will write the result to stdio and loop to <vp>doCompileFiles</vp> again.

This will continue until <vp>Files</vp> becomes empty in which case the <vp>slave</vp> is informed to terminate (<vp>slave:terminate_toRemote()</vp>), and the accumulated result is returned.

The <vp>master</vp> also supports the <vp>compilerMessage</vp> notification:

<vip>
clauses
compilerMessage(compilerMessage_ntf(File, Line, Message)) :-
cs:synchronize({ :- stdio::writef(" %s(%d): %s\n", File, Line, Message) }).
</vip>

In our case it simply writes the messages to the standard output stream.

=== The slave program ===

The slave program is also a console program. But it is very important to notice that the slave does not have a console window attached and that the console can therefore '''''not''''' be used for input/output.

In this slave program everything interesting is packed into the implementation of <vp>theCompiler</vp>:

<vip>
implement theCompiler inherits masterProxy
supports slave
open core, compiler_ms\, master, pfc\asynchronous\

facts
settings : string := "".

clauses
run(MsPipe) :-
new(MsPipe):wait().

clauses
wait() :-
_ = fromLoop:futureExtension::get().

constructors
new : (string MsPipe).
clauses
new(MsPipe) :-
masterProxy::new(This, MsPipe).

clauses
compile(Filename) = compile_rsp(Lines, Errors:value, D:get()) :-
T1 = time::now(),
Errors = varM_integer::new(),
Lines = 20 + math::random(3000),
foreach I = std::cIterate(Lines) + 1 and not(executionContext::isCanceled()) do
foreach _ = std::cIterate(math::random(10000)) do
end foreach,
R = math::random(),
if R < 1 / 2000 then
Errors:inc(),
compilerMessage(compilerMessage_ntf(Filename, I, settings))
end if
end foreach,
D = duration::new(T1, time::now()).

clauses
setSettings(Settings) = unit :-
settings := Settings.

end implement theCompiler
</vip>

<vp>theCompiler</vp> implements the <vp>slave</vp> interface which it pass as argument to the constructor of the <vp>masterProxy</vp> object, thereby the communication and message loops are established.

Recall that <vp>compile</vp> and <vp>setSettings</vp> are suspending predicates.

<vp>compile</vp> performs a simple dummy simulation a compiler, by using CPU, returning messages and a final result.
The simulation "compiles" a random number of lines each with a certain probability to issue a compilerMessage which is notified back to the <vp>master</vp> (i.e. through the proxy object).

The compilation also test for termination request from the master (i.e. <vp>not(executionContext::isCanceled())</vp>), this test would actually only be relevant if the compilation was terminated in the middle of compilation which this example will never do. But when compiling files from an IDE it is custom to have a "stop compilation" facility. This facility could wait all compilers to ask for the next file to compile and terminate them there, but it could also send a terminate request to the slave, in which case the fromLoop would complete.

In this program the main thread will simply <vp>wait</vp>s for the termination of the <vp>fromLoop</vp>.

[[Category:Tutorials]]

Visual Prolog for Tyros

2024-09-25T20:56:43Z

Thomas Linder Puls: lineshift

{{ambox|text= This book is about an '''old''' version of Visual Prolog. We do not provide licenses for that version anymore.
The book may still be useful to you.}}

''Visual Prolog for Tyros'' is a comprehensive book written by ''Eduardo Costa''.

It is a good starting point to study Visual Prolog. And it might be used by teachers for education.

The latest edition of the book is "Visual Prolog 7.3 for Tyros".

The book includes a number of examples illustrating different features of Visual Prolog.

=== Contents ===

'''I Savoir-faire'''

# Introduction
# Forms
# Mouse events
# Less Figures
# Horn Clauses
# Console Applications
# Grammars
# Painting
# Data types
# How to solve it in Prolog
# Facts
# Classes and Objects
# Giuseppe Peano
# L-Systems
# Games
# Animation
# Text Editor
# Printing
# Tab forms and other goodies
# Bugs
# A Data Base Manager
# Books and articles

'''II Artificial Intelligence'''

# Search
# Neural Networks
# Alpha Beta Pruning

=== Download ===

* [https://www.visual-prolog.com/download/73/books/tyros/tyros73.pdf Visual Prolog 7.3 for Tyros] (September, 2010, PDF).

=== Examples from the book ===

* For [https://www.visual-prolog.com/download/73/books/tyros/tyros73.zip Visual Prolog 7.3] (zip).
* For [https://www.visual-prolog.com/download/72/books/tyros/tyros72.zip Visual Prolog 7.2] (zip).
* For [https://www.visual-prolog.com/download/71/Costas-Tyros.zip Visual Prolog 7.1] (zip).

=== Translations ===

* [https://wikiru.visual-prolog.com/index.php?title=Visual_Prolog_for_Tyros Russian]
* [[Visual Prolog for Tyros in Chinese|Chinese]]

[[ru:Visual Prolog для чайников]]
[[Category:Books]]

A Beginners Guide to Visual Prolog

2024-09-25T20:56:01Z

Thomas Linder Puls: notice

__NOTOC__

{{ambox|text=This book is about an '''old''' version of Visual Prolog. We do not provide licenses for that version anymore.

The book may still be useful to you, and the examples are in the current version of Visual Prolog}}

''A Beginners' Guide to Visual Prolog'' is a comprehensive book for absolute beginners written by ''Thomas W. de Boer''.

The book contains already published material, which is used with permision of the authors.

The latest version of the book is devoted to Visual Prolog 7.2, but the principles are still more or less the same.

This book is an introduction. It is meant it is for people, who know little about programming. You should know the basics about computers and that it is possible to program them and that for a program you use a programming language.

What when you know more? Then you should look for other sources.

* When you are programmer and know about other languages like Visual Basic or C##, read the book [[Visual Prolog for Tyros]] by Eduardo Costa.

* When you know about other languages and are curious about Prolog, read the basic the [[:Category:Tutorials|Tutorials]].

* When you have experience in Prolog programming, look for details about Visual Prolog, object orientation in the [[:Category:Tutorials|Tutorials]] section of this site and Visual Prolog [[Language Reference]].

=== Contents ===

# The Integrated Development Environment
# Forms
# Simple user interfacing
# A closer look at the IDE
# Fundamental Prolog
# Data modeling in Prolog
# Using Forms or Dialogs and Controls: a minimal database
# Object oriented programming - classes and objects
# Declarations in Visual Prolog
# Recursion, lists and sorting
# Reading, writing, streams and files
# More data structures: Stacks, Queues and Trees

'''Appendices'''

# Everything about Dialogs and Forms
# List manipulating predicates

=== Download ===
* [https://www.visual-prolog.com/download/72/books/deBoer/VisualPrologBeginners.pdf A Beginners' Guide to Visual Prolog 7.2] (PDF format, English 279 pages).

==== Examples from the book ====
* For [https://www.visual-prolog.com/download/9/books/deBoer/deBoer-BeginnersGuide-examples.zip Visual Prolog 9] (ZIP format, 280 KB).
* For [https://www.visual-prolog.com/download/73/books/deBoer/deBoer-BeginnersGuide-examples.zip Visual Prolog 7.3] (ZIP format, 440 KB).
* For [https://www.visual-prolog.com/download/72/books/deBoer/deBoer-BeginnersGuide-examples.zip Visual Prolog 7.2] (ZIP format, 437 KB).

=== See also ===
[[A Beginners Guide to Visual Prolog in Chinese]]

[[Category:Books]]

Visual Prolog for Tyros

2024-09-25T20:51:40Z

Thomas Linder Puls: notice

Visual Prolog Examples

2024-09-16T13:35:28Z

Thomas Linder Puls: Thomas Linder Puls moved page Visual Prolog Examples to Visual Prolog Demo Examples

#REDIRECT [[Visual Prolog Demo Examples]]

Visual Prolog Demo Examples

2024-09-16T13:35:28Z

Thomas Linder Puls: Thomas Linder Puls moved page Visual Prolog Examples to Visual Prolog Demo Examples

{{ideNavbar|IDE Projects}}

You can download the latest Visual Prolog [https://www.vusual-prolog.com/link/demo.php demo projects].

Notice that some demo programs may require the Commercial Edition. The build system will inform you if that is the case.

If you a newer Commercial Editoion you license file will contain a link to the demo programs correcponding to your version.

For the Personal Edition you can only obtain the "current" version of demos, but you can also obtain the "current" version of the [https://www.visual-prolog.com/download.htm Personal Edition]. Older versions of the Personal Edition can be used freely, but is not otherwise supported.

In older versions of Visual Prolog the demo projects was in the installation and could be installed from the menu entry "Help -> Install Examples ..."

Questions and comments to the demo examples can be given in the [https://www.visual-prolog.com/link/discuss.php discussion forum].

<div style="clear:both"></div>

=== Visual Prolog Demo Examples ===

{|{{prettytable}}
|-
| '''_BeginnersGuide/'''
| This directory contains updated versions of the examples in the old book [[A Beginners Guide to Visual Prolog]].
|-
| '''_tutorial/'''
| This directory contains examples corresponding to the main section of the [[:Category:Tutorials|Tutorials]].
|-
| '''animationControlDemo'''
| This project uses the <vp>animationControl</vp> (this control is not frequently used anymore).
|-
| '''askDialogDemo'''
| This project use a modal dialog to ask the user a question.
|-
| '''BackgroundIntelligentTransferService'''
| This project uses Windows Background Intelligent Transfer Service (BITS).
|-
| '''balloonTipsDemo'''
| This project uses balloon tips popping up as notifications Windows.
|-
| '''bgDemo'''
| This project runs several background jobs in separate threads.
|-
| '''buttonDemo'''
| This program demonstrates how to handle OK and Cancel buttons, how to handle default buttons, how to handle button responders
|-
| '''callProcess'''
| The project invokes an external process and interact with the standard output and standard input of it.
|-
| '''cmdLineDemo'''
| This project uses the <vp>commandLineParser</vp> with several options.
|-
| '''com'''
| This directory contains projects that illustrates how to use a COM component and how to implement one.
|-
| '''direct2DDemo'''
| This project compare GDI+ graphics to "plain" GDI graphics.
|-
| '''dll'''
| This directory contains various projects illustrating the use of DLL.
|-
| '''dockingDemo'''
| This project iullustrates how to use "docking" to define the layout of a dialog.
|-
| '''dragDropTargetOle'''
| This project is a "drop target"
|-
| '''dragNdropDemo'''
| This project illustrates the use of drag and drop.
|-
| '''editor'''
| This project demonstrates how to use the scintilla editor in a program.
|-
| '''formWindowDemo'''
| This project demonstrates the use of forms.
|-
| '''GDI+Example'''
| This project illustrates various GDI+ features.
|-
| '''genericsExample'''
| This project demostrates how to define and work with generic domains.
|-
| '''guiDemo'''
| This project illustrates how to work with GUI.
|-
| '''jsonWebToken'''
| This project demonstrates how to create and decompose JSON web tokens (jwt).
|-
| '''listDemo'''
| This project illustrates various operations on lists.
|-
| '''listViewDemo'''
| This project uses the <vp>listViewControl</vp>.
|-
| '''logDemo'''
| This project demonstrates the use of the <vp>log</vp> tool.
|-
| '''logDemoPE'''
| This project demonstrates the use of the <vp>log</vp> tool in a Personal Edition projectl.
|-
| '''masterSlave'''
| This directory contains projects that utilizes slave process from a master process.
|-
| '''MSXML_Example'''
| This project uses the MSXML component to load an xml file which is visualized in a tree control.
|-
| '''MultiThreadDemo'''
| In the example several threads produces results in the single (common for all threads) "queue", and the primary thread reads them one by one and displays on the screen.
|-
| '''neuralNet'''
| This project builds a pyramid shaped neural network. (Modern neural networks will use vector/matrix/tensor operations).
|-
| '''OdbcDemo'''
| This project demonstrated the use of ODBC (in a GUI program).
|-
| '''pictureDraw'''
| This project draws a picture using GDI+ (<vp>gdiPlus</vp>).
|-
| '''pie'''
| PIE is a Prolog Inference Engine which implements an ISO Prolog like interpreter.
|-
| '''pieDemo'''
| This project uses the <vp>pie</vp> (Prolog Inference Engine) as a scripting language in the project.
|-
| '''progress'''
| This project uses the <vp>progressControl</vp> to illustrate progress in a program.
|-
| '''prologSourceBrowser'''
| This project illustrates the use of several types of GUI controls in a dialog that can browse in files in a directory.
|-
| '''radioButtonDemo'''
| This project demonstrates how to use single radio button group, multiple radio button groups or how to use check boxes.
|-
| '''ribbonDemo'''
| This demo project illustrates how to develop applications using the Ribbon and Command packages of pfc/gui.
|-
| '''ribbonMdiDemo'''
| This demo project illustrates use the ribbonControl in an MDI (Multiple Document Interface) program.
|-
| '''sandClocks'''
| This project can solve a "sand clock" puzles.
|-
| '''simpleOdbc'''
| This project illustrates the use of ODBC in a command line program.
|-
| '''socketAsync'''
| This directory contains a socket server and a corresponding client, both working asynchronously using suspending predicates.
|-
| '''streamDemo'''
| This project illustrates the use of streams.
|-
| '''sudoku'''
| This project can solve soduko's using a constratint programming thechnique.
|-
| '''tabControlDemo'''
| This project uses the <vp>tabControl</vp>.
|-
| '''tail'''
| This project can follow changes to a text/log file.
|-
| '''toolTipDemo'''
| This project illustrates the use of tooltips.
|-
| '''toyIDE'''
| This directory contains several projecs that illustrates how a complex application can be divided into several DLL's.
|-
| '''treeControlDemo'''
| This project uses the <vp>treeControl</vp>
|-
| '''useSyntaxDemo'''
| This project uses the Visual Prolog parser to parse source files and then extracts literals from the syntax trees.
|-
| '''validationDemo'''
| This project illustrates how to use control and dialog validation to validate user input in a dialog.
|-
| '''vipLalrGen'''
| This project is the source code of the Visual Prolog LALR parser generator.
|-
| '''vipPP'''
| This project is the source code of the <vp>vipPP</vp> program that can parse and pretty print Visual Prolog source code.
|-
| '''WatchDir'''
| This project uses <vp>watchDir</vp> to monitor changes in a directory.
|-
| '''watchDirGui'''
| This project uses <vp>watchDir</vp> to monitor changes in a directory (in a GUI program).
|-
| '''webService'''
| This directory contains a webServiceDemo project with a HTML test page and a corresponding Visual Prolog client program.
|-
| '''webView2Demo'''
| This project illustrates the usage of the <vp>webView2</vp> control (Edge browser).
|}

Visual Prolog Demo Examples

2024-09-16T13:34:42Z

Thomas Linder Puls: Discussion forum

Visual Prolog Demo Examples

2024-09-16T13:32:02Z

Thomas Linder Puls: Personal Edition

{{ideNavbar|IDE Projects}}

You can download the latest Visual Prolog [https://www.vusual-prolog.com/link/demo.php demo projects].

Notice that some demo programs may require the Commercial Edition. The build system will inform you if that is the case.

If you a newer Commercial Editoion you license file will contain a link to the demo programs correcponding to your version.

For the Personal Edition you can only obtain the "current" version of demos, but you can also obtain the "current" version of the [https://www.visual-prolog.com/download.htm Personal Edition]. Older versions of the Personal Edition can be used freely, but is not otherwise supported.

In older versions of Visual Prolog the demo projects was in the installation and could be installed from the menu entry "Help -> Install Examples ..."

<div style="clear:both"></div>

=== Visual Prolog Demo Examples ===

{|{{prettytable}}
|-
| '''_BeginnersGuide/'''
| This directory contains updated versions of the examples in the old book [[A Beginners Guide to Visual Prolog]].
|-
| '''_tutorial/'''
| This directory contains examples corresponding to the main section of the [[:Category:Tutorials|Tutorials]].
|-
| '''animationControlDemo'''
| This project uses the <vp>animationControl</vp> (this control is not frequently used anymore).
|-
| '''askDialogDemo'''
| This project use a modal dialog to ask the user a question.
|-
| '''BackgroundIntelligentTransferService'''
| This project uses Windows Background Intelligent Transfer Service (BITS).
|-
| '''balloonTipsDemo'''
| This project uses balloon tips popping up as notifications Windows.
|-
| '''bgDemo'''
| This project runs several background jobs in separate threads.
|-
| '''buttonDemo'''
| This program demonstrates how to handle OK and Cancel buttons, how to handle default buttons, how to handle button responders
|-
| '''callProcess'''
| The project invokes an external process and interact with the standard output and standard input of it.
|-
| '''cmdLineDemo'''
| This project uses the <vp>commandLineParser</vp> with several options.
|-
| '''com'''
| This directory contains projects that illustrates how to use a COM component and how to implement one.
|-
| '''direct2DDemo'''
| This project compare GDI+ graphics to "plain" GDI graphics.
|-
| '''dll'''
| This directory contains various projects illustrating the use of DLL.
|-
| '''dockingDemo'''
| This project iullustrates how to use "docking" to define the layout of a dialog.
|-
| '''dragDropTargetOle'''
| This project is a "drop target"
|-
| '''dragNdropDemo'''
| This project illustrates the use of drag and drop.
|-
| '''editor'''
| This project demonstrates how to use the scintilla editor in a program.
|-
| '''formWindowDemo'''
| This project demonstrates the use of forms.
|-
| '''GDI+Example'''
| This project illustrates various GDI+ features.
|-
| '''genericsExample'''
| This project demostrates how to define and work with generic domains.
|-
| '''guiDemo'''
| This project illustrates how to work with GUI.
|-
| '''jsonWebToken'''
| This project demonstrates how to create and decompose JSON web tokens (jwt).
|-
| '''listDemo'''
| This project illustrates various operations on lists.
|-
| '''listViewDemo'''
| This project uses the <vp>listViewControl</vp>.
|-
| '''logDemo'''
| This project demonstrates the use of the <vp>log</vp> tool.
|-
| '''logDemoPE'''
| This project demonstrates the use of the <vp>log</vp> tool in a Personal Edition projectl.
|-
| '''masterSlave'''
| This directory contains projects that utilizes slave process from a master process.
|-
| '''MSXML_Example'''
| This project uses the MSXML component to load an xml file which is visualized in a tree control.
|-
| '''MultiThreadDemo'''
| In the example several threads produces results in the single (common for all threads) "queue", and the primary thread reads them one by one and displays on the screen.
|-
| '''neuralNet'''
| This project builds a pyramid shaped neural network. (Modern neural networks will use vector/matrix/tensor operations).
|-
| '''OdbcDemo'''
| This project demonstrated the use of ODBC (in a GUI program).
|-
| '''pictureDraw'''
| This project draws a picture using GDI+ (<vp>gdiPlus</vp>).
|-
| '''pie'''
| PIE is a Prolog Inference Engine which implements an ISO Prolog like interpreter.
|-
| '''pieDemo'''
| This project uses the <vp>pie</vp> (Prolog Inference Engine) as a scripting language in the project.
|-
| '''progress'''
| This project uses the <vp>progressControl</vp> to illustrate progress in a program.
|-
| '''prologSourceBrowser'''
| This project illustrates the use of several types of GUI controls in a dialog that can browse in files in a directory.
|-
| '''radioButtonDemo'''
| This project demonstrates how to use single radio button group, multiple radio button groups or how to use check boxes.
|-
| '''ribbonDemo'''
| This demo project illustrates how to develop applications using the Ribbon and Command packages of pfc/gui.
|-
| '''ribbonMdiDemo'''
| This demo project illustrates use the ribbonControl in an MDI (Multiple Document Interface) program.
|-
| '''sandClocks'''
| This project can solve a "sand clock" puzles.
|-
| '''simpleOdbc'''
| This project illustrates the use of ODBC in a command line program.
|-
| '''socketAsync'''
| This directory contains a socket server and a corresponding client, both working asynchronously using suspending predicates.
|-
| '''streamDemo'''
| This project illustrates the use of streams.
|-
| '''sudoku'''
| This project can solve soduko's using a constratint programming thechnique.
|-
| '''tabControlDemo'''
| This project uses the <vp>tabControl</vp>.
|-
| '''tail'''
| This project can follow changes to a text/log file.
|-
| '''toolTipDemo'''
| This project illustrates the use of tooltips.
|-
| '''toyIDE'''
| This directory contains several projecs that illustrates how a complex application can be divided into several DLL's.
|-
| '''treeControlDemo'''
| This project uses the <vp>treeControl</vp>
|-
| '''useSyntaxDemo'''
| This project uses the Visual Prolog parser to parse source files and then extracts literals from the syntax trees.
|-
| '''validationDemo'''
| This project illustrates how to use control and dialog validation to validate user input in a dialog.
|-
| '''vipLalrGen'''
| This project is the source code of the Visual Prolog LALR parser generator.
|-
| '''vipPP'''
| This project is the source code of the <vp>vipPP</vp> program that can parse and pretty print Visual Prolog source code.
|-
| '''WatchDir'''
| This project uses <vp>watchDir</vp> to monitor changes in a directory.
|-
| '''watchDirGui'''
| This project uses <vp>watchDir</vp> to monitor changes in a directory (in a GUI program).
|-
| '''webService'''
| This directory contains a webServiceDemo project with a HTML test page and a corresponding Visual Prolog client program.
|-
| '''webView2Demo'''
| This project illustrates the usage of the <vp>webView2</vp> control (Edge browser).
|}

Visual Prolog Demo Examples

2024-09-16T13:30:57Z

Thomas Linder Puls: update

{{ideNavbar|IDE Projects}}

You can download the latest Visual Prolog [https://www.vusual-prolog.com/link/demo.php demo projects].

Notice that some demo programs may require the Commercial Edition. The build system will inform you if that is the case.

If you a newer Commercial Editoion you license file will contain a link to the demo programs correcponding to your version.

For the Personal Edition you can only obtain the "current" version of demos, but you can also obtain the "current" version of the Personal Edition". Older versions of the Personal Edition can be used freely, but is not otherwise supported.

In older versions of Visual Prolog the demo projects was in the installation and could be installed from the menu entry "Help -> Install Examples ..."

<div style="clear:both"></div>

=== Visual Prolog Demo Examples ===

{|{{prettytable}}
|-
| '''_BeginnersGuide/'''
| This directory contains updated versions of the examples in the old book [[A Beginners Guide to Visual Prolog]].
|-
| '''_tutorial/'''
| This directory contains examples corresponding to the main section of the [[:Category:Tutorials|Tutorials]].
|-
| '''animationControlDemo'''
| This project uses the <vp>animationControl</vp> (this control is not frequently used anymore).
|-
| '''askDialogDemo'''
| This project use a modal dialog to ask the user a question.
|-
| '''BackgroundIntelligentTransferService'''
| This project uses Windows Background Intelligent Transfer Service (BITS).
|-
| '''balloonTipsDemo'''
| This project uses balloon tips popping up as notifications Windows.
|-
| '''bgDemo'''
| This project runs several background jobs in separate threads.
|-
| '''buttonDemo'''
| This program demonstrates how to handle OK and Cancel buttons, how to handle default buttons, how to handle button responders
|-
| '''callProcess'''
| The project invokes an external process and interact with the standard output and standard input of it.
|-
| '''cmdLineDemo'''
| This project uses the <vp>commandLineParser</vp> with several options.
|-
| '''com'''
| This directory contains projects that illustrates how to use a COM component and how to implement one.
|-
| '''direct2DDemo'''
| This project compare GDI+ graphics to "plain" GDI graphics.
|-
| '''dll'''
| This directory contains various projects illustrating the use of DLL.
|-
| '''dockingDemo'''
| This project iullustrates how to use "docking" to define the layout of a dialog.
|-
| '''dragDropTargetOle'''
| This project is a "drop target"
|-
| '''dragNdropDemo'''
| This project illustrates the use of drag and drop.
|-
| '''editor'''
| This project demonstrates how to use the scintilla editor in a program.
|-
| '''formWindowDemo'''
| This project demonstrates the use of forms.
|-
| '''GDI+Example'''
| This project illustrates various GDI+ features.
|-
| '''genericsExample'''
| This project demostrates how to define and work with generic domains.
|-
| '''guiDemo'''
| This project illustrates how to work with GUI.
|-
| '''jsonWebToken'''
| This project demonstrates how to create and decompose JSON web tokens (jwt).
|-
| '''listDemo'''
| This project illustrates various operations on lists.
|-
| '''listViewDemo'''
| This project uses the <vp>listViewControl</vp>.
|-
| '''logDemo'''
| This project demonstrates the use of the <vp>log</vp> tool.
|-
| '''logDemoPE'''
| This project demonstrates the use of the <vp>log</vp> tool in a Personal Edition projectl.
|-
| '''masterSlave'''
| This directory contains projects that utilizes slave process from a master process.
|-
| '''MSXML_Example'''
| This project uses the MSXML component to load an xml file which is visualized in a tree control.
|-
| '''MultiThreadDemo'''
| In the example several threads produces results in the single (common for all threads) "queue", and the primary thread reads them one by one and displays on the screen.
|-
| '''neuralNet'''
| This project builds a pyramid shaped neural network. (Modern neural networks will use vector/matrix/tensor operations).
|-
| '''OdbcDemo'''
| This project demonstrated the use of ODBC (in a GUI program).
|-
| '''pictureDraw'''
| This project draws a picture using GDI+ (<vp>gdiPlus</vp>).
|-
| '''pie'''
| PIE is a Prolog Inference Engine which implements an ISO Prolog like interpreter.
|-
| '''pieDemo'''
| This project uses the <vp>pie</vp> (Prolog Inference Engine) as a scripting language in the project.
|-
| '''progress'''
| This project uses the <vp>progressControl</vp> to illustrate progress in a program.
|-
| '''prologSourceBrowser'''
| This project illustrates the use of several types of GUI controls in a dialog that can browse in files in a directory.
|-
| '''radioButtonDemo'''
| This project demonstrates how to use single radio button group, multiple radio button groups or how to use check boxes.
|-
| '''ribbonDemo'''
| This demo project illustrates how to develop applications using the Ribbon and Command packages of pfc/gui.
|-
| '''ribbonMdiDemo'''
| This demo project illustrates use the ribbonControl in an MDI (Multiple Document Interface) program.
|-
| '''sandClocks'''
| This project can solve a "sand clock" puzles.
|-
| '''simpleOdbc'''
| This project illustrates the use of ODBC in a command line program.
|-
| '''socketAsync'''
| This directory contains a socket server and a corresponding client, both working asynchronously using suspending predicates.
|-
| '''streamDemo'''
| This project illustrates the use of streams.
|-
| '''sudoku'''
| This project can solve soduko's using a constratint programming thechnique.
|-
| '''tabControlDemo'''
| This project uses the <vp>tabControl</vp>.
|-
| '''tail'''
| This project can follow changes to a text/log file.
|-
| '''toolTipDemo'''
| This project illustrates the use of tooltips.
|-
| '''toyIDE'''
| This directory contains several projecs that illustrates how a complex application can be divided into several DLL's.
|-
| '''treeControlDemo'''
| This project uses the <vp>treeControl</vp>
|-
| '''useSyntaxDemo'''
| This project uses the Visual Prolog parser to parse source files and then extracts literals from the syntax trees.
|-
| '''validationDemo'''
| This project illustrates how to use control and dialog validation to validate user input in a dialog.
|-
| '''vipLalrGen'''
| This project is the source code of the Visual Prolog LALR parser generator.
|-
| '''vipPP'''
| This project is the source code of the <vp>vipPP</vp> program that can parse and pretty print Visual Prolog source code.
|-
| '''WatchDir'''
| This project uses <vp>watchDir</vp> to monitor changes in a directory.
|-
| '''watchDirGui'''
| This project uses <vp>watchDir</vp> to monitor changes in a directory (in a GUI program).
|-
| '''webService'''
| This directory contains a webServiceDemo project with a HTML test page and a corresponding Visual Prolog client program.
|-
| '''webView2Demo'''
| This project illustrates the usage of the <vp>webView2</vp> control (Edge browser).
|}

Web Services

2024-09-11T09:45:48Z

Thomas Linder Puls: IISAPI removed

This tutorial describes how to create a Web Application with a HTML/JavaScript front-end that run in the users browser and a backend written in Visual Prolog.

The emphasis is on the Visual Prolog back-end, which implement a JSON-RPC web service. The HTML/JavaScript code is mainly included to make the example self-contained and to illustrate how front-end code can interact with a Visual Prolog web service.

It is described how the service can run as a stand-alone HTTP/HTTPS server

Also notice that this tutorial will not consider SOAP at all.

The tutorial corresponds to the '''webService''' examples.

A web service can as described here be implemented as a stand alone server. Tt can also be implemented as an IISAPI plug-in, but we recommend using a standalone instead of using an IISAPI plug-in.

=== Overview ===

In this section we will try to describe the overall picture of the entire application and the way it works. What takes place is actually rather complex, but fortunately most of the complexity is handled automatically. An understanding of the overall process including knowledge of some of the complexity will however make it easier to understand what needs to be done and why.

The overall work flow of the example application is as follows: The user browses (in a web browser) to the page '''http:<nowiki />//<server>/test.htm''' (or '''http:<nowiki />//<server>/calendar.htm'''), and the server returns the corresponding file to the browser. The browser evaluates the contents of the file, which may result in additional requests for several cascading style scripts (css) files, JavaScript (js) files, images, etc. Furthermore, the HTML file contains embedded JavaScript code, which will make remote procedure calls ('''RPC''') to the web server. The server will execute the corresponding procedures and return the result to the browser. Finally, the embedded JavaScript uses the returned data to update the HTML contents of the browser.

The communication between the client and the server is performed by means of the HTTP (or HTTPS) protocol. So on the server side we need an HTTP server, which can both return files and implement remote procedure calls. The program in '''jsonRpcService_httpApi''' runs the service as a stand alone HTTP server that both handles file requests and implements the remote procedure calls. The program in '''jsonRpcService_isApi''' implements the remote procedure calls as an ISAPI plug-in, the IIS (Microsoft Internet Information Services) is configured to handle the file requests and to use the ISAPI for the remote procedure calls.

The stand alone HTTP server is implemented by means of Microsoft's [http://msdn.microsoft.com/en-us/library/windows/desktop/aa364510(v=vs.85).aspx HTTP Server API], which can share ports and URL's with the Internet Information Services (IIS), such that '''http:<nowiki />//<server>/file''', etc can go to our stand alone server while '''http:<nowiki />//<server>/<something>''' can be handled by the IIS.

=== JSON & JSON-RPC ===

The remote procedure calls are implemented in accordance with the [http://www.jsonrpc.org/specification JSON-RPC 2.0 Specification] specification, which implies that data is encoded in [http://www.json.org/ JSON] ('''J'''ava'''S'''cript '''O'''bject '''N'''otation) format.

JSON syntax is a sub-set of JavaScript (hence the name): When evaluating a valid JSON text it will become a corresponding JavaScript object. You should however ''always'' call a JSON parser instead of evaluating the text: evaluating text is a security risk, since the text could be "code" rather than "data".

It is not necessary to understand the JSON format in details, because on the client side you will work with JavaScript and on the server side you will work with an object/domain representation of JSON: parsing and writing is left to standard software.

When performing a JSON-RPC call the client sends a JSON request object, and the server will respond with a JSON response object, unless the request is a '''notification''', in which case there is no response.

Request objects have four members:
* <vp>jsonrpc</vp>: A string specifying the version of the JSON-RPC protocol. MUST be exactly "2.0".
* <vp>method</vp>: A string containing the name of the method to be invoked.
* <vp>params</vp>: The method parameters (omitted if the method does not take parameters).
**by-position: a JSON array, containing the values in the Server expected order.
**by-name: a JSON object, with member names that match exactly, including case, to the method's expected parameters
* <vp>id</vp>: A client created string or number used to identify the request. The <vp>id</vp> field is omitted for notifications.

A response object contains three members:
* <vp>jsonrpc</vp> A String specifying the version of the JSON-RPC protocol. MUST be exactly "2.0".
* <vp>id</vp> The value submitted by the client.
The third member is one of these:
* <vp>result</vp> (implying that the call succeeded) The result of the procedure call
* <vp>error</vp> (implying that the call failed) An object describing the error which occurred

=== Client side ===

{{Example|This code shows one way to make a procedure call on the client side:
<source lang="JavaScript">
function httpPOST(URL, method, params) {
var ReqObj = { jsonrpc: "2.0", id: getId(), method: method, params: params };
var Req = JSON.stringify(ReqObj);
var xmlHttp = new XMLHttpRequest();
xmlHttp.open("POST", URL, false);
xmlHttp.setRequestHeader('Content-Type', 'application/json-rpc; charset=UTF-8');
xmlHttp.send(Req);
var resp = xmlHttp.responseText;
var respObj = JSON.parse(resp);
var error = respObj.error;
if (error) {
if (Data = error.data) {
log("<pre>" + Data +"</pre>\n");
}
log("<p>error : "+ error.code +": " + error.message + "</p>\n");
} else {
// respObj.result contains the result
}
}</source>
In brief:
* Create a request object
* JSON "stringify" it
* POST it using an XMLHttpRequest object
* JSON parse the response text
* Check for "error" member
}}

There are many other ways to make client side code, typically you will use some standard JavaScript library packages that handles errors and perform the calls asynchronously. '''calendar.htm''' uses such library code, but that is outside the scope of this tutorial.

=== Service Code ===

In Visual Prolog JSON is represented by the domain <vp>json::jsonValue</vp>:

<vip>domains
jsonValue =
n; % null
f; % false
t; % true
r(real Number);
s(string String);
a(jsonValue* Array);
o(jsonObject Object).</vip>

There are only 7 kinds of JSON values: null, false, true, a number, a string, an array and an object.

An array is a sequence of JSON values represented as a list in Visual Prolog.

A JSON object is represented by the <vp>jsonObject</vp> interface in Visual Prolog:

<vip>interface jsonObject supports mapM{string Key, jsonValue Value}
...
end interface jsonObject</vip>

The interface contains a number of convenience predicates/properties (which have been omitted above), but in essence a <vp>jsonObject</vp> is simply a map from Key's (names) to JSON values.

{{Example|This code:
<vip>J = jsonObject::new(),
J:set_boolean("bbb", true),
J:set_string("sss", "The String"),
J:writeTo(stdio::outputStream),
stdio::nl,
jsonPrettyPrint::ppObject(stdio::outputStream, J)</vip>
will produce this output:
<source lang="text">{"bbb":true,"sss":"The String"}
{
"bbb" : true,
"sss" : "The String"
}</source>
<vp>writeTo</vp> produces a condensed JSON representation suitable interprocess communication, etc. <vp>jsonPrettyPrint</vp> can be used to pretty print the values (for example when debugging).
}}

When creating an RPC service you will have to implement an object that supports the <vp>rpcService</vp> interface:

<vip>interface testService supports rpcService
end interface testService

class testService : testService
end class testService</vip>

In the implementation you will inherit from <vp>jsonRpcServiceSupport</vp> which will handle the parsing, writing, etc of JSON:

<vip>implement testService
inherits jsonRpcServiceSupport
open core, json
...

end implement testService</vip>

You will register your procedures in the constructor:

<vip>clauses
new() :-
setProc_name("hello", hello),
setProc_name("calendar", calendar).</vip>

There are four kinds of procedures, with corresponding registration predicates:

* <vp>setProc_array</vp> for registering a procedure that uses positional arguments in an array
* <vp>setProc_name</vp> for registering a procedure that uses named arguments in an object
* <vp>setListener_array</vp> for registering a notification listener that uses positional arguments in an array
* <vp>setListener_name </vp> for registering a notification listener that uses named arguments in an object

In the example there are two procedures "hello" and "calendar" that both uses named arguments. The "hello" code looks like this:

<vip>constants
testService_error : jsonRpcError::serverErrorCode = jsonRpcError::serverError_last+1.
% grows up from "last", which is used for unspecified server error

predicates
hello : jsonProc_name.
clauses
hello(_Context, ArgMap) = o(Result) :-
Result = jsonObject::new(),
Username = ArgMap:get_string("username"),
if "error" = Username then
raise_serviceError(testService_error, "'error' is an invalid user name")
elseif "userError" = Username then
exception::raise_user("'%Name%' is an invalid user name", [namedValue("Name", string(Username))])
elseif "definiteUserError" = Username then
exception::raise_definiteUser("'%Name%' is an invalid user name", [namedValue("Name", string(Username))])
else
Result:set_string("token", string::concat("Hello ", Username))
end if.</vip>

First the <vp>hello</vp> procedure creates a <vp>jsonObject</vp> for the <vp>Result</vp>. Any kind of JSON value are legal as result, but <vp>hello</vp> is designed to return a JSON object with a <vp>"token"</vp> member.

Next it fetches the arguments from <vp>ArgMap</vp>. It expects a string argument named <vp>"username"</vp>.

<vp>hello</vp> uses the value of <vp>Username</vp> to illustrate exception handling and success.

The <vp>"error"</vp> case illustrates how you can raise "service errors", that is errors that are specifically designed for the RPC service. The "userError" and "definiteUserError" cases illustrates what will happen with other exceptions that occurs in the procedure call.

Notice that the client side code should be programmed to deal with errors. On the server side you may of course also handle specific exceptions as in any other program, and perhaps you also want to log all errors somewhere.

If <vp>Username</vp> is not one of the error cases, we map "token" to a string in the <vp>Result</vp>.

{{Example|We recommend that your <vp>jsonProc</vp>'s only deal with argument extraction and result construction, and that you keep the real functionally in a separate business layer as illustrated by this code:
<vip>predicates
hello : jsonProc_name.
clauses
hello(_Context, ArgMap) = o(Result) :-
Result = jsonObject::new(),
Username = ArgMap:get_string("username"),
Token = businessLayer::hello(Username), % actual functionality is in a separate business layer
Result:set_string("token", Token).</vip>}}

=== Stand-alone HTTP server ===

As illustrated by the <vp>jsonRpcService_httpApi</vp> program the <vp>testService</vp> (supporting the <vp>rpcService</vp>) can be used in a stand-alone HTTP server. It does not require much code and it is quite simple to adjust the code to specific needs. Nevertheless the complexity is quite large.

The server is based on Microsoft's [http://msdn.microsoft.com/en-us/library/windows/desktop/aa364510(v=vs.85).aspx HTTP Server API] which cooperates well with Microsoft Internet Information Services (IIS). In fact, it seems that IIS is built on top of the HTTP Server API (or at least that both are built on top of some common base).

The HTTP Server api operates with the following entities:
* Creator/Controller Process
* Server Session
* URL groups
* Request queues
* Worker Processes

The creator/controller process creates a server session, which defines URL groups and request queues. The worker processes attach to the request queues and process the requests they receive.

In the example program the creator/controller process is also the only worker process. And it is outside the scope of this tutorial to consider more complex scenarios.

The server session is the "owner"/"holder" of the URL groups and the request queues, which are the things we really need to consider.

An URL group defined by a set of URL patterns of the forms:
:'''http:<nowiki />//<host>:<port>/<relativeURI>'''
:'''https:<nowiki />//<host>:<port>/<relativeURI>'''

When a request arrives at the computer a matching mechanism will match it against the URL patterns in the active URL groups, the matching will either fail or determine an URL group that covers the URL.

Each URL group is attached to a request queue, and requests matched to a certain URL group is placed in the attached request queue. URL groups that are not attached to a request queue are inactive and does not participate in the matching.

Worker processes dequeue requests from the request queues and handle them. A request queue can have several URL groups attached and each URL group can have several URL patterns. A worker process dequeuing from a certain request queue will therefore receive requests that match some URL pattern in some URL group attached to that queue.

In the example server we create two request queues each having a single URL group attached, and each of these URL groups having one URL pattern. Effectively:
* <vp>reqQueue_rpc</vp> receives requests of the form '''http:<nowiki />//localhost:5555/jsonrpc/<something>''', and
* <vp>reqQueue_file</vp> receives requests of the form '''http:<nowiki />//localhost:5555/<something>''''

<vp>reqQueue_rpc</vp> is a <vp>requestQueue_rpc</vp> handles RPC requests by feeding them to our <vp>testService</vp>.

<vp>reqQueue_file</vp> is a <vp>requestQueue_file</vp> which uses <vp>fileMapper</vp> to map the requests to a file name and an associated <vp>ContentType</vp>, the <vp>requestQueue_file</vp> will then handle the transfer of the file.

=== Server configuration: netsh ===

The example runs smoothly because it uses port 5555 on localhost. Normally you will however want to run applications on port 80 for http and 443 for https, and that will cause some security problems.

If you just change the port number and uses a public hostname you server program will get an 'Access is denied' exception when trying to add the URL patterns to the URL groups.

If you run the server "as Administrator" you will not get the access violation, but it is absolutely not advisable to run the program as administrator, because then it also have rights to do many other harmful things.

To make the program run in normal modes you will have to reserve the URL patterns in question for the user that run the server program.

This is done using the netsh.exe (net shell) program. You will need to manipulate the http URL acl's. For a detailed description see [http://msdn.microsoft.com/en-us/library/windows/desktop/cc307236(v=vs.85).aspx Netsh commands for HTTP].

{{Example|This will give an idea of what to do (in a cmd prompt):
<source lang="text">>netsh http add urlacl http://www.something.com:80/ user=SMT\serviceuser</source>
'''Notice''' that the cmd prompt be run "as Administrator" to make modifications.
If you just write "netsh" it will go into a prompt mode where change to http mode and then just write http commands
<source lang="text">>netsh
netsh>http
netsh http>add urlacl http://www.something.com:80/ user=SMT\serviceuser
netsh http>exit</source>}}

It is possible to make the URL reservations from Visual Prolog, but in case of conflicts and problems it may be better to use the standard program netsh.

Notice that the example program is a console program. In an larger scale context it would seem better to create a genuine windows service. Visual Prolog has a template project for creating services, but that subject is outside the scope of this tutorial.

=== Existing GUI program ===

In the '''webRPC''' example directory there is also a <vp>jsonRpcService_httpGUI</vp>, which illustrated how a GUI program can act like a stand-alone Web RPC Service. You should notice that it is not recommended to let a real service program have a GUI, but it can be quite useful if you need to let other programs interoperate with the GUI program, i.e. in a normal user login session. It can also be used as a "quick and dirty" way to expose already existing GUI code as a Web Service (perhaps as a test before creating the real service).

=== Multi-threading ===

No matter how you run the web service (stand-alone with or without GUI, or as ISAPI) you should notice that the HTTP requests run in parallel in several threads. So it is important to ensure that the request handling's are thread safe. The <vp>requestQueue_rpc::synchronizer</vp> property can be used to synchronize the execution of the RPC's, the property is set to a predicate which will receive <vp>runnable</vp>s, when the runnable is executed the actual RPC call is performed. The runnable's can for example be executed in a monitor ensuring that only one at the time is execute, or be put on a queue and executed sequentially from that or as <vp>jsonRpcService_httpGUI</vp> does be posted to the GUI queue and thus executed by the GUI thread.

=== Visual Prolog Client ===

This tutorial and the mentioned examples has focused on the Visual Prolog server side, using a web browser as client side. But sometimes a Visual Prolog program may need to access a web service as client. The example <vp>jsonRpcClient</vp> illustrates how this can be done. The method is quite similar to the one used in JavaScript:

* Create a <vp>jsonRpcRequest</vp> object, with method name and parameters
* JSON "stringify" it using <vp>asString</vp>
* POST it using an XMLHttpRequest object (an instance of <vp>xmlHTTP</vp> or <vp>xmlHTTP60</vp>)
* JSON parse the response text (using <vp>jsonObject::fromString</vp>)
* Check for "error" member

In the example program you see a <vp>delayCall</vp>, whose purpose is to allow the GUI to be updated, without this call the GUI would not update until after the RPC have completed. The call is however irrelevant for the RPC itself.

=== Skype HTTP/HTTPS Conflict ===
{{:Include/SkypeHTTPConflict}}

=== HTTPS ===

Finally a set if brief notes about Secure connections (SSL/TLS).

HTTPS is the HTTP protocol used over a secure socket. Both the IIS and the stand alone HTTP Server can use HTTPS. To use HTTPS the server computer must have a certificate. It is possible to create a certificate yourself, but a self created certificate is "untrusted" will therefore cause security notifications. This is sufficient for testing and development purposes, but for real scale purposes you will have to acquire a trusted certificate.

In brief a trusted certificate have to be obtained from a trusted provider. The trust lies in three things:
* The provider is itself trusted
* The provider have knowledge about the "real identity" of the certificate holder (through normal purchase chains)
* The provider can revoke the certificate if it is misused somehow

Notice that HTTPS by default uses port 443 (and HTTP uses port 80), and that you have to write "https" in the places where you would otherwise write "http" (e.g. '''https:<nowiki />//+:443/mypath''')

For test purposes you can create self signed certificates using the power shell command "New-SelfSignedSertificate":

New-SelfSignedCertificate -DnsName "*.localhost.xx"" -CertStoreLocation "cert:\LocalMachine\My" -NotAfter (Get-Date).AddYears(10)

If run "Manage Computer Certificates" you will find it in "Personal\Certificates" and if you copy it to "Trusted Root Certificates\Certificates" (it must be both places) then you computer will trust it.

Double clicking the certificate and viewing the details will reveal the ThumbPrint which is the identifier of the certificate.

You will use this identifier to tie the certificate to the connection. This is done by adding an "sslcert" record with "netsh":

netsh http add sslcert hostnameport=demo.localhost.xx:443 certhash=19bde81e1b443b28fe75553cc52e0d8ba99978f1 appid={00112233-4455-6677-8899-AABBCCDDEEFF} certstorename=MY

The "certhash" identifies certificate (the ThumpPrint in the certificate details), the purpose of the "appid" is a unclear to me but it is in any case a GUID.

To make test with "real" server names like "demo.localhost.xx" you can make an 127.0.0.1 entry in the "hosts" file (C:\Windows\System32\Drivers\etc\hosts):
...
# localhost name resolution is handled within DNS itself.
# 127.0.0.1 localhost
# ::1 localhost
127.0.0.1 demo.localhost.xx

In JavaScript you can get the protocol like this:

// JSON RPC handling
const apiUrl = window.location.protocol + '//' + window.location.host + '/api'

For web sockets like this:

// webSocket handling
const wsProtocol = ('https:' == window.location.protocol ? 'wss:' : 'ws:')
const wsUrl = wsProtocol + '//' + window.location.host + '/ws/'

=== See also ===

* [http://www.json.org/ JSON]
* [http://www.jsonrpc.org/specification JSON-RPC 2.0 Specification]
* Microsoft's [http://msdn.microsoft.com/en-us/library/windows/desktop/aa364510(v=vs.85).aspx HTTP Server API]

[[Category:Internet]]

Visual Prolog 11 New Features

2024-04-24T10:50:18Z

Thomas Linder Puls: examples link

Visual Prolog 11 has been extended with {{lang|Suspending Predicates|Suspending Predicates}}.

The development system can only run on 64 bit Windows, but can still build programs for both 32 and 64 bit Windows.

New utility "[[vipLaunch]]" for launching projects in correct IDE. The installer is included in the Visual Prolog 11 installer, but you can also install the latest version directly here [https://www.visual-prolog.com/link/vipLaunch.php vipLaunch installer].

Download Visual Prolog 11 [https://www.visual-prolog.com/link/examples.php?version=11 Demo Examples].

== Build 1105 ==

=== Language ===

* {{lang|Suspending Predicates|Suspending Predicates}}
* {{lang2|Attributes|feature|feature}} attribute, built-in predicate <vp>is_feature_available</vp>, compiler option '''/ENABLEFEature:feature_name'''
* Built-in predicates <vp>convertAllowNull</vp> and <vp>tryConvertAllowNull</vp>
* Built-in constants <interface><vp>::null</vp> for all interfaces
* Warning: explicit <vp>programmingPoint</vp> available
* Embedded string8 (utf8) support (literals and conversions)
* Warning c665 for a fact which is always initialized with a constant and is not changed (switched off by the default)
* Digit separator support (syntax only) <vp>1_000_000</vp> and <vp>0x_1A2B_3C4D</vp>

=== PFC ===

* Support for asynchronous programming by means of suspending predicates:
** New: <vp>executionContext_pool</vp> a multi threaded pool for asynchronous and background work
** New: <vp>executionContext_single</vp> a single threaded worker for asynchronous work
** New: Suspending predicates can be executed in a GUI thread (using <vp>future::submit</vp>)
** New: Diverse suspending predicate domains in <vp>core</vp>
** Updated: <vp>asyncSocket</vp> & <vp>asyncSocketListener</vp>
** Updated: master/slave support
** Updated: <vp>future</vp>/<vp>promise</vp>
** Updated: HTTP server & JSON RPC & <vp>webSocket</vp>
** Updated: <vp>webView2</vp>
** Updated: <vp>watchDirectory</vp>
** Removed: <vp>continuation</vp> class and inteface due to redundancy.
** Removed: <vp>threadpool</vp> and all related classes and interfaces due to redundancy.
** New support class: <vp>resumable</vp> class for internal support of suspending predicates
** New support classes: <vp>tp</vp> (etc) internal win32 threadpool interface for dealing with asynchronous io, timers, syncObject waiting, etc
** Deprecated/removed diverse continuation based stuff
* MSXML import free threaded xmlhttp: including <vp>iXMLHTTPRequest3</vp>
* Predicate <vp>messageBox::displayWarningYesNo_dt</vp> replacement for <vp>displayWarning_dt</vp>
* Deprecate <vp>messageBox::displayWarning_dt</vp>: UX: It is reccomended to use Yes/No warnings instead of OK/Cancel
* Color predicates <vp>blendColor</vp>, <vp>darken</vp> and <vp>lighten</vp> in <vp>gdiplus</vp>.
* <vp>fetchString8asString</vp> and <vp>useLocalTimeValue</vp> properties on <vp>odbcConnection</vp> and <vp>odbcStatement</vp>.
* <vp>delayCallLimit</vp> predicate on <vp>window</vp> for delay calls with a MaxDelay.
* <vp>inputStream_binary</vp> and <vp>outputStream_binary</vp> supports/allows ansi(utf8) mode.
* Improved <vp>outputStream</vp> performance for <vp>messageControl</vp>.
* <vp>event0</vp>, <vp>event1</vp>, ... classes: lock free threadsafe.
* 'Sergoe Fluent Icons'/'Segoe MDL2 Assets' glyph icons in ribbonControl/commands
* Explorer theme is applied to <vp>treeControl</vp> by default.
* <vp>monitorQueue</vp> and <vp>monitorQueue_length</vp> are updated with <vp>close</vp> functionality. As a result the <vp>dequeue</vp> operation has become determ.
* Console projects supports [https://docs.microsoft.com/en-us/windows/console/console-virtual-terminal-sequences Console Virtual Terminal Sequences] (by off default).
* flag <vp>jsonRpcApi{@Context}::exceptionTraceLevel</vp> controlling which/when exception dumps that are send to the client side.

=== IDE ===

* Main IDE is now always 64bit
* [[Ide/Debugger#Debug_Adapter|Debug Adapter]] makes cross-debugging to 32bit possible
* Dynamic Help (based on browse information and syntax parsing results)
* New toolbar
* vipId support
* Use new Sergoe Fluent Icons
* Default SDI project includes 'Sergoe Fluent Icons'/'Segoe MDL2 Assets' glyph icons the ribbonControl/commands
* Add variable $(node_modules)
* New Menu item handlers (move code expert to properties window)
* Alt+X converts (unicode) hex to char
* changes.htm and appData\doc\vip.chm handling
* Updated Welcome window
* splitterControl in welcome page
* Build system: pre-build command
* Automatic parallel obj/deb directories

=== Debugger ===

* Debugging now uses a [[Ide/Debugger#Debug_Adapter|Debug Adapter]]

=== Other ===

* Remove superfluous webRpc demo & update webServiceDemo to dispose the session.
* The <vp>webServiceDemo</vp> is updated to demonstrate usage of the flag <vp>jsonRpcApi{@Context}::exceptionTraceLevel</vp>.
* Add zip / unzip functionality

== Build 1106 ==

=== Language ===

* Fix: Subtype presenter problem
* Fix: Stack overflow exception on binary constant allocation
* Fix: Wrong debug info for unbound variable (functor component)
* Fix: Debugger/presenters: false objects

=== PFC ===

* webView2
** Fix: Windows 7 and Windows 8 compatibility./li>
** Additional CompleteHandler handling (suspending predicates).
* Fix: <vp>ribbonControl</vp>: Release native graphics context.
* odbc: add column/parameter number for results longer than the buffer.
* <vp>window::centerTo</vp>: map to Windows parent (not pfc parent).

=== IDE ===

* <vp>webView2</vp> control show on Windows 7/8 & update build number
* show correct build number

=== Other ===

* <vp>comWrap</vp>: Handle more winRT CompleteHandlers (for webView2)
* Fix: Runtime debugger/presenters: false objects

== Build 1107 ==

=== PFC ===

* New class <vp>gcUcBuffer</vp>: for buffers that cannot be caught by false pointers.
* odbc: utilize <vp>gcUcBuffer</vp> to avoid that odbc buffers are caught by false pointers.
* New predicate <vp>clipBoard::putFileList</vp> for putting files on the clipboard in the pre-defined hDrop format.
* <vp>command</vp> and <vp>ribbonControl</vp>: new responder <vp>queryBadgeState</vp>.
* Prevent <vp>vpi::processEvents</vp> from interfering with <vp>postAction</vp> order.

=== IDE ===

* Personal edition supports 64 bit targets.
* Open external browser for registration, wiki-help and forum links.
* '''Help -> Prolog Foundation Classes (PFC)''' opens vip.chm.

=== Other ===

Fix: MemoryProfiler wrong scaling of total graph.

== Build 1108 ==

=== PFC ===

* New property <vp>remoteAddress</vp> on interface <vp>httpRequest</vp>.
* New predicate <vp>memory::mkCopy_atomic</vp> for copying structs.
* New predicates <vp>formatSocketAddress</vp> and <vp>formatSockAddr</vp> in class <vp>winSock2_api</vp>.
* <vp>winSock2_api</vp> correct and simplify various domains.

=== IDE ===

* Fix: Exceptions when git is not installed.

== Build 1110 ==

=== Language ===

* <vp>match</vp> and <vp>case</vp> has been reserved as keywords in next major release.

=== PFC ===

* Fix: Wrong type of parameter type in predicate <vp>winHttp_native::winHttpSetOption</vp> declaration.
* Fix: Eliminate race condition for <vp>postAction</vp>.
* Deprecate <vp>time::getTickCount</vp> in favour of <vp>performanceCounter</vp>'s.
* Deprecate <vp>regEx::match</vp> because <vp>match</vp> will become a keyword.

== Build 1111 ==

=== PFC ===

* Fix: time_api::getTimeZoneOffset hours -> minutes
* Fix: odbcStatement::free: allow to be called more than once
* Fix: stringFormat (gdiplus): nullary constructor must create a fresh object

=== Debugger ===

Fix: Dictionary loading timeout for large programs in debug adaptor

== See also ==

See also [[Visual Prolog 11 Upgrade Notes]].

[[Category:Release Notes|11 New Features]]

Visual Prolog 11 New Features

2024-04-24T10:49:18Z

Thomas Linder Puls: Build 1111

Visual Prolog 11 has been extended with {{lang|Suspending Predicates|Suspending Predicates}}.

The development system can only run on 64 bit Windows, but can still build programs for both 32 and 64 bit Windows.

New utility "[[vipLaunch]]" for launching projects in correct IDE. The installer is included in the Visual Prolog 11 installer, but you can also install the latest version directly here [https://www.visual-prolog.com/link/vipLaunch.php vipLaunch installer].

Download Visual Prolog 11 [https://www.visual-prolog.com/link/demo.php?version=11 Demo Examples].

== Build 1105 ==

=== Language ===

* {{lang|Suspending Predicates|Suspending Predicates}}
* {{lang2|Attributes|feature|feature}} attribute, built-in predicate <vp>is_feature_available</vp>, compiler option '''/ENABLEFEature:feature_name'''
* Built-in predicates <vp>convertAllowNull</vp> and <vp>tryConvertAllowNull</vp>
* Built-in constants <interface><vp>::null</vp> for all interfaces
* Warning: explicit <vp>programmingPoint</vp> available
* Embedded string8 (utf8) support (literals and conversions)
* Warning c665 for a fact which is always initialized with a constant and is not changed (switched off by the default)
* Digit separator support (syntax only) <vp>1_000_000</vp> and <vp>0x_1A2B_3C4D</vp>

=== PFC ===

* Support for asynchronous programming by means of suspending predicates:
** New: <vp>executionContext_pool</vp> a multi threaded pool for asynchronous and background work
** New: <vp>executionContext_single</vp> a single threaded worker for asynchronous work
** New: Suspending predicates can be executed in a GUI thread (using <vp>future::submit</vp>)
** New: Diverse suspending predicate domains in <vp>core</vp>
** Updated: <vp>asyncSocket</vp> & <vp>asyncSocketListener</vp>
** Updated: master/slave support
** Updated: <vp>future</vp>/<vp>promise</vp>
** Updated: HTTP server & JSON RPC & <vp>webSocket</vp>
** Updated: <vp>webView2</vp>
** Updated: <vp>watchDirectory</vp>
** Removed: <vp>continuation</vp> class and inteface due to redundancy.
** Removed: <vp>threadpool</vp> and all related classes and interfaces due to redundancy.
** New support class: <vp>resumable</vp> class for internal support of suspending predicates
** New support classes: <vp>tp</vp> (etc) internal win32 threadpool interface for dealing with asynchronous io, timers, syncObject waiting, etc
** Deprecated/removed diverse continuation based stuff
* MSXML import free threaded xmlhttp: including <vp>iXMLHTTPRequest3</vp>
* Predicate <vp>messageBox::displayWarningYesNo_dt</vp> replacement for <vp>displayWarning_dt</vp>
* Deprecate <vp>messageBox::displayWarning_dt</vp>: UX: It is reccomended to use Yes/No warnings instead of OK/Cancel
* Color predicates <vp>blendColor</vp>, <vp>darken</vp> and <vp>lighten</vp> in <vp>gdiplus</vp>.
* <vp>fetchString8asString</vp> and <vp>useLocalTimeValue</vp> properties on <vp>odbcConnection</vp> and <vp>odbcStatement</vp>.
* <vp>delayCallLimit</vp> predicate on <vp>window</vp> for delay calls with a MaxDelay.
* <vp>inputStream_binary</vp> and <vp>outputStream_binary</vp> supports/allows ansi(utf8) mode.
* Improved <vp>outputStream</vp> performance for <vp>messageControl</vp>.
* <vp>event0</vp>, <vp>event1</vp>, ... classes: lock free threadsafe.
* 'Sergoe Fluent Icons'/'Segoe MDL2 Assets' glyph icons in ribbonControl/commands
* Explorer theme is applied to <vp>treeControl</vp> by default.
* <vp>monitorQueue</vp> and <vp>monitorQueue_length</vp> are updated with <vp>close</vp> functionality. As a result the <vp>dequeue</vp> operation has become determ.
* Console projects supports [https://docs.microsoft.com/en-us/windows/console/console-virtual-terminal-sequences Console Virtual Terminal Sequences] (by off default).
* flag <vp>jsonRpcApi{@Context}::exceptionTraceLevel</vp> controlling which/when exception dumps that are send to the client side.

=== IDE ===

* Main IDE is now always 64bit
* [[Ide/Debugger#Debug_Adapter|Debug Adapter]] makes cross-debugging to 32bit possible
* Dynamic Help (based on browse information and syntax parsing results)
* New toolbar
* vipId support
* Use new Sergoe Fluent Icons
* Default SDI project includes 'Sergoe Fluent Icons'/'Segoe MDL2 Assets' glyph icons the ribbonControl/commands
* Add variable $(node_modules)
* New Menu item handlers (move code expert to properties window)
* Alt+X converts (unicode) hex to char
* changes.htm and appData\doc\vip.chm handling
* Updated Welcome window
* splitterControl in welcome page
* Build system: pre-build command
* Automatic parallel obj/deb directories

=== Debugger ===

* Debugging now uses a [[Ide/Debugger#Debug_Adapter|Debug Adapter]]

=== Other ===

* Remove superfluous webRpc demo & update webServiceDemo to dispose the session.
* The <vp>webServiceDemo</vp> is updated to demonstrate usage of the flag <vp>jsonRpcApi{@Context}::exceptionTraceLevel</vp>.
* Add zip / unzip functionality

== Build 1106 ==

=== Language ===

* Fix: Subtype presenter problem
* Fix: Stack overflow exception on binary constant allocation
* Fix: Wrong debug info for unbound variable (functor component)
* Fix: Debugger/presenters: false objects

=== PFC ===

* webView2
** Fix: Windows 7 and Windows 8 compatibility./li>
** Additional CompleteHandler handling (suspending predicates).
* Fix: <vp>ribbonControl</vp>: Release native graphics context.
* odbc: add column/parameter number for results longer than the buffer.
* <vp>window::centerTo</vp>: map to Windows parent (not pfc parent).

=== IDE ===

* <vp>webView2</vp> control show on Windows 7/8 & update build number
* show correct build number

=== Other ===

* <vp>comWrap</vp>: Handle more winRT CompleteHandlers (for webView2)
* Fix: Runtime debugger/presenters: false objects

== Build 1107 ==

=== PFC ===

* New class <vp>gcUcBuffer</vp>: for buffers that cannot be caught by false pointers.
* odbc: utilize <vp>gcUcBuffer</vp> to avoid that odbc buffers are caught by false pointers.
* New predicate <vp>clipBoard::putFileList</vp> for putting files on the clipboard in the pre-defined hDrop format.
* <vp>command</vp> and <vp>ribbonControl</vp>: new responder <vp>queryBadgeState</vp>.
* Prevent <vp>vpi::processEvents</vp> from interfering with <vp>postAction</vp> order.

=== IDE ===

* Personal edition supports 64 bit targets.
* Open external browser for registration, wiki-help and forum links.
* '''Help -> Prolog Foundation Classes (PFC)''' opens vip.chm.

=== Other ===

Fix: MemoryProfiler wrong scaling of total graph.

== Build 1108 ==

=== PFC ===

* New property <vp>remoteAddress</vp> on interface <vp>httpRequest</vp>.
* New predicate <vp>memory::mkCopy_atomic</vp> for copying structs.
* New predicates <vp>formatSocketAddress</vp> and <vp>formatSockAddr</vp> in class <vp>winSock2_api</vp>.
* <vp>winSock2_api</vp> correct and simplify various domains.

=== IDE ===

* Fix: Exceptions when git is not installed.

== Build 1110 ==

=== Language ===

* <vp>match</vp> and <vp>case</vp> has been reserved as keywords in next major release.

=== PFC ===

* Fix: Wrong type of parameter type in predicate <vp>winHttp_native::winHttpSetOption</vp> declaration.
* Fix: Eliminate race condition for <vp>postAction</vp>.
* Deprecate <vp>time::getTickCount</vp> in favour of <vp>performanceCounter</vp>'s.
* Deprecate <vp>regEx::match</vp> because <vp>match</vp> will become a keyword.

== Build 1111 ==

=== PFC ===

* Fix: time_api::getTimeZoneOffset hours -> minutes
* Fix: odbcStatement::free: allow to be called more than once
* Fix: stringFormat (gdiplus): nullary constructor must create a fresh object

=== Debugger ===

Fix: Dictionary loading timeout for large programs in debug adaptor

== See also ==

See also [[Visual Prolog 11 Upgrade Notes]].

[[Category:Release Notes|11 New Features]]

Visual Prolog 10 Upgrade Notes

2024-04-18T14:16:03Z

Thomas Linder Puls: ctrl -> clt

This document describes how to upgrade Visual Prolog 9 projects to Visual Prolog 10, for older projects you should also read the [[Visual Prolog 9 Upgrade Notes]].

If you have problems with upgrading your projects and need additional information, you are welcome to ask questions in [http://discuss.visual-prolog.com/viewforum.php?f=2 Visual Prolog Discussion Forum].

By default, the installation of Visual Prolog 10 will not replace any previously installed versions. It is possible to work with several versions on a single computer.
* The Commercial Edition will by default be installed in '''C:\Program Files (x86)\Visual Prolog 10''' or '''C:\Program Files\Visual Prolog 10'''.
* The Personal Edition will by default be installed to '''C:\Program Files (x86)\Visual Prolog 10PE''' or '''C:\Program Files\Visual Prolog 10PE'''.

Visual Prolog 10 projects are backward-compatible with Visual Prolog 9 projects.
If you are going to use different versions of Visual Prolog installed at one computer, avoid opening projects by double-clicking on vipprj files.

'''Notice''' it is highly advisable to have a backup of a project before updating.

=== Superfluos files ===

The following files are superfluous and should be deleted:

* '''.frm''' related to forms
* '''.win''' related to e.g. the task window
* '''.ctl''' related to controls
* '''.dlg''' related to dialogs; '''except''' if it corresponds to "aincient" Visual Prolog 5 resource dialog that has been "inherited" into the project. If in doubt: the code in the corresponding '''.pro''' file of such a dialog will not contain a <vp>generatedInitialize</vp> predicate.

=== Binary memory representation ===

Binaries have changed representation. In the old representation a binary was a pointer to the actual data, and immediately before the data the size of the binary was written. Windows API and other external APIs does not use this representation and as a consequence binaries was often had to be copied from the buffer that cntains it to another "buffer" that can hold the size infront of the data. A <vp>binary</vp> is now represented as a pointer to a memory cell containing a pointer to a data-buffer and the size. So the size is no longer placed in a specific place relative to the actual data. With the old representation <vp>uncheckedConvert</vp> of a binary to the <vp>pointer</vp> domain would result in a pointer to the data. With the new representation this is no longer the case and therefore it has been made illegal to <vp>uncheckedConvert</vp> from <vp>binary</vp> to <vp>pointer</vp>, instead you must use <vp>convert</vp> which will both in old and new representation give a pointer to the data. Alternatively, you can use the extension predicate <vp>binary::data()</vp> instead, e.g. <vp>Pointer = MyBinary:date()</vp>.

=== List comprehension ===

In a list comprehension <vp>[ Exp || Gen ]</vp> the <vp>Exp</vp> must be a procedure (language reference has always required that, but the compiler has accepted <vp>determ</vp> expressions). In cases where <vp>Exp</vp> is determ the following rewrite can be applied <vp>[ V || Gen, V = Exp ]</vp>.

=== <>_list domains deprecated ===

The domains <vp>integer_list</vp>, <vp>integer_list_list</vp>, etc. has been deprecated. In declarations the *-form should be used, but in predicate calls like <vp>tryToTerm</vp> it is necessary to uses the <vp>list{...}</vp> type constructor, e.g. <vp>tryToTerm(list{integer}, String)</vp>. An old program can require a significant amount of updates.

=== Erroneous predicates as values ===

<vp>erroneous</vp> predicates can now be used as a value, for example in <vp>X otherwise raise_error()</vp>. Hereby <vp>erroneous</vp> functions have become superfluous, and subsequently it is now illegal to declare <vp>erroneous</vp> functions (a corresponding <vp>erroneous</vp> predicate must be used instead).

== See also ==

* [[Visual Prolog 10 New Features]]
* [[Visual Prolog 9 Upgrade Notes]]

[[Category:Release Notes|10 Upgrade Notes]]

Language Reference/Suspending Predicates

2024-04-16T12:58:59Z

Thomas Linder Puls: Category

{{languageReferenceNavbar|Suspending Predicates}}

The purpose of '''suspending''' predicates is to support asynchronous programming, parallelism, coroutines, etc.

A suspending predicate can suspend its execution and resume it later when 'possible' or 'feasible'. In an asynchronous context, a suspending predicate suspends its execution when it is waiting for an asynchronous operation to complete, allowing other operations to proceed concurrently.

A key advantage of suspending predicates is that they do not block threads while in suspended state, thus enabling efficient utilization of resources. This feature makes them particularly useful in situations where multiple tasks are being executed concurrently.

=== Example ===

{{Example|
We want to have a loop that reads messages from a <vp>webSocket</vp> and echoes them back to the sender.
Most of the time this loop would be waiting for some operation to complete; notably waiting for an incoming message. With synchronous code this would mean that a thread would be blocked most of its lifetime, consuming the resources of a thread which doesn't really do much.

Using asynchronous programming with promises/futures, the code could look like this:
<vip>
class predicates
echoLoop_async : (webSocket WebSocket) -> future{unit}.
clauses
echoLoop_async(WebSocket) =
WebSocket:readMessage_async():thenDo(
{ (Message) = F :-
if webSocket::close(Status, Reason) = Message then
if 0 <> Status then
stdio::writef("Closed:% %\n", Status, Reason)
end if,
F = future::newUnit()
else
F =
WebSocket:writeMessage_async(Message):thenDo(
{ =
echoLoop_async(WebSocket) %
})
end if
}).
</vip>
Such code has several flaws, but here we will just notice that it is both difficult to write and read.

With suspending predicates, the code can be written like this:
<vip>
class predicates
echoLoop_async : (webSocket WebSocket) suspending.
clauses
echoLoop_async(WebSocket) :-
Message = WebSocket:readMessage_async(),
if webSocket::close(Status, Reason) = Message then
if 0 <> Status then
stdio::writef("Closed:% %\n", Status, Reason)
end if
else
WebSocket:writeMessage_async(Message),
echoLoop_async(WebSocket)
end if.
</vip>
It is clear that this code looks exactly like synchronous code, and is therefore just as easy to read and write. But while the code looks like synchronous code the execution is quite different as described below.
}}

=== Language changes ===

The only new language entity is the keyword <vp>suspending</vp> which is added to a predicate declaration and/or predicate domain.

<vip>
domains
webSocket_asyncOp = (webSocket WebSocket) suspending.
class predicates
echoLoop_async : (webSocket WebSocket) suspending.
tryCalculate : () -> integer Result determ suspending.
</vip>

As mentioned earlier, a suspending predicate can pause its execution and resume it later when it's 'possible' or 'feasible.' The use of quotes highlights that the programming language itself doesn't specify the exact conditions for suspension or resumption. However, in certain contexts, the reasons become evident. For instance, when used for asynchronous operations, suspension occurs while waiting for those operations to finish, and execution resumes once they have completed.

=== Suspension ===

A suspending predicate has the ability to suspend its execution for various reasons, typically when waiting for an asynchronous operation to complete.

The key concern with suspension is understanding what happens when execution is paused. For instance, how does it differ from blocking in a synchronous operation? In essence, when a predicate suspends, the thread that was executing its code can be utilized for other tasks. Consequently, a suspended predicate does not 'tie up' a thread.

It's important to note that the execution of suspending predicates cannot be solely viewed in the context of a single thread performing a sequence of actions. Instead, a suspending predicate may consist of parts that are executed by different threads, and these threads may also perform other tasks in between executing the parts associated with a particular suspending predicate.

=== Submitting suspending predicates ===

Suspending predicates can seamlessly invoke other suspending predicates and non-suspending predicates. However, there are certain limitations on calling non-suspending <vp>nondeterm</vp>/<vp>multi</vp> predicates.

When you call a non-suspending predicate, its result is immediately available when the calling thread returns from the call. In contrast, calling a suspending predicate doesn't provide an immediate result because the predicate may suspend execution until an asynchronous operation is complete. Consequently, a non-suspending predicate cannot directly call a suspending one.

Instead, suspending predicates are '''submitted''' for execution within a designated execution context, typically using <vp>future::submit</vp> or <vp>future::submit_unit</vp>. These routines submits the suspending predicate to an <vp>executionContext</vp> and returns a <vp>future</vp> that completes with the result of the suspending predicate. As a result, when a suspending predicate is submitted for execution, the calling thread can continue to perform other tasks while the predicate is being processed.

{{Example|Here we submit the <vp>echoLoop_async</vp> predicate from above and wait for the completion:
<vip>
...
Future = future::submit_unit({ :- echoLoop_async(WebSocket) }),
_ = Future:get(),
...
</vip>}}

=== Await ===

The semantics of a suspending predicate adhere to the same principles as a non-suspending predicate, with the added capability to suspend and later resume execution.

For instance, consider a clause like this:
<vip>
clauses
p_susp() :-
q_susp().
r_susp().
</vip>

In this scenario, the code will initially call <vp>q_susp</vp>, and only after <vp>q_susp</vp> has finished will <vp>r_susp</vp> be called. During this seemingly sequential execution, the execution may suspend multiple times, but <vp>r_susp</vp> won't be invoked until <vp>q_susp</vp> has completed.

However, in scenarios involving asynchronous operations, it can be advantageous to initiate multiple independent operations in parallel and then wait for their completion before proceeding with the utilization of their results.

{{Example|For example, consider this code:
<vip>
clauses
combinePages_susp() = Combined :-
Page1 = fetch_susp("https://....."),
Page2 = fetch_susp("https://....."),
Combined = combine(Page1, Page2).
</vip>
In this code, the fetching of <vp>Page2</vp> won't commence until the fetching of <vp>Page1</vp> has completed.
}}

To handle such cases, you can <vp>submit</vp> a suspending call to the 'background' and obtain a <vp>future</vp> that can be <vp>await</vp>ed.

{{Example|Here's an example based on the previous clause:
<vip>
clauses
combinePages_susp() = Combined :-
Page1Future = future::submit( { = fetch_susp("https://.....") }),
Page2 = fetch_susp("https://....."),
Page1 = Page1Future:await(),
Combined = combine(Page1, Page2).
</vip>
The first fetch is submitted to the background, and we obtain a <vp>future</vp> for it. We do not create a <vp>future</vp> for the second fetch because we have to wait for all fetches to complete anyway, so the last one might just as well be handled in the direct way.
After the fetch of <vp>Page2</vp> has finished, we <vp>await</vp> the completion of the fetch of <vp>Page1</vp>. Then we combine the pages as before.
}}

=== waitSet ===

Using the strategy outlined above, we would wait sequentially for the background operations to complete. However, this approach is suboptimal when one or more of the background operations completes with an exception. There are two key issues with this:

* We won't 'notice' the exception until we <vp>await</vp> that specific operation, which means we may need to wait on several other operations to complete before detecting the exception.
* We won't <vp>cancel</vp> the other operations even though their results won't be used.

To resolve these issues, we can employ a <vp>waitSet</vp>, which is a set of <vp>future</vp>s to wait for. The <vp>waitSet</vp> itself is also a <vp>future</vp> that completes when either all the <vp>future</vp>s in the set have completed successfully or when one of them has completed with an exception (whichever occurs first). If an exception occurs, the <vp>waitSet</vp> will <vp>cancel</vp> all the remaining non-completed futures and complete itself with the same exception.

{{Example|Here's an example using a <vp>waitSet</vp>:
<vip>
clauses
combinePages_susp() = Combined :-
WaitSet = waitSet::new(),
Page1Future = WaitSet:submit( { = fetch_susp("https://.....") }),
Page2Future = WaitSet:submit( { = fetch_susp("https://.....") }),
WaitSet:await_unit(),
Page1 = Page1Future:await(),
Page2 = Page2Future:await(),
Combined = combine(Page1, Page2).
</vip>
It's worth noting that the actual waiting occurs in <vp>WaitSet:await_unit()</vp>. If one of the operations completes with an exception, that exception will become evident at that line of code.}}

=== Execution and cancellation contexts ===

When suspending predicates as 'submitted for execution' they will be submitted to execution in an <vp>executionContext</vp>.

An <vp>executionContext</vp> provides the infrastructure needed to execute suspending code. Various types of execution contexts are available:

* Threadpools: These enable background processing and parallelism.
* A GUI thread: It executes the suspended parts during message handling steps.
* Regular threads: They enter waiting states to facilitate the resumption of suspended parts.

However, the use of <vp>executionContext</vp>s can give rise to certain challenges. GUI operations, for example, are typically constrained to a GUI context, while threadpools enable background processing and parallelism. This may necessitate context switching in specific situations (though the exact means for doing so may vary).

Additionally, suspending predicates also execute within a '''cancellation''' context.

Both the <vp>executionContext</vp> and the <vp>cancellation</vp> context of a suspending 'task' can be accessed through thread-local variables. It's important to note that most programmers need not directly manipulate these variables, as they are managed and utilized through library software (e.g., <vp>future</vp>'s library).

=== Implementation ===

The implementation of suspending predicates is primarily designed to fulfill the specified semantics, and it is not necessary for programmers to fully understand the intricacies of the implementation. However, a brief description of the underlying implementation is provided for those interested.

Basically, suspending predicates are transformed into 'ordinary' code, and run as such.

The transformation has three major elements:

* Code Transformation: The code is converted into continuation-based code, where all 'returning' actions are replaced by calls to a continuation. Actual returning is employed when the execution suspends and terminates.
* Stack to Heap: Stack-frames are converted into heap-frames, which can persist in the heap while execution is suspended and can be resumed on any thread.
* Backtrack Points: Backtrack points and trap points for suspending predicates are stored in the heap rather than on the run stack.

A critical aspect of the translation scheme is that each time a suspending predicate is called, it is treated as a '''final''' call. Final calls are optimized to discard the current stack frame before making the call, ensuring that the new predicate's stack frame replaces the current one. This means that only one frame is left on the stack, even with nested calls.

When a predicate suspends, it returns from that call and leaves nothing on the stack.

To manage 'what happens next' when a predicate suspends and may return before completing its work, continuations are used. Continuations are predicates that represent 'what to continue with when the current operation is done'.

Continuation predicates are used to handle branching and join back to shared code. For instance, common code after conditional branches is placed into a separate continuation predicate, which is then called at the end of all branches.

This implementation scheme below is illustrative: the actual scheme may differ for various reasons (e.g., optimization). We will use the following naming conventions:

* <vp><name>_susp</vp> indicates that the predicate is suspending. Predicates that does not end in <vp>_susp</vp> are non-suspending.
* Names ending with an underscore represent "translated" predicates and built-in/internal entities.

Let us at first disregard all data and only consider <vp>procedure</vp>s.

A predicate is translated into one that takes an extra continuation argument, where a <vp>continuation_</vp> is an (object) predicate with no arguments.
<vip>
domains
continuation_ = ().
</vip>

The continuation represents what happens after this predicate has done whatever it is supposed to do, i.e. how the computation ''continues'' afterwards.

{{Example|The predicate
<vip>
class predicates
task_susp : () suspending.
</vip>
is translated into a predicate <vp>task_susp_</vp> that takes a continuation as argument instead of returning:
<vip>
class predicates
task_susp_ : (continuation_ Cont_).
</vip>
}}

For every suspending predicate we create a heap-frame class. Where a <vp>heapframe_</vp> is an object with a single predicate <vp>go_</vp>:

<vip>
interface heapframe_
predicates
go_ : ().
end interface heapframe_
</vip>

Such a class will have a constructor that receives the continuation (and any original arguments) as arguments.

{{Example|For the predicate above we will create a class like this:
<vip>
class task_susp_frm_ : heapframe_
constructors
new : (continuation_ Cont_).
end class task_susp_frm_
</vip>
}}

Now let us consider the translation of clauses.

{{Example|We will consider this clause
<vip>
clauses
task_susp() :-
openChannel(),
fetch1_susp(),
fetch2_susp(),
closeChannel().
</vip>
The code will "open a channel" by calling a non-suspending predicate <vp>openChannel</vp>, then it will call the suspending predicate <vp>fetch1_susp</vp>, and so forth.
}}

The original clause will be transformed into one that takes a continuation as argument, and then constructs a heapframe object and finally invoke <vp>go_</vp> on that predicate.

{{Example|The clause will look like this
<vip>
clauses
task_susp_(Cont_) :-
F = task_susp_frm_::new(Cont_),
F:go_().
</vip>
Notice that the call to <vp>go_</vp> is a final call so the stack frame for <vp>task_susp_</vp> is replaced by the stack frame for <vp>go_</vp>. Leaving only one frame on the stack.
}}

The original code of the clause will be moved to the <vp>go_</vp> predicate and a number of <vp>continuation_</vp> predicates.

Each time we call a suspendable predicate we create a continuation predicate in the class and pass that as the continuation argument to the suspendable predicate (i.e. it's translation).

{{Example|For the clause above the class will look like this:
<vip>
implement task_susp_frm_

facts
cont_ : continuation_.

clauses
new(Cont_) :-
cont_ := Cont_.

clauses
go() :-
openChannel(),
fetch1_susp_(cont1_).

predicates
cont1_ : continuation_.
clauses
cont1_() :-
fetch2_susp_(cont2_).

predicates
cont2_ : continuation_.
clauses
cont2_() :-
closeChannel(),
cont_().

end implement task_susp_frm_
</vip>
The overall <vp>continuation_</vp> is stored in a fact variable, it will be invoked when the entire clause has run to the end.
The <vp>go_</vp> clause first call the non-suspending predicate <vp>openChannel</vp> and then it calls the suspending predicate <vp>fetch1_susp</vp> or rather the translation of this predicate <vp>fetch1_susp_</vp>. This predicate is called with the <vp>continuation_</vp> predicate <vp>cont1_</vp>.
<vp>cont1_</vp> represents what happens after the call to <vp>fetch1_susp_</vp> has finished, which is calling <vp>fetch2_susp_</vp> (the translation of <vp>fetch2_susp</vp>) with <vp>cont2_</vp> as argument.
<vp>cont2_</vp> represents what happens after the call to <vp>fetch2_susp_</vp> has finished, which is calling <vp>closeChannel</vp>. And since the entire clause is then finished, we end <vp>cont2_</vp> with calling <vp>cont_</vp>, because it represents what happens after this clause.
}}

Notice that the calls to non-suspending predicates (like <vp>openChannel</vp>) is made in a completely normal way and that these predicates can create stack frames as they like. However all such calls have completed before we call another suspendable predicate. So at the time we call a suspendable predicate the stack only contains the frame of the current suspendable predicate and that frame will be replaced by the new frame because the call to the new suspendable predicate is made as a final call.

Also notice that execution cannot suspend inside a non-suspending predicate, so when suspension takes place there is only one stack frame on the stack, and when we return from that call the stack is completely vacated.

Branching which join back to shared code cause an additional need for continuation predicates as illustrated in this example:

{{Example|Consider this clause
<vip>
clauses
pred_susp() :-
if test() then
sub_susp()
else
ordinary()
end if,
<common code>.
</vip>
<vp><common code></vp> is the continuation of both branches in the <vp>if-then-else</vp>. But the call to <vp>sub_susp</vp> is a final call. So we do not come back to <common code>.
}}

Basically, such common code is put into a separate continuation predicate, which is then called in the end of all branches.

{{Example|Consider this as a kind of "schematic middle step":
<vip>
clauses
pred_susp() :-
if test() then
sub_susp(),
contX_()
else
ordinary(),
contX_()
end if.

predicates
contX_ : continuation_.
clauses
contX_() :-
<common code>.
</vip>
Given this transformation there is no longer code to execute after the <vp>if-then-else</vp>.
}}

==== Backtracking & exception handling ====

Backtracking and exception handling are managed in a similar manner in Visual Prolog. In this discussion, we'll primarily focus on the handling of backtracking.

In Visual Prolog, each thread maintains a chain of backtrack points, and there exists a thread-global pointer known as <vp>bTop_</vp> that points to the head of this chain. Each backtrack point carries essential information needed to transfer control back to the alternative branch (the failure alternative). When a failure occurs, the system removes the first backtrack point from the chain, adjusts the <vp>bTop_</vp> pointer to point to the next backtrack point in the chain, and restores the state based on the information stored in the backtrack point.

The handling of 'cut' (<vp>!</vp>) involves resetting the <vp>bTop_</vp> pointer to a specific value, which is stored in a variable at an earlier point in time. While we won't delve into the intricate details of this process, it's important to note that it involves operations that utilize variables within a clause. Despite the programmer not explicitly specifying the variable, the system manages it like any other variable.

However, when dealing with suspending predicates, two specific issues arise regarding the standard handling of backtracking:

* Backtrack Point Storage: Traditional backtrack points are stored in the stack, which conflicts with the need to entirely clear the stack in case of suspension.
* State Restoration: Non-deterministic (<vp>nondeterm</vp/<vp>multi</vp>) predicates maintain their state on the stack, allowing backtracking to reset to that specific stack state. However, in a suspending context, this approach is problematic since a suspending predicate may resume execution on a completely different stack.

To address the first issue, suspending predicates allocate backtrack points in the heap instead of storing them on the stack. This ensures that they can persist even when the stack is cleared due to suspension.

Regarding the second issue, a non-suspending backtrack point contains information about how to restore the stack and frame pointers. However, restoring the state in this manner doesn't make sense for suspending predicates because they may resume execution on a different stack. Instead, a suspending backtrack point restores the stack to the location where the suspending predicates have their stack frame. This stack frame remains in the same place throughout the execution of suspendable code, except when it suspends and is later resumed in a different location (note that backtracking doesn't occur while execution is suspended). Thus, during the execution of suspendable code on a particular thread and stack, a thread-global pointer is used to indicate where suspending backtrack points should restore to.

The second issue also affects the state of suspendable nondeterministic predicates themselves. Unlike non-suspending predicates, both suspending and non-suspending backtrack points in suspendable nondeterministic predicates store their state in the heap instead of on the stack. This avoids conflicts with suspension and ensures that state can be managed effectively.

In general, calling non-suspending <vp>nondeterm</vp>/<vp>multi</vp> predicates from suspending predicates is not allowed due to the challenges in restoring backtrack points on potentially different stacks. However, it may be possible to do so in cases where it can be guaranteed that all backtracking is completed before reaching a point where a suspending predicate is called. For example, a list comprehension does not leave any backtrack points, so if all calls inside the list comprehension are non-suspending, there is no issue with calling a non-suspending nondeterministic predicate within it.

While it may be difficult to figure out yourself whether those conditions are fulfilled, you don't need to worry the compiler will tell you if there is a problem.

As mentioned, exception handling is handled very similar to backtracking, but simpler in the sense that catch-points cannot be "left-behind" in the same way as backtrack points can. Trap-points are restored when backtracking back into the try section of a try-catch, but the problem that this cause relates to backtracking rather than to the trap-points themselves. Also, in this case the problem is for non-suspending nondeterm/multi predicates.

Windows will however not accept that trap-points are heap allocated. So in on "low level" all exceptions are trapped with completely normal exception trapping code, which then delegates the exception handling to the heap stored trap points:

{{Example|The code for this will look something like this:
<vip>
try
<run suspending code>
catch TraceId do
suspendingExceptionHandling(TraceId)
end try
</vip>
Where <vp>suspendingExceptionHandling</vp> will find the heap allocated trappoint chain and delegate the exception handling to it.}}

==== Parameters & Variables ====

Now let's consider how to deal with parameters, etc.

In Visual Prolog (i.e., for the <vp>prolog</vp> calling convention) all function return values are transformed into output arguments. So, in the final code there is only input and output arguments, but no return values. Output arguments are handled by passing a pointer to where the result must be stored. So, an output argument is actually a input pointer argument.

The general principle for dealing with parameters and variables from the original code is to store them as fact variables in the heapframe object rather than on the run-stack.

{{Example|Several of the predicates here would more naturally be functions, but to maintain focus we will make them into predicates with output variables ourselves. We have also simplified the clause by only having one fetch, this will simplify the example without loosing any essence.
<vip>
class predicates
task_susp : (string Server, string Result [out]) suspending.
clauses
task_susp(Server, Result) :-
openChannel(Server, Channel),
fetch_susp(Channel, Result),
closeChannel(Channel).
</vip>
}}

As before the predicate is translated into one with an additional continuation argument. Furthermore, all output arguments are converted to an input pointer argument instead.

{{Example|
<vip>
class predicates
task_susp_ : (contination_ Cont_, string Server, pointerTo{string} ResultPtr_).
</vip>
}}

Again, we create a heapframe class with a constructor that receives all the arguments of the translated predicate.

{{Example|The class looks like this
<vip>
class task_susp_frm_ : heapframe_
constructors
new : (continuation_ Cont_, string Server, pointerTo{string} ResultPtr_).
end class task_susp_frm_
</vip>
}}

And the original clause is translated into one that creates a heapframe object and invoke <vp>go_</vp> as a final call.

{{Example|The clause will look like this
<vip>
clauses
task_susp_(Cont_, Server, ResultPtr_) :-
F = task_susp_frm_::new(Cont_, Server, ResultPtr_),
F:go_().
</vip>
}}

The heapframe class/object will contain fact variables corresponding to all parameters and variables (optimizations are not considered here). And like before we will place the actual code in the <vp>go_</vp> predicate and <vp>continuation_</vp> predicates.

{{Example|The code will look like this:
<vip>
implement task_susp_

facts
cont_ : continuation_.
channel_ : channel.
resultPtr_ : ::pointerTo{::string}.
server_ : ::string.

clauses
new(Cont_, Server, ResultPtr_) :-
cont_ := Cont_,
server_ := Server,
resultPtr_ := ResultPtr_.

clauses
go_() :-
fact_address_(channel_, ChannelPtr),
openChannel(server_, ChannelPtr),
fetch_susp(cont1_, channel_, resultPtr_).

predicates
cont1_ : continuation_.
clauses
cont1_() :-
closeChannel(channel_),
cont_().

end implement task_susp_
</vip>
}}

There are many details around the handling of the facts that represents parameters and variables. The main principles are:

* Input parameters and variables are represented as facts with their original type. In some places the address of such facts are needed (e.g., <vp>ChannelPtr</vp> in the call to <vp>openChannel</vp>).
* Output parameters (of the predicate itself) are received and stored as a pointerTo{...} fact. In some cases, it may be necessary to dereference the pointer (does not occur in this example).

Visual Prolog 11 Upgrade Notes

2024-04-08T09:30:50Z

Thomas Linder Puls: remove line shift

This document describes how to upgrade Visual Prolog 10 projects to Visual Prolog 11, for older projects you should also read the [[Visual Prolog 10 Upgrade Notes]].

If you have problems with upgrading your projects and need additional information, you are welcome to ask questions in [http://discuss.visual-prolog.com/viewforum.php?f=2 Visual Prolog Discussion Forum].

By default, the installation of Visual Prolog 11 will not replace any older installed versions. It is possible to work with several versions on a single computer. See also [[vipLaunch]].

The Commercial and Personal Edition are identical; differences in capabilities are controlled by the license used to activate the computer.

Entities that are not available to Personal Edition usage are marked with the attribute <vp>[feature("Commercial Edition")]</vp>.

Visual Prolog 11 is installed ''per user'' in '''...\Users\<user>\AppData\Roaming\Visual Prolog\11'''.

Visual Prolog 11 project files are backward-compatible with Visual Prolog 10 project files.

'''Notice''' it is highly advisable to have a backup of a project before updating.

When updating a project you should open the project in the new IDE and accept to remove any non-existing PFC packages. Then build the project and accept to

* delete all bad include directives
* insert new ones and
* add new PFC packages

=== Superfluous Files ===

If you haven't removed the superfluous resource files then see [[Visual Prolog 10 Upgrade Notes#Superfluous_files]].

=== match & case future keywords ===

<vp>match</vp> and <vp>case</vp> will be keywords in future releases of Visual Prolog and you will receive warnings if you use them.

<vp>regEx::</vp><b>match</b> has been retired and renamed to <vp>regEx::matchFirst</vp>

=== gdiplus ===

If your project initializes gdiplus, e.g. like this:

<vip>
clauses
run() :-
_ = mainForm::display(gui::getScreenWindow()),
GDIpToken = gdiplus::startup(),
messageLoop::run(),
gdiplus::shutdown(GDIpToken).
</vip>

Then simply remove the calls to <vp>gdiplus::startup</vp> and <vp>gdiplus::shutdown</vp> code:

<vip>
clauses
run() :-
_ = mainForm::display(gui::getScreenWindow()),
messageLoop::run().
</vip>

The <vp>color</vp> class/interface has been retired, and superseded by the domain <vp>gdiplus_native::color</vp>. In many cases you simply have to remove the call to <vp>color::create</vp>.

This line (in the '''GDI+ Example'')
<vip>
DarkRed = pen::createColor(color::create(gdiplus_native::darkred), penWidth, unit),
</vip>
has been changed to:
<vip>
DarkRed = pen::createColor(gdiplus_native::darkred, penWidth, unit),
</vip>

A little editor trick: if you use autoformatting of code (a project setting) you can just remove <vp>color::create</vp>:
<vip>
DarkRed = pen::createColor((gdiplus_native::darkred), penWidth, unit),
</vip>
When you save the file the superfluous parentheses will be removed automatically. Therefore you can correct an entire file simply by replacing all occurrences of <vp>color::create</vp> with nothing/blank.

Furthermore, some domains have been relocated from the <vp>gdiplus</vp> class to the <vp>gdiplus_native</vp> class. The "Fix" button in the error window should handle that problem automatically. Otherwise, the IDE command '''Insert -> Qualification Ctrl+Shift+S''' can also insert or correct the qualification.

The object predicate <vp>graphics::drawString/6</vp> has been retired, instead you will have to choose between:

<vip>
predicates
drawStringIn : (font Font, brush Brush, rectF LayoutRect, string String, stringFormat StringFormat = stringFormat::null).
drawStringAt : (font Font, brush Brush, pointF Origin, string String, stringFormat StringFormat = stringFormat::null).
</vip>

* <vp>graphics::drawStringIn</vp> draws the string in the rectangle <vp>LayoutRect</vp> or
* <vp>graphics::drawStringAt</vp> draws the string at the point <vp>Origin</vp>

=== treeModel_std & treeNode_std ===

If you use the <vp>treeControl</vp> with the <vp>treeModel_std</vp> you will have to add <vp>code::value</vp> as argument to <vp>treeModel_std</vp> and <vp>treeNode_std</vp>. Notice that this is not necessary in clauses; only in other places (declarations, ...).

Here illustrated with code from the <vp>dragNdropDemo</vp> in the examples:

<vip>
implement mainForm inherits formWindow
open core, vpiDomains, treeModel_std{core::value}
...
predicates
onDragBegin : treeControl{treeNode_std{value}}::dragBeginResponder.
...
% This code is maintained automatically, do not update it manually. 10:41:58-23.11.2011
facts
treeCtl : treecontrol{treeNode_std{value}}.
...
</vip>

Notice that if you have deleted the form/dialog file (as described in [[Visual Prolog 10 Upgrade Notes#Superfluos_files|superfluous Files]]) then you can (despite the warning in the comment) edit directly in the "auto"-code.

=== codePageId ansi & threadAnsi ===

The following <vp>codePageID</vp>'s have been deprecated:

<vip>
constants
ansi : codePage = 0 [deprecated("It is recommended not to use this codepage, but use an explicit encoding instead")].
threadAnsi : codePage = 3 [deprecated("It is recommended not to use this codepage, but use an explicit encoding instead")].
% @short Represents the systems/threads current ANSI codePage.
% It is recommended not to use this codepage but use an explicit encoding instead.
% @end
</vip>

The problem with these system/user codepages is that they are often set to some regional codepage with 8 bit characters. Files written like must be read with the same codepage, otherwise characters may become wrong or even lost.

Some time ago (unknown when) Microsoft have introduced the possibility to use utf-8 as system/user codepage. Using utf-8 is technically the best choice, because it "unites" all regional "things" into a single codepage. However but the transition from old regional codepages to utf-8 is "difficult", because you will still need to read a file with the codepage that was used to write it.

We recommend that you "migrate" text files to utf-8 (or utf-16 if you mainly use "special" characters, like chinese). If you add a byte order mark the format becomes "visible", but in some contexts (certain Internet contexts and using foreign applications) byte order marks in utf-8 files will not be accepted.

=== Fallback CodePage ===

Several text file related predicates have been equipped with a non-optional <vp>FallbackCodePage</vp> argument. For example:

<vip>
class inputStream_file : inputStream
...
constructors
openFileText : (string Filename, codePage FallbackCodePage, fileSystem_api::accessPermit Access = fileSystem_api::permitRead).
</vip>

The predicate <vp>inputStream_file::openFileText</vp> examines the file to open searching for Byte Order Marks and obvious utf-16 format. If it is not possible to determine the codepage like that the <vp>FallbackCodePage</vp> will be used. Such predicates used to user the <vp>threadAnsi</vp> codepage, but (as described above) this can lead to problems with "old" files and new settings and files written on one computer and read on another. For this reason you must now (explicitly) decide which codepage to use if it cannot be inferred.

=== COM component classes ===

The import of COM components has been simplified for certain COM components. Instead of being defined in a separate Visual Prolog class many COM components are now created by calling a predicate.

For example, to create an XMLHTTP component you would construct object using the corresponding constructor <vp>XmlHttp = xmlhttp60::new()</vp>, now you will instead call the predicate <vp>XmlHttp = msxml_HTTP_api::newXmlhttp60()</vp>.

=== watchDirectory ===

<vp>watchDirectory</vp> has been updated to use suspending predicates, and as result <vp>watchDirectory::start</vp> takes an <vp>executionContext</vp> as argument. In most cases <vp>pfc\asynchronous\executionContext_pool::defaultPool</vp> can be used.

<vip>
WD = watchDirectory::start(FullDir, pfc\asynchronous\executionContext_pool::defaultPool),
</vip>

=== Master/slave ===

The master/slave concept has been updated to use {{lang|Suspending Predicates|suspending predicates}} instead of explicit <vp>continuation</vp>s. The article [[Master/slave processes]] and the corresponding demo example has been updated to reflect the changes.

=== Web Services & webSockets ===

The Web Services and <vp>webSocket</vp>s support has been updated to use {{lang|Suspending Predicates|suspending predicates}} for asynchronous operation. The main updates necessary to make an old program working is remove all access to <vp>threadpool</vp>s.

This code
<vip>
clauses
runServer() :-
...
mkService(Session, "File service", "", requestQueue_content::new(threadpool, demoFileService::contentMapper)),
...
</vip>
will look like this:
<vip>
clauses
runServer() :-
...
mkService(Session, "File service", "", requestQueue_content::new(demoFileService::contentMapper)),
...
</vip>

If necessary you can add an explicit <vp>executionContext</vp> (<vp>Ctx</vp>):

<vip>
clauses
runServer() :-
httpServer_api::httpInitialize(httpServer_native::http_initialize_server),
Session = session::new(),
Ctx = pfc\asynchronous\executionContext_pool::defaultPool,
try
cleanup:alsoDispose(Session),
% Demo file service for html, JavaScript , images, etc to the client
mkService(Session, "File service", "", requestQueue_content::new(demoFileService::contentMapper, Ctx)),
...
</vip>

The changes in <vp>webSocket</vp> requires more attention. You will have to remove <vp>continuation</vp>s and use {{lang|Suspending Predicates|suspending predicates}} instead.

For example, the predicate onAttach_async must now be a suspending predicate:

<vip>
interface webSocketService

predicates
onAttach_async : (httpRequest Request, webSocket WebSocket) suspending.
...
</vip>

The implementation of this predicate:

<vip>
clauses
onAttach_async(Request, WebSocket, Continuation) :-
onAttach2_async(filename::getLastDirectory(Request:path, _), WebSocket, Continuation).
</vip>

should drop the <vp>Continuation</vp> argument:

<vip>
clauses
onAttach_async(Request, WebSocket) :-
onAttach2_async(filename::getLastDirectory(Request:path, _), WebSocket).
</vip>

<vp>onAttach2_async</vp> should also be declared as a suspending predicate (without a <vp>continuation</vp> argument):

<vip>
predicates
onAttach2_async : (string Last, webSocket WebSocket) suspending.
</vip>

The interesting part is that the real functional predicates like:

<vip>
class predicates
echoLoop_async : (webSocket WebSocket, continuation{unit} Continuation).
clauses
echoLoop_async(WebSocket, Continuation) :-
WebSocket:readMessage_async(
Continuation:mkContinue(
{ (Message) :-
if webSocket::close(Status, Reason) = Message then
if 0 <> Status then
stdio::writef("Closed:% %\n", Status, Reason)
end if,
Continuation:success(unit)
else
if webSocket::ss(U16) = Message then
stdio::writef("Message:%\n", segmented_utf16::getAsString(U16))
end if,
WebSocket:writeMessage_async(Message,
Continuation:mkContinue(
{ :-
echoLoop_async(WebSocket, Continuation) %
}))
end if
})).
</vip>

Should now be implemented as a suspending predicate which result in much simpler code:

<vip>
class predicates
echoLoop_async : (webSocket WebSocket) suspending.
clauses
echoLoop_async(WebSocket) :-
Message = WebSocket:readMessage_async(),
if webSocket::close(Status, Reason) = Message then
if 0 <> Status then
stdio::writef("Closed:% %\n", Status, Reason)
end if
else
if webSocket::ss(U16) = Message then
stdio::writef("Message:%\n", segmented_utf16::getAsString(U16))
end if,
WebSocket:writeMessage_async(Message),
echoLoop_async(WebSocket)
end if.
</vip>

Especially, notice that this fragment of the code:

<vip>
clauses
...
WebSocket:readMessage_async(
Continuation:mkContinue(
{ (Message) :-
...
})).
</vip>

simply becomes an ordinary call:

<vip>
clauses
...
Message = WebSocket:readMessage_async(),
...
</vip>

== See also ==

* [[Visual Prolog 11 New Features]]
* [[Visual Prolog 10 Upgrade Notes]]

[[Category:Release Notes|11 Upgrade Notes]]

Visual Prolog 11 Upgrade Notes

2024-04-08T09:29:55Z

Thomas Linder Puls: mach & case