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

Language Reference/Terms/in

2024-09-27T03:25:48Z

SergeMukhin: typo

<vipbnf><InOperator>:
in</vipbnf>

The <vp>in</vp> operator is used to test for member ship of a collection (e.g. a list) and to nondeterministically generate the members of a collection.

{{Example|
<vip>predicates
p : (Type X, Type* L).
clauses
p(X, L) :-
if X in L then
write("X is in L\n")
end if.</vip>
<vp>p</vp> is a procedure that takes a value <vp>X</vp> and a list <vp>L</vp> as arguments. If <vp>X</vp> is in the list <vp>L</vp> then it will write <vp>"X is in L"</vp>. In this case in is used as an in-test (membership test).
}}

{{Example|
<vip>predicates
q : (Type* L).
clauses
q(L) :-
foreach X in L do
writef("% is in L\n", X)
end foreach.</vip>
<vp>q</vp> is a procedure that takes a list <vp>L</vp> as argument. The "in" operator is used to nondeterministically return the members of L, so that they can be written.}}

The <vp>in</vp> operator can be defined for any domain and interface using the <vp>in_test</vp> and <vp>in_iterate</vp> attributes.

The <vp>in_test(<predicate name>)</vp> attribute defines the predicate that is used as in-test for a certain domain or interface. Likewise the <vp>in_iterate</vp> attribute defines the predicate that is used as in-iterator for the domain/interface.

{{Example|
<vip>domains
tree{E} = empty; node(tree{E} Left, E Value, tree{E} Right)
[in_test(isMemberTree), in_iterate(getAll_nd)].</vip>
When the program contains <vp>A in B</vp> where <vp>A</vp> is bound <vp>B</vp> is a <vp>tree{E}</vp> then <vp>isMemberTree</vp> is actually called.

In that case <vp>A in B</vp> corresponds to <vp>isMemberTree(A, B)</vp>.

If <vp>A</vp> is free the call corresponds to <vp>A = getAll_nd(B)</vp>.}}

For a domain <collection> the predicate must have the type:

<vip>predicates
<predicate> : (<some-type> Elem, <collection> Collection) determ.</vip>

{{Example|
<vip>interface collection [in_test(contains), in_iterate(getAll_nd)]
...
end interface collection</vip>
When the program contains <vp>A in B</vp> where <vp>A</vp> is bound <vp>B</vp> is a <vp>collection</vp> then <vp>contains</vp> is actually called.

In that case <vp>A in B</vp> corresponds to <vp>B:contains(A)</vp>.

If <vp>A</vp> is free the call corresponds to <vp>A = B:getAll_nd()</vp>.}}

For a domain <vp><collection></vp> the <vp>in_test</vp> and <vp>in_iterate</vp> predicate must fulfill these schematic declarations:

<vip>domains
<collection> = ... [in_test(<in_test>), in_iterate(<in_iterate>)].
class predicates
<in_test> : (<some-type> Elem, <collection> Collection) determ.
<in_iterate : (<collection> Collection) -> <some-type> Elem nondeterm.</vip>

For an interface <vp><collection></vp> the <vp>in_test</vp> and <vp>in_iterate</vp> predicate must fulfill these schematic declarations:

<vip>interface <collection> [in_test(<in_test>), in_iterate(<in_iterate>)]
predicates
<in_test> : (<some-type> Elem) determ.
<in_iterate : () -> <some-type> Elem nondeterm.
...
end interface <collection></vip>

The <vp>in</vp> operator is predefined on list domains, and in PFC the collections have suitable attributes.

{{Example|
<vip>clauses
p() :-
foreach X in [1, 2, 3, 4] do % in_iterate
if X in [2, 4] then % in_test
...
end if
end foreach.</vip>

The first <vp>in</vp> is the predefined <vp>in_iterate</vp> for the list domain, and the second one is the predefined <vp>in_test</vp>.

<vip>clauses
q() :-
M1 = setM_redBlack::new(),
M1:inset("a"),
M1:inset("b"),
M2 = setM_redBlack::new(),
M2:inset("b"),
foreach X in M1 do % in_iterate
if X in M2 then % in_test
...
end if
end foreach.</vip>

For collections the <vp>in</vp> operators resolve to <vp>contains</vp> and <vp>getAll_nd</vp>:

<vip>interface collection{@Type}
[in_test(contains), in_iterate(getAll_nd)]

predicates
contains : (@Type Value) determ.
% @short Succeeds if the collection contains the value @Type
% @end

predicates
getAll_nd : () -> @Type Value nondeterm.
% @short @Type is nondeterministic iteration of the elements in the collection.
% @end

...

end interface collection</vip>}}
<noinclude>{{LanguageReferenceSubarticle|Terms/in}}</noinclude>

Language Reference/Terms

2024-08-09T05:44:48Z

SergeMukhin: typo

{{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}}

Ide/Key Bindings

2024-02-27T10:35:20Z

SergeMukhin: remove old accelerators

{{ideNavbar|Key Bindings}}

The table below shows Visual Prolog accelerator keys by functions.

:{| {{prettytable}}
|-
|colspan="2" align="center" style="background:#cee0f2; text-align:center; font-weight:bold; color: #006B9C;" |
Edit
|-
| Copy
| Ctrl-C or Ctrl-Ins
|-
| Copy Position
| Ctrl-Alt-Shift-C
|-
| Cut
| Ctrl-X or Shift-Del
|-
| Paste
| Ctrl-V or Shift-Ins
|-
| Undo
| Ctrl-Z
|-
| Redo
| Ctrl-Y
|-
| Select All
| Ctrl-A
|-
| Select Current Word
| Ctrl-W
|-
| Delete
| Del
|-
| Delete Line
| Ctrl-Shift-L
|-
| Delete to End of Line
| Ctrl-Shift-E
|-
| Delete to Start of Line
| Ctrl-Shift-H
|-
| Word Delete To End
| Ctrl-Del
|-
| Replace
| Ctrl-H
|-
| Lower Case
| Ctrl-U
|-
| Upper Case
| Ctrl-Shift-U
|-
| Toggle Case
| Ctrl-Alt-U
|-
| Zoom In
| Ctrl-[+] or Ctrl-Mouse wheel up
|-
| Zoom Out
| Ctrl-[-] or Ctrl-Mouse wheel down
|-
| Zoom to Normal
| Ctrl-0
|-
| Comment Line(s)
| Ctrl-Alt-5
|-
| Uncomment Line(s)
| Ctrl-Alt-Shift-5
|-
| Duplcate Line
| Ctrl-Alt-R
|-
| Add qualification
| Ctrl-Shift-S
|-
| Insert Date Stamp
| Ctrl-Shift-Y
|-
|colspan="2" align="center" style="background:#cee0f2; text-align:center; font-weight:bold; color: #006B9C;" |
Navigation
|-
| Find
| Ctrl-F
|-
| Find in Files
| Ctrl-Shift-F
|-
| Find Next
| F3
|-
| Find Previous
| Shift-F3
|-
| Last Searchs Result Window
| Ctrl-Alt-S
|-
| Locate in Project Tree
| Ctrl-T
|-
| Go Back
| Ctrl-Shift-F8
|-
| Go to Address
| Ctrl-G
|-
| Go to Definition
| F12
Ctrl-Shift-C
|-
| Go To Declaration
| Ctrl-F12
Ctrl-Shift-D
|-
| Go to Related Files
| Ctrl-R
|-
| Go to Executing Predicate Source
| Ctrl-E
|-
| Go To Line
| Ctrl-F2
|-
| Go To Position on Clipboard
| Shift-F2
|-
| Go To Next Error
| F8
|-
| Go To Previous Error
| Shift-F8
|-
| Go To Next Bookmark
| F6
|-
| Go To Previous Bookmark
| Shift-F6
|-
| Window Navigation Dialog
| Ctrl-Tab or Ctrl-F6
|-
| Set/Remove bookmark
| Ctrl-K
|-
|colspan="2" align="center" style="background:#cee0f2; text-align:center; font-weight:bold; color: #006B9C;" |
Compile
|-
| Build
| Ctrl-Shift-B
|-
| Stop Build
| Ctrl-Break
|-
| Compile
| Ctrl-F7
|-
| Rebuild Project
| Ctrl-Shift-Alt-B
|-
| Run
| Ctrl-F5
|-
| Run in Window
| Alt-F5
|-
|colspan="2" align="center" style="background:#cee0f2; text-align:center; font-weight:bold; color: #006B9C;" |
Debug
|-
| Start Debugging
| F5
|-
| Run Debugging Skipping Soft Breakpoints
| Ctrl-Shift-F10
|-
| Stop Debugging
| Shift-F5
|-
| Restart Debugging
| Ctrl-Shift-F5
|-
| CallStack Window
| Ctrl-Alt-C
|-
| Variable Window
| Ctrl-Alt-V
|-
| Watch Window
| Ctrl-Alt-W
|-
| Facts Window
| Ctrl-Alt-F
|-
| Threads Window
| Ctrl-Alt-H
|-
| Modules Window
| Ctrl-Alt-L
|-
| Exceptions Window
| Ctrl-Alt-X
|-
| Breakpoints Window
| Ctrl-Alt-B
|-
| Bookmarks Window
| Ctrl-Alt-K
|-
| Disassembly Window
| Ctrl-Alt-D
|-
| Disassembly Window from Current Line
| Ctrl-D
|-
| Registers window
| Ctrl-Alt-G
|-
| Memory Dump 1 Window
| Ctrl-Alt-M
|-
| Toggle Breakpoint
| F9
|-
| Toggle Hard/Soft Breakpoint
| Ctrl-F9
|-
| Breakpoint Properties
| Alt-F9
|-
| Step Into
| F11
|-
| Step out of
| Shift-F11
|-
| Step Over
| F10
|-
| Run To Cursor
| Ctrl-F10
|-
|colspan="2" align="center" style="background:#cee0f2; text-align:center; font-weight:bold; color: #006B9C;" |
Project
|-
| Add Module to Project
| Ctrl-Shift-A
|-
| Create Project Item
| Ctrl-N
|-
| Create Project Item in Existing Package
| Ctrl-Alt-N
|-
|colspan="2" align="center" style="background:#cee0f2; text-align:center; font-weight:bold; color: #006B9C;" |
IDE
|-
| Close all other editors
| Ctrl-Q
|-
| Prune open editors
| Ctrl-Shift-Q
|-
| Close the active window
| Ctrl-F4
|-
| Project window
| Ctrl-Alt-P
|-
| Project Settings
| Alt-F7
|-
| Open File
| Ctrl-O
|-
| Save File
| F2
|-
| Save Project
| Ctrl-S
|-
| Source Browser
| Ctrl-B
|-
|colspan="2" align="center" style="background:#cee0f2; text-align:center; font-weight:bold; color: #006B9C;" |
Other
|-
| Help
| F1
|-
| Messages Window
| Ctrl-Alt-O
|-
| Error/Warnings Window
| Ctrl-Alt-E
|-
| Print
| Ctrl-P
|-
| Exit IDE
| Alt-F4
|}

[[ru:IDE:Горячие Клавиши]]

Ide/Key Bindings

2024-02-25T12:46:47Z

SergeMukhin: remove old accelerators

{{ideNavbar|Key Bindings}}

The table below shows Visual Prolog accelerator keys by functions.

:{| {{prettytable}}
|-
|colspan="2" align="center" style="background:#cee0f2; text-align:center; font-weight:bold; color: #006B9C;" |
Edit
|-
| Copy
| Ctrl-C or Ctrl-Ins
|-
| Copy Position
| Ctrl-Alt-Shift-C
|-
| Cut
| Ctrl-X or Shift-Del
|-
| Paste
| Ctrl-V or Shift-Ins
|-
| Undo
| Ctrl-Z
|-
| Redo
| Ctrl-Y
|-
| Select All
| Ctrl-A
|-
| Select Current Word
| Ctrl-W
|-
| Delete
| Del
|-
| Delete Line
| Ctrl-Shift-L
|-
| Delete to End of Line
| Ctrl-Shift-E
|-
| Delete to Start of Line
| Ctrl-Shift-H
|-
| Word Delete To End
| Ctrl-Del
|-
| Replace
| Ctrl-H
|-
| Lower Case
| Ctrl-U
|-
| Upper Case
| Ctrl-Shift-U
|-
| Toggle Case
| Ctrl-Alt-U
|-
| Zoom In
| Ctrl-[+] or Ctrl-Mouse wheel up
|-
| Zoom Out
| Ctrl-[-] or Ctrl-Mouse wheel down
|-
| Zoom to Normal
| Ctrl-0
|-
| Comment Line(s)
| Ctrl-Alt-5
|-
| Uncomment Line(s)
| Ctrl-Alt-Shift-5
|-
| Duplcate Line
| Ctrl-Alt-R
|-
| Add qualification
| Ctrl-Shift-S
|-
| Insert Date Stamp
| Ctrl-Shift-Y
|-
|colspan="2" align="center" style="background:#cee0f2; text-align:center; font-weight:bold; color: #006B9C;" |
Navigation
|-
| Find
| Ctrl-F
|-
| Find in Files
| Ctrl-Shift-F
|-
| Find Next
| F3
|-
| Find Previous
| Shift-F3
|-
| Last Searchs Result Window
| Ctrl-Alt-S
|-
| Locate in Project Tree
| Ctrl-T
|-
| Go Back
| Ctrl-Shift-F8
|-
| Go to Address
| Ctrl-G
|-
| Go to Definition
| F12
Ctrl-Shift-C
|-
| Go To Declaration
| Ctrl-F12
Ctrl-Shift-D
|-
| Go to Related Files
| Ctrl-R
|-
| Go to Executing Predicate Source
| Ctrl-E
|-
| Go To Line
| Ctrl-F2
|-
| Go To Position on Clipboard
| Shift-F2
|-
| Go To Next Error
| F8
|-
| Go To Previous Error
| Shift-F8
|-
| Go To Next Bookmark
| F6
|-
| Go To Previous Bookmark
| Shift-F6
|-
| Window Navigation Dialog
| Ctrl-Tab or Ctrl-F6
|-
| Set/Remove bookmark
| Ctrl-K
|-
|colspan="2" align="center" style="background:#cee0f2; text-align:center; font-weight:bold; color: #006B9C;" |
Compile
|-
| Build
| Ctrl-Shift-B
|-
| Stop Build
| Ctrl-Break
|-
| Compile
| Ctrl-F7
|-
| Rebuild Project
| Ctrl-Shift-Alt-B
|-
| Run
| Ctrl-F5
|-
| Run in Window
| Alt-F5
|-
|colspan="2" align="center" style="background:#cee0f2; text-align:center; font-weight:bold; color: #006B9C;" |
Debug
|-
| Start Debugging
| F5
|-
| Run Debugging Skipping Soft Breakpoints
| Ctrl-Shift-F10
|-
| Stop Debugging
| Shift-F5
|-
| Restart Debugging
| Ctrl-Shift-F5
|-
| CallStack Window
| Ctrl-Alt-C
|-
| Variable Window
| Ctrl-Alt-V
|-
| Watch Window
| Ctrl-Alt-W
|-
| Facts Window
| Ctrl-Alt-F
|-
| Threads Window
| Ctrl-Alt-H
|-
| Modules Window
| Ctrl-Alt-L
|-
| Exceptions Window
| Ctrl-Alt-X
|-
| Breakpoints Window
| Ctrl-Alt-B
|-
| Bookmarks Window
| Ctrl-Alt-K
|-
| Disassembly Window
| Ctrl-Alt-D
|-
| Disassembly Window from Current Line
| Ctrl-D
|-
| Registers window
| Ctrl-Alt-G
|-
| Memory Dump 1 Window
| Ctrl-Alt-M
|-
| Toggle Breakpoint
| F9
|-
| Toggle Hard/Soft Breakpoint
| Ctrl-F9
|-
| Breakpoint Properties
| Alt-F9
|-
| Breakpoint -> Bookmark
| Ctrl-Alt-F9
|-
| Bookmark -> Breakpoint
| Ctrl-Alt-F9
|-
| Step Into
| F11
|-
| Step out of
| Shift-F11
|-
| Step Over
| F10
|-
| Run To Cursor
| Ctrl-F10
|-
|colspan="2" align="center" style="background:#cee0f2; text-align:center; font-weight:bold; color: #006B9C;" |
Project
|-
| Add Module to Project
| Ctrl-Shift-A
|-
| Create Project Item
| Ctrl-N
|-
| Create Project Item in Existing Package
| Ctrl-Alt-N
|-
|colspan="2" align="center" style="background:#cee0f2; text-align:center; font-weight:bold; color: #006B9C;" |
IDE
|-
| Close all other editors
| Ctrl-Q
|-
| Prune open editors
| Ctrl-Shift-Q
|-
| Close the active window
| Ctrl-F4
|-
| Project window
| Ctrl-Alt-P
|-
| Project Settings
| Alt-F7
|-
| Open File
| Ctrl-O
|-
| Save File
| F2
|-
| Save Project
| Ctrl-S
|-
| Source Browser
| Ctrl-B
|-
|colspan="2" align="center" style="background:#cee0f2; text-align:center; font-weight:bold; color: #006B9C;" |
Other
|-
| Help
| F1
|-
| Messages Window
| Ctrl-Alt-O
|-
| Error/Warnings Window
| Ctrl-Alt-E
|-
| Print
| Ctrl-P
|-
| Exit IDE
| Alt-F4
|}

[[ru:IDE:Горячие Клавиши]]

Ide/Key Bindings

2024-02-22T08:52:27Z

SergeMukhin: remove acc for new\open project

{{ideNavbar|Key Bindings}}

The table below shows Visual Prolog accelerator keys by functions.

:{| {{prettytable}}
|-
|colspan="2" align="center" style="background:#cee0f2; text-align:center; font-weight:bold; color: #006B9C;" |
Edit
|-
| Copy
| Ctrl-C or Ctrl-Ins
|-
| Copy Position
| Ctrl-Alt-Shift-C
|-
| Cut
| Ctrl-X or Shift-Del
|-
| Paste
| Ctrl-V or Shift-Ins
|-
| Undo
| Ctrl-Z
|-
| Redo
| Ctrl-Y or Ctrl-Shift-Z
|-
| Select All
| Ctrl-A
|-
| Select Current Word
| Ctrl-W
|-
| Delete
| Del
|-
| Delete Line
| Ctrl-Shift-L
|-
| Delete to End of Line
| Ctrl-Shift-E
|-
| Delete to Start of Line
| Ctrl-Shift-H
|-
| Word Delete To End
| Ctrl-Del
|-
| Replace
| Ctrl-H
|-
| Lower Case
| Ctrl-U
|-
| Upper Case
| Ctrl-Shift-U
|-
| Toggle Case
| Ctrl-Alt-U
|-
| Zoom In
| Ctrl-[+] or Ctrl-Mouse wheel up
|-
| Zoom Out
| Ctrl-[-] or Ctrl-Mouse wheel down
|-
| Zoom to Normal
| Ctrl-0
|-
| Comment Line(s)
| Ctrl-Alt-5
|-
| Uncomment Line(s)
| Ctrl-Alt-Shift-5
|-
| Duplcate Line
| Ctrl-Alt-R
|-
| Add qualification
| Ctrl-Shift-S
|-
| Insert Date Stamp
| Ctrl-Shift-Y
|-
|colspan="2" align="center" style="background:#cee0f2; text-align:center; font-weight:bold; color: #006B9C;" |
Navigation
|-
| Find
| Ctrl-F
|-
| Find in Files
| Ctrl-Shift-F
|-
| Find Next
| F3
|-
| Find Previous
| Shift-F3
|-
| Last Searchs Result Window
| Ctrl-Alt-S
|-
| Locate in Project Tree
| Ctrl-T
|-
| Go Back
| Ctrl-Shift-F8
|-
| Go to Address
| Ctrl-G
|-
| Go to Definition
| F12
Ctrl-Shift-C
|-
| Go To Declaration
| Ctrl-F12
Ctrl-Shift-D
|-
| Go to Related Files
| Ctrl-R
|-
| Go to Executing Predicate Source
| Ctrl-E
|-
| Go To Line
| Ctrl-F2
|-
| Go To Position on Clipboard
| Shift-F2
|-
| Go To Next Error
| F8
|-
| Go To Previous Error
| Shift-F8
|-
| Go To Next Bookmark
| F6
|-
| Go To Previous Bookmark
| Shift-F6
|-
| Window Navigation Dialog
| Ctrl-Tab or Ctrl-F6
|-
| Set/Remove bookmark
| Ctrl-K
|-
|colspan="2" align="center" style="background:#cee0f2; text-align:center; font-weight:bold; color: #006B9C;" |
Compile
|-
| Build
| Ctrl-Shift-B
|-
| Stop Build
| Ctrl-Break
|-
| Build Resource Only
| Alt-F8
|-
| Compile
| Ctrl-F7
|-
| Rebuild Project
| Ctrl-Shift-Alt-B
|-
| Run
| Ctrl-F5
|-
| Run in Window
| Alt-F5
|-
| 32 bit Platform
| Ctrl-Alt-3
|-
| 64 bit Platform
| Ctrl-Alt-6
|-
|colspan="2" align="center" style="background:#cee0f2; text-align:center; font-weight:bold; color: #006B9C;" |
Debug
|-
| Start Debugging
| F5
|-
| Run Debugging Skipping Soft Breakpoints
| Ctrl-Shift-F10
|-
| Stop Debugging
| Shift-F5
|-
| Restart Debugging
| Ctrl-Shift-F5
|-
| Refresh Debug Window
| Ctrl-R
|-
| CallStack Window
| Ctrl-Alt-C
|-
| Variable Window
| Ctrl-Alt-V
|-
| Watch Window
| Ctrl-Alt-W
|-
| Facts Window
| Ctrl-Alt-F
|-
| Delete Object from Facts Tree Retract Fact(s)
| Ctrl-Del
|-
| Threads Window
| Ctrl-Alt-H
|-
| Modules Window
| Ctrl-Alt-L
|-
| Exceptions Window
| Ctrl-Alt-X
|-
| Breakpoints Window
| Ctrl-Alt-B
|-
| Bookmarks Window
| Ctrl-Alt-K
|-
| Disassembly Window
| Ctrl-Alt-D
|-
| Disassembly Window from Current Line
| Ctrl-D
|-
| Registers window
| Ctrl-Alt-G
|-
| Memory Dump 1 Window
| Ctrl-Alt-M
|-
| Toggle Breakpoint
| F9
|-
| Toggle Hard/Soft Breakpoint
| Ctrl-F9
|-
| Breakpoint Properties
| Alt-F9
|-
| Breakpoint -> Bookmark
| Ctrl-Alt-F9
|-
| Bookmark -> Breakpoint
| Ctrl-Alt-F9
|-
| Step Into
| F11
|-
| Step out of
| Shift-F11
|-
| Step Over
| F10
|-
| Run To Cursor
| Ctrl-F10
|-
|colspan="2" align="center" style="background:#cee0f2; text-align:center; font-weight:bold; color: #006B9C;" |
Project
|-
| Add Module to Project
| Ctrl-Shift-A
|-
| Create Project Item
| Ctrl-N
|-
| Create Project Item in Existing Package
| Ctrl-Alt-N
|-
|colspan="2" align="center" style="background:#cee0f2; text-align:center; font-weight:bold; color: #006B9C;" |
IDE
|-
| Close all other editors
| Ctrl-Q
|-
| Prune open editors
| Ctrl-Shift-Q
|-
| Close the active window
| Ctrl-F4
|-
| Project window
| Ctrl-Alt-P
|-
| Project Settings
| Alt-F7
|-
| Open File
| Ctrl-O
|-
| Save File
| F2
|-
| Save Project
| Ctrl-S
|-
| Source Browser
| Ctrl-B
|-
|colspan="2" align="center" style="background:#cee0f2; text-align:center; font-weight:bold; color: #006B9C;" |
Other
|-
| Help
| F1
|-
| Messages Window
| Ctrl-Alt-O
|-
| Error/Warnings Window
| Ctrl-Alt-E
|-
| Print
| Ctrl-P
|-
| Exit IDE
| Alt-F4
|}

[[ru:IDE:Горячие Клавиши]]

Language Reference/Built-in entities/Domains

2023-11-12T12:33:23Z

SergeMukhin: remove ()

{|{{prettytable}}
|-
|[[#any|any]]
|Universal term type.
|-
|[[#char|char]]
|Wide (two-bytes) character.
|-
|[[#string|string]]
|Wide zero-terminated sequence of wide characters.
|-
|[[#string8|string8]]
|Zero-terminated sequence of ASCII (one-byte) characters.
|-
|[[#symbol|symbol]]
|Wide zero-terminated sequence of wide characters.
|-
|[[#binary|binary]]
|Sequence of bytes.
|-
|[[#binaryNonAtomic|binaryNonAtomic]]
|Sequence of bytes.
|-
|[[#integer|integer]]
|32 bit signed integer.
|-
|[[#integer64|integer64]]
|64 bit signed integer.
|-
|[[#integerNative|integerNative]]
|Signed integer with platform size (32 bit in a 32 bit program; 64 bit in a 64 bit program).
|-
|[[#unsigned|unsigned]]
|32 bit unsigned integer.
|-
|[[#unsigned64|unsigned64]]
|64 bit unsigned integer.
|-
|[[#unsignedNative|unsignedNative]]
|Unsigned integer with platform size (32 bit in a 32 bit program; 64 bit in a 64 bit program).
|-
|[[#real|real]]
|Float-pointing number.
|-
|[[#real32|real32]]
|Float-pointing number.
|-
|[[#pointer|pointer]]
|pointer to a memory address.
|-
|[[#handle|handle]]
|a handle (e.g. native file and windows handles).
|-
|[[#boolean|boolean]]
|Boolean values.
|-
|[[#factDB|factDB]]
|Descriptors of named internal databases.
|-
|[[#compareResult|compareResult]]
|Values of comparison result.
|}

==== any ====

Universal term type.

<vip>any</vip>

The values of this domain are any terms. Such a value contains the reference to the term type library and a term itself.

==== char ====

Wide character.

<vip>char</vip>

The values of this domain are UNICODE characters. Implemented as 2 unsigned bytes.

Only assignment and comparison (in the lexicographical sense) operations are applied to the values of this domain. 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> correspond to 4 hexadecimal digits. Also, the backslash symbol and the single quote can be represented by an escape-sequence only.

==== compareResult ====

The result of a comparison. For instance, the built-in procedure {{lang2|Built-in entities|compare|compare/2->}} has "compareResult" as the domain of its result.
<vip>domains
compareResult = less; equal; greater.
</vip>

==== string ====

Utf-16 strings.

<vip>string</vip>

A string represented as a pointer to a zero terminated sequence of characters in utf-16 encoding. Values in the sequence are 16 bits, but certain rare characters (code points) are encoded using two such values. Strings are immutable.

In source code a string literal can be specified as a set of sequences of characters surrounded by the double quotes.

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

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

A string literal consists of one or more <vpbnf><StringLiteralPart></vpbnf>'s, which are concatenated. <vpbnf><StringLiteralPart></vpbnf>'s starting with <vp>@</vp> does not use escape sequences, whereas <vpbnf><StringLiteralPart></vpbnf>'s without <vp>@</vp> uses the following escape sequences:

*<vp>\\</vp> representing <vp>\</vp>
*<vp>\t</vp> representing Tab-character
*<vp>\n</vp> representing newline-character
*<vp>\r</vp> representing carriage return
*<vp>\'</vp> representing single quote
*<vp>\"</vp> representing double quote
*<vp>\u</vp> followed by exactly four <vpbnf><HexadecimalDigit></vpbnf>'s representing the Unicode character corresponding to the digits.

The double quotes in the string can be represented by the escape-sequence only (the single quote can be represented both with an escape-sequence and a graphical symbol).

==== string8 ====

A built-in domain who's elements are sequences of (one-byte) ASCII-characters. It is implemented as a pointer to the zero terminated array of ASCII characters. Only assignment and comparison for equality (in the lexicographical sense) operations are applied to the values of this domain. Currently no literals are allowed for this domain.

==== symbol ====

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

<vip>symbol</vip>

A <vp>symbol</vp> is stored in a global symbol table, and that storage guarenties that the pointer value of symbols will be the same for the same symbol. Once a <vp>symbol</vp> is put into the symbol table it is never removed again, so <vp>symbol</vp>s are never reclaimed. Their storage will live untill the program terminates. So the <vp>symbol</vp> data type should not be used for large documents, etc.

The <vp>symbol</vp> domain is a subtype of the <vp>string</vp> domain, so a symbol can be used everywhere instead of a string. The opposite is not the case because a <vp>string</vp> will have to be found or inserted in the global symbol table to become a <vp>symbol</vp>. So to create a symbol from a string you will have to <vp>convert</vp> the string to the symbol domain (or a subtype of the <vp>symbol</vp> domain).

The equality operation is very efficient for <vp>symbol</vp>s since their pointer value will be the same if the <vp>symbol</vp> is the same. I.e. there is no need to compare the actual characters to determine equality.

Other comparison operations (less than, case insensitive comparison, etc) are the same as for <vp>string</vp> in fact all other operations on <vp>symbol</vp> is simply carried out by the corresponding string operations.

==== binary ====

Sequence of bytes.

<vip>binary</vip>

Values of this domain are used for holding binary data. A binary value is implemented as a pointer to the sequence of bytes that represents the contents of a binary term.

The length of a binary term is situated in the '''4 bytes''' immediately preceding this sequence of bytes. The 4 bytes contains:

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

where <vp>ByteLen</vp> - is the length of the binary term and 4 is number of bytes occupied by size field.

Only assignment and comparison operations are applied to values of '''binary domain'''.

Two binary terms are compared in the following way:

*If they are of different sizes, the bigger is considered larger.
*Otherwise, they are compared byte by byte, as unsigned values. Comparison stops when two differing bytes are found and the result of their comparison is the result of the comparison of the binary terms. Two binary terms are equal if they have the same sizes and all bytes are equal.

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

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

Each ''expression'' should be calculate on compiling time and its value should be in the range from <vp>0</vp> to <vp>255</vp>.

==== binaryNonAtomic ====

Sequence of bytes.

<vip>binaryNonAtomic</vip>

Same as [[#binary|binary]], but can contain pointers because it is scanned by the garbage collector.

==== integer ====

32 bit signed integer.

<vip>integer</vip>

Values of this domain occupy 4 bytes. Arithmetic operations (<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->}} operations are applied to values of this domain.

The permitted number range is from <vp>-2147483648</vp> to <vp>2147483647</vp>.

The syntax for the <vp>integer</vp> literal is determined by the <vpbnf><Integer></vpbnf> rule:

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

<vip>integer64</vip>

Values of this domain occupy 8 bytes.

The permitted number range is from <vp>-2^63 = -9223372036854775808</vp> to <vp>2^63-1 = 9223372036854775807</vp>.

The syntax for <vp>integer64</vp> literal is the same as <vpbnf><Integer></vpbnf> rule.

The set of operations for <vp>integer64</vp> is similar to the one for <vpbnf><Integer></vpbnf>.

==== integerNative ====

Signed integer number with platform size (32 bit in a 32 bit program; 64 bit in a 64 bit program).

<vip>integerNative</vip>

==== unsigned ====

32 bit unsigned integer.

<vip>unsigned</vip>

Values of this domain occupy 4 bytes. Arithmetic operations (<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->}} operations are applied to values of this domain.

The permitted number range is from <vp>0</vp> to <vp>4294967295</vp>.

The syntax for <vp>unsigned</vp> number images is the same as for <vp>integer</vp> numbers. The usage of minus sign (<vpbnf><UnaryMinus></vpbnf>) is not allowed for an image of an <vp>unsigned</vp> number.

==== unsigned64 ====

64 bit unsigned integer.

<vip>unsigned64</vip>

Values of this domain occupy 8 bytes.

The permitted number range is from <vp>0</vp> to <vp>2^64-1 = 18,446,744,073,709,551,615</vp>.

The syntax for <vp>unsigned64</vp> number images is the same as for <vp>integer64</vp> numbers. The usage of minus sign (<vpbnf><UnaryMinus></vpbnf>) is not allowed for an image of an <vp>unsigned64</vp> number.

The set of operations for <vp>unsigned64</vp> is similar to the one for <vpbnf><Unsigned></vpbnf>.

==== unsignedNative ====

Unsigned integer number with platform size (32 bit in a 32 bit program; 64 bit in a 64 bit program).

<vip>unsignedNative</vip>

==== real ====

Float-pointing number.

<vip>real</vip>

Values of this domain occupy 8 bytes. This numerical real domain is introduced for the user's convenience only. All arithmetic, comparison, and assignment operations are applied to values of <vp>real</vp> domain.

The permitted number range is <vp>-1.7e+308</vp> to <vp>1.7e+308</vp>. Values from integral domains are automatically converted to real numbers when necessary.

The syntax for the floating-point number literal is determined by the <vpbnf><Real></vpbnf> rule:

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

Float-pointing number.

<vip>real32</vip>

Values of this domain occupy 4 bytes. This numerical <vp>real32</vp> domain is introduced for the user's convenience only. All arithmetic, comparison, and assignment operations can be applied to values of <vp>real32</vp> domain.

The permitted number range is <vp>-3.4e+38</vp> to <vp>3.4e+38</vp>.

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

==== pointer ====

A pointer to a memory address.

<vip>pointer</vip>

A pointer directly corresponds to memory addresses. Only the equality operation can be applied to the values of this domain. 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>. It's definition is like this (but it is built-in):

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

==== handle ====

A handle is used for Windows API function call. Values of this domain has the same size as a pointer (i.e. 4 on 32bit platfor and 8 on 64bit platform).

There are no operations for this domain and cannot be converted (except uncheckedConvert) to/from other domains.

There is a built-in [[#nullHandle|nullHandle]] and [[#invalidHandle|invalidHandle]] constant for this type

==== boolean ====

Boolean values.

<vip>boolean</vip>

This domain is introduced for the user convenience only. It is treated as usual compound domain with the following definition:

<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 the constants of this domain. The compiler automatically builds the corresponding compound terms from such constants whenever it's in need. At the runtime the 1st field of this structure contains the address of the corresponding domain descriptor and the 2nd field contains either zero (for class facts sections) or pointer to an object (i.e. <vp>This</vp>, for object facts sections).
<noinclude>{{LanguageReferenceSubarticle|Built-in entities/Domains}}</noinclude>

Language Reference/Terms

2023-02-19T19:18:44Z

SergeMukhin: /* Object Expressions */

{{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> objets.

<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/Built-in entities/Predicates

2021-06-07T16:51:04Z

SergeMukhin: typo

<noinclude>__NOTOC__</noinclude>

{|{{prettytable}}
|-
|[[Language_Reference/Terms#and_.28.2C.29|and/2]] [[Language_Reference/Terms#and_.28.2C.29|,/2]]
|Term "and"
|-
|[[#assert|assert/1]]
|Insert the specified fact at the end of the matched internal facts database.
|-
|[[#asserta|asserta/1]]
|Insert a fact at the beginning of the matched internal facts database.
|-
|[[#assertz|assertz/1]]
|Insert a fact at the end of the matched internal facts database.
|-
|[[#bound|bound/1]] <vp>determ</vp>
|Test whether the specified variable is bound to a value.
|-
|[[#class_name|class_name/0->]]
|This compile time predicate returns the string ''ClassName'' that represents the name of the current interface or class.
|-
|[[#compare|compare/2->]]
|Returns the result of the variables' comparison.
|-
|[[#constant_name|constant_name/0->]]
|This compile time predicate returns the string ''ConstantName'' that represents the name of the current constant. Typically used in execepion definitions.
|-
|[[#convert|convert/2->]]
|Checked term conversion.
|-
|[[#digitsOf|digitsOf/1->]]
|Returns precision of the specified floating-point domain.
|-
|[[#errorExit|errorExit/1]] <vp>erroneous</vp>
|Performs a run-time error with the specified return code ''ErrorNumber'' and sets the internal error information.
|-
|[[#fact_address|fact_address/1->]]
|Returns the address of a fact variable.
|-
|[[#fail|fail/0]] <vp>failure</vp>
|Invoke backtracking.
|-
|[[#free|free/1]] <vp>determ</vp>
|Check whether a variable is free.
|-
|[[#fromEllipsis|fromEllipsis/1->]]
|Creates the list of terms of the universal type <vp>any</vp> from the ''EllipsisBlock''.
|-
|[[#hasDomain|hasDomain/2]] [[#hasDomain|hasDomain/2->]]
|Declares/restricts the type of a variable or value.
|-
|[[Language_Reference/Terms#in|in/2]] <vp>determ</vp> [[Language_Reference/Terms#in|in/2]] <vp>nondeterm</vp>
|Infix operator "in" (in-test and in-iterator).
|-
|[[#isErroneous|isErroneous/1]] <vp>determ</vp>
|Returns the lower bound value of the specified numeric domain.
|-
|[[#lowerBound|lowerBound/1->]]
|Returns the lower bound value of the specified numeric domain.
|-
|[[#maxDigits|maxDigits/1->]]
|Retrieves the value of digits (precision) of the basic domain corresponding to the specified floating-point domain ''domainName''.
|-
|[[#not|not/1]] <vp>determ</vp>
|Negate the result (success/fail) of subgoal.
|-
|[[Language_Reference/Terms#otherwise|otherwise/2]]
|Infix expression operator providing a value when a determ expression fails
|-
|[[Language_Reference/Terms#or_.28.3B.29|or/2]] [[Language_Reference/Terms#and_.28.3B.29|;/2]]
|Nondeterministic term "or"
|-
|[[Language_Reference/Terms#orelse|orelse]]
|Deterministic term "or"
|-
|[[#predicate_fullname|predicate_fullname/1->]]
|This compile time predicate returns the string ''PredicateFullName'' that represent the name of the predicate in which clause body <vp>predicate_name</vp> is called. The returned predicate name is qualified with a scope name.
|-
|[[#predicate_name|predicate_name/1->]]
|This compile time predicate returns the string ''PredicateName'' that represent the name of the predicate in which clause body <vp>predicate_name</vp> is called. The returned predicate name is not qualified with a scope name.
|-
|[[#programPoint|programPoint/0->]]
|This compile time predicate returns the <vp>programPoint</vp> corresponding to the place where it is called.
|-
|[[#retract|retract/1]] <vp>nondeterm</vp>
|Remove a matched fact from the matched internal facts database.
|-
|[[#retractall|retractall/1]]
|Remove all matching facts from the matched internal facts database.
|-
|[[#retractFactDb|retractFactDb/1]]
|Remove all facts from the specified named internal facts database.
|-
|[[#sizeBitsOf|sizeBitsOf/1->]]
|Retrieves the number of bits occupied in memory by an entity of the specified domain ''DomainName''.
|-
|[[#sizeOf|sizeOf/1->]]
|Retrieves the number of bytes occupied in memory by the specified term.
|-
|[[#sizeOfDomain|sizeOfDomain/1->]]
|Retrieves the number of bytes occupied in memory by the entity of the specified domain ''DomainName''.
|-
|[[#sourcefile_lineno|sourcefile_lineno/0->]]
|Returns the current line number in the source file processed by the compiler .
|-
|[[#sourcefile_name|sourcefile_name/0->]]
|Returns the name of the source file processed by the compiler.
|-
|[[#sourcefile_timestamp|sourcefile_timestamp/0->]]
|Returns the string representing the date and time of the source file processed by the compiler.
|-
|[[#succeed|succeed/0]]
|The predicate <vp>succeed/0</vp> will always succeed.
|-
|[[#toAny|toAny/1->]]
|Converts the specified ''Term'' to the value of the universal term type <vp>any</vp>.
|-
|[[#toBinary|toBinary/1->]]
|Converts the specified Term to the binary representation.
|-
|[[#toBoolean|toBoolean/1->]]
|The purpose of this meta-predicate is to convert the deterministic call (to a predicate or fact) to the procedure that returns the value of <vp>boolean</vp> domain.
|-
|[[#toEllipsis|toEllipsis/1->]]
|Creates the ''EllipsisBlock'' from the list of <vp>any</vp> type values.
|-
|[[#toString|toString/1->]]
|Converts the specified ''Term'' to the string representation.
|-
|[[#toTerm|toTerm/1->]] [[#toTerm|toTerm/2->]]
|Converts the string/binary representation of the specified term ''SrcTerm'' into representation corresponding to the domain of ''PrologTerm'' variable of the return value.
|-
|[[#tryToTerm|tryToTerm/1->]] <vp>determ</vp> [[#tryToTerm|tryToTerm/2->]] <vp>determ</vp>
|Converts the string/binary representation of the specified term ''SrcTerm'' into representation corresponding to the domain of ''PrologTerm'' variable of the return value.
|-
|[[#tryConvert|tryConvert/2->]] <vp>determ</vp>
|Checks whether the input term ''InputTerm'' can be strictly converted into the specified domain ''returnDomain'' and returns the converted term ''ReturnTerm''.
|-
|[[#typeDescriptorOf|typeDescriptorOf/1->]]
|Returns the <vp>typeDescriptor</vp> of a value.
|-
|[[#typeLibraryOf|typeLibraryOf/1->]]
|Returns the <vp>typeLibrary</vp> of a value.
|-
|[[#uncheckedConvert|uncheckedConvert/2->]]
|Unchecked conversion of domains.
|-
|[[#upperBound|upperBound/1->]]
|Returns the upper bound value of the specified numeric domain.
|}

The following predicates are deprecated:
{|{{prettytable}}
|-
| finally/2
| Use [[Language_Reference/Terms#try-finally| <vp>try-finally</vp>]] constuction instead.
|-
| findall/3
| Use list comprehension [[Language_Reference/Terms#List_Comprehension| <vp>[ ... || ... ]</vp>]] instead
|-
| trap/3 <vp>determ</vp>
| Use [[Language_Reference/Terms#try-catch| <vp>try-catch</vp>]] constuction instead.
|}

==== and ====

See [[Language_Reference/Terms#and_.28.2C.29|and (,)]].

==== assert ====

<vip>assert : (<fact-term> FactTerm).</vip>

Insert the specified fact at the end of the matched internal facts database

<vp>assert(Fact)</vp> inserts <vp>Fact</vp> in the matched internal facts database after any other stored facts for the corresponding database predicate. <vp>Fact</vp> must be a term belonging to the domain of an internal facts database. <vp>assert/1</vp> applied to a single fact changes the existing instance of a fact to the specified one. <vp>assert/1</vp> has the same effect as [[#assertz|assertz/1]]. See also [[#asserta|asserta/1]].

Notice that the combination of [[#retract|retract/1]] and <vp>assert/1</vp> like the following can lead to endless loop:

<vip>loop() :-
retract(fct(X)),
... % creating Y from X
assert(fct(Y)),
fail.</vip>

The problem is that the retract in first line will eventually retract the fact asserted in the last line, because that fact is inserted ''last'' in the fact chain.

Exceptions:

* Attempt to assert a second instance to a fact declared as determ.

==== asserta ====

<vip>asserta : (<fact-term> FactTerm).</vip>

Insert a fact at the beginning of the matched internal facts database.

The <vp>asserta(Fact)</vp> predicate inserts a <vp>Fact</vp> in the matched internal facts database before any other stored facts for the corresponding predicate. The <vp>Fact</vp> must be a term belonging to the domain of an internal facts database. The <vp>asserta/1</vp> applied to a single fact changes the existing instance of a fact to the specified one. See also [[#assert|assert/1]] and [[#assertz|assertz/1]].

Exceptions:

* Attempt to a fact declared as determ, but the fact instance already exists.

==== assertz ====

<vip>assertz : (<fact-term> FactTerm).</vip>

<vp>assertz</vp> does exactly the same as the [[#assert|assert/1]] predicate.

==== bound ====

<vip>bound : (<variable> Variable) determ.</vip>

Test whether the specified variable is bound to a value.

The <vp>bound(Variable)</vp> succeeds if <vp>Variable</vp> is bound and fails if it is free. The <vp>bound</vp> predicate is used to control flow patterns and to check the binding of reference variables. The <vp>bound</vp> predicate treats the specified <vp>Variable</vp> as bound if any of it's part is instantiated.

See also [[#free|free/1]].

==== class_name ====

<vip>class_Name : () -> string ClassName.</vip>

This compile time predicate returns the string <vp>ClassName</vp> that represents the name of the current interface or class.

==== compare ====

<vip>compare : (A Left, A Right) -> compareResult CompareResult.</vip>

Comparison of two terms of the same domain, resturns the value of [[#compareResult|compareResult]] domain.

<vp>CompareResult</vp> = compare("<vp>bar</vp>", "<vp>foo</vp>")

==== constant_name ====

<vip>constant_name : () -> string ConstantName.</vip>

This compile time predicate returns the string <vp>ConstantName</vp> that represents the name of the current constant. It is typically used in exception definitions.

==== convert ====

<vip>convert : (<type> Type, Term) -> <type> Converted.</vip>

Checked term conversion.

Call-template for this function is:

<vp>ReturnTerm</vp> = convert(returnDomain, <vp>InputTerm</vp>)

* <vpbnf>returnDomain</vpbnf>: Specifies a domain to which function <vp>convert/2-></vp> converts <vp>InputTerm</vp>. Here ''returnDomain'' must be a name of built-in Visual Prolog domain, an interface domain, a name of such user defined domain that is synonym to one of built-in Visual Prolog domains, a numeric domain, binary and pointer domains. The domain name ''returnDomain'' must be specified at compile-time, i.e. it cannot come from a variable.

* <vpbnf><InputTerm></vpbnf>: Specifies the value that must be converted. <vp>InputTerm</vp> may be any Prolog term or an expression. If <vp>InputTerm</vp> is an expression, then it will be evaluated before the conversion.

* <vpbnf><ReturnTerm></vpbnf>: Returned parameter <vp>ReturnTerm</vp> will be of ''returnDomain'' type.

The <vp>convert</vp> predicate performs a clean and genuine conversion of the given <vp>InputTerm</vp>, returning a new term <vp>ReturnTerm</vp> of the specified new domain ''returnDomain''. If <vp>convert</vp> cannot perform the required conversion, it rises errors. The similar functionality is provided by the [[#tryConvert|tryConvert/2->]] predicate, but <vp>tryConvert-></vp> fails and does not produce any runtime errors if it cannot perform the conversion.

===== Allowed conversions =====

* Between numerical domains.
* Between interface types.
* Between [[#string|string]] and [[#symbol|symbol]] domains.
* From [[#binary|binary]] to [[#pointer|pointer]].
* For synonyms of mentioned domains.
* Between [http://wiki.visual-prolog.com/index.php?title=How_To_Remove_Reference_Domains_from_a_Project reference] domains and corresponding non-reference domains.

The contrast to these is [[#uncheckedConvert|uncheckedConvert/2->]] predicate, which performs an unchecked conversion between terms from any domains, which have the same bit-size.

The <vp>convert/2-></vp> (or [[#tryConvert|tryConvert/2->]]) predicate accomplishes a checked explicit conversion, when the source and target domains are statically known during the compilation. The result of an explicit conversion can be one of the following:

* '''ok''' the successful conversion to the target domain;
* '''run-time-check''' the conversion to the target domain with generation of run-time checking for compatibility;
* '''error''' the conversion is impossible, error output.

===== Rules of Checked Explicit Conversions =====

* Synonyms of domains are converted using the same rules that are applied to the domains themselves.
* Numerical domains can be converted to the numerical domains only.
* Integral constants are the representatives of the anonymous integral domain: <vp>[const .. const]</vp>.
* Real constants are the representatives of the anonymous real domain: <vp>digits</vp> <vp>dig [const .. const]</vp>, where <vp>dig</vp> is the number of the digits in mantissa without insignificant zeroes.
* A value of the symbol domain can be converted to the string domain and vice versa.
* A value of binary domain can be converted to the pointer domain.
* The domains that are implicitly introduced for interfaces can be converted only to the interface domains according to the rules specified below.
* All other domains cannot be converted.

===== Conversions of Numerical Domains =====

* The range is considered first during such conversion. If the ranges of source and target do not intersect, then an error is produced. If the ranges of source and target only partially intersect, then run-time checking is generated. Also, if one of domains is real and another is an integral one, then the integer range is converted to the real range before the comparison.
* When input term in real and output is integer, then <vp>convert/2-></vp> and [[#tryConvert|tryConvert/2->]] predicates truncate the input value to the nearest integer value, which is nearer to zero.

===== Conversions of Interface Types =====

Predicate <vp>convert/2-></vp> allow to convert any object to any interface type. The actual correctness of such conversion is checked at runtime. When object is created, its type is internally stored, therefore when the object is passed as argument it still remember about its original type. This original type is used for checking allowed conversions. The example:

<vip>interface x
supports a, b
end interface x</vip>

If object is created by class, which implements <vp>x</vp> interface, and then object is passed as parameter of type <vp>a</vp> to some predicate, then it is allowed to convert the object to <vp>b</vp> type.

Exceptions:

* Check range error.
* Unsupported interface type.

==== digitsOf ====

<vip>digitsOf : (<real-domain> Domain) -> unsigned.</vip>

Returns precision of the specified floating-point domain.

Call-template for this function is:

<vip>Precision = digitsof(domainName)</vip>

The input parameter ''domainName'' of this compiling-time predicate is a floating-point domain, it should be explicitly specified at compile-time (that is, ''domainName'' cannot come from a variable). The predicate returns the number <vpbnf><Precision></vpbnf> that was determined by the <vp>digits</vp> attribute in the domain declaration.

The compiler guarantees that values of the domain ''domainName'' will have at least <vpbnf><Precision></vpbnf> number of significant decimal digits.

==== errorExit ====

<vip>errorExit : (unsigned ErrorNumber) erroneous.</vip>

Performs a run-time error with the specified return code <vp>ErrorNumber</vp>, which can be used in the [[#try-catch-finally|try-catch-finally]].

==== fact_address ====

<vip>fact_address : (FactType FactVariable) -> memory::pointerTo{FactType} PointerToFactVariable.</vip>

The <vp>fact_address</vp> predicate returns the address (as a <vp>memory::pointerTo{FactType}</vp>) of a fact variable <vp>FactVariable</vp> of type <vp>FactType</vp>.

<vp>FactVariable</vp> '''''must''''' be a fact variable.

==== fail ====

<vip>fail : () failure.</vip>

The <vp>fail</vp> predicate forces failure and, hence, always causes backtracking. A clause that fails (with <vp>fail</vp> or for some other reason) cannot bind output arguments.

==== free ====

<vip>free : (<variableName> Variable) determ.</vip>

Check whether a variable is free.

Call-template for this predicate is:

<vip>free(Variable)</vip>

The <vp>free</vp> predicate succeeds if the specified <vp>Variable</vp> is free and fails if <vp>Variable</vp> is bound. The <vp>free</vp> predicate treats the specified <vp>Variable</vp> as bound if any of it's part are instantiated.

See also [[#bound|bound/1]].

==== fromEllipsis ====

<vip>fromEllipsis : (...) -> any* AnyTermList.</vip>

This predicate creates the list of terms of the universal type <vp>any</vp> from the ''EllipsisBlock'' '''...''' (i.e. from the special varying parameters block).

Call-template for this function is:

<vip>AnyTermList = fromEllipsis(EllipsisBlock )</vip>

See also [[#toEllipsis|toEllipsis/1->]].

==== hasDomain ====

<vp>hasDomain</vp> is not really a predicate, but more a type declaration/restriction. It has two forms a non-function for declaring/restricting the type of a variable and a function form for declaring/restricting the type of a value.

The non-function form is called with a type as first parmeter and a variable as second parameter.

<vip>hasDomain : (<type> Type, Type Variable).</vip>

The only effect of the call is that the <vp>Variable</vp> will be restricted to the type <vp>Type</vp>.

The variable can be free, bound or of some mixed flow and the binding of the variable will not change in any way.

The function form is called with a type as first argument and a value as second argument, and it returns the same value.

<vip>hasDomain : (<type> Type, Type Value) -> Type Value.</vip>

The only effect of the call is to ensure that the <vp>Value</vp> will be restricted to the type <vp>Type</vp>.

==== lowerBound ====

<vip>lowerBound : (<numeric-domain> NumericDomain) -> <numeric-domain> LowerBound.</vip>

Returns the lower bound of the specified <vp>NumericDomain</vp>.

Call-template for this function is:

<vip>LowerBoundValue = lowerBound(domainName)</vip>

The <vp>lowerBound</vp> is a compiling-time predicate. The <vp>lowerBound</vp> returns the lower bound value <vp>LowerBoundValue</vp> of the specified numeric domain ''domainName''. The return value <vp>LowerBoundValue</vp> belongs to the same domain ''domainName''. The ''domainName'' parameter should be the name of any numerical domain; this domain name should be explicitly specified at compile-time (that is, ''domainName'' cannot come from a variable). See also [[#upperBound|upperBound/1->]].

It will give a compile time error if the specified domain ''domainName'' is not numeric domain.

==== in ====

See [[Language_Reference/Terms#in|in/2]].

==== isErroneous ====

<vip>isErroneous : (<fact-variable> FactVariable) determ.</vip>

The predicate succeeds if the specified fact variable is <vp>erroneous</vp>.

Call-template for this predicate is:

<vip>isErroneous(factVariableName)</vip>

The predicate succeeds if the specified fact variable <vp>factVariableName</vp> has the <vp>erroneous</vp> value, otherwise it fails.

See also [[#notErroneous|notErroneous]].

==== maxDigits ====

<vip>maxDigits : (<real-domain> RealDomain) -> unsigned MaxDigits</vip>

Retrieves the value of digits (precision) of the basic domain corresponding to the specified floating-point domain <vp>RealDomain</vp>.

Call-template for this function is:

<vip>MaxDigitsNumber = maxdigits(domainName)</vip>

The return maximal number of digits <vp>MaxDigitsNumber</vp> for the ''domainName'' parameter, which should be the name of a <vp>real</vp> domain.

==== not ====

See [[Language_Reference/Terms#not|not]].

==== notErroneous ====

The <vp>notErroneous/1-></vp> predicate will succeed with the value of a fact if the fact is not erroneous. The main purpose of the predicate is to get an atomic view of the fact in a multi-threaded application.

{{Example|
<vip>
facts
theFact : integer := erroneous.
clauses
ppp() :-
if F = notErroneous(theFact) then
% theFact was not erroneous, its value was F
end if.
</vip>
The related code using <vp>isErroneous/1</vp> is not threadsafe:
<vip>
clauses
ppp() :-
if not(isErroneous(theFact)) then
% theFact was not erroneous, but it can be in the next line
F = theFact
end if.
</vip>
}}

See also [[#isErroneous|isErroneous]].

==== otherwise ====

See {{Lang2|Terms|otherwise|otherwise}}.

==== or ====

See [[Language_Reference/Terms#or_.28.3B.29|or (;)]].

==== orelse ====

See [[Language_Reference/Terms#orelse|orelse]].

==== predicate_fullname ====

<vip>predicate_fullname : () -> string PredicateFullName.</vip>

This predicate returns the name <vp>PredicateFullName</vp> of the predicate in which it is invoked. The returned predicate name is qualified with a scope name.

<vp>predicate_fullname</vp> can only be used inside a clause. Use of <vp>predicate_fullname</vp> in other places causes a compile time error. See also [[#predicate_name|predicate_name]].

==== predicate_name ====

<vip>predicate_name : () -> string PredicateName.</vip>

This predicate returns the name <vp>PredicateName</vp> of the predicate in which it is invoked.

<vp>predicate_name</vp> can only be used inside a clause. Use of <vp>predicate_name</vp> in other places causes a compile time error. See also [[#predicate_fullname|predicate_fullname]]

==== programPoint ====

<vip>programPoint : () -> core::programPoint ProgramPoint.</vip>

This predicate returns the name <vp>programPoint</vp> corresponding to the place where it is invoked.

==== retract ====

<vip>retract : (<fact-term> FactTerm) nondeterm anyflow.</vip>

Successively removes the first matching fact from the facts database. Fails when no more facts match.

Call-template for this predicate is:

<vip>retract(FactTemplate)</vip>

Here <vp>FactTemplate</vp> should be a fact term. The <vp>retract/1</vp> predicate deletes the first fact that matches the <vp>FactTemplate</vp> in the appropriated facts database. During backtracking, the rest of the matching facts will be deleted.

Notice that <vp>FactTemplate</vp> can have any level of instantiation. The <vp>FactTemplate</vp> is matched with the facts in the facts database, which means that any free variables will be bound in the call to <vp>retract/1</vp>.

The <vp>FactTemplate</vp> can contain any anonymous variables. That is, variables with names consisting from the single underscore <vp>_</vp> or a variable with a name starting with an underscore <vp>_AnyValue</vp> if the variable occurs only once in the clause. For example.

<vip>retract(person("Hans", _Age)),</vip>

will retract the first matched person fact that has "<vp>Hans</vp>" as the first argument and anything as the second argument.

When retracting a fact, which is declared to be determ, the call to <vp>retract/1</vp> will be deterministic.

See also [[#retractall|retractall/1]] and [[#retractFactDb|retractFactDb]].

The <vp>retract/1</vp> predicate cannot be applied to single facts or fact variables.

Be careful calling <vp>retract/1</vp> with free <vp>FactTemplate</vp> variable if any single fact is declared in the project current scope. If you retract a single fact, then the run-time error is generated. The <vp>retract/1</vp> predicate fails when there are no more matches.

==== retractall ====

<vip>retractall : (<fact-term> FactTerm) .</vip>

Remove all matching facts from the facts database.

Call-template for this predicate is:

<vip>retractall(FactTemplate)</vip>

Here <vp>FactTemplate</vp> should be a fact term.

The <vp>retractall/1</vp> retracts all facts which match the given ''FactTemplate''. It always succeeds, even if no facts were retracted.

Attempting to retract a <vp>single</vp> fact will cause a compile time error.

It is not possible to obtain any output values from <vp>retractall/1</vp>. For this reason, the variables in the call must be bound or be a single underscores (anonymous). Notice that <vp>FactTemplate</vp> can have any level of instantiation, but free variables must be single underscores ("unconditionally anonymous"). In difference to [[#retract|retract/1]] "conditionally" anonymous variables with names starting from the underscore (like <vp>_AnyValue</vp>) cannot be used in <vp>retractall/1</vp>.

See also [[#retract|retract/1]] and [[#retractFactDb|retractFactDb/1]].

==== retractFactDb ====

<vip>retractFactDb : (factDB FactDB).</vip>

Remove all facts from the named internal facts database <vp>FactDB</vp>.

Call-template for this predicate is:

<vip>retractFactDb(FactDB)</vip>

The <vp>retractFactDb/1</vp> removes all facts from the named facts database <vp>FactDB</vp>.

Notice, it is impossible to retract <vp>single</vp> facts and fact variables, so the predicate leaves such ones as they are.

See also [[#retractall|retractall/1]] and [[#retract|retract/1]].

==== retractAll/2 ====

Obsolete predicate! Use [[#retractFactDb|retractFactDb/1]] instead.

==== sizeBitsOf ====

<vip>sizeBitsOf : (<domain> DomainName) -> unsigned BitSize.</vip>

Retrieves the number of bits occupied in memory by an entity of the specified domain <vp>DomainName</vp>.

Call-template for this function is:

<vip>BitSize = sizeBitsOf(DomainName)</vip>

This compiling-time predicate receives the domain <vp>DomainName</vp> as input parameter and return the size of memory that is occupied by the entity of the given domain. The result is measured in bits. For the integer domains <vp>sizeBitsOf/1-></vp> predicate returns the value that was defined for the size-field in a domain's declaration.

The following is always true for the integral domains:

<vip>sizeOfDomain(domain)*8 - 7 <= sizeBitsOf(domain) <= sizeOfDomain(domain)*8</vip>

See also [[#sizeOfDomain|sizeOfDomain]]/1->.

==== sizeOf ====

<vip>sizeOf : (Type Term) -> integer ByteSize.</vip>

Retrieves the number of bytes occupied in memory by the specified term <vp>Term</vp>.

Call-template for this function is:

<vip>ByteSize = sizeOf(Term)</vip>

The <vp>sizeOf/1-></vp> function receives a term as input parameter and returns value <vp>ByteSize</vp> that specifies the number of bytes occupied in memory by this term <vp>Term</vp>.

==== sizeOfDomain ====

<vip>sizeOfDomain : (<domain> Domain) -> integer ByteSize.</vip>

Retrieves the number of bytes occupied in memory by the entity of the specified domain <vp>DomainName</vp>.

Call-template for this function is:

<vip>ByteSize = sizeOfDomain(DomainName)</vip>

This compiling-time predicate receives the domain <vp>DomainName</vp> as input parameter and return the size of memory that is occupied by the entity of the given domain. The result is measured in bytes. The returned value <vp>ByteSize</vp> belongs to the integer domain. Compare with [[#sizeBitsOf|sizeBitsOf/1->]], which returns size of a domain measured in bits.

==== sourcefile_lineno ====

<vip>sourcefile_lineno : () -> unsigned LineNumber.</vip>

Returns the current line number in the source file processed by the compiler.

==== sourcefile_name ====

<vip>sourcefile_name : () -> string FileName.</vip>

Returns the name of the source file processed by the compiler.

==== sourcefile_timestamp ====

<vip>sourcefile_timestamp : () -> string TimeStamp..</vip>

Returns a string that represents the date and time of the currently compiled source file in format YYYY-MM-DD HH:mm:ss. Where:

* YYYY - Year.
* MM - Month.
* DD - Day.
* HH - Hour.
* mm - Minute.
* ss - Second.

==== succeed ====

<vip>succeed : ().</vip>

The predicate <vp>succeed/0</vp> will always succeed.

==== toAny ====

<vip>toAny : (Term) -> any UniversalTypeValue.</vip>

Converts the specified <vp>Term</vp> to the value of universal term type <vp>any</vp>.

Call-template for this function is:

<vip>UniversalTypeValue = toAny(Term)</vip>

A term of the <vp>any</vp> domain can be converted back to its original type using the <vp>toTerm</vp> predicates (see {{lang2|Built-in entities/Predicates|toTerm|toTerm}}).

==== toBinary ====

<vip>toBinary : (Term) -> binary Serialized.</vip>

Converts the specified <vp>Term</vp> to [[#binary|binary]] representation.

Call-template for this function is:

<vip>Serialized = toBinary(Term)</vip>

When a <vp>Term</vp> (of some domain ''domainName'') is converted into a binary, it can safely be stored in a file or sent over a network to another program. Later the obtained binary value <vp>Serialized</vp> can be converted back to a Visual Prolog term, using [[#toTerm|toTerm/1->]] function (the domain for the reversed term should be adequate to ''domainName'') for the reverse conversion.

==== toBoolean ====

<vip>toBoolean : (<deterministic_expression> SubGoal) -> boolean Succeed.</vip>

The purpose of this meta-predicate is to convert an expression to the value of boolean domain.

Call-template for this meta-predicate is:

<vip>True_or_False = toBoolean(deterministic_expression)</vip>

this is equivalent to

<vip>True_or_False = if deterministic_expression then true else false end if</vip>

The <vp>toBoolean/1-></vp> meta-predicate returns [[#boolean|boolean]] value. The result is <vp>true</vp> if ''deterministic_call'' succeeds. The result is <vp>false</vp> if ''deterministic_call'' fails.

==== toEllipsis ====

<vip>toEllipsis : (any* AnyTermList) -> ....</vip>

This predicate creates ''EllipsisBlock'' '''...''' (i.e. the special varying parameters block) from the list of terms of the universal type <vp>any</vp>. Such ''EllipsisBlock'' can be later passed to a predicate which expects the varying number of arguments (i.e. is declared with the ellipsis (''...'')), like <vp>write/...</vp>, at the position of the ellipsis (''...'').

Call-template for this function is:

<vip>EllipsisBlock = toEllipsis(<any_term_list>), write(EllipsisBlock)</vip>

See also [[#fromEllipsis|fromEllipsis/1->]].

==== toString ====

<vip>toString : (Term) -> string Serialized.</vip>

Converts the specified <vp>Term</vp> to string representation.

Call-template for this function is:

<vip>Serialized = toString(Term)</vip>

When a <vp>Term</vp> (of some domain ''domainName'') is converted into a string, it can safely be stored in a file or sent over a network to another program. Later the obtained string value can be converted back to a Visual Prolog term, using [[#toTerm|toTerm/1->]] function (the domain of the return value should be adequate to ''domainName'') for the reverse conversion.

==== toTerm ====

<vip>toTerm : (string Serialized) -> Term.
toTerm : (binary Serialized) -> Term.
toTerm : (any Serialized) -> Term.
toTerm : (<domain> Type, string Serialized) -> Term.
toTerm : (<domain> Type, binary Serialized) -> Term.
toTerm : (<domain> Type, any Serialized) -> Term.</vip>

Converts the string/binary/any representation of the specified term <vp>Serialized</vp> into representation corresponding to the domain of <vp>Term</vp> variable of the return value. The domain can be stated explicitly or it can be left to the compiler to determine a suitable domain.

Call-template for this function is:

<vip>Term = toTerm(Serialized) % with implicit domain
Term = toTerm(domainName, Serialized) % with explicit domain, domainName</vip>

If the domain is not specified the compiler must be able to determine the domain for the returned value <vp>Term</vp> at compile-time. Notice that binary version of <vp>toTerm</vp> predicate performs almost byte to byte conversion and only checking general compatibility of <vp>Serialized</vp> data with the domain required to the return value <vp>Term</vp>. The programmer is wholly responsible for providing binary data of <vp>Serialized</vp> that can be correctly converted to the term of the desired domain. The <vp>toTerm</vp> predicates are counterparts to predicates [[#toBinary|toBinary/1->]] and [[#toString|toString/1->]]. When a ''Term'' (of some domain ''domainName'') is converted into a binary or string representation <vp>Serialized</vp> (by [[#toBinary|toBinary/1->]] or [[#toString|toString/1->]] or [[#toAny|toAny/1->]] correspondingly), it can safely be stored in a file or sent over a network to another program. Later the corresponding <vp>toTerm/1</vp>-> function can convert the obtained string/binary value <vp>Serialized</vp> back to a Visual Prolog term <vp>Term</vp>. For correctness of the reverse conversion the domain of the clause variable <vp>Term</vp> should be adequate to the initial domain ''domainName''.

See also [[#tryToTerm|tryToTerm]].

It gives a compile time error if the compiler cannot determine the return domain.

Exceptions

* Run time errors are generated when the <vp>toTerm</vp> predicate cannot convert the string or binary into a term of the specified domain.

==== tryToTerm ====

<vip>tryToTerm : (string Serialized) -> Term.
tryToTerm : (binary Serialized) -> Term.
tryToTerm : (any Serialized) -> Term.
tryToTerm : (<domain> Type, string Serialized) -> Term.
tryToTerm : (<domain> Type, binary Serialized) -> Term.
tryToTerm : (<domain> Type, any Serialized) -> Term.</vip>

Converts the string/binary/any representation <vp>Serialized</vp> into a term <vp>Term</vp> like [[#toTerm|toTerm]]. The only difference between the predicates is that <vp>tryToTerm</vp> fails if it cannot convert the string or binary or any into a term of the specified domain whereas toTerm raises an exception.

See also [[#toTerm|toTerm]].

==== tryConvert ====

<vip>tryConvert : (<type> Type, Value) -> <type> Converted determ.</vip>

Checks whether the input term <vp>Value</vp> can be strictly converted into the specified domain <vp>Type</vp> and returns the converted term <vp>Converted</vp>.

Call-template for this function is:

<vip>ReturnTerm = tryConvert(returnDomain, InputTerm)</vip>

Arguments:

* <vp>returnDomain</vp>: Specifies a domain to which <vp>tryConvert/2-></vp> predicate tries to convert the specified <vp>InputTerm</vp>. Here ''returnDomain'' can be any domain accessible in the current scope. The domain name ''returnDomain'' must be specified at compile-time, i.e. it cannot come from a variable.
* <vpbnf><InputTerm></vpbnf>: Specifies the term that must be converted. <vp>InputTerm</vp> may be any Prolog term or an expression. If <vp>InputTerm</vp> is an expression, then it will be evaluated before conversion.
* <vpbnf><ReturnTerm></vpbnf>: Returned term <vp>ReturnTerm</vp> will be of ''returnDomain'' domain.

The conversion rules are the same as of the embedded predicate [[#convert|convert/2->]], but <vp>tryConvert/2-></vp> fails when [[#convert|convert/2->]] generates conversion errors.

This predicate succeeds if the corresponding conversion succeeds. Otherwise it fails. The <vp>tryConvert/2-></vp> predicate tries to perform a clean and genuine conversion of the given <vp>InputTerm</vp> into a value of the specified domain ''returnDomain''. The <vp>tryConvert/2-></vp> predicate will fail if the required conversion cannot be performed. When <vp>tryConvert/2-></vp> predicate succeeds, it returns the term <vp>ReturnTerm</vp> converted to the specified domain ''returnDomain''.

For allowed conversions and rules of checked explicit conversions see [[#convert|convert/2->]] predicate.

See also [[#uncheckedConvert|uncheckedConvert/2->]].

==== typeDescriptorOf ====

<vip>typeDescriptorOf : (<type> Type) -> typeDescriptor TypeDescriptor.
typeDescriptorOf : (Type Value) -> typeDescriptor TypeDescriptor.</vip>

Reflection predicate that returns the <vp>typeDescriptor</vp> of a type or a value.

A <vp>typeDescriptor</vp> is the reflection descriptor of an uninstantiated type/domain.

==== typeLibraryOf ====

<vip>typeLibraryOf : (<type> Type) -> typeLibrary TypeLibrary.
typeLibraryOf : (Type Value) -> typeLibrary TypeLibrary.</vip>

Reflection predicate that returns the <vp>typeLibrary</vp> of a type or a value.

A <vp>typeLibrary</vp> is the reflection descriptor of an instantiated type/domain.

==== uncheckedConvert ====

<vip>uncheckedConvert : (<type> Type, Value) -> <type> Converted.</vip>

Unchecked conversion of a value to another type.

Call-template for this function is:

<vip>ReturnTerm = uncheckedConvert(returnDomain, InputTerm)</vip>

Arguments:

* <vp>returnDomain</vp>: Specifies a domain to which <vp>uncheckedConvert</vp> predicate unsafely converts the specified <vp>InputTerm</vp>. Here ''returnDomain'' can be any domain accessible in the current scope, the <vp>ReturnTerm</vp> should has the same bit-size as the <vp>InputTerm</vp>. The domain name ''returnDomain'' must be specified at compile-time, i.e. it cannot come from a variable.
* <vpbnf><InputTerm></vpbnf>: Specifies the value that must be converted. <vp>InputTerm</vp> may be any Prolog term or an expression. If ''InputTerm'' is an expression, then it will be evaluated before conversion.
* <vpbnf><ReturnTerm></vpbnf>: Returned parameter <vp>ReturnTerm</vp> will be of ''returnDomain'' type.

<vp>uncheckedConvert</vp> evaluates <vp>InputTerm</vp>, change the type to ''returnDomain'' without any modification of the memory pattern and unifies with <vp>ReturnTerm</vp>. The <vp>uncheckedConvert</vp> predicate performs no runtime checks. It makes only compile time checking of bit-size equality of the converted domains. So almost any term may be quite recklessly converted to any other term. So quite disastrous results may occur if you try to use variables incorrectly converted by <vp>uncheckedConvert</vp>. Be extremely careful implementing <vp>uncheckedConvert</vp>; we strongly recommend you always, when it is possible, using of [[#convert|convert/2->]] and [[#tryConvert|tryConvert/2->]]. But notice that, when an object is returned by COM system it is necessary to convert it by <vp>uncheckedConvert</vp>, as Prolog program does not have information about its actual type.

==== upperBound ====

<vip>upperBound : (<numeric-domain> NumericDomain) -> <numeric-domain> UpperBound.</vip>

Returns the upper bound value of the specified numeric domain.

Call-template for this function is:

<vip>UpperBound = upperBound(domainName)</vip>

The <vp>upperBound</vp> is a compiling-time predicate. The <vp>upperBound</vp> returns the upper bound value of the specified numeric domain ''domainName''. The return value <vp>UpperBound</vp> belongs to the same domain ''domainName''. The ''domainName'' parameter should be the name of any numerical domain; this domain name should be explicitly specified at compile-time (that is, ''domainName'' cannot come from a variable).

See also [[#lowerBound|lowerBound/1->]].

Will cause a compile time error if the specified domain ''domainName'' is not numeric domain.
<noinclude>{{LanguageReferenceSubarticle|Built-in entities/Predicates}}</noinclude>

Language Reference/Built-in entities/Predicates

2021-06-07T16:41:46Z

SergeMukhin: misspelling

<noinclude>__NOTOC__</noinclude>

{|{{prettytable}}
|-
|[[Language_Reference/Terms#and_.28.2C.29|and/2]] [[Language_Reference/Terms#and_.28.2C.29|,/2]]
|Term "and"
|-
|[[#assert|assert/1]]
|Insert the specified fact at the end of the matched internal facts database.
|-
|[[#asserta|asserta/1]]
|Insert a fact at the beginning of the matched internal facts database.
|-
|[[#assertz|assertz/1]]
|Insert a fact at the end of the matched internal facts database.
|-
|[[#bound|bound/1]] <vp>determ</vp>
|Test whether the specified variable is bound to a value.
|-
|[[#class_name|class_name/0->]]
|This compile time predicate returns the string ''ClassName'' that represents the name of the current interface or class.
|-
|[[#compare|compare/2->]]
|Returns the result of the variables' comparison.
|-
|[[#constant_name|constant_name/0->]]
|This compile time predicate returns the string ''ConstantName'' that represents the name of the current constant. Typically used in execepion definitions.
|-
|[[#convert|convert/2->]]
|Checked term conversion.
|-
|[[#digitsOf|digitsOf/1->]]
|Returns precision of the specified floating-point domain.
|-
|[[#errorExit|errorExit/1]] <vp>erroneous</vp>
|Performs a run-time error with the specified return code ''ErrorNumber'' and sets the internal error information.
|-
|[[#fact_address|fact_address/1->]]
|Returns the address of a fact variable.
|-
|[[#fail|fail/0]] <vp>failure</vp>
|Invoke backtracking.
|-
|[[#free|free/1]] <vp>determ</vp>
|Check whether a variable is free.
|-
|[[#fromEllipsis|fromEllipsis/1->]]
|Creates the list of terms of the universal type <vp>any</vp> from the ''EllipsisBlock''.
|-
|[[#hasDomain|hasDomain/2]] [[#hasDomain|hasDomain/2->]]
|Declares/restricts the type of a variable or value.
|-
|[[Language_Reference/Terms#in|in/2]] <vp>determ</vp> [[Language_Reference/Terms#in|in/2]] <vp>nondeterm</vp>
|Infix operator "in" (in-test and in-iterator).
|-
|[[#isErroneous|isErroneous/1]] <vp>determ</vp>
|Returns the lower bound value of the specified numeric domain.
|-
|[[#lowerBound|lowerBound/1->]]
|Returns the lower bound value of the specified numeric domain.
|-
|[[#maxDigits|maxDigits/1->]]
|Retrieves the value of digits (precision) of the basic domain corresponding to the specified floating-point domain ''domainName''.
|-
|[[#not|not/1]] <vp>determ</vp>
|Negate the result (success/fail) of subgoal.
|-
|[[Language_Reference/Terms#otherwise|otherwise/2]]
|Infix expression operator providing a value when a determ expression fails
|-
|[[Language_Reference/Terms#or_.28.3B.29|or/2]] [[Language_Reference/Terms#and_.28.3B.29|;/2]]
|Nondeterministic term "or"
|-
|[[Language_Reference/Terms#orelse|orelse]]
|Deterministic term "or"
|-
|[[#predicate_fullname|predicate_fullname/1->]]
|This compile time predicate returns the string ''PredicateFullName'' that represent the name of the predicate in which clause body <vp>predicate_name</vp> is called. The returned predicate name is qualified with a scope name.
|-
|[[#predicate_name|predicate_name/1->]]
|This compile time predicate returns the string ''PredicateName'' that represent the name of the predicate in which clause body <vp>predicate_name</vp> is called. The returned predicate name is not qualified with a scope name.
|-
|[[#programPoint|programPoint/0->]]
|This compile time predicate returns the <vp>programPoint</vp> corresponding to the place where it is called.
|-
|[[#retract|retract/1]] <vp>nondeterm</vp>
|Remove a matched fact from the matched internal facts database.
|-
|[[#retractall|retractall/1]]
|Remove all matching facts from the matched internal facts database.
|-
|[[#retractFactDb|retractFactDb/1]]
|Remove all facts from the specified named internal facts database.
|-
|[[#sizeBitsOf|sizeBitsOf/1->]]
|Retrieves the number of bits occupied in memory by an entity of the specified domain ''DomainName''.
|-
|[[#sizeOf|sizeOf/1->]]
|Retrieves the number of bytes occupied in memory by the specified term.
|-
|[[#sizeOfDomain|sizeOfDomain/1->]]
|Retrieves the number of bytes occupied in memory by the entity of the specified domain ''DomainName''.
|-
|[[#sourcefile_lineno|sourcefile_lineno/0->]]
|Returns the current line number in the source file processed by the compiler .
|-
|[[#sourcefile_name|sourcefile_name/0->]]
|Returns the name of the source file processed by the compiler.
|-
|[[#sourcefile_timestamp|sourcefile_timestamp/0->]]
|Returns the string representing the date and time of the source file processed by the compiler.
|-
|[[#succeed|succeed/0]]
|The predicate <vp>succeed/0</vp> will always succeed.
|-
|[[#toAny|toAny/1->]]
|Converts the specified ''Term'' to the value of the universal term type <vp>any</vp>.
|-
|[[#toBinary|toBinary/1->]]
|Converts the specified Term to the binary representation.
|-
|[[#toBoolean|toBoolean/1->]]
|The purpose of this meta-predicate is to convert the deterministic call (to a predicate or fact) to the procedure that returns the value of <vp>boolean</vp> domain.
|-
|[[#toEllipsis|toEllipsis/1->]]
|Creates the ''EllipsisBlock'' from the list of <vp>any</vp> type values.
|-
|[[#toString|toString/1->]]
|Converts the specified ''Term'' to the string representation.
|-
|[[#toTerm|toTerm/1->]] [[#toTerm|toTerm/2->]]
|Converts the string/binary representation of the specified term ''SrcTerm'' into representation corresponding to the domain of ''PrologTerm'' variable of the return value.
|-
|[[#tryToTerm|tryToTerm/1->]] <vp>determ</vp> [[#tryToTerm|tryToTerm/2->]] <vp>determ</vp>
|Converts the string/binary representation of the specified term ''SrcTerm'' into representation corresponding to the domain of ''PrologTerm'' variable of the return value.
|-
|[[#tryConvert|tryConvert/2->]] <vp>determ</vp>
|Checks whether the input term ''InputTerm'' can be strictly converted into the specified domain ''returnDomain'' and returns the converted term ''ReturnTerm''.
|-
|[[#typeDescriptorOf|typeDescriptorOf/1->]]
|Returns the <vp>typeDescriptor</vp> of a value.
|-
|[[#typeLibraryOf|typeLibraryOf/1->]]
|Returns the <vp>typeLibrary</vp> of a value.
|-
|[[#uncheckedConvert|uncheckedConvert/2->]]
|Unchecked conversion of domains.
|-
|[[#upperBound|upperBound/1->]]
|Returns the upper bound value of the specified numeric domain.
|}

The following predicates are deprecated:
{|{{prettytable}}
|-
| finally/2
| Use [[Language_Reference/Terms#try-finally| <vp>try-finally</vp>]] constuction instead.
|-
| findall/3
| Use list comprehension [[Language_Reference/Terms#List_Comprehension| <vp>[ ... || ... ]</vp>]] instead
|-
| trap/3 <vp>determ</vp>
| Use [[Language_Reference/Terms#try-catch| <vp>try-catch</vp>]] constuction instead.
|}

==== and ====

See [[Language_Reference/Terms#and_.28.2C.29|and (,)]].

==== assert ====

<vip>assert : (<fact-term> FactTerm).</vip>

Insert the specified fact at the end of the matched internal facts database

<vp>assert(Fact)</vp> inserts <vp>Fact</vp> in the matched internal facts database after any other stored facts for the corresponding database predicate. <vp>Fact</vp> must be a term belonging to the domain of an internal facts database. <vp>assert/1</vp> applied to a single fact changes the existing instance of a fact to the specified one. <vp>assert/1</vp> has the same effect as [[#assertz|assertz/1]]. See also [[#asserta|asserta/1]].

Notice that the combination of [[#retract|retract/1]] and <vp>assert/1</vp> like the following can lead to endless loop:

<vip>loop() :-
retract(fct(X)),
... % creating Y from X
assert(fct(Y)),
fail.</vip>

The problem is that the retract in first line will eventually retract the fact asserted in the last line, because that fact is inserted ''last'' in the fact chain.

Exceptions:

* Attempt to assert a second instance to a fact declared as determ.

==== asserta ====

<vip>asserta : (<fact-term> FactTerm).</vip>

Insert a fact at the beginning of the matched internal facts database.

The <vp>asserta(Fact)</vp> predicate inserts a <vp>Fact</vp> in the matched internal facts database before any other stored facts for the corresponding predicate. The <vp>Fact</vp> must be a term belonging to the domain of an internal facts database. The <vp>asserta/1</vp> applied to a single fact changes the existing instance of a fact to the specified one. See also [[#assert|assert/1]] and [[#assertz|assertz/1]].

Exceptions:

* Attempt to a fact declared as determ, but the fact instance already exists.

==== assertz ====

<vip>assertz : (<fact-term> FactTerm).</vip>

<vp>assertz</vp> does exactly the same as the [[#assert|assert/1]] predicate.

==== bound ====

<vip>bound : (<variable> Variable) determ.</vip>

Test whether the specified variable is bound to a value.

The <vp>bound(Variable)</vp> succeeds if <vp>Variable</vp> is bound and fails if it is free. The <vp>bound</vp> predicate is used to control flow patterns and to check the binding of reference variables. The <vp>bound</vp> predicate treats the specified <vp>Variable</vp> as bound if any of it's part is instantiated.

See also [[#free|free/1]].

==== class_name ====

<vip>class_Name : () -> string ClassName.</vip>

This compile time predicate returns the string <vp>ClassName</vp> that represents the name of the current interface or class.

==== compare ====

<vip>compare : (A Left, A Right) -> compareResult CompareResult.</vip>

Comparison of two terms of the same domain, resturns the value of [[#compareResult|compareResult]] domain.

<vp>CompareResult</vp> = compare("<vp>bar</vp>", "<vp>foo</vp>")

==== constant_name ====

<vip>constant_name : () -> string ConstantName.</vip>

This compile time predicate returns the string <vp>ConstantName</vp> that represents the name of the current constant. It is typically used in exception definitions.

==== convert ====

<vip>convert : (<type> Type, Term) -> <type> Converted.</vip>

Checked term conversion.

Call-template for this function is:

<vp>ReturnTerm</vp> = convert(returnDomain, <vp>InputTerm</vp>)

* <vpbnf>returnDomain</vpbnf>: Specifies a domain to which function <vp>convert/2-></vp> converts <vp>InputTerm</vp>. Here ''returnDomain'' must be a name of built-in Visual Prolog domain, an interface domain, a name of such user defined domain that is synonym to one of built-in Visual Prolog domains, a numeric domain, binary and pointer domains. The domain name ''returnDomain'' must be specified at compile-time, i.e. it cannot come from a variable.

* <vpbnf><InputTerm></vpbnf>: Specifies the value that must be converted. <vp>InputTerm</vp> may be any Prolog term or an expression. If <vp>InputTerm</vp> is an expression, then it will be evaluated before the conversion.

* <vpbnf><ReturnTerm></vpbnf>: Returned parameter <vp>ReturnTerm</vp> will be of ''returnDomain'' type.

The <vp>convert</vp> predicate performs a clean and genuine conversion of the given <vp>InputTerm</vp>, returning a new term <vp>ReturnTerm</vp> of the specified new domain ''returnDomain''. If <vp>convert</vp> cannot perform the required conversion, it rises errors. The similar functionality is provided by the [[#tryConvert|tryConvert/2->]] predicate, but <vp>tryConvert-></vp> fails and does not produce any runtime errors if it cannot perform the conversion.

===== Allowed conversions =====

* Between numerical domains.
* Between interface types.
* Between [[#string|string]] and [[#symbol|symbol]] domains.
* From [[#binary|binary]] to [[#pointer|pointer]].
* For synonyms of mentioned domains.
* Between [http://wiki.visual-prolog.com/index.php?title=How_To_Remove_Reference_Domains_from_a_Project reference] domains and corresponding non-reference domains.

The contrast to these is [[#uncheckedConvert|uncheckedConvert/2->]] predicate, which performs an unchecked conversion between terms from any domains, which have the same bit-size.

The <vp>convert/2-></vp> (or [[#tryConvert|tryConvert/2->]]) predicate accomplishes a checked explicit conversion, when the source and target domains are statically known during the compilation. The result of an explicit conversion can be one of the following:

* '''ok''' the successful conversion to the target domain;
* '''run-time-check''' the conversion to the target domain with generation of run-time checking for compatibility;
* '''error''' the conversion is impossible, error output.

===== Rules of Checked Explicit Conversions =====

* Synonyms of domains are converted using the same rules that are applied to the domains themselves.
* Numerical domains can be converted to the numerical domains only.
* Integral constants are the representatives of the anonymous integral domain: <vp>[const .. const]</vp>.
* Real constants are the representatives of the anonymous real domain: <vp>digits</vp> <vp>dig [const .. const]</vp>, where <vp>dig</vp> is the number of the digits in mantissa without insignificant zeroes.
* A value of the symbol domain can be converted to the string domain and vice versa.
* A value of binary domain can be converted to the pointer domain.
* The domains that are implicitly introduced for interfaces can be converted only to the interface domains according to the rules specified below.
* All other domains cannot be converted.

===== Conversions of Numerical Domains =====

* The range is considered first during such conversion. If the ranges of source and target do not intersect, then an error is produced. If the ranges of source and target only partially intersect, then run-time checking is generated. Also, if one of domains is real and another is an integral one, then the integer range is converted to the real range before the comparison.
* When input term in real and output is integer, then <vp>convert/2-></vp> and [[#tryConvert|tryConvert/2->]] predicates truncate the input value to the nearest integer value, which is nearer to zero.

===== Conversions of Interface Types =====

Predicate <vp>convert/2-></vp> allow to convert any object to any interface type. The actual correctness of such conversion is checked at runtime. When object is created, its type is internally stored, therefore when the object is passed as argument it still remember about its original type. This original type is used for checking allowed conversions. The example:

<vip>interface x
supports a, b
end interface x</vip>

If object is created by class, which implements <vp>x</vp> interface, and then object is passed as parameter of type <vp>a</vp> to some predicate, then it is allowed to convert the object to <vp>b</vp> type.

Exceptions:

* Check range error.
* Unsupported interface type.

==== digitsOf ====

<vip>digitsOf : (<real-domain> Domain) -> unsigned.</vip>

Returns precision of the specified floating-point domain.

Call-template for this function is:

<vip>Precision = digitsof(domainName)</vip>

The input parameter ''domainName'' of this compiling-time predicate is a floating-point domain, it should be explicitly specified at compile-time (that is, ''domainName'' cannot come from a variable). The predicate returns the number <vpbnf><Precision></vpbnf> that was determined by the <vp>digits</vp> attribute in the domain declaration.

The compiler guarantees that values of the domain ''domainName'' will have at least <vpbnf><Precision></vpbnf> number of significant decimal digits.

==== errorExit ====

<vip>errorExit : (unsigned ErrorNumber) erroneous.</vip>

Performs a run-time error with the specified return code <vp>ErrorNumber</vp>, which can be used in the [[#try-catch-finally|try-catch-finally]].

==== fact_address ====

<vip>fact_address : (FactType FactVariable) -> memory::pointerTo{FactType} PointerToFactVariable.</vip>

The <vp>fact_address</vp> predicate returns the address (as a <vp>memory::pointerTo{FactType}</vp>) of a fact variable <vp>FactVariable</vp> of type <vp>FactType</vp>.

<vp>FactVariable</vp> '''''must''''' be a fact variable.

==== fail ====

<vip>fail : () failure.</vip>

The <vp>fail</vp> predicate forces failure and, hence, always causes backtracking. A clause that fails (with <vp>fail</vp> or for some other reason) cannot bind output arguments.

==== free ====

<vip>free : (<variableName> Variable) determ.</vip>

Check whether a variable is free.

Call-template for this predicate is:

<vip>free(Variable)</vip>

The <vp>free</vp> predicate succeeds if the specified <vp>Variable</vp> is free and fails if <vp>Variable</vp> is bound. The <vp>free</vp> predicate treats the specified <vp>Variable</vp> as bound if any of it's part are instantiated.

See also [[#bound|bound/1]].

==== fromEllipsis ====

<vip>fromEllipsis : (...) -> any* AnyTermList.</vip>

This predicate creates the list of terms of the universal type <vp>any</vp> from the ''EllipsisBlock'' '''...''' (i.e. from the special varying parameters block).

Call-template for this function is:

<vip>AnyTermList = fromEllipsis(EllipsisBlock )</vip>

See also [[#toEllipsis|toEllipsis/1->]].

==== hasDomain ====

<vp>hasDomain</vp> is not really a predicate, but more a type declaration/restriction. It has two forms a non-function for declaring/restricting the type of a variable and a function form for declaring/restricting the type of a value.

The non-function form is called with a type as first parmeter and a variable as second parameter.

<vip>hasDomain : (<type> Type, Type Variable).</vip>

The only effect of the call is that the <vp>Variable</vp> will be restricted to the type <vp>Type</vp>.

The variable can be free, bound or of some mixed flow and the binding of the variable will not change in any way.

The function form is called with a type as first argument and a value as second argument, and it returns the same value.

<vip>hasDomain : (<type> Type, Type Value) -> Type Value.</vip>

The only effect of the call is to ensure that the <vp>Value</vp> will be restricted to the type <vp>Type</vp>.

==== lowerBound ====

<vip>lowerBound : (<numeric-domain> NumericDomain) -> <numeric-domain> LowerBound.</vip>

Returns the lower bound of the specified <vp>NumericDomain</vp>.

Call-template for this function is:

<vip>LowerBoundValue = lowerBound(domainName)</vip>

The <vp>lowerBound</vp> is a compiling-time predicate. The <vp>lowerBound</vp> returns the lower bound value <vp>LowerBoundValue</vp> of the specified numeric domain ''domainName''. The return value <vp>LowerBoundValue</vp> belongs to the same domain ''domainName''. The ''domainName'' parameter should be the name of any numerical domain; this domain name should be explicitly specified at compile-time (that is, ''domainName'' cannot come from a variable). See also [[#upperBound|upperBound/1->]].

It will give a compile time error if the specified domain ''domainName'' is not numeric domain.

==== in ====

See [[Language_Reference/Terms#in|in/2]].

==== isErroneous ====

<vip>isErroneous : (<fact-variable> FactVariable) determ.</vip>

The predicate succeeds if the specified fact variable is <vp>erroneous</vp>.

Call-template for this predicate is:

<vip>isErroneous(factVariableName)</vip>

The predicate succeeds if the specified fact variable <vp>factVariableName</vp> has the <vp>erroneous</vp> value, otherwise it fails.

See also [[#notErroneous|notErroneous]].

==== maxDigits ====

<vip>maxDigits : (<real-domain> RealDomain) -> unsigned MaxDigits</vip>

Retrieves the value of digits (precision) of the basic domain corresponding to the specified floating-point domain <vp>RealDomain</vp>.

Call-template for this function is:

<vip>MaxDigitsNumber = maxdigits(domainName)</vip>

The return maximal number of digits <vp>MaxDigitsNumber</vp> for the ''domainName'' parameter, which should be the name of a <vp>real</vp> domain.

==== not ====

See [[Language_Reference/Terms#not|not]].

==== notErroneous ====

The <vp>notErroneous/1-></vp> predicate will succeed with the value of a fact if the fact is not erroneous. The main purpose of the predicate is to get an atomic view of the fact in a multi-threaded application.

{{Example|
<vip>
facts
theFact : integer := erroneous.
clauses
ppp() :-
if F = notErroneous(theFact) then
% theFact was not erroneous, its value was F
end if.
</vip>
The related code using <vp>isErroneous/1</vp> is not threadsafe:
<vip>
clauses
ppp() :-
if not(isErroneous(theFact)) then
% theFact was not erroneous, but it can be in the next line
F = theFact
end if.
</vip>
}}

See also [[#isErroneous|isErroneous]].

==== otherwise ====

See {{Lang2|Terms|otherwise|otherwise}}.

==== or ====

See [[Language_Reference/Terms#or_.28.3B.29|or (;)]].

==== orelse ====

See [[Language_Reference/Terms#orelse|orelse]].

==== predicate_fullname ====

<vip>predicate_fullname : () -> string PredicateFullName.</vip>

This predicate returns the name <vp>PredicateFullName</vp> of the predicate in which it is invoked. The returned predicate name is qualified with a scope name.

<vp>predicate_fullname</vp> can only be used inside a clause. Use of <vp>predicate_fullname</vp> in other places causes a compile time error. See also [[#predicate_name|predicate_name]].

==== predicate_name ====

<vip>predicate_name : () -> string PredicateName.</vip>

This predicate returns the name <vp>PredicateName</vp> of the predicate in which it is invoked.

<vp>predicate_name</vp> can only be used inside a clause. Use of <vp>predicate_name</vp> in other places causes a compile time error. See also [[#predicate_fullname|predicate_fullname]]

==== programPoint ====

<vip>programPoint : () -> core::programPoint ProgramPoint.</vip>

This predicate returns the name <vp>programPoint</vp> corresponding to the place where it is invoked.

==== retract ====

<vip>retract : (<fact-term> FactTerm) nondeterm anyflow.</vip>

Successively removes the first matching fact from the facts database. Fails when no more facts match.

Call-template for this predicate is:

<vip>retract(FactTemplate)</vip>

Here <vp>FactTemplate</vp> should be a fact term. The <vp>retract/1</vp> predicate deletes the first fact that matches the <vp>FactTemplate</vp> in the appropriated facts database. During backtracking, the rest of the matching facts will be deleted.

Notice that <vp>FactTemplate</vp> can have any level of instantiation. The <vp>FactTemplate</vp> is matched with the facts in the facts database, which means that any free variables will be bound in the call to <vp>retract/1</vp>.

The <vp>FactTemplate</vp> can contain any anonymous variables. That is, variables with names consisting from the single underscore <vp>_</vp> or a variable with a name starting with an underscore <vp>_AnyValue</vp> if the variable occurs only once in the clause. For example.

<vip>retract(person("Hans", _Age)),</vip>

will retract the first matched person fact that has "<vp>Hans</vp>" as the first argument and anything as the second argument.

When retracting a fact, which is declared to be determ, the call to <vp>retract/1</vp> will be deterministic.

See also [[#retractall|retractall/1]] and [[#retractFactDb|retractFactDb]].

The <vp>retract/1</vp> predicate cannot be applied to single facts or fact variables.

Be careful calling <vp>retract/1</vp> with free <vp>FactTemplate</vp> variable if any single fact is declared in the project current scope. If you retract a single fact, then the run-time error is generated. The <vp>retract/1</vp> predicate fails when there are no more matches.

==== retractall ====

<vip>retractall : (<fact-term> FactTerm) .</vip>

Remove all matching facts from the facts database.

Call-template for this predicate is:

<vip>retractall(FactTemplate)</vip>

Here <vp>FactTemplate</vp> should be a fact term.

The <vp>retractall/1</vp> retracts all facts which match the given ''FactTemplate''. It always succeeds, even if no facts were retracted.

Attempting to retract a <vp>single</vp> fact will cause a compile time error.

It is not possible to obtain any output values from <vp>retractall/1</vp>. For this reason, the variables in the call must be bound or be a single underscores (anonymous). Notice that <vp>FactTemplate</vp> can have any level of instantiation, but free variables must be single underscores ("unconditionally anonymous"). In difference to [[#retract|retract/1]] "conditionally" anonymous variables with names starting from the underscore (like <vp>_AnyValue</vp>) cannot be used in <vp>retractall/1</vp>.

See also [[#retract|retract/1]] and [[#retractFactDb|retractFactDb/1]].

==== retractFactDb ====

<vip>retractFactDb : (factDB FactDB).</vip>

Remove all facts from the named internal facts database <vp>FactDB</vp>.

Call-template for this predicate is:

<vip>retractFactDb(FactDB)</vip>

The <vp>retractFactDb/1</vp> removes all facts from the named facts database <vp>FactDB</vp>.

Notice, it is impossible to retract <vp>single</vp> facts and fact variables, so the predicate leaves such ones as they are.

See also [[#retractall|retractall/1]] and [[#retract|retract/1]].

==== retractAll/2 ====

Obsolete predicate! Use [[#retractFactDb|retractFactDb/1]] instead.

==== sizeBitsOf ====

<vip>sizeBitsOf : (<domain> DomainName) -> unsigned BitSize.</vip>

Retrieves the number of bits occupied in memory by an entity of the specified domain <vp>DomainName</vp>.

Call-template for this function is:

<vip>BitSize = sizeBitsOf(DomainName)</vip>

This compiling-time predicate receives the domain <vp>DomainName</vp> as input parameter and return the size of memory that is occupied by the entity of the given domain. The result is measured in bits. For the integer domains <vp>sizeBitsOf/1-></vp> predicate returns the value that was defined for the size-field in a domain's declaration.

The following is always true for the integral domains:

<vip>sizeOfDomain(domain)*8 - 7 <= sizeBitsOf(domain) <= sizeOfDomain(domain)*8</vip>

See also [[#sizeOfDomain|sizeOfDomain]]/1->.

==== sizeOf ====

<vip>sizeOf : (Type Term) -> integer ByteSize.</vip>

Retrieves the number of bytes occupied in memory by the specified term <vp>Term</vp>.

Call-template for this function is:

<vip>ByteSize = sizeOf(Term)</vip>

The <vp>sizeOf/1-></vp> function receives a term as input parameter and returns value <vp>ByteSize</vp> that specifies the number of bytes occupied in memory by this term <vp>Term</vp>.

==== sizeOfDomain ====

<vip>sizeOfDomain : (<domain> Domain) -> integer ByteSize.</vip>

Retrieves the number of bytes occupied in memory by the entity of the specified domain <vp>DomainName</vp>.

Call-template for this function is:

<vip>ByteSize = sizeOfDomain(DomainName)</vip>

This compiling-time predicate receives the domain <vp>DomainName</vp> as input parameter and return the size of memory that is occupied by the entity of the given domain. The result is measured in bytes. The returned value <vp>ByteSize</vp> belongs to the integer domain. Compare with [[#sizeBitsOf|sizeBitsOf/1->]], which returns size of a domain measured in bits.

==== sourcefile_lineno ====

<vip>sourcefile_lineno : () -> unsigned LineNumber.</vip>

Returns the current line number in the source file processed by the compiler.

==== sourcefile_name ====

<vip>sourcefile_name : () -> string FileName.</vip>

Returns the name of the source file processed by the compiler.

==== sourcefile_timestamp ====

<vip>sourcefile_timestamp : () -> string TimeStamp..</vip>

Returns a string that represents the date and time of the currently compiled source file in format YYYY-MM-DD HH:mm:ss. Where:

* YYYY - Year.
* MM - Month.
* DD - Day.
* HH - Hour.
* mm - Minute.
* ss - Second.

==== succeed ====

<vip>succeed : ().</vip>

The predicate <vp>succeed/0</vp> will always succeed.

==== toAny ====

<vip>toAny : (Term) -> any UniversalTypeValue.</vip>

Converts the specified <vp>Term</vp> to the value of universal term type <vp>any</vp>.

Call-template for this function is:

<vip>UniversalTypeValue = toAny(Term)</vip>

A term of the <vp>any</vp> domain can be converted back to its original type using the <vp>toTerm</vp> predicates (see {{lang2|Built-in entities/Predicates|toTerm|toTerm}}).

==== toBinary ====

<vip>toBinary : (Term) -> binary Serialized.</vip>

Converts the specified <vp>Term</vp> to [[#binary|binary]] representation.

Call-template for this function is:

<vip>Serialized = toBinary(Term)</vip>

When a <vp>Term</vp> (of some domain ''domainName'') is converted into a binary, it can safely be stored in a file or sent over a network to another program. Later the obtained binary value <vp>Serialized</vp> can be converted back to a Visual Prolog term, using [[#toTerm|toTerm/1->]] function (the domain for the reversed term should be adequate to ''domainName'') for the reverse conversion.

==== toBoolean ====

<vip>toBoolean : (<deterministic_expression> SubGoal) -> boolean Succeed.</vip>

The purpose of this meta-predicate is to convert an expression to the value of boolean domain.

Call-template for this meta-predicate is:

<vip>True_or_False = toBoolean(deterministic_expression)</vip>

this is equivalent to

<vip>True_or_False = if deterministic_expression then true else false end if</vip>

The <vp>toBoolean/1-></vp> meta-predicate returns [[#boolean|boolean]] value. The result is <vp>true</vp> if ''deterministic_call'' succeeds. The result is <vp>false</vp> if ''deterministic_call'' fails.

==== toEllipsis ====

<vip>toEllipsis : (any* AnyTermList) -> ....</vip>

This predicate creates ''EllipsisBlock'' '''...''' (i.e. the special varying parameters block) from the list of terms of the universal type <vp>any</vp>. Such ''EllipsisBlock'' can be later passed to a predicate which expects the varying number of arguments (i.e. is declared with the ellipsis (''...'')), like <vp>write/...</vp>, at the position of the ellipsis (''...'').

Call-template for this function is:

<vip>EllipsisBlock = toEllipsis(<any_term_list>), write(EllipsisBlock)</vip>

See also [[#fromEllipsis|fromEllipsis/1->]].

==== toString ====

<vip>toString : (Term) -> string Serialized.</vip>

Converts the specified <vp>Term</vp> to string representation.

Call-template for this function is:

<vip>Serialized = toString(Term)</vip>

When a <vp>Term</vp> (of some domain ''domainName'') is converted into a string, it can safely be stored in a file or sent over a network to another program. Later the obtained string value can be converted back to a Visual Prolog term, using [[#toTerm|toTerm/1->]] function (the domain of the return value should be adequate to ''domainName'') for the reverse conversion.

==== toTerm ====

<vip>toTerm : (string Serialized) -> Term.
toTerm : (binary Serialized) -> Term.
toTerm : (any Serialized) -> Term.
toTerm : (<domain> Type, string Serialized) -> Term.
toTerm : (<domain> Type, binary Serialized) -> Term.
toTerm : (<domain> Type, any Serialized) -> Term.</vip>

Converts the string/binary/any representation of the specified term <vp>Serialized</vp> into representation corresponding to the domain of <vp>Term</vp> variable of the return value. The domain can be stated explicitly or it can be left to the compiler to determine a suitable domain.

Call-template for this function is:

<vip>Term = toTerm(Serialized) % with implicit domain
Term = toTerm(domainName, Serialized) % with explicit domain, domainName</vip>

If the domain is not specified the compiler must be able to determine the domain for the returned value <vp>Term</vp> at compile-time. Notice that binary version of <vp>toTerm</vp> predicate performs almost byte to byte conversion and only checking general compatibility of <vp>Serialized</vp> data with the domain required to the return value <vp>Term</vp>. The programmer is wholly responsible for providing binary data of <vp>Serialized</vp> that can be correctly converted to the term of the desired domain. The <vp>toTerm</vp> predicates are counterparts to predicates [[#toBinary|toBinary/1->]] and [[#toString|toString/1->]]. When a ''Term'' (of some domain ''domainName'') is converted into a binary or string representation <vp>Serialized</vp> (by [[#toBinary|toBinary/1->]] or [[#toString|toString/1->]] or [[#toAny|toAny/1->]] correspondingly), it can safely be stored in a file or sent over a network to another program. Later the corresponding <vp>toTerm/1</vp>-> function can convert the obtained string/binary value <vp>Serialized</vp> back to a Visual Prolog term <vp>Term</vp>. For correctness of the reverse conversion the domain of the clause variable <vp>Term</vp> should be adequate to the initial domain ''domainName''.

See also [[#tryToTerm|tryToTerm]].

It gives a compile time error if the compiler cannot determine the return domain.

Exceptions

* Run time errors are generated when the <vp>toTerm</vp> predicate cannot convert the string or binary into a term of the specified domain.

==== tryToTerm ====

<vip>tryToTerm : (string Serialized) -> Term.
tryToTerm : (binary Serialized) -> Term.
tryToTerm : (any Serialized) -> Term.
tryToTerm : (<domain> Type, string Serialized) -> Term.
tryToTerm : (<domain> Type, binary Serialized) -> Term.
tryToTerm : (<domain> Type, any Serialized) -> Term.</vip>

Converts the string/binary/any representation <vp>Serialized</vp> into a term <vp>Term</vp> like [[#toTerm|toTerm]]. The only difference between the predicates is that <vp>tryToTerm</vp> fails if it cannot convert the string or binary or any into a term of the specified domain whereas toTerm raises an exception.

See also [[#toTerm|toTerm]].

==== tryConvert ====

<vip>tryConvert : (<type> Type, Value) -> <type> Converted determ.</vip>

Checks whether the input term <vp>Value</vp> can be strictly converted into the specified domain <vp>Type</vp> and returns the converted term <vp>Converted</vp>.

Call-template for this function is:

<vip>ReturnTerm = tryConvert(returnDomain, InputTerm)</vip>

Arguments:

* <vp>returnDomain</vp>: Specifies a domain to which <vp>tryConvert/2-></vp> predicate tries to convert the specified <vp>InputTerm</vp>. Here ''returnDomain'' can be any domain accessible in the current scope. The domain name ''returnDomain'' must be specified at compile-time, i.e. it cannot come from a variable.
* <vpbnf><InputTerm></vpbnf>: Specifies the term that must be converted. <vp>InputTerm</vp> may be any Prolog term or an expression. If <vp>InputTerm</vp> is an expression, then it will be evaluated before conversion.
* <vpbnf><ReturnTerm></vpbnf>: Returned term <vp>ReturnTerm</vp> will be of ''returnDomain'' domain.

The conversion rules are the same as of the embedded predicate [[#convert|convert/2->]], but <vp>tryConvert/2-></vp> fails when [[#convert|convert/2->]] generates conversion errors.

This predicate succeeds if the corresponding conversion succeeds. Otherwise it fails. The <vp>tryConvert/2-></vp> predicate tries to perform a clean and genuine conversion of the given <vp>InputTerm</vp> into a value of the specified domain ''returnDomain''. The <vp>tryConvert/2-></vp> predicate will fail if the required conversion cannot be performed. When <vp>tryConvert/2-></vp> predicate succeeds, it returns the term <vp>ReturnTerm</vp> converted to the specified domain ''returnDomain''.

For allowed conversions and rules of checked explicit conversions see [[#convert|convert/2->]] predicate.

See also [[#uncheckedConvert|uncheckedConvert/2->]].

==== typeDescriptorOf ====

<vip>typeDescriptorOf : (<type> Type) -> typeDescriptor TypeDescriptor.
typeDescriptorOf : (Type Value) -> typeDescriptor TypeDescriptor.</vip>

Reflection predicate that returns the <vp>typeDescriptor</vp> of a type or a value.

A <vp>typeDescriptor</vp> is the reflection descriptor of an uninstantiated type/domain.

==== typeLibraryOf ====

<vip>typeLibraryOf : (<type> Type) -> typeLibrary TypeLibrary.
typeLibraryOf : (Type Value) -> typeLibrary TypeLibrary.</vip>

Reflection predicate that returns the <vp>typeLibrary</vp> of a type or a value.

A <vp>typeLibrary</vp> is the reflection descriptor of an instantiated type/domain.

==== uncheckedConvert ====

<vip>uncheckedConvert : (<type> Type, Value) -> <type> Converted.</vip>

Unchecked conversion of a value to another type.

Call-template for this function is:

<vip>ReturnTerm = uncheckedConvert(returnDomain, InputTerm)</vip>

Arguments:

* <vp>returnDomain</vp>: Specifies a domain to which <vp>uncheckedConvert</vp> predicate unsafely converts the specified <vp>InputTerm</vp>. Here ''returnDomain'' can be any domain accessible in the current scope, the <vp>ReturnTerm</vp> should has the same bit-size as the <vp>InputTerm</vp>. The domain name ''returnDomain'' must be specified at compile-time, i.e. it cannot come from a variable.
* <vpbnf><InputTerm></vpbnf>: Specifies the value that must be converted. <vp>InputTerm</vp> may be any Prolog term or an expression. If ''InputTerm'' is an expression, then it will be evaluated before conversion.
* <vpbnf><ReturnTerm></vpbnf>: Returned parameter <vp>ReturnTerm</vp> will be of ''returnDomain'' type.

<vp>uncheckedConvert</vp> evaluates <vp>InputTerm</vp>, change the type to ''returnDomain'' without any modification of the memory pattern and unifies with <vp>ReturnTerm</vp>. The <vp>uncheckedConvert</vp> predicate performs no runtime checks. It makes only compile time checking of bit-size equality of the converted domains. So almost any term may be quite recklessly converted to any other term. So quite disastrous results may occur if you try to use variables incorrectly converted by <vp>uncheckedConvert</vp>. Be extremely careful implementing <vp>uncheckedConvert</vp>; we strongly recommend you always, when it is possible, using of [[#convert|convert/2->]] and [[#tryConvert|tryConvert/2->]]. But notice that, when an object is returned by COM system it is necessary to convert it by <vp>uncheckedConvert</vp>, as Prolog program does not have information about its actual type.

==== upperBound ====

<vip>upperBound : (<numeric-domain> NumericDomain) -> <number-domain> UpperBound.</vip>

Returns the upper bound value of the specified numeric domain.

Call-template for this function is:

<vip>UpperBound = upperBound(domainName)</vip>

The <vp>upperBound</vp> is a compiling-time predicate. The <vp>upperBound</vp> returns the upper bound value of the specified numeric domain ''domainName''. The return value <vp>UpperBound</vp> belongs to the same domain ''domainName''. The ''domainName'' parameter should be the name of any numerical domain; this domain name should be explicitly specified at compile-time (that is, ''domainName'' cannot come from a variable).

See also [[#lowerBound|lowerBound/1->]].

Will cause a compile time error if the specified domain ''domainName'' is not numeric domain.
<noinclude>{{LanguageReferenceSubarticle|Built-in entities/Predicates}}</noinclude>

Visual Prolog 7.5 Upgrade Notes

2020-09-25T13:46:18Z

SergeMukhin: formaing

This document describes how to upgrade Visual Prolog 7.4 projects to Visual Prolog 7.5, for older projects you should also read [[Visual Prolog 7.4 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 7.5 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 7.5''' or '''C:\Program Files\Visual Prolog 7.5'''.
* The Personal Edition will by default be installed to '''C:\Program Files (x86)\Visual Prolog 7.5PE''' or '''C:\Program Files\Visual Prolog 7.5PE'''.

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

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

When your open a project in the Visual Prolog 7.5 IDE, it will automatically create a new .vipprj project file in XML format instead of the .prj6 files used by previous versions. The .prj6 file will still exist but it will not be updated by Visual Prolog 7.5, so the two files will come out of sync and therefore it is safest to delete the .prj6 file after the update.
After loading the project you should rebuild the entire project with the help of the '''Build | Rebuild All command''' and answer "Yes to All" to the messages suggesting adding or removing packages and include statements. You may have to build again several times to complete the build process.

Notice that you should simply delete include directives to PFC files which cannot be found: proper include directives will (normally) be inserted automatically.

Many projects will only require:
* Accept to remove all unexisting packages
* Accept to add required packages
* Delete all include directives for files that does not exist
* Accept to add include directives

== Manual updates ==

This section describes things that may need manual and semi-manual updates.

=== findall, trap and finally ===

The predicates <vp>findall/3</vp>, <vp>trap/3</vp> and <vp>finally/2</vp> have been deprecated.

<vp>findall/3</vp> should be replaced by using list comprehension:

<vip>findall(X, B, L) ==> L = [ X || B ]</vip>

<vp>trap/3</vp> and <vp>finally/2</vp> should be replaced by the try construct:

<vip>trap(P, E, H) ==> try P catch E do H end try
finally(P, F) ==> try P finally F end try</vip>

In all three cases the IDE will provide a "Fix" button in the error window than can make the rewrite, notice however that it may be necessary to make these in the opposite direction (last error first) to avoid that one fix will make the next fail.

=== Must unity ===

Must unify "==" can no longer be used on terms that will always unify, you should use "=" instead.

== See also ==

* [[New Features in Visual Prolog 7.5]]
* [[Visual Prolog 7.4 Upgrade Notes]]

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

Visual Prolog 7.5 Upgrade Notes

2020-09-25T13:45:35Z

SergeMukhin: misspelling

This document describes how to upgrade Visual Prolog 7.4 projects to Visual Prolog 7.5, for older projects you should also read [[Visual Prolog 7.4 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 7.5 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 7.5''' or '''C:\Program Files\Visual Prolog 7.5'''.
* The Personal Edition will by default be installed to '''C:\Program Files (x86)\Visual Prolog 7.5PE''' or '''C:\Program Files\Visual Prolog 7.5PE'''.

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

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

When your open a project in the Visual Prolog 7.5 IDE, it will automatically create a new .vipprj project file in XML format instead of the .prj6 files used by previous versions. The .prj6 file will still exist but it will not be updated by Visual Prolog 7.5, so the two files will come out of sync and therefore it is safest to delete the .prj6 file after the update.
After loading the project you should rebuild the entire project with the help of the '''Build | Rebuild All command''' and answer "Yes to All" to the messages suggesting adding or removing packages and include statements. You may have to build again several times to complete the build process.

Notice that you should simply delete include directives to PFC files which cannot be found: proper include directives will (normally) be inserted automatically.

Many projects will only require:
* Accept to remove all unexisting packages
* Accept to add required packages
* Delete all include directives for files that does not exist
* Accept to add include directives

== Manual updates ==

This section describes things that may need manual and semi-manual updates.

=== findall, trap and finally ===

The predicates <vp>findall/3</vp>, <vp>trap/3</vp> and <vp>finally/2</vp> have been deprecated.

<vp>findall/3</vp> should be replaced by using list comprehension:

<vip>findall(X, B, L) ==> L = [ X || B]</vip>

<vp>trap/3</vp> and <vp>finally/2</vp> should be replaced by the try construct:

<vip>trap(P, E, H) ==> try P catch E do H end try
finally(P, F) ==> try P finally F end try</vip>

In all three cases the IDE will provide a "Fix" button in the error window than can make the rewrite, notice however that it may be necessary to make these in the opposite direction (last error first) to avoid that one fix will make the next fail.

=== Must unity ===

Must unify "==" can no longer be used on terms that will always unify, you should use "=" instead.

== See also ==

* [[New Features in Visual Prolog 7.5]]
* [[Visual Prolog 7.4 Upgrade Notes]]

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

Language Reference/Built-in entities/Constants

2020-07-07T11:02:20Z

SergeMukhin: format: HH-MM-SS -> HH:MM:SS

{|{{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 special constant of a pointer type with the zero value.

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

==== nullHandle ====

A special constant of a handle type with the zero value.

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

==== invalidHandle ====

A special constant of a handle type with the invalid (-1) value.

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

Language Reference/Built-in entities/Constants

2020-07-07T10:50:47Z

SergeMukhin: format HH:MM:SS -> HH:MM

{|{{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 special constant of a pointer type with the zero value.

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

==== nullHandle ====

A special constant of a handle type with the zero value.

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

==== invalidHandle ====

A special constant of a handle type with the invalid (-1) value.

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

Language Reference/Directives

2020-02-18T17:09:53Z

SergeMukhin: add #stringinclude

{{languageReferenceNavbar|Directives}}

Each compiler directive starts from the <vp>#</vp> character. The following directives are supported:

* <vp>#include</vp>, <vp>#bininclude </vp>, <vp>#stringinclude </vp> - file inclusion.
* <vp>#if</vp>, <vp>#then</vp>, <vp>#else</vp>, <vp>#elseif</vp>, <vp>#endif</vp> - conditional statements.
* <vp>#export</vp>, <vp>#externally</vp> - exporting and importing classes.
* <vp>#message</vp>, <vp>#error</vp>, <vp>#requires</vp>, <vp>#orrequires</vp> - compilation time information.
* <vp>#options</vp> - compiler options.

=== Source File Inclusion ===

The <vp>#include</vp> compiler directive is used to include the contents of another file into your program source code during compilation. It has the following syntax:

<vipbnf><Pp_dir_include> :
#include <String_literal></vipbnf>

The {{lang2|Lexical_Elements|String_Literals|<vpbnf><String_literal></vpbnf>}} should specify an existing filename.

<vip>#include "pfc\\exception\\exception.ph" % Includes pfc\exception\exception.ph file</vip>

<vip>#include @"pfc\vpi\vpimessage\vpimessage.ph" % Includes pfc\vpi\vpimessage\vpimessage.ph</vip>

This compiler directive uses "include the first file occurrence only" semantics. That is, if a compilation unit contains several include directives for the same file, it will be included only one time with the first include directive.

Each included file must contain several accomplished scopes; an included file cannot contain uncompleted scopes. That is, it should contain several accomplished interface declarations, class declarations, class implementations or/and several compiler directives.

The compiler tries to find the specified include source file in the following way:

#If the filename contains an absolute path, then this file should be included.
#Otherwise, the compiler searches for the specified include filename among the paths that had been defined by the <vp>/Include</vp> command line option. These paths are handled consequently as they are specified in the option. In the IDE you can set these paths in the '''Include Directories''' in the '''Directories''' tab of the '''Project Settings''' dialog.

If the compiler does not find the specified file a compiling time error is generated.

=== Text File Inclusion ===

The <vp>#stringinclude</vp> compiler directive is used to include (during compilation) the contents of a file (specified by the {{lang2|Lexical_Elements|String_Literals|string_literal}} string) as a ::{{lang2|Built-in_entities|string|string}} constant into your program source code. It has the following syntax:

<vipbnf><Pp_dir_bininclude> :
#stringinclude( <String_literal> )</vipbnf>

This directive can be used in any places where {{lang2|Built-in_entities|string|string}} constants are allowed. The {{lang2|Lexical_Elements|String_Literals|string_literal}} should specify an existing filename. The syntax is the same as in the <vp>#include</vp> compiler directive described in the previous paragraph {{lang2|Directives|Source_File_Inclusion|Source File Inclusions}}. The compiler tries to find the specified file in the same way as for <vp>#include</vp> compiler directive. If the file has a byte-order-mark it will be treated accordingly, if the file does not have byte order mark and does not appear to be in utf-16 it will be read with the current codepage (it is recommended to use files with byte-order-mark utf-8 or utf-16).
{{Example|A typical usage is like this:
<vip>
constants
myText : string = #stringinclude("text.txt").
% String constant from contents of the file "text.txt".
</vip>
}}

=== Binary File Inclusion ===

The <vp>#bininclude</vp> compiler directive is used to include (during compilation) the contents of a file (specified by the {{lang2|Lexical_Elements|String_Literals|string_literal}} string) as a ::{{lang2|Built-in_entities|binary|binary}} constant into your program source code. It has the following syntax:

<vipbnf><Pp_dir_bininclude> :
#bininclude( <String_literal> )</vipbnf>

This directive can be used in any places where {{lang2|Built-in_entities|binary|binary}} constants are allowed. The {{lang2|Lexical_Elements|String_Literals|string_literal}} should specify an existing filename. The syntax is the same as in the <vp>#include</vp> compiler directive described in the previous paragraph {{lang2|Directives|Source_File_Inclusion|Source File Inclusions}}. The compiler tries to find the specified file in the same way as for <vp>#include</vp> compiler directive.

{{Example|A typical usage is like this:
<vip>
constants
myBin : binary = #bininclude("Bin.bin").
% Binary constant from contents of the file "Bin.bin".
</vip>
}}

When creating a binary constant the compiler adds the EOS symbol immediately after this constant.

=== Exporting and Importing Classes ===

Compiler directives <vp>#export</vp> and <vp>#externally</vp> are used to determine lists of exported and imported classes, respectively. They have the following syntax:

<vipbnf><Pp_dir_export> :
#export <ClassNames>-comma-sep-list
<Pp_dir_export> :
#externally <ClassNames>-comma-sep-list</vipbnf>

These compiler directives are applied only to classes {{lang|Classes|classNames}}, which do not construct objects.

They can be used only outside scopes; that is, they cannot be used inside declarations of interfaces and classes and they cannot be used inside implementations of classes.

By default, predicates within one executed module are hidden at runtime for all other executed modules. An <vp>#export</vp> compiler directive makes names of specified classes public outside the module in which they are declared (and implemented). Therefore, all predicates from this module declared in the classes (specified in an <vp>#export</vp> directive) become accessible while runtime from other executed modules.

Usually, an <vp>#export</vp> compiler directives can be used in projects, which target modules are DLLs. It enumerates classes declared in a DLL, which should be accessible to other modules that use this DLL.

If a compilation unit export some class, then this compilation unit should contain this class implementation.

Also an <vp>#export</vp> compiler directives can be used to specify {{lang2|Directives|Conditional_Compilation|condition}} expressions for <vp>#if</vp> compiler directives.

For example, let us suppose that somewhere in the beginning of a compilation unit the compiler has met the <vp>#export</vp> compiler directive like this:

<vip>#export className</vip>

Then the compiler, if in the subsequent code it meets an <vp>#if</vp> compiler directive with the same <vp>#export</vp> compiler directive used as the condition expression, for example like this:

<vip>#if #export className #then ... #endif </vip>

Then the compiler evaluates the <vp>#export</vp> condition expression as <vp>true</vp> and, hence, the compiler executes the <vp>#then</vp> branch of the conditional compilation directive.

For example, the following <vp>#export</vp> compiler directive with the subsequent <vp>#if</vp> conditional compilation compiler directive:

<vip>#export className
...
#if #export className #then #requires "some.pack" #endif</vip>

guaranty that the <vp>"some.pack"</vp> package will be included into the compilation unit.

From the other hand, if an <vp>#export</vp> compiler directive is not met by the compiler (somewhere in the compilation unit before the <vp>#if</vp> compiler directive, which uses the same <vp>#export</vp> compiler directive as the conditional expression), then the compiler evaluates this <vp>#export</vp> condition expression as <vp>false</vp>. Hence, the compiler will not execute the <vp>#then</vp> branch of the <vp>#if</vp> conditional compilation directive. That is, the single <vp>#if</vp> compiler directive without previous <vp>#export</vp> directive

<vip>#if #export className #then #requires "some.pack" #endif</vip>

does not requires to include the <vp>"some.pack"</vp> package.

An <vp>#externally</vp> compiler directive is counterpart to an <vp>#export</vp> compiler directive. An <vp>#externally</vp> compiler directive can be used instead of (and concurrently with) an <vp>IMPORTS</vp> directive in definition files. An <vp>#externally</vp> compiler directive enumerates classes, which are declared in a module but implemented in other modules. Therefore, the compiler will not produce errors when it detects such classes. The referenced classes can be implemented (and exported) in DLLs, which can be linked to the module at runtime.

The <vp>#export</vp> and <vp>#externally</vp> compiler directives can be used as <vpbnf><Condition></vpbnf> boolean expressions in {{lang2|Directives|Conditional Compilation|Conditional Compilation}}.

For example, like this:

<vip>#if #export className #then #include "Some package.pack" #endif</vip>

=== Compile Time Information ===

Compiler directives <vp>#message</vp>, <vp>#requires</vp>, <vp>#orrequires</vp>, and <vp>#error</vp> can be used to issue user-defined messages into a listing file while compilation of project modules and to interrupt compilation.

These directives can be used either outside scopes (interface declaration, class declaration or class implementation), or inside scopes but outside sections. They have the following syntax:

<vipbnf><Pp_dir_message>: one of
#message <String_literal>
#error <String_literal>
#requires <String_literal> <Pp_dir_orrequires>-list-opt
#orrequires <String_literal></vipbnf>

When the compiler meets any of these directives, it generates the correspondent warning message and place the directive text into a ''listing file''.

A listing file name can be specified with the compiler directive:

<source lang="text">/listingfile:"FileName"</source>

Notice that no empty spaces can be used between the colon <vp>:</vp> (after <vp>/listinglile</vp>) and <vp>"FileName"</vp>.

By default the compiler does NOT generate informative messages for the <vp>#message</vp>, <vp>#requires</vp>, and <vp>#orrequires</vp> directives. You can switch generation of these informative messages ON specifying the compiler options:

<source lang="text">/listing:message
/listing:requires
/listing:ALL</source>

{{Example| In this case, when the compiler meets a directive like:

<vip>#message "Some message"</vip>

it will place the following text into the listing file:

<source lang="text">C:\Tests\test\test.pro(14,10) : information c062: #message "Some message"</source>
}}

The directive <vp>#requires</vp> (<vp>#orrequires</vp>) issues arbitrary user-defined messages about the needed source (object) files into a listing file. The <vp>#orrequires</vp> directive cannot be used alone: the <vp>#requires</vp> directive should immediately (separated with white spaces or comments only) precede it.

The directive <vp>#error</vp> always terminates the compilation and issues the user-defined error message like the following into a listing file:

<source lang="text">C:\Tests\test\test.pro(14,10) : error c080: #error "Compilation is interrupted"</source>

You can parse and analyze these messages and accept the required actions. For example, the VDE analyzes information printed by the <vp>#requires</vp> and <vp>#orrequires</vp> directives and automatically adds all needed PFC packages and standard libraries to the compiled project (See also the '''Handling Project Modules''' topic).

{{Example| The directives <vp>#requires</vp> and <vp>#orrequires</vp> can be used like this:

<vip>#requires @"\Common\Sources\CommonTypes.pack"
#orrequires @"\Common\Lib\CommonTypes.lib"
#orrequires @"\Common\Obj\Foreign.obj"
#if someClass::debugLevel > 0 #then
#requires @"\Sources\Debug\Tools.pack"
#orrequires @"\Lib\Debug\Tools.lib"
#else
#requires @"\Sources\Release\Tools.pack"
#orrequires @"\Lib\Release\Tools.lib"
#endif
#orrequires "SomeLibrary.lib"
#requires "SomePackage.pack"
#if someClass::debugLevel > 0 #then
#orrequires @"\Debug\SomePackage.lib"
#else
#orrequires @"\Release\SomePackage.lib"
#endif</vip>
}}

{{Example| The <vp>#message</vp> directive can be used like this:

<vip>#message "Some text"
#if someClass::someConstant > 0 #then
#message "someClass::someConstant > 0"
#else
#message "someClass::someConstant <= 0"
#endif
class someClass
#if ::compiler_version > 600 #then
#message "New compiler"
constants
someConstant = 1.
#else
#message "Old compiler"
constants
someConstant = 0.
#endif
end class someClass</vip>
}}

{{Example| The <vp>#error</vp> can be used like this:

<vip>#if someClass::debugLevel > 0 #then
#error "Debug version is not yet implemented"
#endif</vip>
}}

=== Compiler options directive ===

Compiler directive <vp>#options <string_literal></vp> affects the whole compilation unit. This directive should be used outside scopes and conditional compilation statements in the main source file for a compilation unit (i.e. in the source file which is passed to the compiler). Otherwise the compiler generates a warning message and ignores the directive.

The <vp><string_literal></vp> can only contain the following compiler options:

<vip>"/Warning"
"/Check"
"/NOCheck"
"/Optimize"
"/DEBug"
"/GOAL"
"/MAXErrors"
"/MAXWarnings"
"/profile"</vip>

Otherwise the compiler generates the error message for invalid option.
If there are several <vp>#options</vp> directives they are handled in the textual order.

=== Conditional Compilation ===

The conditional programming constructions are part of the Visual Prolog language. Only other compiler directives, {{lang|Compilation Units|Compilation Units}}, and {{lang|Program Sections|Program Sections}} (including empty) can be conditional. The following syntax is used:

<vipbnf><ConditionalItem> :
#if <Condition> #then <CompilationItem>-list-opt <ElseIfItem>-list-opt <ElseItem>-opt #endif</vipbnf>

<vipbnf><ElseIfItem> :
#elseif <Condition> #then <CompilationItem></vipbnf>

<vipbnf><ElseItem> :
#else <CompilationItem></vipbnf>

Here <vpbnf><Condition></vpbnf> can be any expression, which can be evaluated to fail or succeed during compilation time.

Each one conditional compilation statement must be in one file, that is, the compiler directives <vp>#if</vp>, <vp>#then</vp>, <vp>#elseif</vp> and <vp>#else</vp> (if present), <vp>#endif</vp> of the same level of nesting must be in one file.

During compilation the compiler evaluates the conditions, in order to determine which parts to include in the final program. Parts that are excluded from the final program are called the dead branches.

All branches of conditional compilation items are syntax checked and must be syntactically correct. That is, also the dead branches must be syntactically correct.

The compiler only calculates conditions on a need to know basis, i.e. it does not calculate conditions in dead branches.

A condition may not depend on any code, which is located textually inside the conditional statement.

The example below is '''illegal''' because the condition depends on the scope (and constant) which is declared inside the condition branch.

<vip>#if aaa::x > 7 #then % ERROR!
class aaa
constants
x = 3
end class aaa
#else
class aaa
constants
x = 23
end class aaa
#endif</vip>

Language Reference/Terms

2019-10-29T10:57:49Z

SergeMukhin: add --

{{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>:
<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}}.

=== 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/Terms

2018-07-31T13:21:47Z

SergeMukhin: /* or (;) */

{{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>:
<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

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

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

=== 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/Objects and Polymorphism

2017-07-10T09:36:38Z

SergeMukhin: /* Parametric Polymorphism */

{{languageReferenceNavbar|Generic Interfaces and Classes}}

The programming language Visual Prolog has gone through a huge development in the latest years, and this will also continue in future. Most noticeable is the shift to object-orientation, and the introduction of parametric polymorphism. In this paper we will explain the reason for introducing these features. Examples will be used to illustrate how these facilities can help to tackle the increasing complexity and size of software.

=== Motivation ===

While Prolog has many great virtues, one must remember that it is from the IT-bronze-age, and it would be silly to think that it would stay contemporary after three decades or more, especially considering the speed with, which the IT-world has evolved since then. Back then you could write an amazing Prolog program that described how to get a cabbage, a goat, a wolf and a farmer across a river in a little boat without anybody eating anybody. You can still write such programs just as easily (see [[Farmer, Wolf, Goat and Cabbage]]), but they are just not that amazing anymore. Show it to your children and they will immediately ask why the solution is not an animation, and explain that there are millions of much more advanced programs one click away on the Internet already.

Programs today must be more advanced than yesterday. They also have to live and interact with a much larger world than yesterday. And this is an ongoing story.

Many attempts has been made to help tackle these challenges; we have chosen to add the elements that we believe are the winners to Visual Prolog. These are especially object-orientation and parametric polymorphism, but there are also other new elements especially taken from the functional programming world.

=== Goals and Means ===

The goals of the language update is to provide better means for creating and maintaining more complex programs for more complex surroundings.

==== Simplicity ====

Humans are better to dealing with simple things than complex things, so one important way to deal with complexity is to reduce it to something simpler, especially by using "structure" to organize the complexity.

The main "trick" is the ''divide and conquer '' principle: Divide the original problem into separate sub-problems that can be solved individually. I.e., the solution to the overall problem consists of a number of sub-solutions and something that combines these into the overall solution.

==== Maintainability ====

For software it is often not enough to solve a problem, we must also be able to maintain and extend the solution in an evolving world. So it is important that the used methods not only solve the problem, but also result in a program that can be maintained. Here it is important that the program is understandable and especially that the ''divides'' are visible and clear in the program.

==== Reuse and sharing ====

When you divide problems into sub-problems, perhaps repeatedly, you will sometimes see similar sub-problems. Then it would of course be nice to short cut by reusing a similar solution. Such a solution can be adopted into the new context, but there are two ways this can happen. We can make a copy and update it to its new purpose, or we can try to share the code between the two problems.

The latter is clearly the hardest and only makes sense if both pieces of software are still maintained. But in that case you will have the advantage that maintenance made in one context is also shared with the other context.

==== Flexibility ====

It is also desirable that your software is flexible. You may for example need to deliver several variants of your software to different customers. Or you may need to reconfigure the software to a changed context. Also some of your shared sub-solutions may need to go into contexts that are not completely the same.

==== Power ====

Finally, it is of course desirable if language extensions add additional programming power. For example, by simplifying the code necessary to tackle certain standard "issues".

=== Polymorphism ===

Visual Prolog has been extended with many language features that support the goals above, but it is still up to the programmer to apply these features such that the goals are achieved. Here we will focus on understanding and using polymorphism.

The object-system in Visual Prolog gives so called '' subsumption polymorphism'', and from Visual Prolog 7.0 you also have '' parametric polymorphism''. Polymorphism is especially well-suited for '' divide and conquer'' that supports ''sharing'' of code.

==== Subsumption polymorphism ====

An object is a closed entity that carries state and code. The object provides an interface through which the surroundings can interact with the object. The object can also interact with other objects through their interfaces.

Each interface has an explicit definition in the source code. The definition effectively consists of a name and a number of predicate declarations.

Let us assume that we want an object through which some administrative system can report salary. In an oversimplified world, such an object might have this interface:

<vip>interface salarySystem
predicates
salary : (string Name, real Amount).
end interface salarySystem</vip>

An object with this interface will allow you to report an Amount for a person (identified by Name).

The salarySystem interface defines a data type that can be used in the program. The main salary reporting predicate in the application might be declared like this:

<vip>class predicates
reportSalary : (salarySystem SalarySystem).</vip>

For the sake of the example, we simply hard code a little salary reporting like this:

<vip>clauses
reportSalary(SalarySystem) :-
SalarySystem:salary("John D", 135.12),
SalarySystem:salary("Elvis P", 117.00).</vip>

We will of course also need to implement our salary system objects, and that is where the subsumption polymorphism comes in play. The thing is that our customers of course use a lot of different salary systems, which must receive input in many different formats and using many different media. Objects are implemented by classes, and the fortunate thing is that many different classes can implement the same interface. Objects produced by any such class can be used by the reportSalary predicate. Thus, the reportSalary predicate is ''polymorphic'' because the salarySystem type '' subsumes'' all the different implementations of the interface. To deal with the ACME salary system we declare this class:

<vip>class acme : salarySystem
end class acme</vip>

The declaration simply says that acme is a class that produces objects of type salarySystem. The class also needs an implementation:

<vip>implement acme
constants
fmt = "SAL:%>>>%\n".
clauses
salary(Name, Amount) :-
stdio::writef(fmt, Name, Amount).
end implement acme</vip>

To illustrate the polymorphism, we will also implement the integration to the O'Salery system. Again we declare and implement a class:

<vip>class oSalary : salarySystem
end class oSalary

implement oSalary
constants
fmt = "<salary name=\"%\" wage=\"%\" />\n".
clauses
salary(Name, Amount) :-
stdio::writef(fmt, Name, Amount).
end implement oSalary</vip>

Now let us try our two salary system integrations:

<vip>clauses
test():-
ACME = acme::new(),
reportSalary(ACME),
Osalery = oSalary::new(),
reportSalary(Osalery).</vip>

In the test predicate above, we create one of each salary systems and report salary to them. The result looks like this:

<vip>SAL:John D>>>135.12
SAL:Elvis P>>>117
<salary name="John D" wage="135.12" />
<salary name="Elvis P" wage="117" /></vip>

In this example, the difference was not that big, but we might also have placed the result in a database, used a foreign API, called a WEB service or whatever.

The solution above uses the divide and conquer principle to separate the reporting in a vendor independent part and a vendor specific part. In this case the vendor independent part also deals with the company level in the reporting, were as the vendor dependent part only deals with the person level.

We have used subsumption polymorphism to provide the flexibility to deal with many different salary systems in a seamless way. In real world, this may not be as simple as here though. The key to success is that the salarySystem interface is a sufficiently powerful abstraction/generalization of ''all'' the relevant salary systems. It may for example be necessary to provide several different ways to identify persons in the salary predicate. Different salary systems can then use the identification method, which is appropriate for them and ignore the rest.

The reportSalary predicate is ''shared'' across different salary systems. The sharing is a high-level domain specific sharing, within the same application or variants of it.

Visual Prolog also has another kind of subsumption polymorphism: Predicate values. A predicate value is a predicate that is bound to variables, transferred as parameter and/or stored in facts. Again, the polymorphism comes from a type that ''subsumes'' many different implementations.

As an example, PFC uses predicate values in its heavily used ''event notification scheme''. A scheme that can of course also be used outside PFC.

The event notification scheme has two kinds of actors: the event source and the event listener. There is one event source, but there can be any number of listeners. The event source offers predicates for registering and deregistering event listeners. When the event occurs all registered listeners are notified.

The interesting thing is that the event listener is a predicate, meaning that the notification will immediately execute code. In addition, due to the subsumption polymorphism each listener can have its own implementation and thus perform quite different actions.

A very important property of predicate values is that they can be '''''object''''' predicates, and that these have access to the object state to which they belong.

We shall not describe the event notification scheme in details here, though it is good to understand. The reader is encouraged to study the concept in PFC (look for ''addXxxxListener''). However, the use of predicate values will be exercised in the example in the job-scheduling example in the end of this paper.

==== Parametric Polymorphism ====

Like for subsumption polymorphism the purpose of ''parametric'' polymorphism is to use the same code for many things. However, where subsumption polymorphism is mainly about supplying different implementations to the same context, parametric polymorphism is mainly about using the same implementation in different contexts.

Let us start with a very simple example, to introduce the concepts. We will implement a function, which takes the list as argument and returns the elements one by one (non-deterministically).

In Visual Prolog the list domain is a polymorphic domain: If Elem is a type/domain then Elem* the list domain of Elem. The new thing is that ''parameters'' like Elem and type expressions like Elem* can be used in declarations, and that the resulting declaration will cover any instantiation of such parameters.

Therefore we can declare our getMember_nd function like this:

<vip>predicates
getMember_nd : (Elem* List) -> Elem Value
nondeterm.</vip>

This declaration says that getMember_nd is a function, which takes a list of Elem argument and returns an Elem, where Elem is any domain/type.

The implementation is straightforward:

<vip>clauses
getMember_nd([V|_L]) = V.
getMember_nd([_V|L]) = getMember_nd(L).</vip>

Without further notice getMember_nd can be used on any list kind:

<vip>clauses
run():-
console::init(),
L = [[1,2,3], [7,-7], [9,4,5]],
foreach X = list::getMember_nd(L) do
stdio::writef("X = %\n", X)
end foreach.</vip>

Here Elem is integer* (i.e. list of integers). The output looks like this:

<vip>X = [1,2,3]
X = [7,-7]
X = [9,4,5]</vip>

The list domain is a predefined polymorphic domain. But you can also define polymorphic domains yourself. As an example we can create a ''priority queue''; sometimes called a heap. Let me warn you, the implementation I will use here is not particularly efficient; it is just simple.

The idea of the priority queue is that we can insert some Data with a Priority, later we can then retrieve the data with lowest Priority. It sounds a bit strange, that it is the one with the lowest Priority that is retrieved; but that is how it normally works. I assume that it comes from the idea of first priority, second priority, etc. where smaller number means higher priority.

Anyway, in this case we want to implement the queue as a list of tuple's, each tuple has two elements the first is the Priority and the second is the Data. Furthermore, we will keep the list sorted after Priority (i.e. an invariant), such that the smallest element is always first in the list.

'''tuple''' is already defined in Visual Prolog its definition looks like this:

<vip>domains
tuple{T1, T2} = tuple(T1, T2).</vip>

There are also tuple's with other arities, but we only need the pair. This is an example of a programmer defined polymorphic domain. What the definition says is that tuple is a domain with two type parameters T1 and T2. You may think of it as an infinite family of domains corresponding to all instantiations of the type parameters, e.g.:

<vip>domains
tuple_char_char = tuple(char, char).
tuple_char_integer = tuple(char, integer).
tuple_char_string = tuple(char, string).
...</vip>

The single domain definition above corresponds to all these domains, but actually the domain names/expressions look like this:

<vip> tuple{char, char}
tuple{char, integer}
tuple{char, string}
...</vip>

The values looks as expected; let us take a relatively complex one right away:

<vip> X = tuple(tuple('a',"a"), [1.2])</vip>

X is a tuple, its first element is itself a tuple (containing a char and a string), its second element is a list of real's. Subsequently, X has this type:

<vip> tuple{ tuple{char, string}, real* } </vip>

As you can see type expressions can become rather complex. You will probably soon get use to this, but below I will show a little scheme that can be used to keep type expressions simpler and more understandable, and which will at the same time make your program more type safe.

We are now ready to define our queue domain:

<vip>domains
queue_rep{Priority, Data} = tuple{Priority, Data}*.</vip>

The _rep in the domain name has to do with the scheme mentioned above, right now you can simply ignore it. The domain definition says that queue_rep is a domain with two type parameters Priority and Data further more it is a list of tuple's of these types.

You may wonder why Priority is a type parameter, you may think that it should have been a number type like integer. However, in Visual Prolog 7.0 all data types are ordered, and therefore any data type can be used as a priority. Using a type parameter here makes the resulting queue more flexible. And at least I do not have to choose whether the priority should be integer, unsigned or real.

To know whether you can use a type parameter or have to use a regular type you will have to consider what you need from the type. Like here where we need ordering (comparison). The following is possible on type parameters:

*transferring as parameter

*binding and unifying (with values of same type)

*comparing (with values of same type)

*writing on streams

*reading from streams

The last thing is partially wrong, the compiler allows this, but in practice you cannot read all kind of data, it is for example not possible to read predicate values and objects from streams.

Let us return to our priority queue. Now that we have defined the domain that represents the queues, we will also have to declare and implement the suitable operations.

Let us start with the simple ones. First we need an operation to obtain the least element in the queue (i.e. the one with least Priority). This can be declared like this:

<vip>predicates
tryGetLeast_rep : (queue_rep{Priority, Data} Queue) -> tuple{Priority, Data} Least determ.</vip>

The predicate is determ because the queue might be empty. The predicate is a function whose argument is a priority queue and which returns a tuple containing both the Priority and the Data. It does not remove the element from the queue, because I want to be able to peek at the element without removing it.

The list is sorted with the least element first, so the implementation is trivial:

<vip>clauses
tryGetLeast_rep([Least|_]) = Least.</vip>

Similarly we need a predicate for removing the least element:

<vip>predicates
deleteLeast_rep : (queue_rep{Priority, Data} Queue1) -> queue_rep{Priority, Data} Queue.
clauses
deleteLeast_rep([]) = [].
deleteLeast_rep([_Least|Rest]) = Rest.</vip>

Finally we need an insert predicate:

<vip>predicates
insert_rep : (queue_rep{Pri, Data} Q1, Pri P, Data D) -> queue_rep{Pri, Data} Q0.
clauses
insert_rep([], Pri, Data) = [tuple(Pri, Data)].

insert_rep(Q1, Pri, Data) = Q0 :-
[tuple(P1,D1)|Rest] = Q1,
if Pri <= P1 then
Q0 = [tuple(Pri, Data)| Q1]
else
Q0 =
[tuple(P1,D1) | insert_rep(Rest, Pri, Data)]
end if.</vip>

I have chosen shorter variable names to make the code fit the narrow column, but at the same time it gives me the opportunity to explain that type variables like Pri above only have scope in the declaration/definition where they occur. Therefore, there is nothing wrong with using Priority in one declaration and Pri in another. Nevertheless, you should of course choose variable names with care, because good names make the code clearer. The compiler would not mind if you exchange Priority and Data, but I am sure that it could confuse many programmers.

In future versions of Visual Prolog there will also be type variables whose scope is a complete interface/class/implementation.

The priority queue above can be used for various purposes, but it has two disadvantages, which both relate to the way we have defined the queue domain itself:

<vip>domains
queue_rep{Priority, Data} = tuple{Priority, Data}*.</vip>

A definition like this one is just an abbreviation or synonym, so queue_rep{integer, sting} is exactly the same as tuple{integer, string}*.

#The debugger will always show the unfolded type (i.e. tuple{integer, string}*) and this can be rather confusing.

#Any piece of data that have this type can accidentally be given as argument to the priority queue predicates. However, the priority queue operations not only require that the data has this type, it also expect that it is sorted in a specific way (i.e. that the data satisfies the invariant).

The latter problem could just as easy exist without polymorphism. It comes from using a general data structure for something specific. If you do this, you can mix anything that is of the general kind even though it is of different specific kinds.

So instead we just consider the queue_rep domain as being the internal ''representation'' of the queues, hence the extension _rep. To the external world we will wrap each queue_rep queue inside a functor.

Therefore, to the real queue domain will look like this:

<vip>domains
queue{Priority, Data} = queue(queue_rep{Priority, Data}).</vip>

Such a domain is neither an abbreviation nor a synonym.

The exported/public predicates will of course work on queue 's, so the complete class declaration looks like this:

<vip>class priorityQueue
open core

domains
queue_rep{Priority, Data} = tuple{Priority, Data}*.

domains
queue{Priority, Data} = queue(queue_rep{Priority, Data}).

constants
empty : queue{Priority, Data} = queue([]).

predicates
insert : (queue{Pri, Data} Q1, Pri Pri, Data Data) -> queue{Pri, Data} Q0.

predicates
tryGetLeast : (queue{Priority, Data} Queue) -> tuple{Priority, Data} Least determ.

predicates
deleteLeast : (queue{Priority, Data} Queue1) -> queue{Priority, Data} Queue.
end class priorityQueue</vip>

I have also added an empty queue constant to the class. As a user of the class you then do not need to be concerned with the representation of the queues at all, there are predicates and constants for everything.

The predicates in this class are very simple to implement given the predicates we implemented before, the only thing they should do is to remove and add the queue functor in the relevant places:

<vip>clauses
insert(queue(Queue), Priority, Data) = queue(insert_rep(Queue, Priority, Data)).

clauses
tryGetLeast(queue(Queue)) = tryGetLeast_rep(Queue).

clauses
deleteLeast(queue(Queue)) = queue(deleteLeast_rep(Queue)).</vip>

Using this _rep scheme is a bit less efficient, because of the extra functor, and it is entirely up to your temperament whether to use it or not. In any case it makes your type unique, rather than being a synonym type.

Priority queues can be used like this:

<vip>clauses
test():-
Pq1 = priorityQueue::empty,
Pq2 = priorityQueue::insert(Pq1, 17, "World"),
Pq3 = priorityQueue::insert(Pq2, 12, "Hello"),
Pq4 = priorityQueue::insert(Pq3, 23, "!"),
stdio::writef("%\n", Pq4).</vip>

The output looks like this (except for additional white space):

<vip>queue( [tuple(12,"Hello"), tuple(17,"World"), tuple(23,"!") ] )</vip>

It may seem that polymorphism disables type check, but in fact it gives a very strong but flexible type check. If, for example, I write:

<vip>clauses
test():-
Pq1 = priorityQueue::empty,
Pq2 = priorityQueue::insert(Pq1, 17, "World"),
Pq3 = priorityQueue::insert(Pq2, 12, 13).</vip>

Then I will get the error message:

error c504: The expression has type '::integer', which is incompatible with the type '::string'

The first insert forces the Data type of Pq2 to be string, therefore you cannot use an integer in the next line.

What may be more surprising is that it also forces the Data type of Pq1 to be string. Therefore this code gives exactly the same error:

<vip>clauses
test():-
Pq1 = priorityQueue::empty,
Pq2 = priorityQueue::insert(Pq1, 17, "World"),
Pq3 = priorityQueue::insert(Pq1, 12, 13).</vip>

On the other hand this is legal:

<vip>clauses
test():-
Pq1a = priorityQueue::empty,
Pq2 = priorityQueue::insert(Pq1a, 17, "World"),
Pq1b = priorityQueue::empty,
Pq3 = priorityQueue::insert(Pq1b, 12, 13).</vip>

The "moral" is that the constant empty is polymorphic, but variables can only have a monomorphic type, so when empty is bound to a variable a concrete type is chosen and "frozen".

The priority queue above can be use for numerous purposes. And the code can be shared between all such uses, both within a single program and across programs. If I choose to make a more efficient solution to the priority queue, then I will benefit from this in all places where it is used.

Parametric polymorphism is used to solve different problems in the same way (e.g. a using priority queue), and as such it is often used to make basic library software.

Subsumption polymorphism is in many respects the complement to parametric polymorphism: it is used solve the same problem in '' different'' ways (e.g. reporting salaries to ''different'' salary systems), and as such it is often used at high levels in applications to deal with variance.

However, the world is not black and white in this respect, there are many graduations and clear exceptions to this.

=== Example: Job Scheduler ===

Now let us try to combine some of the things from above to produce a simple, but yet powerful '''''job scheduler'''''.

A ''job'' is just some computation that should be performed. You register a job in the scheduler; the scheduler will then start the job at the requested time. Given such an "alarm clock" scheduler it is relatively easy to deal with reoccurring jobs and jobs that start in X minutes rather than at a certain time, and so forth. Here we will only consider the "alarm clock" functionality.

The scheduler will rely on a timer event: every time the timer even triggers it will see if any jobs are due, and execute these.

In this example I will just assume that time is an integer. I might want to use several schedulers in my program, so I choose to represent each scheduler by an object. Therefore the scheduler is mainly described as an interface, i.e. the type of the scheduler objects. The declaration of the scheduler looks like this:

<vip>interface scheduler
domains
job = (integer Time) procedure (i).

predicates
registerJob : (integer Time, job Job).

predicates
timerTick : (integer Time).
end interface scheduler</vip>

A job is a predicate value acting as a callback. I have chosen that the job receive the invocation Time as a parameter. This is mainly for illustrative purposes and simplicity. In real life, I would probably rather give it the scheduler, which I would enrich with predicates for obtaining the current time and probably other things as well. That way the job can itself decide which information it wants to obtain.

registerJob has the obvious functionality.

timerTick should be invoked regularly, since this is the heart of the scheduler.

The implementation looks like this:

<vip>implement scheduler
open core, priorityQueue
facts
jobQueue : queue{integer, job}.

clauses
new() :-
jobQueue := empty.

clauses
registerJob(Time, Job) :-
jobQueue := insert(jobQueue, Time, Job).

clauses
timerTick(Time) :-
if
tuple(T, Job) = tryGetLeast(jobQueue),
T <= Time
then
Job(Time),
jobQueue := deleteLeast(jobQueue),
timerTick(Time)
end if.
end implement scheduler</vip>

Most of the implementation is completely trivial. The main thing is that I use a priority internally for storing the jobs, with the time as priority. This have the advantage that the "most due" job is always easily accessible.

There is a jobQueue fact that is initialized in the constructor, and registerJob simply insert the job in the priority queue.

The important things take place in timerTick. It peek at the "least" job in the queue. If this hob should be started now or earlier then it is stated and removed from the queue, and then the rest of the queue is considered.

If the "least" job is not due then we do nothing, i.e. then we wait for another timer tick.

Before we use the scheduler I want to point out that several good reasons why the scheduler does not contain the actual timer:

*It may be important to be in synchronization with some external clock

*In some contexts the increment in the Time parameter need not be the same al the time

*In some contexts the Time does not relate to real time. (E.g. game steps, workflow steps., etc).

*In a GUI application it may be important that the timerTick's are invoked from a window event. I.e. to keep the application single threaded.

Using external timer ticks makes all this possible.

Let us use the timer in a console program, where the clock is provided by a simple for loop:

<vip>class predicates
traceJob : (integer Time).
clauses
traceJob(Time) :-
stdio::write("Now: ", Time, "\n").

clauses
test() :-
Scheduler = scheduler::new(),
Scheduler:registerJob(500, traceJob),
foreach Time = std::fromTo(1,1000) do
Scheduler:timerTick(Time)
end foreach.</vip>

The traceJob simply writes the clock. We create a scheduler and register the traceJob for running at Time = 500, and then we start the clock.

We can also make a job that reschedules itself and thus runs repeatedly. To do this the job must have access to the scheduler and therefore we save it in a fact:

<vip>class predicates
cyclicJob : (integer Time).
clauses
cyclicJob(Time) :-
stdio::write("Hello World!\n"),
scheduler:registerJob(Time+50, cyclicJob).

class facts
scheduler : scheduler := erroneous.
clauses
test() :-
scheduler := scheduler::new(),
scheduler:registerJob(5, cyclicJob),
foreach Time = std::fromTo(1,200) do
scheduler:timerTick(Time)
end foreach.</vip>

In the scheduler we have clearly used the (parametric) polymorphic priority queue. We have also used the (subsumption) polymorphism that comes from predicate values, such that we can register jobs with different implementation in the scheduler. The parametric polymorphism has exploited the homogeneous treatment of prioritizing things, no matter which kind of things we are dealing with. The subsumption polymorphism has been used to deal with the heterogeneous nature of jobs themselves.

[[ru:Объекты и полиморфизм. Ч.1]]

Language Reference/Classes

2017-07-10T09:18:32Z

SergeMukhin:

{{languageReferenceNavbar|Classes}}

A class declaration defines the appearance of the class to the surroundings: the surroundings can see and use exactly those entities mentioned in the class declaration. We say that the declaration of a class specifies the public part of the class.

A class declaration can contain constant and domain definitions and predicate declarations.

If the class states a construction type <vpbnf><ConstructionType></vpbnf>, then it constructs objects of that type. Object constructing classes have at least one constructor, but more can be declared. Classes that do not explicitly declare any constructors are automatically equipped with the default constructors (i.e. <vp>new/0</vp>).

Objects are constructed by invoking one of constructors of the class.

Constructors are also used when initializing inherited classes.

Everything mentioned in a class declaration belongs to the class, rather than to objects it constructs. Everything that relates to the objects must be declared in the construction type of the objects constructed by the class.

Any class declaration <vpbnf><ClassDeclaration></vpbnf> must have an accompanying class implementation {{lang|Implementations|<vpbnf><ClassImplementation></vpbnf>}}. The definition/implementation of predicates declared in the class declaration is provided by the class implementation. Likewise the definition of the predicates supported by the objects constructed by the class is provided by the class implementation. Both kinds of predicates can be implemented by clauses, but object predicates can also be inherited from other classes.

It is important to notice that a class declaration does not state anything about code inheritance. Code inheritance is a completely private matter that can only be stated in the class implementation. (This is unlike many other object oriented programming languages, and serves to hide all implementation details in the ''implementation).''

If the class does not state a construction type <vpbnf><ConstructionType></vpbnf>, then the class cannot manufacture any objects; it therefore plays the role of a module rather than a "real" class.

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

<vipbnf><ConstructionType> :
: <InterfaceName></vipbnf>

<vipbnf><ClassName> :
<LowerCaseIdentifier></vipbnf>

See also {{lang|Generic Interfaces and Classes|Generic Interfaces and Classes}} and {{lang|Monitors|Monitors}}.

The <vpbnf><ClassName></vpbnf> in the end of the class declaration must (if present) be identical to the one in the beginning of the class declaration.

Notice that you can use the same class name <vpbnf><ClassName></vpbnf> as the interface name <vpbnf><ConstructionType></vpbnf> specified as the construction type to this class. That is you can write:

<vip>class interfaceAndClassName : interfaceAndClassName</vip>

Notice that both the class and the interface can declare domains and constants and these must not conflict with each other since they end up in the same name space (because they can be qualified only with the same name of the interface or the class).

The <vpbnf><ScopeQualifications></vpbnf> must be of the kind {{lang2|Interfaces|Open_Qualification|<vpbnf><OpenQualification></vpbnf>}}.

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|Constructors_Sections|constructorsSection}}
*{{lang2|Properties|Properties_Sections|propertiesSection}}
*{{lang2|Directives|Conditional_Compilation|conditionalSection}}

{{lang2|Predicates|Constructors_Sections|constructorsSection}}s are only legal if the class states a <vpbnf><ConstructionType></vpbnf>.

All sections contained (transitively) in conditional sections must also be of those kinds.

Language Reference/Properties

2017-07-10T09:16:09Z

SergeMukhin: /* Properties from Interface */

{{languageReferenceNavbar|Properties}}

Properties are named values associated with classes and objects. Actually they are syntactic sugar for get/set predicates for the property value. And in that sense they are a language incarnation of a frequently used programming pattern.

=== Properties Sections ===

A properties section declares a set of object or class properties in the current scope.

<vipbnf><PropertiesSection> :
class-opt properties <PropertyDeclaration>-dot-term-list-opt</vipbnf>

The keyword <vp>class</vp> can be used only inside class implementations, since:
* properties declared in an interface are always object properties and
* properties declared in a class declaration are always class properties.

=== Property Declaration ===

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

<vipbnf><FlowPattern>: one of
(i)
(o)</vipbnf>

It is possible to get the value of a property that has the (o) flow, and it is possible to set the value of a property that has the (i) flow.
If the flow patterns are not stated, both (i) and (o) are assumed, so it is possible bot to set and get the value of such properties.

Though it is legal to state (i) and (o) simultaneously, it is considered better practice to omit them in the get+set case.

{{example|Assume we declare them with an i/o pattern as:
<vip>properties
durationO : real (o). % a get only property
durationI : real (i). % a set only property
durationIO : real (i) (o). % a "full" property, which can both be set and get.
duration : real. % equivalent to the declaration above and preferred.</vip>}}

In the sequel we will use the use the following example:

{{example|<vip>interface ip
properties
duration : real.
initialized : boolean (o).
scale : real.
end interface</vip>
<vp>duration</vp> and <vp>scale</vp> are get+set properties, and <vp>initialized</vp> is a get-only property.}}

Properties are used like fact variables. It is possible to qualify properties for with a scope name or an object.

{{example|<vp>X</vp> is an object that supports the interface <vp>ip</vp>

<vip>X:duration := 5,
if true = X:initialized then ... else ... end if,
X:scale := 2.56,
....</vip>

Inside an implementation of a class that supports <vp>ip</vp> you access the properties as if they were facts.

<vip>duration := 5,
if true = initialized then ... else ... end if,
scale := 2.56,
....</vip>}}

=== Implementation ===

A property is implemented by defining a function for getting the value and a predicate to set it.

{{example|
<vip>clauses
% implementation of the get function of the duration property
duration() = duration_fact.

clauses
% implementation of the set predicate of the duration property
duration(D) :-
duration_fact := D / scale.</vip>}}

Alternatively the property can be implemented as a fact variable with the same name as the property.

{{example|
<vip>facts
% the initialized property is implemented by a fact variable
initialized : boolean := false.
% the scale property is implemented by a fact variable
scale : real := 1.2</vip>}}

In this case the compiler will implicitly provide clauses that implement the get and set predicates.

{{example|For the two fact variable implementations above the compiler will provide clauses corresponding to this
<vip>
clauses
% implicit get clause for the initialized property
initialized() = initialized.

clauses
% implicit get clause for the scale property
scale() = scale.

clauses
% implicit set clause for the scale property
scale(V) :-
scale := V.
</vip>
As mentioned below it would not be legal to state these clauses in a program.}}

It is illegal to have set and get predicates and a fact with the same name, meaning that a property is either implemented by programmer provided clauses or by a fact; mixed implementation is not possible.

{{example|We want to send a '''changed''' event when the <vp>duration</vp> property changes value. Therefore we have to implement the property by predicates, and use a fact variable with an other name for storing the value.
<vip>properties
duration : integer.
facts
duration_fact : integer.
clauses
duration() = duration_fact.
clauses
duration(D) :-
OldDuration = duration_fact,
duration_fact := D,
OldDuration <> D,
!,
sendChanged().
duration(_D).</vip>
It is not possible to use the <vp>duration</vp> predicates as predicates (they are not declared as predicates, but as a property; it is just the way the get and set of the property are implemented).

But in the predicate names are "used" - so you cannot declare predicates <vp>duration\1</vp> or <vp>duration\0-></vp>.}}

As mentioned above properties are always implemented by get/set predicates even when the program implement them by a fact variable.

=== Properties from Interface ===

An interface can support a subset of another interface by stating the properties in a properties from section. The <vp>properties from</vp> section names the interface and all supported properties.

If an interface supports a subset of another interface it is neither subtype or super-type related to the other interface.

The important thing about the <vp>properties from</vp> section is that the mentioned properties retain their origin interface. Therefore:

*there will be no support conflict with any properties from the origin interface;
*they can be inherited as the properties from the origin interface.

<vipbnf><PropertiesFromInterface> :
properties from <InterfaceName> <PropertyName>-comma-sep-list-opt</vipbnf>

<vpbnf><PropertiesFromInterface></vpbnf> can only be used in interface definitions.

{{Example|
<vip>interface aaa
properties
pp : integer.
qq : boolean.
end interface aaa

interface bbb
properties from aaa
pp
properties
rr : string.
end interface bbb

interface ccc supports aaa, bbb
end interface ccc</vip>

Even though <vp>aaa</vp> and <vp>bbb</vp> both declare a property <vp>pp</vp>, <vp>ccc</vp> can support them both without any conflicts, because <vp>pp</vp> has <vp>aaa</vp> as an origin interface in all cases.
}}

{{Example|
<vip>interface aaa
properties
pp : integer.
qq : boolean.
end interface aaa

interface bbb
properties from aaa
pp
properties
rr : string.
end interface bbb

class aaa_class : aaa
end class aaa_class

class bbb_class : bbb
end class bbb_class

implement aaa_class inherits bbb_class
facts
pp_fact(): integer.
clauses
pp()= pp_fact-3.
clauses
pp(D):- pp_fact:=D+3.
end implement aaa_class</vip>

<vp>aaa_class</vp> can inherit <vp>pp</vp> from <vp>bbb_class</vp>, because <vp>pp</vp> in both classes has <vp>aaa</vp> as origin interface.
}}

Language Reference/Terms

2017-03-22T11:57:39Z

SergeMukhin: misspelling

{{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>:
<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

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

=== 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 pendand:

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

{{Template:NonReleased}}

<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 trh 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}}.

=== 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/Built-in entities/Predicates

2016-04-06T08:58:23Z

SergeMukhin: /* toBoolean */

<noinclude>__NOTOC__</noinclude>

{|{{prettytable}}
|-
|[[Language_Reference/Terms#and_.28.2C.29|and/2]] [[Language_Reference/Terms#and_.28.2C.29|,/2]]
|Term "and"
|-
|[[#assert|assert/1]]
|Insert the specified fact at the end of the matched internal facts database.
|-
|[[#asserta|asserta/1]]
|Insert a fact at the beginning of the matched internal facts database.
|-
|[[#assertz|assertz/1]]
|Insert a fact at the end of the matched internal facts database.
|-
|[[#bound|bound/1]] <vp>determ</vp>
|Test whether the specified variable is bound to a value.
|-
|[[#class_name|class_name/0->]]
|This compile time predicate returns the string ''ClassName'' that represents the name of the current interface or class.
|-
|[[#compare|compare/2->]]
|Returns the result of the variables' comparison.
|-
|[[#convert|convert/2->]]
|Checked term conversion.
|-
|[[#digitsOf|digitsOf/1->]]
|Returns precision of the specified floating-point domain.
|-
|[[#errorExit|errorExit/1]] <vp>erroneous</vp>
|Performs a run-time error with the specified return code ''ErrorNumber'' and sets the internal error information.
|-
|[[#fail|fail/0]] <vp>failure</vp>
|Invoke backtracking.
|-
|[[#free|free/1]] <vp>determ</vp>
|Check whether a variable is free.
|-
|[[#fromEllipsis|fromEllipsis/1->]]
|Creates the list of terms of the universal type <vp>any</vp> from the ''EllipsisBlock''.
|-
|[[#hasDomain|hasDomain/2]] [[#hasDomain|hasDomain/2->]]
|Declares/restricts the type of a variable or value.
|-
|[[Language_Reference/Terms#in|in/2]] <vp>determ</vp> [[Language_Reference/Terms#in|in/2]] <vp>nondeterm</vp>
|Infix operator "in" (in-test and in-iterator).
|-
|[[#isErroneous|isErroneous/1]] <vp>determ</vp>
|Returns the lower bound value of the specified numeric domain.
|-
|[[#lowerBound|lowerBound/1->]]
|Returns the lower bound value of the specified numeric domain.
|-
|[[#maxDigits|maxDigits/1->]]
|Retrieves the value of digits (precision) of the basic domain corresponding to the specified floating-point domain ''domainName''.
|-
|[[#not|not/1]] <vp>determ</vp>
|Negate the result (success/fail) of subgoal.
|-
|[[Language_Reference/Terms#or_.28.3B.29|or/2]] [[Language_Reference/Terms#and_.28.3B.29|;/2]]
|Nondeterministic term "or"
|-
|[[Language_Reference/Terms#orelse|orelse]]
|Deterministic term "or"
|-
|[[#predicate_fullname|predicate_fullname/1->]]
|This compile time predicate returns the string ''PredicateFullName'' that represent the name of the predicate in which clause body <vp>predicate_name</vp> is called. The returned predicate name is qualified with a scope name.
|-
|[[#predicate_name|predicate_name/1->]]
|This compile time predicate returns the string ''PredicateName'' that represent the name of the predicate in which clause body <vp>predicate_name</vp> is called. The returned predicate name is not qualified with a scope name.
|-
|[[#programPoint|programPoint/0->]]
|This compile time predicate returns the <vp>programPoint</vp> corresponding to the place where it is called.
|-
|[[#retract|retract/1]] <vp>nondeterm</vp>
|Remove a matched fact from the matched internal facts database.
|-
|[[#retractall|retractall/1]]
|Remove all matching facts from the matched internal facts database.
|-
|[[#retractFactDb|retractFactDb/1]]
|Remove all facts from the specified named internal facts database.
|-
|[[#sizeBitsOf|sizeBitsOf/1->]]
|Retrieves the number of bits occupied in memory by an entity of the specified domain ''DomainName''.
|-
|[[#sizeOf|sizeOf/1->]]
|Retrieves the number of bytes occupied in memory by the specified term.
|-
|[[#sizeOfDomain|sizeOfDomain/1->]]
|Retrieves the number of bytes occupied in memory by the entity of the specified domain ''DomainName''.
|-
|[[#sourcefile_lineno|sourcefile_lineno/0->]]
|Returns the current line number in the source file processed by the compiler .
|-
|[[#sourcefile_name|sourcefile_name/0->]]
|Returns the name of the source file processed by the compiler.
|-
|[[#sourcefile_timestamp|sourcefile_timestamp/0->]]
|Returns the string representing the date and time of the source file processed by the compiler.
|-
|[[#succeed|succeed/0]]
|The predicate <vp>succeed/0</vp> will always succeed.
|-
|[[#toAny|toAny/1->]]
|Converts the specified ''Term'' to the value of the universal term type <vp>any</vp>.
|-
|[[#toBinary|toBinary/1->]]
|Converts the specified Term to the binary representation.
|-
|[[#toBoolean|toBoolean/1->]]
|The purpose of this meta-predicate is to convert the deterministic call (to a predicate or fact) to the procedure that returns the value of <vp>boolean</vp> domain.
|-
|[[#toEllipsis|toEllipsis/1->]]
|Creates the ''EllipsisBlock'' from the list of <vp>any</vp> type values.
|-
|[[#toString|toString/1->]]
|Converts the specified ''Term'' to the string representation.
|-
|[[#toTerm|toTerm/1->]] [[#toTerm|toTerm/2->]]
|Converts the string/binary representation of the specified term ''SrcTerm'' into representation corresponding to the domain of ''PrologTerm'' variable of the return value.
|-
|[[#tryToTerm|tryToTerm/1->]] <vp>determ</vp> [[#tryToTerm|tryToTerm/2->]] <vp>determ</vp>
|Converts the string/binary representation of the specified term ''SrcTerm'' into representation corresponding to the domain of ''PrologTerm'' variable of the return value.
|-
|[[#tryConvert|tryConvert/2->]] <vp>determ</vp>
|Checks whether the input term ''InputTerm'' can be strictly converted into the specified domain ''returnDomain'' and returns the converted term ''ReturnTerm''.
|-
|[[#uncheckedConvert|uncheckedConvert/2->]]
|Unchecked conversion of domains.
|-
|[[#upperBound|upperBound/1->]]
|Returns the upper bound value of the specified numeric domain.
|}

The following predicates are deprecated:
{|{{prettytable}}
|-
| finally/2
| Use [[Language_Reference/Terms#try-finally| <vp>try-finally</vp>]] constuction instead.
|-
| findall/3
| Use list comprehension [[Language_Reference/Terms#List_Comprehension| <vp>[ ... || ... ]</vp>]] instead
|-
| trap/3 <vp>determ</vp>
| Use [[Language_Reference/Terms#try-catch| <vp>try-catch</vp>]] constuction instead.
|}

==== and ====

See [[Language_Reference/Terms#and_.28.2C.29|and (,)]].

==== assert ====

<vip>assert : (<fact-term> FactTerm).</vip>

Insert the specified fact at the end of the matched internal facts database

<vp>assert(Fact)</vp> inserts <vp>Fact</vp> in the matched internal facts database after any other stored facts for the corresponding database predicate. <vp>Fact</vp> must be a term belonging to the domain of an internal facts database. <vp>assert/1</vp> applied to a single fact changes the existing instance of a fact to the specified one. <vp>assert/1</vp> has the same effect as [[#assertz|assertz/1]]. See also [[#asserta|asserta/1]].

Notice that the combination of [[#retract|retract/1]] and <vp>assert/1</vp> like the following can lead to endless loop:

<vip>loop() :-
retract(fct(X)),
... % creating Y from X
assert(fct(Y)),
fail.</vip>

The problem is that the retract in first line will eventually retract the fact asserted in the last line, because that fact is inserted ''last'' in the fact chain.

Exceptions:

* Attempt to assert a second instance to a fact declared as determ.

==== asserta ====

<vip>asserta : (<fact-term> FactTerm).</vip>

Insert a fact at the beginning of the matched internal facts database.

The <vp>asserta(Fact)</vp> predicate inserts a <vp>Fact</vp> in the matched internal facts database before any other stored facts for the corresponding predicate. The <vp>Fact</vp> must be a term belonging to the domain of an internal facts database. The <vp>asserta/1</vp> applied to a single fact changes the existing instance of a fact to the specified one. See also [[#assert|assert/1]] and [[#assertz|assertz/1]].

Exceptions:

* Attempt to a fact declared as determ, but the fact instance already exists.

==== assertz ====

<vip>assertz : (<fact-term> FactTerm).</vip>

<vp>assertz</vp> does exactly the same as the [[#assert|assert/1]] predicate.

==== bound ====

<vip>bound : (<variable> Variable) determ.</vip>

Test whether the specified variable is bound to a value.

The <vp>bound(Variable)</vp> succeeds if <vp>Variable</vp> is bound and fails if it is free. The <vp>bound</vp> predicate is used to control flow patterns and to check the binding of reference variables. The <vp>bound</vp> predicate treats the specified <vp>Variable</vp> as bound if any of it's part is instantiated.

See also [[#free|free/1]].

==== class_name ====

<vip>class_Name : () -> string ClassName.</vip>

This compile time predicate returns the string <vp>ClassName</vp> that represents the name of the current interface or class.

==== compare ====

<vip>compare : (A Left, A Right) -> compareResult CompareResult.</vip>

Comparison of two terms of the same domain, resturns the value of [[#compareResult|compareResult]] domain.

<vp>CompareResult</vp> = compare("<vp>bar</vp>", "<vp>foo</vp>")

==== convert ====

<vip>convert : (<type> Type, Term) -> <type> Converted.</vip>

Checked term conversion.

Call-template for this function is:

<vp>ReturnTerm</vp> = convert(returnDomain, <vp>InputTerm</vp>)

* <vpbnf>returnDomain</vpbnf>: Specifies a domain to which function <vp>convert/2-></vp> converts <vp>InputTerm</vp>. Here ''returnDomain'' must be a name of built-in Visual Prolog domain, an interface domain, a name of such user defined domain that is synonym to one of built-in Visual Prolog domains, a numeric domain, binary and pointer domains. The domain name ''returnDomain'' must be specified at compile-time, i.e. it cannot come from a variable.

* <vpbnf><InputTerm></vpbnf>: Specifies the value that must be converted. <vp>InputTerm</vp> may be any Prolog term or an expression. If <vp>InputTerm</vp> is an expression, then it will be evaluated before the conversion.

* <vpbnf><ReturnTerm></vpbnf>: Returned parameter <vp>ReturnTerm</vp> will be of ''returnDomain'' type.

The <vp>convert</vp> predicate performs a clean and genuine conversion of the given <vp>InputTerm</vp>, returning a new term <vp>ReturnTerm</vp> of the specified new domain ''returnDomain''. If <vp>convert</vp> cannot perform the required conversion, it rises errors. The similar functionality is provided by the [[#tryConvert|tryConvert/2->]] predicate, but <vp>tryConvert-></vp> fails and does not produce any runtime errors if it cannot perform the conversion.

===== Allowed conversions =====

* Between numerical domains.
* Between interface types.
* Between [[#string|string]] and [[#symbol|symbol]] domains.
* From [[#binary|binary]] to [[#pointer|pointer]].
* For synonyms of mentioned domains.
* Between [http://wiki.visual-prolog.com/index.php?title=How_To_Remove_Reference_Domains_from_a_Project reference] domains and corresponding non-reference domains.

The contrast to these is [[#uncheckedConvert|uncheckedConvert/2->]] predicate, which performs an unchecked conversion between terms from any domains, which have the same bit-size.

The <vp>convert/2-></vp> (or [[#tryConvert|tryConvert/2->]]) predicate accomplishes a checked explicit conversion, when the source and target domains are statically known during the compilation. The result of an explicit conversion can be one of the following:

* '''ok''' the successful conversion to the target domain;
* '''run-time-check''' the conversion to the target domain with generation of run-time checking for compatibility;
* '''error''' the conversion is impossible, error output.

===== Rules of Checked Explicit Conversions =====

* Synonyms of domains are converted using the same rules that are applied to the domains themselves.
* Numerical domains can be converted to the numerical domains only.
* Integral constants are the representatives of the anonymous integral domain: <vp>[const .. const]</vp>.
* Real constants are the representatives of the anonymous real domain: <vp>digits</vp> <vp>dig [const .. const]</vp>, where <vp>dig</vp> is the number of the digits in mantissa without insignificant zeroes.
* A value of the symbol domain can be converted to the string domain and vice versa.
* A value of binary domain can be converted to the pointer domain.
* The domains that are implicitly introduced for interfaces can be converted only to the interface domains according to the rules specified below.
* All other domains cannot be converted.

===== Conversions of Numerical Domains =====

* The range is considered first during such conversion. If the ranges of source and target do not intersect, then an error is produced. If the ranges of source and target only partially intersect, then run-time checking is generated. Also, if one of domains is real and another is an integral one, then the integer range is converted to the real range before the comparison.
* When input term in real and output is integer, then <vp>convert/2-></vp> and [[#tryConvert|tryConvert/2->]] predicates truncate the input value to the nearest integer value, which is nearer to zero.

===== Conversions of Interface Types =====

Predicate <vp>convert/2-></vp> allow to convert any object to any interface type. The actual correctness of such conversion is checked at runtime. When object is created, its type is internally stored, therefore when the object is passed as argument it still remember about its original type. This original type is used for checking allowed conversions. The example:

<vip>interface x
supports a, b
end interface x</vip>

If object is created by class, which implements <vp>x</vp> interface, and then object is passed as parameter of type <vp>a</vp> to some predicate, then it is allowed to convert the object to <vp>b</vp> type.

Exceptions:

* Check range error.
* Unsupported interface type.

==== digitsOf ====

<vip>digitsOf : (<real-domain> Domain) -> unsigned.</vip>

Returns precision of the specified floating-point domain.

Call-template for this function is:

<vip>Precision = digitsof(domainName)</vip>

The input parameter ''domainName'' of this compiling-time predicate is a floating-point domain, it should be explicitly specified at compile-time (that is, ''domainName'' cannot come from a variable). The predicate returns the number <vpbnf><Precision></vpbnf> that was determined by the <vp>digits</vp> attribute in the domain declaration.

The compiler guarantees that values of the domain ''domainName'' will have at least <vpbnf><Precision></vpbnf> number of significant decimal digits.

==== errorExit ====

<vip>errorExit : (unsigned ErrorNumber) erroneous.</vip>

Performs a run-time error with the specified return code <vp>ErrorNumber</vp>, which can be used in the [[#try-catch-finally|try-catch-finally]].

==== fail ====

<vip>fail : () failure.</vip>

The <vp>fail</vp> predicate forces failure and, hence, always causes backtracking. A clause that fails (with <vp>fail</vp> or for some other reason) cannot bind output arguments.

==== free ====

<vip>free : (<variableName> Variable) determ.</vip>

Check whether a variable is free.

Call-template for this predicate is:

<vip>free(Variable)</vip>

The <vp>free</vp> predicate succeeds if the specified <vp>Variable</vp> is free and fails if <vp>Variable</vp> is bound. The <vp>free</vp> predicate treats the specified <vp>Variable</vp> as bound if any of it's part are instantiated.

See also [[#bound|bound/1]].

==== fromEllipsis ====

<vip>fromEllipsis : (...) -> any* AnyTermList.</vip>

This predicate creates the list of terms of the universal type <vp>any</vp> from the ''EllipsisBlock'' '''...''' (i.e. from the special varying parameters block).

Call-template for this function is:

<vip>AnyTermList = fromEllipsis(EllipsisBlock )</vip>

See also [[#toEllipsis|toEllipsis/1->]].

==== hasDomain ====

<vp>hasDomain</vp> is not really a predicate, but more a type declaration/restriction. It has two forms a non-function for declaring/restricting the type of a variable and a function form for declaring/restricting the type of a value.

The non-function form is called with a type as first parmeter and a variable as second parameter.

<vip>hasDomain : (<type> Type, Type Variable).</vip>

The only effect of the call is that the <vp>Variable</vp> will be restricted to the type <vp>Type</vp>.

The variable can be free, bound or of some mixed flow and the binding of the variable will not change in any way.

The function form is called with a type as first argument and a value as second argument, and it returns the same value.

<vip>hasDomain : (<type> Type, Type Value) -> Type Value.</vip>

The only effect of the call is to ensure that the <vp>Value</vp> will be restricted to the type <vp>Type</vp>.

==== lowerBound ====

<vip>lowerBound : (<numeric-domain> NumericDomain) -> <numeric-domain> LowerBound.</vip>

Returns the lower bound of the specified <vp>NumericDomain</vp>.

Call-template for this function is:

<vip>LowerBoundValue = lowerBound(domainName)</vip>

The <vp>lowerBound</vp> is a compiling-time predicate. The <vp>lowerBound</vp> returns the lower bound value <vp>LowerBoundValue</vp> of the specified numeric domain ''domainName''. The return value <vp>LowerBoundValue</vp> belongs to the same domain ''domainName''. The ''domainName'' parameter should be the name of any numerical domain; this domain name should be explicitly specified at compile-time (that is, ''domainName'' cannot come from a variable). See also [[#upperBound|upperBound/1->]].

It will give a compile time error if the specified domain ''domainName'' is not numeric domain.

==== in ====

See [[Language_Reference/Terms#in|in/2]].

==== isErroneous ====

<vip>isErroneous : (<fact-variable> FactVariable) determ.</vip>

The predicate succeeds if the specified fact variable is <vp>erroneous</vp>.

Call-template for this predicate is:

<vip>isErroneous(factVariableName)</vip>

The predicate succeeds if the specified fact variable <vp>factVariableName</vp> has the <vp>erroneous</vp> value, otherwise it fails.

==== maxDigits ====

<vip>maxDigits : (<real-domain> RealDomain) -> unsigned MaxDigits</vip>

Retrieves the value of digits (precision) of the basic domain corresponding to the specified floating-point domain <vp>RealDomain</vp>.

Call-template for this function is:

<vip>MaxDigitsNumber = maxdigits(domainName)</vip>

The return maximal number of digits <vp>MaxDigitsNumber</vp> for the ''domainName'' parameter, which should be the name of a <vp>real</vp> domain.

==== not ====

See [[Language_Reference/Terms#not|not]].

==== or ====

See [[Language_Reference/Terms#or_.28.3B.29|or (;)]].

==== orelse ====

See [[Language_Reference/Terms#orelse|orelse]].

==== predicate_fullname ====

<vip>predicate_fullname : () -> string PredicateFullName.</vip>

This predicate returns the name <vp>PredicateFullName</vp> of the predicate in which it is invoked. The returned predicate name is qualified with a scope name.

<vp>predicate_fullname</vp> can only be used inside a clause. Use of <vp>predicate_fullname</vp> in other places causes a compile time error. See also [[#predicate_name|predicate_name]].

==== predicate_name ====

<vip>predicate_name : () -> string PredicateName.</vip>

This predicate returns the name <vp>PredicateName</vp> of the predicate in which it is invoked.

<vp>predicate_name</vp> can only be used inside a clause. Use of <vp>predicate_name</vp> in other places causes a compile time error. See also [[#predicate_fullname|predicate_fullname]]

==== programPoint ====

<vip>programPoint : () -> core::programPoint ProgramPoint.</vip>

This predicate returns the name <vp>programPoint</vp> corresponding to the place where it is invoked.

==== retract ====

<vip>retract : (<fact-term> FactTerm) nondeterm anyflow.</vip>

Successively removes the first matching fact from the facts database. Fails when no more facts match.

Call-template for this predicate is:

<vip>retract(FactTemplate)</vip>

Here <vp>FactTemplate</vp> should be a fact term. The <vp>retract/1</vp> predicate deletes the first fact that matches the <vp>FactTemplate</vp> in the appropriated facts database. During backtracking, the rest of the matching facts will be deleted.

Notice that <vp>FactTemplate</vp> can have any level of instantiation. The <vp>FactTemplate</vp> is matched with the facts in the facts database, which means that any free variables will be bound in the call to <vp>retract/1</vp>.

The <vp>FactTemplate</vp> can contain any anonymous variables. That is, variables with names consisting from the single underscore <vp>_</vp> or a variable with a name starting with an underscore <vp>_AnyValue</vp> if the variable occurs only once in the clause. For example.

<vip>retract(person("Hans", _Age)),</vip>

will retract the first matched person fact that has "<vp>Hans</vp>" as the first argument and anything as the second argument.

When retracting a fact, which is declared to be determ, the call to <vp>retract/1</vp> will be deterministic.

See also [[#retractall|retractall/1]] and [[#retractFactDb|retractFactDb]].

The <vp>retract/1</vp> predicate cannot be applied to single facts or fact variables.

Be careful calling <vp>retract/1</vp> with free <vp>FactTemplate</vp> variable if any single fact is declared in the project current scope. If you retract a single fact, then the run-time error is generated. The <vp>retract/1</vp> predicate fails when there are no more matches.

==== retractall ====

<vip>retractall : (<fact-term> FactTerm) .</vip>

Remove all matching facts from the facts database.

Call-template for this predicate is:

<vip>retractall(FactTemplate)</vip>

Here <vp>FactTemplate</vp> should be a fact term.

The <vp>retractall/1</vp> retracts all facts which match the given ''FactTemplate''. It always succeeds, even if no facts were retracted.

Attempting to retract a <vp>single</vp> fact will cause a compile time error.

It is not possible to obtain any output values from <vp>retractall/1</vp>. For this reason, the variables in the call must be bound or be a single underscores (anonymous). Notice that <vp>FactTemplate</vp> can have any level of instantiation, but free variables must be single underscores ("unconditionally anonymous"). In difference to [[#retract|retract/1]] "conditionally" anonymous variables with names starting from the underscore (like <vp>_AnyValue</vp>) cannot be used in <vp>retractall/1</vp>.

See also [[#retract|retract/1]] and [[#retractFactDb|retractFactDb/1]].

==== retractFactDb ====

<vip>retractFactDb : (factDB FactDB).</vip>

Remove all facts from the named internal facts database <vp>FactDB</vp>.

Call-template for this predicate is:

<vip>retractFactDb(FactDB)</vip>

The <vp>retractFactDb/1</vp> removes all facts from the named facts database <vp>FactDB</vp>.

Notice, it is impossible to retract <vp>single</vp> facts and fact variables, so the predicate leaves such ones as they are.

See also [[#retractall|retractall/1]] and [[#retract|retract/1]].

==== retractAll/2 ====

Obsolete predicate! Use [[#retractFactDb|retractFactDb/1]] instead.

==== sizeBitsOf ====

<vip>sizeBitsOf : (<domain> DomainName) -> unsigned BitSize.</vip>

Retrieves the number of bits occupied in memory by an entity of the specified domain <vp>DomainName</vp>.

Call-template for this function is:

<vip>BitSize = sizeBitsOf(DomainName)</vip>

This compiling-time predicate receives the domain <vp>DomainName</vp> as input parameter and return the size of memory that is occupied by the entity of the given domain. The result is measured in bits. For the integer domains <vp>sizeBitsOf/1-></vp> predicate returns the value that was defined for the size-field in a domain's declaration.

The following is always true for the integral domains:

<vip>sizeOfDomain(domain)*8 - 7 <= sizeBitsOf(domain) <= sizeOfDomain(domain)*8</vip>

See also [[#sizeOfDomain|sizeOfDomain]]/1->.

==== sizeOf ====

<vip>sizeOf : (Type Term) -> integer ByteSize.</vip>

Retrieves the number of bytes occupied in memory by the specified term <vp>Term</vp>.

Call-template for this function is:

<vip>ByteSize = sizeOf(Term)</vip>

The <vp>sizeOf/1-></vp> function receives a term as input parameter and returns value <vp>ByteSize</vp> that specifies the number of bytes occupied in memory by this term <vp>Term</vp>.

==== sizeOfDomain ====

<vip>sizeOfDomain : (<domain> Domain) -> integer ByteSize.</vip>

Retrieves the number of bytes occupied in memory by the entity of the specified domain <vp>DomainName</vp>.

Call-template for this function is:

<vip>ByteSize = sizeOfDomain(DomainName)</vip>

This compiling-time predicate receives the domain <vp>DomainName</vp> as input parameter and return the size of memory that is occupied by the entity of the given domain. The result is measured in bytes. The returned value <vp>ByteSize</vp> belongs to the integer domain. Compare with [[#sizeBitsOf|sizeBitsOf/1->]], which returns size of a domain measured in bits.

==== sourcefile_lineno ====

<vip>sourcefile_lineno : () -> unsigned LineNumber.</vip>

Returns the current line number in the source file processed by the compiler.

==== sourcefile_name ====

<vip>sourcefile_name : () -> string FileName.</vip>

Returns the name of the source file processed by the compiler.

==== sourcefile_timestamp ====

<vip>sourcefile_timestamp : () -> string TimeStamp..</vip>

Returns a string that represents the date and time of the currently compiled source file in format YYYY-MM-DD HH:mm:ss. Where:

* YYYY - Year.
* MM - Month.
* DD - Day.
* HH - Hour.
* mm - Minute.
* ss - Second.

==== succeed ====

<vip>succeed : ().</vip>

The predicate <vp>succeed/0</vp> will always succeed.

==== toAny ====

<vip>toAny : (Term) -> any UniversalTypeValue.</vip>

Converts the specified <vp>Term</vp> to the value of universal term type <vp>any</vp>.

Call-template for this function is:

<vip>UniversalTypeValue = toAny(Term)</vip>

A term of the <vp>any</vp> domain can be converted back to its original type using the <vp>toTerm</vp> predicates (see {{lang2|Built-in entities/Predicates|toTerm|toTerm}}).

==== toBinary ====

<vip>toBinary : (Term) -> binary Serialized.</vip>

Converts the specified <vp>Term</vp> to [[#binary|binary]] representation.

Call-template for this function is:

<vip>Serialized = toBinary(Term)</vip>

When a <vp>Term</vp> (of some domain ''domainName'') is converted into a binary, it can safely be stored in a file or sent over a network to another program. Later the obtained binary value <vp>Serialized</vp> can be converted back to a Visual Prolog term, using [[#toTerm|toTerm/1->]] function (the domain for the reversed term should be adequate to ''domainName'') for the reverse conversion.

==== toBoolean ====

<vip>toBoolean : (<deterministic_expression> SubGoal) -> boolean Succeed.</vip>

The purpose of this meta-predicate is to convert an expression to the value of boolean domain.

Call-template for this meta-predicate is:

<vip>True_or_False = toBoolean(deterministic_expression)</vip>

this is equivalent to

<vip>True_or_False = if deterministic_expression then true else false end if</vip>

The <vp>toBoolean/1-></vp> meta-predicate returns [[#boolean|boolean]] value. The result is <vp>true</vp> if ''deterministic_call'' succeeds. The result is <vp>false</vp> if ''deterministic_call'' fails.

==== toEllipsis ====

<vip>toEllipsis : (any* AnyTermList) -> ....</vip>

This predicate creates ''EllipsisBlock'' '''...''' (i.e. the special varying parameters block) from the list of terms of the universal type <vp>any</vp>. Such ''EllipsisBlock'' can be later passed to a predicate which expects the varying number of arguments (i.e. is declared with the ellipsis (''...'')), like <vp>write/...</vp>, at the position of the ellipsis (''...'').

Call-template for this function is:

<vip>EllipsisBlock = toEllipsis(<any_term_list>), write(EllipsisBlock)</vip>

See also [[#fromEllipsis|fromEllipsis/1->]].

==== toString ====

<vip>toString : (Term) -> string Serialized.</vip>

Converts the specified <vp>Term</vp> to string representation.

Call-template for this function is:

<vip>Serialized = toString(Term)</vip>

When a <vp>Term</vp> (of some domain ''domainName'') is converted into a string, it can safely be stored in a file or sent over a network to another program. Later the obtained string value can be converted back to a Visual Prolog term, using [[#toTerm|toTerm/1->]] function (the domain of the return value should be adequate to ''domainName'') for the reverse conversion.

==== toTerm ====

<vip>toTerm : (string Serialized) -> Term.
toTerm : (binary Serialized) -> Term.
toTerm : (any Serialized) -> Term.
toTerm : (<domain> Type, string Serialized) -> Term.
toTerm : (<domain> Type, binary Serialized) -> Term.
toTerm : (<domain> Type, any Serialized) -> Term.</vip>

Converts the string/binary/any representation of the specified term <vp>Serialized</vp> into representation corresponding to the domain of <vp>Term</vp> variable of the return value. The domain can be stated explicitly or it can be left to the compiler to determine a suitable domain.

Call-template for this function is:

<vip>Term = toTerm(Serialized) % with implicit domain
Term = toTerm(domainName, Serialized) % with explicit domain, domainName</vip>

If the domain is not specified the compiler must be able to determine the domain for the returned value <vp>Term</vp> at compile-time. Notice that binary version of <vp>toTerm</vp> predicate performs almost byte to byte conversion and only checking general compatibility of <vp>Serialized</vp> data with the domain required to the return value <vp>Term</vp>. The programmer is wholly responsible for providing binary data of <vp>Serialized</vp> that can be correctly converted to the term of the desired domain. The <vp>toTerm</vp> predicates are counterparts to predicates [[#toBinary|toBinary/1->]] and [[#toString|toString/1->]]. When a ''Term'' (of some domain ''domainName'') is converted into a binary or string representation <vp>Serialized</vp> (by [[#toBinary|toBinary/1->]] or [[#toString|toString/1->]] or [[#toAny|toAny/1->]] correspondingly), it can safely be stored in a file or sent over a network to another program. Later the corresponding <vp>toTerm/1</vp>-> function can convert the obtained string/binary value <vp>Serialized</vp> back to a Visual Prolog term <vp>Term</vp>. For correctness of the reverse conversion the domain of the clause variable <vp>Term</vp> should be adequate to the initial domain ''domainName''.

See also [[#tryToTerm|tryToTerm]].

It gives a compile time error if the compiler cannot determine the return domain.

Exceptions

* Run time errors are generated when the <vp>toTerm</vp> predicate cannot convert the string or binary into a term of the specified domain.

==== tryToTerm ====

<vip>tryToTerm : (string Serialized) -> Term.
tryToTerm : (binary Serialized) -> Term.
tryToTerm : (any Serialized) -> Term.
tryToTerm : (<domain> Type, string Serialized) -> Term.
tryToTerm : (<domain> Type, binary Serialized) -> Term.
tryToTerm : (<domain> Type, any Serialized) -> Term.</vip>

Converts the string/binary/any representation <vp>Serialized</vp> into a term <vp>Term</vp> like [[#toTerm|toTerm]]. The only difference between the predicates is that <vp>tryToTerm</vp> fails if it cannot convert the string or binary or any into a term of the specified domain whereas toTerm raises an exception.

See also [[#toTerm|toTerm]].

==== tryConvert ====

<vip>tryConvert : (<type> Type, Value) -> <type> Converted determ.</vip>

Checks whether the input term <vp>Value</vp> can be strictly converted into the specified domain <vp>Type</vp> and returns the converted term <vp>Converted</vp>.

Call-template for this function is:

<vip>ReturnTerm = tryConvert(returnDomain, InputTerm)</vip>

Arguments:

* <vp>returnDomain</vp>: Specifies a domain to which <vp>tryConvert/2-></vp> predicate tries to convert the specified <vp>InputTerm</vp>. Here ''returnDomain'' can be any domain accessible in the current scope. The domain name ''returnDomain'' must be specified at compile-time, i.e. it cannot come from a variable.
* <vpbnf><InputTerm></vpbnf>: Specifies the term that must be converted. <vp>InputTerm</vp> may be any Prolog term or an expression. If <vp>InputTerm</vp> is an expression, then it will be evaluated before conversion.
* <vpbnf><ReturnTerm></vpbnf>: Returned term <vp>ReturnTerm</vp> will be of ''returnDomain'' domain.

The conversion rules are the same as of the embedded predicate [[#convert|convert/2->]], but <vp>tryConvert/2-></vp> fails when [[#convert|convert/2->]] generates conversion errors.

This predicate succeeds if the corresponding conversion succeeds. Otherwise it fails. The <vp>tryConvert/2-></vp> predicate tries to perform a clean and genuine conversion of the given <vp>InputTerm</vp> into a value of the specified domain ''returnDomain''. The <vp>tryConvert/2-></vp> predicate will fail if the required conversion cannot be performed. When <vp>tryConvert/2-></vp> predicate succeeds, it returns the term <vp>ReturnTerm</vp> converted to the specified domain ''returnDomain''.

For allowed conversions and rules of checked explicit conversions see [[#convert|convert/2->]] predicate.

See also [[#uncheckedConvert|uncheckedConvert/2->]].

==== uncheckedConvert ====

<vip>uncheckedConvert : (<type> Type, Value) -> <type> Converted.</vip>

Unchecked conversion of a value to another type.

Call-template for this function is:

<vip>ReturnTerm = uncheckedConvert(returnDomain, InputTerm)</vip>

Arguments:

* <vp>returnDomain</vp>: Specifies a domain to which <vp>uncheckedConvert</vp> predicate unsafely converts the specified <vp>InputTerm</vp>. Here ''returnDomain'' can be any domain accessible in the current scope, the <vp>ReturnTerm</vp> should has the same bit-size as the <vp>InputTerm</vp>. The domain name ''returnDomain'' must be specified at compile-time, i.e. it cannot come from a variable.
* <vpbnf><InputTerm></vpbnf>: Specifies the value that must be converted. <vp>InputTerm</vp> may be any Prolog term or an expression. If ''InputTerm'' is an expression, then it will be evaluated before conversion.
* <vpbnf><ReturnTerm></vpbnf>: Returned parameter <vp>ReturnTerm</vp> will be of ''returnDomain'' type.

<vp>uncheckedConvert</vp> evaluates <vp>InputTerm</vp>, change the type to ''returnDomain'' without any modification of the memory pattern and unifies with <vp>ReturnTerm</vp>. The <vp>uncheckedConvert</vp> predicate performs no runtime checks. It makes only compile time checking of bit-size equality of the converted domains. So almost any term may be quite recklessly converted to any other term. So quite disastrous results may occur if you try to use variables incorrectly converted by <vp>uncheckedConvert</vp>. Be extremely careful implementing <vp>uncheckedConvert</vp>; we strongly recommend you always, when it is possible, using of [[#convert|convert/2->]] and [[#tryConvert|tryConvert/2->]]. But notice that, when an object is returned by COM system it is necessary to convert it by <vp>uncheckedConvert</vp>, as Prolog program does not have information about its actual type.

==== upperBound ====

<vip>upperBound : (<numeric-domain> NumericDomain) -> <number-domain> UpperBound.</vip>

Returns the upper bound value of the specified numeric domain.

Call-template for this function is:

<vip>UpperBound = upperBound(domainName)</vip>

The <vp>upperBound</vp> is a compiling-time predicate. The <vp>upperBound</vp> returns the upper bound value of the specified numeric domain ''domainName''. The return value <vp>UpperBound</vp> belongs to the same domain ''domainName''. The ''domainName'' parameter should be the name of any numerical domain; this domain name should be explicitly specified at compile-time (that is, ''domainName'' cannot come from a variable).

See also [[#lowerBound|lowerBound/1->]].

Will cause a compile time error if the specified domain ''domainName'' is not numeric domain.
<noinclude>{{LanguageReferenceSubarticle|Built-in entities/Predicates}}</noinclude>

Language Reference/Built-in entities/Predicates

2016-04-06T08:47:20Z

SergeMukhin: /* sourcefile_timestamp */

<noinclude>__NOTOC__</noinclude>

{|{{prettytable}}
|-
|[[Language_Reference/Terms#and_.28.2C.29|and/2]] [[Language_Reference/Terms#and_.28.2C.29|,/2]]
|Term "and"
|-
|[[#assert|assert/1]]
|Insert the specified fact at the end of the matched internal facts database.
|-
|[[#asserta|asserta/1]]
|Insert a fact at the beginning of the matched internal facts database.
|-
|[[#assertz|assertz/1]]
|Insert a fact at the end of the matched internal facts database.
|-
|[[#bound|bound/1]] <vp>determ</vp>
|Test whether the specified variable is bound to a value.
|-
|[[#class_name|class_name/0->]]
|This compile time predicate returns the string ''ClassName'' that represents the name of the current interface or class.
|-
|[[#compare|compare/2->]]
|Returns the result of the variables' comparison.
|-
|[[#convert|convert/2->]]
|Checked term conversion.
|-
|[[#digitsOf|digitsOf/1->]]
|Returns precision of the specified floating-point domain.
|-
|[[#errorExit|errorExit/1]] <vp>erroneous</vp>
|Performs a run-time error with the specified return code ''ErrorNumber'' and sets the internal error information.
|-
|[[#fail|fail/0]] <vp>failure</vp>
|Invoke backtracking.
|-
|[[#free|free/1]] <vp>determ</vp>
|Check whether a variable is free.
|-
|[[#fromEllipsis|fromEllipsis/1->]]
|Creates the list of terms of the universal type <vp>any</vp> from the ''EllipsisBlock''.
|-
|[[#hasDomain|hasDomain/2]] [[#hasDomain|hasDomain/2->]]
|Declares/restricts the type of a variable or value.
|-
|[[Language_Reference/Terms#in|in/2]] <vp>determ</vp> [[Language_Reference/Terms#in|in/2]] <vp>nondeterm</vp>
|Infix operator "in" (in-test and in-iterator).
|-
|[[#isErroneous|isErroneous/1]] <vp>determ</vp>
|Returns the lower bound value of the specified numeric domain.
|-
|[[#lowerBound|lowerBound/1->]]
|Returns the lower bound value of the specified numeric domain.
|-
|[[#maxDigits|maxDigits/1->]]
|Retrieves the value of digits (precision) of the basic domain corresponding to the specified floating-point domain ''domainName''.
|-
|[[#not|not/1]] <vp>determ</vp>
|Negate the result (success/fail) of subgoal.
|-
|[[Language_Reference/Terms#or_.28.3B.29|or/2]] [[Language_Reference/Terms#and_.28.3B.29|;/2]]
|Nondeterministic term "or"
|-
|[[Language_Reference/Terms#orelse|orelse]]
|Deterministic term "or"
|-
|[[#predicate_fullname|predicate_fullname/1->]]
|This compile time predicate returns the string ''PredicateFullName'' that represent the name of the predicate in which clause body <vp>predicate_name</vp> is called. The returned predicate name is qualified with a scope name.
|-
|[[#predicate_name|predicate_name/1->]]
|This compile time predicate returns the string ''PredicateName'' that represent the name of the predicate in which clause body <vp>predicate_name</vp> is called. The returned predicate name is not qualified with a scope name.
|-
|[[#programPoint|programPoint/0->]]
|This compile time predicate returns the <vp>programPoint</vp> corresponding to the place where it is called.
|-
|[[#retract|retract/1]] <vp>nondeterm</vp>
|Remove a matched fact from the matched internal facts database.
|-
|[[#retractall|retractall/1]]
|Remove all matching facts from the matched internal facts database.
|-
|[[#retractFactDb|retractFactDb/1]]
|Remove all facts from the specified named internal facts database.
|-
|[[#sizeBitsOf|sizeBitsOf/1->]]
|Retrieves the number of bits occupied in memory by an entity of the specified domain ''DomainName''.
|-
|[[#sizeOf|sizeOf/1->]]
|Retrieves the number of bytes occupied in memory by the specified term.
|-
|[[#sizeOfDomain|sizeOfDomain/1->]]
|Retrieves the number of bytes occupied in memory by the entity of the specified domain ''DomainName''.
|-
|[[#sourcefile_lineno|sourcefile_lineno/0->]]
|Returns the current line number in the source file processed by the compiler .
|-
|[[#sourcefile_name|sourcefile_name/0->]]
|Returns the name of the source file processed by the compiler.
|-
|[[#sourcefile_timestamp|sourcefile_timestamp/0->]]
|Returns the string representing the date and time of the source file processed by the compiler.
|-
|[[#succeed|succeed/0]]
|The predicate <vp>succeed/0</vp> will always succeed.
|-
|[[#toAny|toAny/1->]]
|Converts the specified ''Term'' to the value of the universal term type <vp>any</vp>.
|-
|[[#toBinary|toBinary/1->]]
|Converts the specified Term to the binary representation.
|-
|[[#toBoolean|toBoolean/1->]]
|The purpose of this meta-predicate is to convert the deterministic call (to a predicate or fact) to the procedure that returns the value of <vp>boolean</vp> domain.
|-
|[[#toEllipsis|toEllipsis/1->]]
|Creates the ''EllipsisBlock'' from the list of <vp>any</vp> type values.
|-
|[[#toString|toString/1->]]
|Converts the specified ''Term'' to the string representation.
|-
|[[#toTerm|toTerm/1->]] [[#toTerm|toTerm/2->]]
|Converts the string/binary representation of the specified term ''SrcTerm'' into representation corresponding to the domain of ''PrologTerm'' variable of the return value.
|-
|[[#tryToTerm|tryToTerm/1->]] <vp>determ</vp> [[#tryToTerm|tryToTerm/2->]] <vp>determ</vp>
|Converts the string/binary representation of the specified term ''SrcTerm'' into representation corresponding to the domain of ''PrologTerm'' variable of the return value.
|-
|[[#tryConvert|tryConvert/2->]] <vp>determ</vp>
|Checks whether the input term ''InputTerm'' can be strictly converted into the specified domain ''returnDomain'' and returns the converted term ''ReturnTerm''.
|-
|[[#uncheckedConvert|uncheckedConvert/2->]]
|Unchecked conversion of domains.
|-
|[[#upperBound|upperBound/1->]]
|Returns the upper bound value of the specified numeric domain.
|}

The following predicates are deprecated:
{|{{prettytable}}
|-
| finally/2
| Use [[Language_Reference/Terms#try-finally| <vp>try-finally</vp>]] constuction instead.
|-
| findall/3
| Use list comprehension [[Language_Reference/Terms#List_Comprehension| <vp>[ ... || ... ]</vp>]] instead
|-
| trap/3 <vp>determ</vp>
| Use [[Language_Reference/Terms#try-catch| <vp>try-catch</vp>]] constuction instead.
|}

==== and ====

See [[Language_Reference/Terms#and_.28.2C.29|and (,)]].

==== assert ====

<vip>assert : (<fact-term> FactTerm).</vip>

Insert the specified fact at the end of the matched internal facts database

<vp>assert(Fact)</vp> inserts <vp>Fact</vp> in the matched internal facts database after any other stored facts for the corresponding database predicate. <vp>Fact</vp> must be a term belonging to the domain of an internal facts database. <vp>assert/1</vp> applied to a single fact changes the existing instance of a fact to the specified one. <vp>assert/1</vp> has the same effect as [[#assertz|assertz/1]]. See also [[#asserta|asserta/1]].

Notice that the combination of [[#retract|retract/1]] and <vp>assert/1</vp> like the following can lead to endless loop:

<vip>loop() :-
retract(fct(X)),
... % creating Y from X
assert(fct(Y)),
fail.</vip>

The problem is that the retract in first line will eventually retract the fact asserted in the last line, because that fact is inserted ''last'' in the fact chain.

Exceptions:

* Attempt to assert a second instance to a fact declared as determ.

==== asserta ====

<vip>asserta : (<fact-term> FactTerm).</vip>

Insert a fact at the beginning of the matched internal facts database.

The <vp>asserta(Fact)</vp> predicate inserts a <vp>Fact</vp> in the matched internal facts database before any other stored facts for the corresponding predicate. The <vp>Fact</vp> must be a term belonging to the domain of an internal facts database. The <vp>asserta/1</vp> applied to a single fact changes the existing instance of a fact to the specified one. See also [[#assert|assert/1]] and [[#assertz|assertz/1]].

Exceptions:

* Attempt to a fact declared as determ, but the fact instance already exists.

==== assertz ====

<vip>assertz : (<fact-term> FactTerm).</vip>

<vp>assertz</vp> does exactly the same as the [[#assert|assert/1]] predicate.

==== bound ====

<vip>bound : (<variable> Variable) determ.</vip>

Test whether the specified variable is bound to a value.

The <vp>bound(Variable)</vp> succeeds if <vp>Variable</vp> is bound and fails if it is free. The <vp>bound</vp> predicate is used to control flow patterns and to check the binding of reference variables. The <vp>bound</vp> predicate treats the specified <vp>Variable</vp> as bound if any of it's part is instantiated.

See also [[#free|free/1]].

==== class_name ====

<vip>class_Name : () -> string ClassName.</vip>

This compile time predicate returns the string <vp>ClassName</vp> that represents the name of the current interface or class.

==== compare ====

<vip>compare : (A Left, A Right) -> compareResult CompareResult.</vip>

Comparison of two terms of the same domain, resturns the value of [[#compareResult|compareResult]] domain.

<vp>CompareResult</vp> = compare("<vp>bar</vp>", "<vp>foo</vp>")

==== convert ====

<vip>convert : (<type> Type, Term) -> <type> Converted.</vip>

Checked term conversion.

Call-template for this function is:

<vp>ReturnTerm</vp> = convert(returnDomain, <vp>InputTerm</vp>)

* <vpbnf>returnDomain</vpbnf>: Specifies a domain to which function <vp>convert/2-></vp> converts <vp>InputTerm</vp>. Here ''returnDomain'' must be a name of built-in Visual Prolog domain, an interface domain, a name of such user defined domain that is synonym to one of built-in Visual Prolog domains, a numeric domain, binary and pointer domains. The domain name ''returnDomain'' must be specified at compile-time, i.e. it cannot come from a variable.

* <vpbnf><InputTerm></vpbnf>: Specifies the value that must be converted. <vp>InputTerm</vp> may be any Prolog term or an expression. If <vp>InputTerm</vp> is an expression, then it will be evaluated before the conversion.

* <vpbnf><ReturnTerm></vpbnf>: Returned parameter <vp>ReturnTerm</vp> will be of ''returnDomain'' type.

The <vp>convert</vp> predicate performs a clean and genuine conversion of the given <vp>InputTerm</vp>, returning a new term <vp>ReturnTerm</vp> of the specified new domain ''returnDomain''. If <vp>convert</vp> cannot perform the required conversion, it rises errors. The similar functionality is provided by the [[#tryConvert|tryConvert/2->]] predicate, but <vp>tryConvert-></vp> fails and does not produce any runtime errors if it cannot perform the conversion.

===== Allowed conversions =====

* Between numerical domains.
* Between interface types.
* Between [[#string|string]] and [[#symbol|symbol]] domains.
* From [[#binary|binary]] to [[#pointer|pointer]].
* For synonyms of mentioned domains.
* Between [http://wiki.visual-prolog.com/index.php?title=How_To_Remove_Reference_Domains_from_a_Project reference] domains and corresponding non-reference domains.

The contrast to these is [[#uncheckedConvert|uncheckedConvert/2->]] predicate, which performs an unchecked conversion between terms from any domains, which have the same bit-size.

The <vp>convert/2-></vp> (or [[#tryConvert|tryConvert/2->]]) predicate accomplishes a checked explicit conversion, when the source and target domains are statically known during the compilation. The result of an explicit conversion can be one of the following:

* '''ok''' the successful conversion to the target domain;
* '''run-time-check''' the conversion to the target domain with generation of run-time checking for compatibility;
* '''error''' the conversion is impossible, error output.

===== Rules of Checked Explicit Conversions =====

* Synonyms of domains are converted using the same rules that are applied to the domains themselves.
* Numerical domains can be converted to the numerical domains only.
* Integral constants are the representatives of the anonymous integral domain: <vp>[const .. const]</vp>.
* Real constants are the representatives of the anonymous real domain: <vp>digits</vp> <vp>dig [const .. const]</vp>, where <vp>dig</vp> is the number of the digits in mantissa without insignificant zeroes.
* A value of the symbol domain can be converted to the string domain and vice versa.
* A value of binary domain can be converted to the pointer domain.
* The domains that are implicitly introduced for interfaces can be converted only to the interface domains according to the rules specified below.
* All other domains cannot be converted.

===== Conversions of Numerical Domains =====

* The range is considered first during such conversion. If the ranges of source and target do not intersect, then an error is produced. If the ranges of source and target only partially intersect, then run-time checking is generated. Also, if one of domains is real and another is an integral one, then the integer range is converted to the real range before the comparison.
* When input term in real and output is integer, then <vp>convert/2-></vp> and [[#tryConvert|tryConvert/2->]] predicates truncate the input value to the nearest integer value, which is nearer to zero.

===== Conversions of Interface Types =====

Predicate <vp>convert/2-></vp> allow to convert any object to any interface type. The actual correctness of such conversion is checked at runtime. When object is created, its type is internally stored, therefore when the object is passed as argument it still remember about its original type. This original type is used for checking allowed conversions. The example:

<vip>interface x
supports a, b
end interface x</vip>

If object is created by class, which implements <vp>x</vp> interface, and then object is passed as parameter of type <vp>a</vp> to some predicate, then it is allowed to convert the object to <vp>b</vp> type.

Exceptions:

* Check range error.
* Unsupported interface type.

==== digitsOf ====

<vip>digitsOf : (<real-domain> Domain) -> unsigned.</vip>

Returns precision of the specified floating-point domain.

Call-template for this function is:

<vip>Precision = digitsof(domainName)</vip>

The input parameter ''domainName'' of this compiling-time predicate is a floating-point domain, it should be explicitly specified at compile-time (that is, ''domainName'' cannot come from a variable). The predicate returns the number <vpbnf><Precision></vpbnf> that was determined by the <vp>digits</vp> attribute in the domain declaration.

The compiler guarantees that values of the domain ''domainName'' will have at least <vpbnf><Precision></vpbnf> number of significant decimal digits.

==== errorExit ====

<vip>errorExit : (unsigned ErrorNumber) erroneous.</vip>

Performs a run-time error with the specified return code <vp>ErrorNumber</vp>, which can be used in the [[#try-catch-finally|try-catch-finally]].

==== fail ====

<vip>fail : () failure.</vip>

The <vp>fail</vp> predicate forces failure and, hence, always causes backtracking. A clause that fails (with <vp>fail</vp> or for some other reason) cannot bind output arguments.

==== free ====

<vip>free : (<variableName> Variable) determ.</vip>

Check whether a variable is free.

Call-template for this predicate is:

<vip>free(Variable)</vip>

The <vp>free</vp> predicate succeeds if the specified <vp>Variable</vp> is free and fails if <vp>Variable</vp> is bound. The <vp>free</vp> predicate treats the specified <vp>Variable</vp> as bound if any of it's part are instantiated.

See also [[#bound|bound/1]].

==== fromEllipsis ====

<vip>fromEllipsis : (...) -> any* AnyTermList.</vip>

This predicate creates the list of terms of the universal type <vp>any</vp> from the ''EllipsisBlock'' '''...''' (i.e. from the special varying parameters block).

Call-template for this function is:

<vip>AnyTermList = fromEllipsis(EllipsisBlock )</vip>

See also [[#toEllipsis|toEllipsis/1->]].

==== hasDomain ====

<vp>hasDomain</vp> is not really a predicate, but more a type declaration/restriction. It has two forms a non-function for declaring/restricting the type of a variable and a function form for declaring/restricting the type of a value.

The non-function form is called with a type as first parmeter and a variable as second parameter.

<vip>hasDomain : (<type> Type, Type Variable).</vip>

The only effect of the call is that the <vp>Variable</vp> will be restricted to the type <vp>Type</vp>.

The variable can be free, bound or of some mixed flow and the binding of the variable will not change in any way.

The function form is called with a type as first argument and a value as second argument, and it returns the same value.

<vip>hasDomain : (<type> Type, Type Value) -> Type Value.</vip>

The only effect of the call is to ensure that the <vp>Value</vp> will be restricted to the type <vp>Type</vp>.

==== lowerBound ====

<vip>lowerBound : (<numeric-domain> NumericDomain) -> <numeric-domain> LowerBound.</vip>

Returns the lower bound of the specified <vp>NumericDomain</vp>.

Call-template for this function is:

<vip>LowerBoundValue = lowerBound(domainName)</vip>

The <vp>lowerBound</vp> is a compiling-time predicate. The <vp>lowerBound</vp> returns the lower bound value <vp>LowerBoundValue</vp> of the specified numeric domain ''domainName''. The return value <vp>LowerBoundValue</vp> belongs to the same domain ''domainName''. The ''domainName'' parameter should be the name of any numerical domain; this domain name should be explicitly specified at compile-time (that is, ''domainName'' cannot come from a variable). See also [[#upperBound|upperBound/1->]].

It will give a compile time error if the specified domain ''domainName'' is not numeric domain.

==== in ====

See [[Language_Reference/Terms#in|in/2]].

==== isErroneous ====

<vip>isErroneous : (<fact-variable> FactVariable) determ.</vip>

The predicate succeeds if the specified fact variable is <vp>erroneous</vp>.

Call-template for this predicate is:

<vip>isErroneous(factVariableName)</vip>

The predicate succeeds if the specified fact variable <vp>factVariableName</vp> has the <vp>erroneous</vp> value, otherwise it fails.

==== maxDigits ====

<vip>maxDigits : (<real-domain> RealDomain) -> unsigned MaxDigits</vip>

Retrieves the value of digits (precision) of the basic domain corresponding to the specified floating-point domain <vp>RealDomain</vp>.

Call-template for this function is:

<vip>MaxDigitsNumber = maxdigits(domainName)</vip>

The return maximal number of digits <vp>MaxDigitsNumber</vp> for the ''domainName'' parameter, which should be the name of a <vp>real</vp> domain.

==== not ====

See [[Language_Reference/Terms#not|not]].

==== or ====

See [[Language_Reference/Terms#or_.28.3B.29|or (;)]].

==== orelse ====

See [[Language_Reference/Terms#orelse|orelse]].

==== predicate_fullname ====

<vip>predicate_fullname : () -> string PredicateFullName.</vip>

This predicate returns the name <vp>PredicateFullName</vp> of the predicate in which it is invoked. The returned predicate name is qualified with a scope name.

<vp>predicate_fullname</vp> can only be used inside a clause. Use of <vp>predicate_fullname</vp> in other places causes a compile time error. See also [[#predicate_name|predicate_name]].

==== predicate_name ====

<vip>predicate_name : () -> string PredicateName.</vip>

This predicate returns the name <vp>PredicateName</vp> of the predicate in which it is invoked.

<vp>predicate_name</vp> can only be used inside a clause. Use of <vp>predicate_name</vp> in other places causes a compile time error. See also [[#predicate_fullname|predicate_fullname]]

==== programPoint ====

<vip>programPoint : () -> core::programPoint ProgramPoint.</vip>

This predicate returns the name <vp>programPoint</vp> corresponding to the place where it is invoked.

==== retract ====

<vip>retract : (<fact-term> FactTerm) nondeterm anyflow.</vip>

Successively removes the first matching fact from the facts database. Fails when no more facts match.

Call-template for this predicate is:

<vip>retract(FactTemplate)</vip>

Here <vp>FactTemplate</vp> should be a fact term. The <vp>retract/1</vp> predicate deletes the first fact that matches the <vp>FactTemplate</vp> in the appropriated facts database. During backtracking, the rest of the matching facts will be deleted.

Notice that <vp>FactTemplate</vp> can have any level of instantiation. The <vp>FactTemplate</vp> is matched with the facts in the facts database, which means that any free variables will be bound in the call to <vp>retract/1</vp>.

The <vp>FactTemplate</vp> can contain any anonymous variables. That is, variables with names consisting from the single underscore <vp>_</vp> or a variable with a name starting with an underscore <vp>_AnyValue</vp> if the variable occurs only once in the clause. For example.

<vip>retract(person("Hans", _Age)),</vip>

will retract the first matched person fact that has "<vp>Hans</vp>" as the first argument and anything as the second argument.

When retracting a fact, which is declared to be determ, the call to <vp>retract/1</vp> will be deterministic.

See also [[#retractall|retractall/1]] and [[#retractFactDb|retractFactDb]].

The <vp>retract/1</vp> predicate cannot be applied to single facts or fact variables.

Be careful calling <vp>retract/1</vp> with free <vp>FactTemplate</vp> variable if any single fact is declared in the project current scope. If you retract a single fact, then the run-time error is generated. The <vp>retract/1</vp> predicate fails when there are no more matches.

==== retractall ====

<vip>retractall : (<fact-term> FactTerm) .</vip>

Remove all matching facts from the facts database.

Call-template for this predicate is:

<vip>retractall(FactTemplate)</vip>

Here <vp>FactTemplate</vp> should be a fact term.

The <vp>retractall/1</vp> retracts all facts which match the given ''FactTemplate''. It always succeeds, even if no facts were retracted.

Attempting to retract a <vp>single</vp> fact will cause a compile time error.

It is not possible to obtain any output values from <vp>retractall/1</vp>. For this reason, the variables in the call must be bound or be a single underscores (anonymous). Notice that <vp>FactTemplate</vp> can have any level of instantiation, but free variables must be single underscores ("unconditionally anonymous"). In difference to [[#retract|retract/1]] "conditionally" anonymous variables with names starting from the underscore (like <vp>_AnyValue</vp>) cannot be used in <vp>retractall/1</vp>.

See also [[#retract|retract/1]] and [[#retractFactDb|retractFactDb/1]].

==== retractFactDb ====

<vip>retractFactDb : (factDB FactDB).</vip>

Remove all facts from the named internal facts database <vp>FactDB</vp>.

Call-template for this predicate is:

<vip>retractFactDb(FactDB)</vip>

The <vp>retractFactDb/1</vp> removes all facts from the named facts database <vp>FactDB</vp>.

Notice, it is impossible to retract <vp>single</vp> facts and fact variables, so the predicate leaves such ones as they are.

See also [[#retractall|retractall/1]] and [[#retract|retract/1]].

==== retractAll/2 ====

Obsolete predicate! Use [[#retractFactDb|retractFactDb/1]] instead.

==== sizeBitsOf ====

<vip>sizeBitsOf : (<domain> DomainName) -> unsigned BitSize.</vip>

Retrieves the number of bits occupied in memory by an entity of the specified domain <vp>DomainName</vp>.

Call-template for this function is:

<vip>BitSize = sizeBitsOf(DomainName)</vip>

This compiling-time predicate receives the domain <vp>DomainName</vp> as input parameter and return the size of memory that is occupied by the entity of the given domain. The result is measured in bits. For the integer domains <vp>sizeBitsOf/1-></vp> predicate returns the value that was defined for the size-field in a domain's declaration.

The following is always true for the integral domains:

<vip>sizeOfDomain(domain)*8 - 7 <= sizeBitsOf(domain) <= sizeOfDomain(domain)*8</vip>

See also [[#sizeOfDomain|sizeOfDomain]]/1->.

==== sizeOf ====

<vip>sizeOf : (Type Term) -> integer ByteSize.</vip>

Retrieves the number of bytes occupied in memory by the specified term <vp>Term</vp>.

Call-template for this function is:

<vip>ByteSize = sizeOf(Term)</vip>

The <vp>sizeOf/1-></vp> function receives a term as input parameter and returns value <vp>ByteSize</vp> that specifies the number of bytes occupied in memory by this term <vp>Term</vp>.

==== sizeOfDomain ====

<vip>sizeOfDomain : (<domain> Domain) -> integer ByteSize.</vip>

Retrieves the number of bytes occupied in memory by the entity of the specified domain <vp>DomainName</vp>.

Call-template for this function is:

<vip>ByteSize = sizeOfDomain(DomainName)</vip>

This compiling-time predicate receives the domain <vp>DomainName</vp> as input parameter and return the size of memory that is occupied by the entity of the given domain. The result is measured in bytes. The returned value <vp>ByteSize</vp> belongs to the integer domain. Compare with [[#sizeBitsOf|sizeBitsOf/1->]], which returns size of a domain measured in bits.

==== sourcefile_lineno ====

<vip>sourcefile_lineno : () -> unsigned LineNumber.</vip>

Returns the current line number in the source file processed by the compiler.

==== sourcefile_name ====

<vip>sourcefile_name : () -> string FileName.</vip>

Returns the name of the source file processed by the compiler.

==== sourcefile_timestamp ====

<vip>sourcefile_timestamp : () -> string TimeStamp..</vip>

Returns a string that represents the date and time of the currently compiled source file in format YYYY-MM-DD HH:mm:ss. Where:

* YYYY - Year.
* MM - Month.
* DD - Day.
* HH - Hour.
* mm - Minute.
* ss - Second.

==== succeed ====

<vip>succeed : ().</vip>

The predicate <vp>succeed/0</vp> will always succeed.

==== toAny ====

<vip>toAny : (Term) -> any UniversalTypeValue.</vip>

Converts the specified <vp>Term</vp> to the value of universal term type <vp>any</vp>.

Call-template for this function is:

<vip>UniversalTypeValue = toAny(Term)</vip>

A term of the <vp>any</vp> domain can be converted back to its original type using the <vp>toTerm</vp> predicates (see {{lang2|Built-in entities/Predicates|toTerm|toTerm}}).

==== toBinary ====

<vip>toBinary : (Term) -> binary Serialized.</vip>

Converts the specified <vp>Term</vp> to [[#binary|binary]] representation.

Call-template for this function is:

<vip>Serialized = toBinary(Term)</vip>

When a <vp>Term</vp> (of some domain ''domainName'') is converted into a binary, it can safely be stored in a file or sent over a network to another program. Later the obtained binary value <vp>Serialized</vp> can be converted back to a Visual Prolog term, using [[#toTerm|toTerm/1->]] function (the domain for the reversed term should be adequate to ''domainName'') for the reverse conversion.

==== toBoolean ====

<vip>toBoolean : (<term> SubGoal) -> boolean Succeed.</vip>

The purpose of this meta-predicate is to convert the deterministic call (to a predicate or fact) to the procedure that returns the value of [[#boolean|boolean]] domain.

Call-template for this meta-predicate is:

<vip>True_or_False = toBoolean(deterministic_call)</vip>

The <vp>toBoolean/1-></vp> meta-predicate returns [[#boolean|boolean]] value. The result is <vp>true</vp> if ''deterministic_call'' succeeds. The result is <vp>false</vp> if ''deterministic_call'' fails.

==== toEllipsis ====

<vip>toEllipsis : (any* AnyTermList) -> ....</vip>

This predicate creates ''EllipsisBlock'' '''...''' (i.e. the special varying parameters block) from the list of terms of the universal type <vp>any</vp>. Such ''EllipsisBlock'' can be later passed to a predicate which expects the varying number of arguments (i.e. is declared with the ellipsis (''...'')), like <vp>write/...</vp>, at the position of the ellipsis (''...'').

Call-template for this function is:

<vip>EllipsisBlock = toEllipsis(<any_term_list>), write(EllipsisBlock)</vip>

See also [[#fromEllipsis|fromEllipsis/1->]].

==== toString ====

<vip>toString : (Term) -> string Serialized.</vip>

Converts the specified <vp>Term</vp> to string representation.

Call-template for this function is:

<vip>Serialized = toString(Term)</vip>

When a <vp>Term</vp> (of some domain ''domainName'') is converted into a string, it can safely be stored in a file or sent over a network to another program. Later the obtained string value can be converted back to a Visual Prolog term, using [[#toTerm|toTerm/1->]] function (the domain of the return value should be adequate to ''domainName'') for the reverse conversion.

==== toTerm ====

<vip>toTerm : (string Serialized) -> Term.
toTerm : (binary Serialized) -> Term.
toTerm : (any Serialized) -> Term.
toTerm : (<domain> Type, string Serialized) -> Term.
toTerm : (<domain> Type, binary Serialized) -> Term.
toTerm : (<domain> Type, any Serialized) -> Term.</vip>

Converts the string/binary/any representation of the specified term <vp>Serialized</vp> into representation corresponding to the domain of <vp>Term</vp> variable of the return value. The domain can be stated explicitly or it can be left to the compiler to determine a suitable domain.

Call-template for this function is:

<vip>Term = toTerm(Serialized) % with implicit domain
Term = toTerm(domainName, Serialized) % with explicit domain, domainName</vip>

If the domain is not specified the compiler must be able to determine the domain for the returned value <vp>Term</vp> at compile-time. Notice that binary version of <vp>toTerm</vp> predicate performs almost byte to byte conversion and only checking general compatibility of <vp>Serialized</vp> data with the domain required to the return value <vp>Term</vp>. The programmer is wholly responsible for providing binary data of <vp>Serialized</vp> that can be correctly converted to the term of the desired domain. The <vp>toTerm</vp> predicates are counterparts to predicates [[#toBinary|toBinary/1->]] and [[#toString|toString/1->]]. When a ''Term'' (of some domain ''domainName'') is converted into a binary or string representation <vp>Serialized</vp> (by [[#toBinary|toBinary/1->]] or [[#toString|toString/1->]] or [[#toAny|toAny/1->]] correspondingly), it can safely be stored in a file or sent over a network to another program. Later the corresponding <vp>toTerm/1</vp>-> function can convert the obtained string/binary value <vp>Serialized</vp> back to a Visual Prolog term <vp>Term</vp>. For correctness of the reverse conversion the domain of the clause variable <vp>Term</vp> should be adequate to the initial domain ''domainName''.

See also [[#tryToTerm|tryToTerm]].

It gives a compile time error if the compiler cannot determine the return domain.

Exceptions

* Run time errors are generated when the <vp>toTerm</vp> predicate cannot convert the string or binary into a term of the specified domain.

==== tryToTerm ====

<vip>tryToTerm : (string Serialized) -> Term.
tryToTerm : (binary Serialized) -> Term.
tryToTerm : (any Serialized) -> Term.
tryToTerm : (<domain> Type, string Serialized) -> Term.
tryToTerm : (<domain> Type, binary Serialized) -> Term.
tryToTerm : (<domain> Type, any Serialized) -> Term.</vip>

Converts the string/binary/any representation <vp>Serialized</vp> into a term <vp>Term</vp> like [[#toTerm|toTerm]]. The only difference between the predicates is that <vp>tryToTerm</vp> fails if it cannot convert the string or binary or any into a term of the specified domain whereas toTerm raises an exception.

See also [[#toTerm|toTerm]].

==== tryConvert ====

<vip>tryConvert : (<type> Type, Value) -> <type> Converted determ.</vip>

Checks whether the input term <vp>Value</vp> can be strictly converted into the specified domain <vp>Type</vp> and returns the converted term <vp>Converted</vp>.

Call-template for this function is:

<vip>ReturnTerm = tryConvert(returnDomain, InputTerm)</vip>

Arguments:

* <vp>returnDomain</vp>: Specifies a domain to which <vp>tryConvert/2-></vp> predicate tries to convert the specified <vp>InputTerm</vp>. Here ''returnDomain'' can be any domain accessible in the current scope. The domain name ''returnDomain'' must be specified at compile-time, i.e. it cannot come from a variable.
* <vpbnf><InputTerm></vpbnf>: Specifies the term that must be converted. <vp>InputTerm</vp> may be any Prolog term or an expression. If <vp>InputTerm</vp> is an expression, then it will be evaluated before conversion.
* <vpbnf><ReturnTerm></vpbnf>: Returned term <vp>ReturnTerm</vp> will be of ''returnDomain'' domain.

The conversion rules are the same as of the embedded predicate [[#convert|convert/2->]], but <vp>tryConvert/2-></vp> fails when [[#convert|convert/2->]] generates conversion errors.

This predicate succeeds if the corresponding conversion succeeds. Otherwise it fails. The <vp>tryConvert/2-></vp> predicate tries to perform a clean and genuine conversion of the given <vp>InputTerm</vp> into a value of the specified domain ''returnDomain''. The <vp>tryConvert/2-></vp> predicate will fail if the required conversion cannot be performed. When <vp>tryConvert/2-></vp> predicate succeeds, it returns the term <vp>ReturnTerm</vp> converted to the specified domain ''returnDomain''.

For allowed conversions and rules of checked explicit conversions see [[#convert|convert/2->]] predicate.

See also [[#uncheckedConvert|uncheckedConvert/2->]].

==== uncheckedConvert ====

<vip>uncheckedConvert : (<type> Type, Value) -> <type> Converted.</vip>

Unchecked conversion of a value to another type.

Call-template for this function is:

<vip>ReturnTerm = uncheckedConvert(returnDomain, InputTerm)</vip>

Arguments:

* <vp>returnDomain</vp>: Specifies a domain to which <vp>uncheckedConvert</vp> predicate unsafely converts the specified <vp>InputTerm</vp>. Here ''returnDomain'' can be any domain accessible in the current scope, the <vp>ReturnTerm</vp> should has the same bit-size as the <vp>InputTerm</vp>. The domain name ''returnDomain'' must be specified at compile-time, i.e. it cannot come from a variable.
* <vpbnf><InputTerm></vpbnf>: Specifies the value that must be converted. <vp>InputTerm</vp> may be any Prolog term or an expression. If ''InputTerm'' is an expression, then it will be evaluated before conversion.
* <vpbnf><ReturnTerm></vpbnf>: Returned parameter <vp>ReturnTerm</vp> will be of ''returnDomain'' type.

<vp>uncheckedConvert</vp> evaluates <vp>InputTerm</vp>, change the type to ''returnDomain'' without any modification of the memory pattern and unifies with <vp>ReturnTerm</vp>. The <vp>uncheckedConvert</vp> predicate performs no runtime checks. It makes only compile time checking of bit-size equality of the converted domains. So almost any term may be quite recklessly converted to any other term. So quite disastrous results may occur if you try to use variables incorrectly converted by <vp>uncheckedConvert</vp>. Be extremely careful implementing <vp>uncheckedConvert</vp>; we strongly recommend you always, when it is possible, using of [[#convert|convert/2->]] and [[#tryConvert|tryConvert/2->]]. But notice that, when an object is returned by COM system it is necessary to convert it by <vp>uncheckedConvert</vp>, as Prolog program does not have information about its actual type.

==== upperBound ====

<vip>upperBound : (<numeric-domain> NumericDomain) -> <number-domain> UpperBound.</vip>

Returns the upper bound value of the specified numeric domain.

Call-template for this function is:

<vip>UpperBound = upperBound(domainName)</vip>

The <vp>upperBound</vp> is a compiling-time predicate. The <vp>upperBound</vp> returns the upper bound value of the specified numeric domain ''domainName''. The return value <vp>UpperBound</vp> belongs to the same domain ''domainName''. The ''domainName'' parameter should be the name of any numerical domain; this domain name should be explicitly specified at compile-time (that is, ''domainName'' cannot come from a variable).

See also [[#lowerBound|lowerBound/1->]].

Will cause a compile time error if the specified domain ''domainName'' is not numeric domain.
<noinclude>{{LanguageReferenceSubarticle|Built-in entities/Predicates}}</noinclude>

Language Reference/Built-in entities/Predicates

2016-04-06T08:45:28Z

SergeMukhin: /* sourcefile_timestamp */

<noinclude>__NOTOC__</noinclude>

{|{{prettytable}}
|-
|[[Language_Reference/Terms#and_.28.2C.29|and/2]] [[Language_Reference/Terms#and_.28.2C.29|,/2]]
|Term "and"
|-
|[[#assert|assert/1]]
|Insert the specified fact at the end of the matched internal facts database.
|-
|[[#asserta|asserta/1]]
|Insert a fact at the beginning of the matched internal facts database.
|-
|[[#assertz|assertz/1]]
|Insert a fact at the end of the matched internal facts database.
|-
|[[#bound|bound/1]] <vp>determ</vp>
|Test whether the specified variable is bound to a value.
|-
|[[#class_name|class_name/0->]]
|This compile time predicate returns the string ''ClassName'' that represents the name of the current interface or class.
|-
|[[#compare|compare/2->]]
|Returns the result of the variables' comparison.
|-
|[[#convert|convert/2->]]
|Checked term conversion.
|-
|[[#digitsOf|digitsOf/1->]]
|Returns precision of the specified floating-point domain.
|-
|[[#errorExit|errorExit/1]] <vp>erroneous</vp>
|Performs a run-time error with the specified return code ''ErrorNumber'' and sets the internal error information.
|-
|[[#fail|fail/0]] <vp>failure</vp>
|Invoke backtracking.
|-
|[[#free|free/1]] <vp>determ</vp>
|Check whether a variable is free.
|-
|[[#fromEllipsis|fromEllipsis/1->]]
|Creates the list of terms of the universal type <vp>any</vp> from the ''EllipsisBlock''.
|-
|[[#hasDomain|hasDomain/2]] [[#hasDomain|hasDomain/2->]]
|Declares/restricts the type of a variable or value.
|-
|[[Language_Reference/Terms#in|in/2]] <vp>determ</vp> [[Language_Reference/Terms#in|in/2]] <vp>nondeterm</vp>
|Infix operator "in" (in-test and in-iterator).
|-
|[[#isErroneous|isErroneous/1]] <vp>determ</vp>
|Returns the lower bound value of the specified numeric domain.
|-
|[[#lowerBound|lowerBound/1->]]
|Returns the lower bound value of the specified numeric domain.
|-
|[[#maxDigits|maxDigits/1->]]
|Retrieves the value of digits (precision) of the basic domain corresponding to the specified floating-point domain ''domainName''.
|-
|[[#not|not/1]] <vp>determ</vp>
|Negate the result (success/fail) of subgoal.
|-
|[[Language_Reference/Terms#or_.28.3B.29|or/2]] [[Language_Reference/Terms#and_.28.3B.29|;/2]]
|Nondeterministic term "or"
|-
|[[Language_Reference/Terms#orelse|orelse]]
|Deterministic term "or"
|-
|[[#predicate_fullname|predicate_fullname/1->]]
|This compile time predicate returns the string ''PredicateFullName'' that represent the name of the predicate in which clause body <vp>predicate_name</vp> is called. The returned predicate name is qualified with a scope name.
|-
|[[#predicate_name|predicate_name/1->]]
|This compile time predicate returns the string ''PredicateName'' that represent the name of the predicate in which clause body <vp>predicate_name</vp> is called. The returned predicate name is not qualified with a scope name.
|-
|[[#programPoint|programPoint/0->]]
|This compile time predicate returns the <vp>programPoint</vp> corresponding to the place where it is called.
|-
|[[#retract|retract/1]] <vp>nondeterm</vp>
|Remove a matched fact from the matched internal facts database.
|-
|[[#retractall|retractall/1]]
|Remove all matching facts from the matched internal facts database.
|-
|[[#retractFactDb|retractFactDb/1]]
|Remove all facts from the specified named internal facts database.
|-
|[[#sizeBitsOf|sizeBitsOf/1->]]
|Retrieves the number of bits occupied in memory by an entity of the specified domain ''DomainName''.
|-
|[[#sizeOf|sizeOf/1->]]
|Retrieves the number of bytes occupied in memory by the specified term.
|-
|[[#sizeOfDomain|sizeOfDomain/1->]]
|Retrieves the number of bytes occupied in memory by the entity of the specified domain ''DomainName''.
|-
|[[#sourcefile_lineno|sourcefile_lineno/0->]]
|Returns the current line number in the source file processed by the compiler .
|-
|[[#sourcefile_name|sourcefile_name/0->]]
|Returns the name of the source file processed by the compiler.
|-
|[[#sourcefile_timestamp|sourcefile_timestamp/0->]]
|Returns the string representing the date and time of the source file processed by the compiler.
|-
|[[#succeed|succeed/0]]
|The predicate <vp>succeed/0</vp> will always succeed.
|-
|[[#toAny|toAny/1->]]
|Converts the specified ''Term'' to the value of the universal term type <vp>any</vp>.
|-
|[[#toBinary|toBinary/1->]]
|Converts the specified Term to the binary representation.
|-
|[[#toBoolean|toBoolean/1->]]
|The purpose of this meta-predicate is to convert the deterministic call (to a predicate or fact) to the procedure that returns the value of <vp>boolean</vp> domain.
|-
|[[#toEllipsis|toEllipsis/1->]]
|Creates the ''EllipsisBlock'' from the list of <vp>any</vp> type values.
|-
|[[#toString|toString/1->]]
|Converts the specified ''Term'' to the string representation.
|-
|[[#toTerm|toTerm/1->]] [[#toTerm|toTerm/2->]]
|Converts the string/binary representation of the specified term ''SrcTerm'' into representation corresponding to the domain of ''PrologTerm'' variable of the return value.
|-
|[[#tryToTerm|tryToTerm/1->]] <vp>determ</vp> [[#tryToTerm|tryToTerm/2->]] <vp>determ</vp>
|Converts the string/binary representation of the specified term ''SrcTerm'' into representation corresponding to the domain of ''PrologTerm'' variable of the return value.
|-
|[[#tryConvert|tryConvert/2->]] <vp>determ</vp>
|Checks whether the input term ''InputTerm'' can be strictly converted into the specified domain ''returnDomain'' and returns the converted term ''ReturnTerm''.
|-
|[[#uncheckedConvert|uncheckedConvert/2->]]
|Unchecked conversion of domains.
|-
|[[#upperBound|upperBound/1->]]
|Returns the upper bound value of the specified numeric domain.
|}

The following predicates are deprecated:
{|{{prettytable}}
|-
| finally/2
| Use [[Language_Reference/Terms#try-finally| <vp>try-finally</vp>]] constuction instead.
|-
| findall/3
| Use list comprehension [[Language_Reference/Terms#List_Comprehension| <vp>[ ... || ... ]</vp>]] instead
|-
| trap/3 <vp>determ</vp>
| Use [[Language_Reference/Terms#try-catch| <vp>try-catch</vp>]] constuction instead.
|}

==== and ====

See [[Language_Reference/Terms#and_.28.2C.29|and (,)]].

==== assert ====

<vip>assert : (<fact-term> FactTerm).</vip>

Insert the specified fact at the end of the matched internal facts database

<vp>assert(Fact)</vp> inserts <vp>Fact</vp> in the matched internal facts database after any other stored facts for the corresponding database predicate. <vp>Fact</vp> must be a term belonging to the domain of an internal facts database. <vp>assert/1</vp> applied to a single fact changes the existing instance of a fact to the specified one. <vp>assert/1</vp> has the same effect as [[#assertz|assertz/1]]. See also [[#asserta|asserta/1]].

Notice that the combination of [[#retract|retract/1]] and <vp>assert/1</vp> like the following can lead to endless loop:

<vip>loop() :-
retract(fct(X)),
... % creating Y from X
assert(fct(Y)),
fail.</vip>

The problem is that the retract in first line will eventually retract the fact asserted in the last line, because that fact is inserted ''last'' in the fact chain.

Exceptions:

* Attempt to assert a second instance to a fact declared as determ.

==== asserta ====

<vip>asserta : (<fact-term> FactTerm).</vip>

Insert a fact at the beginning of the matched internal facts database.

The <vp>asserta(Fact)</vp> predicate inserts a <vp>Fact</vp> in the matched internal facts database before any other stored facts for the corresponding predicate. The <vp>Fact</vp> must be a term belonging to the domain of an internal facts database. The <vp>asserta/1</vp> applied to a single fact changes the existing instance of a fact to the specified one. See also [[#assert|assert/1]] and [[#assertz|assertz/1]].

Exceptions:

* Attempt to a fact declared as determ, but the fact instance already exists.

==== assertz ====

<vip>assertz : (<fact-term> FactTerm).</vip>

<vp>assertz</vp> does exactly the same as the [[#assert|assert/1]] predicate.

==== bound ====

<vip>bound : (<variable> Variable) determ.</vip>

Test whether the specified variable is bound to a value.

The <vp>bound(Variable)</vp> succeeds if <vp>Variable</vp> is bound and fails if it is free. The <vp>bound</vp> predicate is used to control flow patterns and to check the binding of reference variables. The <vp>bound</vp> predicate treats the specified <vp>Variable</vp> as bound if any of it's part is instantiated.

See also [[#free|free/1]].

==== class_name ====

<vip>class_Name : () -> string ClassName.</vip>

This compile time predicate returns the string <vp>ClassName</vp> that represents the name of the current interface or class.

==== compare ====

<vip>compare : (A Left, A Right) -> compareResult CompareResult.</vip>

Comparison of two terms of the same domain, resturns the value of [[#compareResult|compareResult]] domain.

<vp>CompareResult</vp> = compare("<vp>bar</vp>", "<vp>foo</vp>")

==== convert ====

<vip>convert : (<type> Type, Term) -> <type> Converted.</vip>

Checked term conversion.

Call-template for this function is:

<vp>ReturnTerm</vp> = convert(returnDomain, <vp>InputTerm</vp>)

* <vpbnf>returnDomain</vpbnf>: Specifies a domain to which function <vp>convert/2-></vp> converts <vp>InputTerm</vp>. Here ''returnDomain'' must be a name of built-in Visual Prolog domain, an interface domain, a name of such user defined domain that is synonym to one of built-in Visual Prolog domains, a numeric domain, binary and pointer domains. The domain name ''returnDomain'' must be specified at compile-time, i.e. it cannot come from a variable.

* <vpbnf><InputTerm></vpbnf>: Specifies the value that must be converted. <vp>InputTerm</vp> may be any Prolog term or an expression. If <vp>InputTerm</vp> is an expression, then it will be evaluated before the conversion.

* <vpbnf><ReturnTerm></vpbnf>: Returned parameter <vp>ReturnTerm</vp> will be of ''returnDomain'' type.

The <vp>convert</vp> predicate performs a clean and genuine conversion of the given <vp>InputTerm</vp>, returning a new term <vp>ReturnTerm</vp> of the specified new domain ''returnDomain''. If <vp>convert</vp> cannot perform the required conversion, it rises errors. The similar functionality is provided by the [[#tryConvert|tryConvert/2->]] predicate, but <vp>tryConvert-></vp> fails and does not produce any runtime errors if it cannot perform the conversion.

===== Allowed conversions =====

* Between numerical domains.
* Between interface types.
* Between [[#string|string]] and [[#symbol|symbol]] domains.
* From [[#binary|binary]] to [[#pointer|pointer]].
* For synonyms of mentioned domains.
* Between [http://wiki.visual-prolog.com/index.php?title=How_To_Remove_Reference_Domains_from_a_Project reference] domains and corresponding non-reference domains.

The contrast to these is [[#uncheckedConvert|uncheckedConvert/2->]] predicate, which performs an unchecked conversion between terms from any domains, which have the same bit-size.

The <vp>convert/2-></vp> (or [[#tryConvert|tryConvert/2->]]) predicate accomplishes a checked explicit conversion, when the source and target domains are statically known during the compilation. The result of an explicit conversion can be one of the following:

* '''ok''' the successful conversion to the target domain;
* '''run-time-check''' the conversion to the target domain with generation of run-time checking for compatibility;
* '''error''' the conversion is impossible, error output.

===== Rules of Checked Explicit Conversions =====

* Synonyms of domains are converted using the same rules that are applied to the domains themselves.
* Numerical domains can be converted to the numerical domains only.
* Integral constants are the representatives of the anonymous integral domain: <vp>[const .. const]</vp>.
* Real constants are the representatives of the anonymous real domain: <vp>digits</vp> <vp>dig [const .. const]</vp>, where <vp>dig</vp> is the number of the digits in mantissa without insignificant zeroes.
* A value of the symbol domain can be converted to the string domain and vice versa.
* A value of binary domain can be converted to the pointer domain.
* The domains that are implicitly introduced for interfaces can be converted only to the interface domains according to the rules specified below.
* All other domains cannot be converted.

===== Conversions of Numerical Domains =====

* The range is considered first during such conversion. If the ranges of source and target do not intersect, then an error is produced. If the ranges of source and target only partially intersect, then run-time checking is generated. Also, if one of domains is real and another is an integral one, then the integer range is converted to the real range before the comparison.
* When input term in real and output is integer, then <vp>convert/2-></vp> and [[#tryConvert|tryConvert/2->]] predicates truncate the input value to the nearest integer value, which is nearer to zero.

===== Conversions of Interface Types =====

Predicate <vp>convert/2-></vp> allow to convert any object to any interface type. The actual correctness of such conversion is checked at runtime. When object is created, its type is internally stored, therefore when the object is passed as argument it still remember about its original type. This original type is used for checking allowed conversions. The example:

<vip>interface x
supports a, b
end interface x</vip>

If object is created by class, which implements <vp>x</vp> interface, and then object is passed as parameter of type <vp>a</vp> to some predicate, then it is allowed to convert the object to <vp>b</vp> type.

Exceptions:

* Check range error.
* Unsupported interface type.

==== digitsOf ====

<vip>digitsOf : (<real-domain> Domain) -> unsigned.</vip>

Returns precision of the specified floating-point domain.

Call-template for this function is:

<vip>Precision = digitsof(domainName)</vip>

The input parameter ''domainName'' of this compiling-time predicate is a floating-point domain, it should be explicitly specified at compile-time (that is, ''domainName'' cannot come from a variable). The predicate returns the number <vpbnf><Precision></vpbnf> that was determined by the <vp>digits</vp> attribute in the domain declaration.

The compiler guarantees that values of the domain ''domainName'' will have at least <vpbnf><Precision></vpbnf> number of significant decimal digits.

==== errorExit ====

<vip>errorExit : (unsigned ErrorNumber) erroneous.</vip>

Performs a run-time error with the specified return code <vp>ErrorNumber</vp>, which can be used in the [[#try-catch-finally|try-catch-finally]].

==== fail ====

<vip>fail : () failure.</vip>

The <vp>fail</vp> predicate forces failure and, hence, always causes backtracking. A clause that fails (with <vp>fail</vp> or for some other reason) cannot bind output arguments.

==== free ====

<vip>free : (<variableName> Variable) determ.</vip>

Check whether a variable is free.

Call-template for this predicate is:

<vip>free(Variable)</vip>

The <vp>free</vp> predicate succeeds if the specified <vp>Variable</vp> is free and fails if <vp>Variable</vp> is bound. The <vp>free</vp> predicate treats the specified <vp>Variable</vp> as bound if any of it's part are instantiated.

See also [[#bound|bound/1]].

==== fromEllipsis ====

<vip>fromEllipsis : (...) -> any* AnyTermList.</vip>

This predicate creates the list of terms of the universal type <vp>any</vp> from the ''EllipsisBlock'' '''...''' (i.e. from the special varying parameters block).

Call-template for this function is:

<vip>AnyTermList = fromEllipsis(EllipsisBlock )</vip>

See also [[#toEllipsis|toEllipsis/1->]].

==== hasDomain ====

<vp>hasDomain</vp> is not really a predicate, but more a type declaration/restriction. It has two forms a non-function for declaring/restricting the type of a variable and a function form for declaring/restricting the type of a value.

The non-function form is called with a type as first parmeter and a variable as second parameter.

<vip>hasDomain : (<type> Type, Type Variable).</vip>

The only effect of the call is that the <vp>Variable</vp> will be restricted to the type <vp>Type</vp>.

The variable can be free, bound or of some mixed flow and the binding of the variable will not change in any way.

The function form is called with a type as first argument and a value as second argument, and it returns the same value.

<vip>hasDomain : (<type> Type, Type Value) -> Type Value.</vip>

The only effect of the call is to ensure that the <vp>Value</vp> will be restricted to the type <vp>Type</vp>.

==== lowerBound ====

<vip>lowerBound : (<numeric-domain> NumericDomain) -> <numeric-domain> LowerBound.</vip>

Returns the lower bound of the specified <vp>NumericDomain</vp>.

Call-template for this function is:

<vip>LowerBoundValue = lowerBound(domainName)</vip>

The <vp>lowerBound</vp> is a compiling-time predicate. The <vp>lowerBound</vp> returns the lower bound value <vp>LowerBoundValue</vp> of the specified numeric domain ''domainName''. The return value <vp>LowerBoundValue</vp> belongs to the same domain ''domainName''. The ''domainName'' parameter should be the name of any numerical domain; this domain name should be explicitly specified at compile-time (that is, ''domainName'' cannot come from a variable). See also [[#upperBound|upperBound/1->]].

It will give a compile time error if the specified domain ''domainName'' is not numeric domain.

==== in ====

See [[Language_Reference/Terms#in|in/2]].

==== isErroneous ====

<vip>isErroneous : (<fact-variable> FactVariable) determ.</vip>

The predicate succeeds if the specified fact variable is <vp>erroneous</vp>.

Call-template for this predicate is:

<vip>isErroneous(factVariableName)</vip>

The predicate succeeds if the specified fact variable <vp>factVariableName</vp> has the <vp>erroneous</vp> value, otherwise it fails.

==== maxDigits ====

<vip>maxDigits : (<real-domain> RealDomain) -> unsigned MaxDigits</vip>

Retrieves the value of digits (precision) of the basic domain corresponding to the specified floating-point domain <vp>RealDomain</vp>.

Call-template for this function is:

<vip>MaxDigitsNumber = maxdigits(domainName)</vip>

The return maximal number of digits <vp>MaxDigitsNumber</vp> for the ''domainName'' parameter, which should be the name of a <vp>real</vp> domain.

==== not ====

See [[Language_Reference/Terms#not|not]].

==== or ====

See [[Language_Reference/Terms#or_.28.3B.29|or (;)]].

==== orelse ====

See [[Language_Reference/Terms#orelse|orelse]].

==== predicate_fullname ====

<vip>predicate_fullname : () -> string PredicateFullName.</vip>

This predicate returns the name <vp>PredicateFullName</vp> of the predicate in which it is invoked. The returned predicate name is qualified with a scope name.

<vp>predicate_fullname</vp> can only be used inside a clause. Use of <vp>predicate_fullname</vp> in other places causes a compile time error. See also [[#predicate_name|predicate_name]].

==== predicate_name ====

<vip>predicate_name : () -> string PredicateName.</vip>

This predicate returns the name <vp>PredicateName</vp> of the predicate in which it is invoked.

<vp>predicate_name</vp> can only be used inside a clause. Use of <vp>predicate_name</vp> in other places causes a compile time error. See also [[#predicate_fullname|predicate_fullname]]

==== programPoint ====

<vip>programPoint : () -> core::programPoint ProgramPoint.</vip>

This predicate returns the name <vp>programPoint</vp> corresponding to the place where it is invoked.

==== retract ====

<vip>retract : (<fact-term> FactTerm) nondeterm anyflow.</vip>

Successively removes the first matching fact from the facts database. Fails when no more facts match.

Call-template for this predicate is:

<vip>retract(FactTemplate)</vip>

Here <vp>FactTemplate</vp> should be a fact term. The <vp>retract/1</vp> predicate deletes the first fact that matches the <vp>FactTemplate</vp> in the appropriated facts database. During backtracking, the rest of the matching facts will be deleted.

Notice that <vp>FactTemplate</vp> can have any level of instantiation. The <vp>FactTemplate</vp> is matched with the facts in the facts database, which means that any free variables will be bound in the call to <vp>retract/1</vp>.

The <vp>FactTemplate</vp> can contain any anonymous variables. That is, variables with names consisting from the single underscore <vp>_</vp> or a variable with a name starting with an underscore <vp>_AnyValue</vp> if the variable occurs only once in the clause. For example.

<vip>retract(person("Hans", _Age)),</vip>

will retract the first matched person fact that has "<vp>Hans</vp>" as the first argument and anything as the second argument.

When retracting a fact, which is declared to be determ, the call to <vp>retract/1</vp> will be deterministic.

See also [[#retractall|retractall/1]] and [[#retractFactDb|retractFactDb]].

The <vp>retract/1</vp> predicate cannot be applied to single facts or fact variables.

Be careful calling <vp>retract/1</vp> with free <vp>FactTemplate</vp> variable if any single fact is declared in the project current scope. If you retract a single fact, then the run-time error is generated. The <vp>retract/1</vp> predicate fails when there are no more matches.

==== retractall ====

<vip>retractall : (<fact-term> FactTerm) .</vip>

Remove all matching facts from the facts database.

Call-template for this predicate is:

<vip>retractall(FactTemplate)</vip>

Here <vp>FactTemplate</vp> should be a fact term.

The <vp>retractall/1</vp> retracts all facts which match the given ''FactTemplate''. It always succeeds, even if no facts were retracted.

Attempting to retract a <vp>single</vp> fact will cause a compile time error.

It is not possible to obtain any output values from <vp>retractall/1</vp>. For this reason, the variables in the call must be bound or be a single underscores (anonymous). Notice that <vp>FactTemplate</vp> can have any level of instantiation, but free variables must be single underscores ("unconditionally anonymous"). In difference to [[#retract|retract/1]] "conditionally" anonymous variables with names starting from the underscore (like <vp>_AnyValue</vp>) cannot be used in <vp>retractall/1</vp>.

See also [[#retract|retract/1]] and [[#retractFactDb|retractFactDb/1]].

==== retractFactDb ====

<vip>retractFactDb : (factDB FactDB).</vip>

Remove all facts from the named internal facts database <vp>FactDB</vp>.

Call-template for this predicate is:

<vip>retractFactDb(FactDB)</vip>

The <vp>retractFactDb/1</vp> removes all facts from the named facts database <vp>FactDB</vp>.

Notice, it is impossible to retract <vp>single</vp> facts and fact variables, so the predicate leaves such ones as they are.

See also [[#retractall|retractall/1]] and [[#retract|retract/1]].

==== retractAll/2 ====

Obsolete predicate! Use [[#retractFactDb|retractFactDb/1]] instead.

==== sizeBitsOf ====

<vip>sizeBitsOf : (<domain> DomainName) -> unsigned BitSize.</vip>

Retrieves the number of bits occupied in memory by an entity of the specified domain <vp>DomainName</vp>.

Call-template for this function is:

<vip>BitSize = sizeBitsOf(DomainName)</vip>

This compiling-time predicate receives the domain <vp>DomainName</vp> as input parameter and return the size of memory that is occupied by the entity of the given domain. The result is measured in bits. For the integer domains <vp>sizeBitsOf/1-></vp> predicate returns the value that was defined for the size-field in a domain's declaration.

The following is always true for the integral domains:

<vip>sizeOfDomain(domain)*8 - 7 <= sizeBitsOf(domain) <= sizeOfDomain(domain)*8</vip>

See also [[#sizeOfDomain|sizeOfDomain]]/1->.

==== sizeOf ====

<vip>sizeOf : (Type Term) -> integer ByteSize.</vip>

Retrieves the number of bytes occupied in memory by the specified term <vp>Term</vp>.

Call-template for this function is:

<vip>ByteSize = sizeOf(Term)</vip>

The <vp>sizeOf/1-></vp> function receives a term as input parameter and returns value <vp>ByteSize</vp> that specifies the number of bytes occupied in memory by this term <vp>Term</vp>.

==== sizeOfDomain ====

<vip>sizeOfDomain : (<domain> Domain) -> integer ByteSize.</vip>

Retrieves the number of bytes occupied in memory by the entity of the specified domain <vp>DomainName</vp>.

Call-template for this function is:

<vip>ByteSize = sizeOfDomain(DomainName)</vip>

This compiling-time predicate receives the domain <vp>DomainName</vp> as input parameter and return the size of memory that is occupied by the entity of the given domain. The result is measured in bytes. The returned value <vp>ByteSize</vp> belongs to the integer domain. Compare with [[#sizeBitsOf|sizeBitsOf/1->]], which returns size of a domain measured in bits.

==== sourcefile_lineno ====

<vip>sourcefile_lineno : () -> unsigned LineNumber.</vip>

Returns the current line number in the source file processed by the compiler.

==== sourcefile_name ====

<vip>sourcefile_name : () -> string FileName.</vip>

Returns the name of the source file processed by the compiler.

==== sourcefile_timestamp ====

<vip>sourcefile_timestamp : () -> string TimeStamp..</vip>

Returns a string that represents the date and time of the currently compiled source file in format <vp>YYYY-MM-DD</vp> <vp>HH:mm:ss</vp>. Where:

* <vp>YYYY</vp> - Year.
* <vp>MM</vp> - Month.
* <vp>DD</vp> - Day.
* <vp>HH</vp> - Hour.
* <vp>mm</vp> - Minute.
* <vp>ssS</vp> - Second.

==== succeed ====

<vip>succeed : ().</vip>

The predicate <vp>succeed/0</vp> will always succeed.

==== toAny ====

<vip>toAny : (Term) -> any UniversalTypeValue.</vip>

Converts the specified <vp>Term</vp> to the value of universal term type <vp>any</vp>.

Call-template for this function is:

<vip>UniversalTypeValue = toAny(Term)</vip>

A term of the <vp>any</vp> domain can be converted back to its original type using the <vp>toTerm</vp> predicates (see {{lang2|Built-in entities/Predicates|toTerm|toTerm}}).

==== toBinary ====

<vip>toBinary : (Term) -> binary Serialized.</vip>

Converts the specified <vp>Term</vp> to [[#binary|binary]] representation.

Call-template for this function is:

<vip>Serialized = toBinary(Term)</vip>

When a <vp>Term</vp> (of some domain ''domainName'') is converted into a binary, it can safely be stored in a file or sent over a network to another program. Later the obtained binary value <vp>Serialized</vp> can be converted back to a Visual Prolog term, using [[#toTerm|toTerm/1->]] function (the domain for the reversed term should be adequate to ''domainName'') for the reverse conversion.

==== toBoolean ====

<vip>toBoolean : (<term> SubGoal) -> boolean Succeed.</vip>

The purpose of this meta-predicate is to convert the deterministic call (to a predicate or fact) to the procedure that returns the value of [[#boolean|boolean]] domain.

Call-template for this meta-predicate is:

<vip>True_or_False = toBoolean(deterministic_call)</vip>

The <vp>toBoolean/1-></vp> meta-predicate returns [[#boolean|boolean]] value. The result is <vp>true</vp> if ''deterministic_call'' succeeds. The result is <vp>false</vp> if ''deterministic_call'' fails.

==== toEllipsis ====

<vip>toEllipsis : (any* AnyTermList) -> ....</vip>

This predicate creates ''EllipsisBlock'' '''...''' (i.e. the special varying parameters block) from the list of terms of the universal type <vp>any</vp>. Such ''EllipsisBlock'' can be later passed to a predicate which expects the varying number of arguments (i.e. is declared with the ellipsis (''...'')), like <vp>write/...</vp>, at the position of the ellipsis (''...'').

Call-template for this function is:

<vip>EllipsisBlock = toEllipsis(<any_term_list>), write(EllipsisBlock)</vip>

See also [[#fromEllipsis|fromEllipsis/1->]].

==== toString ====

<vip>toString : (Term) -> string Serialized.</vip>

Converts the specified <vp>Term</vp> to string representation.

Call-template for this function is:

<vip>Serialized = toString(Term)</vip>

When a <vp>Term</vp> (of some domain ''domainName'') is converted into a string, it can safely be stored in a file or sent over a network to another program. Later the obtained string value can be converted back to a Visual Prolog term, using [[#toTerm|toTerm/1->]] function (the domain of the return value should be adequate to ''domainName'') for the reverse conversion.

==== toTerm ====

<vip>toTerm : (string Serialized) -> Term.
toTerm : (binary Serialized) -> Term.
toTerm : (any Serialized) -> Term.
toTerm : (<domain> Type, string Serialized) -> Term.
toTerm : (<domain> Type, binary Serialized) -> Term.
toTerm : (<domain> Type, any Serialized) -> Term.</vip>

Converts the string/binary/any representation of the specified term <vp>Serialized</vp> into representation corresponding to the domain of <vp>Term</vp> variable of the return value. The domain can be stated explicitly or it can be left to the compiler to determine a suitable domain.

Call-template for this function is:

<vip>Term = toTerm(Serialized) % with implicit domain
Term = toTerm(domainName, Serialized) % with explicit domain, domainName</vip>

If the domain is not specified the compiler must be able to determine the domain for the returned value <vp>Term</vp> at compile-time. Notice that binary version of <vp>toTerm</vp> predicate performs almost byte to byte conversion and only checking general compatibility of <vp>Serialized</vp> data with the domain required to the return value <vp>Term</vp>. The programmer is wholly responsible for providing binary data of <vp>Serialized</vp> that can be correctly converted to the term of the desired domain. The <vp>toTerm</vp> predicates are counterparts to predicates [[#toBinary|toBinary/1->]] and [[#toString|toString/1->]]. When a ''Term'' (of some domain ''domainName'') is converted into a binary or string representation <vp>Serialized</vp> (by [[#toBinary|toBinary/1->]] or [[#toString|toString/1->]] or [[#toAny|toAny/1->]] correspondingly), it can safely be stored in a file or sent over a network to another program. Later the corresponding <vp>toTerm/1</vp>-> function can convert the obtained string/binary value <vp>Serialized</vp> back to a Visual Prolog term <vp>Term</vp>. For correctness of the reverse conversion the domain of the clause variable <vp>Term</vp> should be adequate to the initial domain ''domainName''.

See also [[#tryToTerm|tryToTerm]].

It gives a compile time error if the compiler cannot determine the return domain.

Exceptions

* Run time errors are generated when the <vp>toTerm</vp> predicate cannot convert the string or binary into a term of the specified domain.

==== tryToTerm ====

<vip>tryToTerm : (string Serialized) -> Term.
tryToTerm : (binary Serialized) -> Term.
tryToTerm : (any Serialized) -> Term.
tryToTerm : (<domain> Type, string Serialized) -> Term.
tryToTerm : (<domain> Type, binary Serialized) -> Term.
tryToTerm : (<domain> Type, any Serialized) -> Term.</vip>

Converts the string/binary/any representation <vp>Serialized</vp> into a term <vp>Term</vp> like [[#toTerm|toTerm]]. The only difference between the predicates is that <vp>tryToTerm</vp> fails if it cannot convert the string or binary or any into a term of the specified domain whereas toTerm raises an exception.

See also [[#toTerm|toTerm]].

==== tryConvert ====

<vip>tryConvert : (<type> Type, Value) -> <type> Converted determ.</vip>

Checks whether the input term <vp>Value</vp> can be strictly converted into the specified domain <vp>Type</vp> and returns the converted term <vp>Converted</vp>.

Call-template for this function is:

<vip>ReturnTerm = tryConvert(returnDomain, InputTerm)</vip>

Arguments:

* <vp>returnDomain</vp>: Specifies a domain to which <vp>tryConvert/2-></vp> predicate tries to convert the specified <vp>InputTerm</vp>. Here ''returnDomain'' can be any domain accessible in the current scope. The domain name ''returnDomain'' must be specified at compile-time, i.e. it cannot come from a variable.
* <vpbnf><InputTerm></vpbnf>: Specifies the term that must be converted. <vp>InputTerm</vp> may be any Prolog term or an expression. If <vp>InputTerm</vp> is an expression, then it will be evaluated before conversion.
* <vpbnf><ReturnTerm></vpbnf>: Returned term <vp>ReturnTerm</vp> will be of ''returnDomain'' domain.

The conversion rules are the same as of the embedded predicate [[#convert|convert/2->]], but <vp>tryConvert/2-></vp> fails when [[#convert|convert/2->]] generates conversion errors.

This predicate succeeds if the corresponding conversion succeeds. Otherwise it fails. The <vp>tryConvert/2-></vp> predicate tries to perform a clean and genuine conversion of the given <vp>InputTerm</vp> into a value of the specified domain ''returnDomain''. The <vp>tryConvert/2-></vp> predicate will fail if the required conversion cannot be performed. When <vp>tryConvert/2-></vp> predicate succeeds, it returns the term <vp>ReturnTerm</vp> converted to the specified domain ''returnDomain''.

For allowed conversions and rules of checked explicit conversions see [[#convert|convert/2->]] predicate.

See also [[#uncheckedConvert|uncheckedConvert/2->]].

==== uncheckedConvert ====

<vip>uncheckedConvert : (<type> Type, Value) -> <type> Converted.</vip>

Unchecked conversion of a value to another type.

Call-template for this function is:

<vip>ReturnTerm = uncheckedConvert(returnDomain, InputTerm)</vip>

Arguments:

* <vp>returnDomain</vp>: Specifies a domain to which <vp>uncheckedConvert</vp> predicate unsafely converts the specified <vp>InputTerm</vp>. Here ''returnDomain'' can be any domain accessible in the current scope, the <vp>ReturnTerm</vp> should has the same bit-size as the <vp>InputTerm</vp>. The domain name ''returnDomain'' must be specified at compile-time, i.e. it cannot come from a variable.
* <vpbnf><InputTerm></vpbnf>: Specifies the value that must be converted. <vp>InputTerm</vp> may be any Prolog term or an expression. If ''InputTerm'' is an expression, then it will be evaluated before conversion.
* <vpbnf><ReturnTerm></vpbnf>: Returned parameter <vp>ReturnTerm</vp> will be of ''returnDomain'' type.

<vp>uncheckedConvert</vp> evaluates <vp>InputTerm</vp>, change the type to ''returnDomain'' without any modification of the memory pattern and unifies with <vp>ReturnTerm</vp>. The <vp>uncheckedConvert</vp> predicate performs no runtime checks. It makes only compile time checking of bit-size equality of the converted domains. So almost any term may be quite recklessly converted to any other term. So quite disastrous results may occur if you try to use variables incorrectly converted by <vp>uncheckedConvert</vp>. Be extremely careful implementing <vp>uncheckedConvert</vp>; we strongly recommend you always, when it is possible, using of [[#convert|convert/2->]] and [[#tryConvert|tryConvert/2->]]. But notice that, when an object is returned by COM system it is necessary to convert it by <vp>uncheckedConvert</vp>, as Prolog program does not have information about its actual type.

==== upperBound ====

<vip>upperBound : (<numeric-domain> NumericDomain) -> <number-domain> UpperBound.</vip>

Returns the upper bound value of the specified numeric domain.

Call-template for this function is:

<vip>UpperBound = upperBound(domainName)</vip>

The <vp>upperBound</vp> is a compiling-time predicate. The <vp>upperBound</vp> returns the upper bound value of the specified numeric domain ''domainName''. The return value <vp>UpperBound</vp> belongs to the same domain ''domainName''. The ''domainName'' parameter should be the name of any numerical domain; this domain name should be explicitly specified at compile-time (that is, ''domainName'' cannot come from a variable).

See also [[#lowerBound|lowerBound/1->]].

Will cause a compile time error if the specified domain ''domainName'' is not numeric domain.
<noinclude>{{LanguageReferenceSubarticle|Built-in entities/Predicates}}</noinclude>

Language Reference/Built-in entities/Predicates

2016-04-06T08:41:59Z

SergeMukhin: /* toEllipsis */

<noinclude>__NOTOC__</noinclude>

{|{{prettytable}}
|-
|[[Language_Reference/Terms#and_.28.2C.29|and/2]] [[Language_Reference/Terms#and_.28.2C.29|,/2]]
|Term "and"
|-
|[[#assert|assert/1]]
|Insert the specified fact at the end of the matched internal facts database.
|-
|[[#asserta|asserta/1]]
|Insert a fact at the beginning of the matched internal facts database.
|-
|[[#assertz|assertz/1]]
|Insert a fact at the end of the matched internal facts database.
|-
|[[#bound|bound/1]] <vp>determ</vp>
|Test whether the specified variable is bound to a value.
|-
|[[#class_name|class_name/0->]]
|This compile time predicate returns the string ''ClassName'' that represents the name of the current interface or class.
|-
|[[#compare|compare/2->]]
|Returns the result of the variables' comparison.
|-
|[[#convert|convert/2->]]
|Checked term conversion.
|-
|[[#digitsOf|digitsOf/1->]]
|Returns precision of the specified floating-point domain.
|-
|[[#errorExit|errorExit/1]] <vp>erroneous</vp>
|Performs a run-time error with the specified return code ''ErrorNumber'' and sets the internal error information.
|-
|[[#fail|fail/0]] <vp>failure</vp>
|Invoke backtracking.
|-
|[[#free|free/1]] <vp>determ</vp>
|Check whether a variable is free.
|-
|[[#fromEllipsis|fromEllipsis/1->]]
|Creates the list of terms of the universal type <vp>any</vp> from the ''EllipsisBlock''.
|-
|[[#hasDomain|hasDomain/2]] [[#hasDomain|hasDomain/2->]]
|Declares/restricts the type of a variable or value.
|-
|[[Language_Reference/Terms#in|in/2]] <vp>determ</vp> [[Language_Reference/Terms#in|in/2]] <vp>nondeterm</vp>
|Infix operator "in" (in-test and in-iterator).
|-
|[[#isErroneous|isErroneous/1]] <vp>determ</vp>
|Returns the lower bound value of the specified numeric domain.
|-
|[[#lowerBound|lowerBound/1->]]
|Returns the lower bound value of the specified numeric domain.
|-
|[[#maxDigits|maxDigits/1->]]
|Retrieves the value of digits (precision) of the basic domain corresponding to the specified floating-point domain ''domainName''.
|-
|[[#not|not/1]] <vp>determ</vp>
|Negate the result (success/fail) of subgoal.
|-
|[[Language_Reference/Terms#or_.28.3B.29|or/2]] [[Language_Reference/Terms#and_.28.3B.29|;/2]]
|Nondeterministic term "or"
|-
|[[Language_Reference/Terms#orelse|orelse]]
|Deterministic term "or"
|-
|[[#predicate_fullname|predicate_fullname/1->]]
|This compile time predicate returns the string ''PredicateFullName'' that represent the name of the predicate in which clause body <vp>predicate_name</vp> is called. The returned predicate name is qualified with a scope name.
|-
|[[#predicate_name|predicate_name/1->]]
|This compile time predicate returns the string ''PredicateName'' that represent the name of the predicate in which clause body <vp>predicate_name</vp> is called. The returned predicate name is not qualified with a scope name.
|-
|[[#programPoint|programPoint/0->]]
|This compile time predicate returns the <vp>programPoint</vp> corresponding to the place where it is called.
|-
|[[#retract|retract/1]] <vp>nondeterm</vp>
|Remove a matched fact from the matched internal facts database.
|-
|[[#retractall|retractall/1]]
|Remove all matching facts from the matched internal facts database.
|-
|[[#retractFactDb|retractFactDb/1]]
|Remove all facts from the specified named internal facts database.
|-
|[[#sizeBitsOf|sizeBitsOf/1->]]
|Retrieves the number of bits occupied in memory by an entity of the specified domain ''DomainName''.
|-
|[[#sizeOf|sizeOf/1->]]
|Retrieves the number of bytes occupied in memory by the specified term.
|-
|[[#sizeOfDomain|sizeOfDomain/1->]]
|Retrieves the number of bytes occupied in memory by the entity of the specified domain ''DomainName''.
|-
|[[#sourcefile_lineno|sourcefile_lineno/0->]]
|Returns the current line number in the source file processed by the compiler .
|-
|[[#sourcefile_name|sourcefile_name/0->]]
|Returns the name of the source file processed by the compiler.
|-
|[[#sourcefile_timestamp|sourcefile_timestamp/0->]]
|Returns the string representing the date and time of the source file processed by the compiler.
|-
|[[#succeed|succeed/0]]
|The predicate <vp>succeed/0</vp> will always succeed.
|-
|[[#toAny|toAny/1->]]
|Converts the specified ''Term'' to the value of the universal term type <vp>any</vp>.
|-
|[[#toBinary|toBinary/1->]]
|Converts the specified Term to the binary representation.
|-
|[[#toBoolean|toBoolean/1->]]
|The purpose of this meta-predicate is to convert the deterministic call (to a predicate or fact) to the procedure that returns the value of <vp>boolean</vp> domain.
|-
|[[#toEllipsis|toEllipsis/1->]]
|Creates the ''EllipsisBlock'' from the list of <vp>any</vp> type values.
|-
|[[#toString|toString/1->]]
|Converts the specified ''Term'' to the string representation.
|-
|[[#toTerm|toTerm/1->]] [[#toTerm|toTerm/2->]]
|Converts the string/binary representation of the specified term ''SrcTerm'' into representation corresponding to the domain of ''PrologTerm'' variable of the return value.
|-
|[[#tryToTerm|tryToTerm/1->]] <vp>determ</vp> [[#tryToTerm|tryToTerm/2->]] <vp>determ</vp>
|Converts the string/binary representation of the specified term ''SrcTerm'' into representation corresponding to the domain of ''PrologTerm'' variable of the return value.
|-
|[[#tryConvert|tryConvert/2->]] <vp>determ</vp>
|Checks whether the input term ''InputTerm'' can be strictly converted into the specified domain ''returnDomain'' and returns the converted term ''ReturnTerm''.
|-
|[[#uncheckedConvert|uncheckedConvert/2->]]
|Unchecked conversion of domains.
|-
|[[#upperBound|upperBound/1->]]
|Returns the upper bound value of the specified numeric domain.
|}

The following predicates are deprecated:
{|{{prettytable}}
|-
| finally/2
| Use [[Language_Reference/Terms#try-finally| <vp>try-finally</vp>]] constuction instead.
|-
| findall/3
| Use list comprehension [[Language_Reference/Terms#List_Comprehension| <vp>[ ... || ... ]</vp>]] instead
|-
| trap/3 <vp>determ</vp>
| Use [[Language_Reference/Terms#try-catch| <vp>try-catch</vp>]] constuction instead.
|}

==== and ====

See [[Language_Reference/Terms#and_.28.2C.29|and (,)]].

==== assert ====

<vip>assert : (<fact-term> FactTerm).</vip>

Insert the specified fact at the end of the matched internal facts database

<vp>assert(Fact)</vp> inserts <vp>Fact</vp> in the matched internal facts database after any other stored facts for the corresponding database predicate. <vp>Fact</vp> must be a term belonging to the domain of an internal facts database. <vp>assert/1</vp> applied to a single fact changes the existing instance of a fact to the specified one. <vp>assert/1</vp> has the same effect as [[#assertz|assertz/1]]. See also [[#asserta|asserta/1]].

Notice that the combination of [[#retract|retract/1]] and <vp>assert/1</vp> like the following can lead to endless loop:

<vip>loop() :-
retract(fct(X)),
... % creating Y from X
assert(fct(Y)),
fail.</vip>

The problem is that the retract in first line will eventually retract the fact asserted in the last line, because that fact is inserted ''last'' in the fact chain.

Exceptions:

* Attempt to assert a second instance to a fact declared as determ.

==== asserta ====

<vip>asserta : (<fact-term> FactTerm).</vip>

Insert a fact at the beginning of the matched internal facts database.

The <vp>asserta(Fact)</vp> predicate inserts a <vp>Fact</vp> in the matched internal facts database before any other stored facts for the corresponding predicate. The <vp>Fact</vp> must be a term belonging to the domain of an internal facts database. The <vp>asserta/1</vp> applied to a single fact changes the existing instance of a fact to the specified one. See also [[#assert|assert/1]] and [[#assertz|assertz/1]].

Exceptions:

* Attempt to a fact declared as determ, but the fact instance already exists.

==== assertz ====

<vip>assertz : (<fact-term> FactTerm).</vip>

<vp>assertz</vp> does exactly the same as the [[#assert|assert/1]] predicate.

==== bound ====

<vip>bound : (<variable> Variable) determ.</vip>

Test whether the specified variable is bound to a value.

The <vp>bound(Variable)</vp> succeeds if <vp>Variable</vp> is bound and fails if it is free. The <vp>bound</vp> predicate is used to control flow patterns and to check the binding of reference variables. The <vp>bound</vp> predicate treats the specified <vp>Variable</vp> as bound if any of it's part is instantiated.

See also [[#free|free/1]].

==== class_name ====

<vip>class_Name : () -> string ClassName.</vip>

This compile time predicate returns the string <vp>ClassName</vp> that represents the name of the current interface or class.

==== compare ====

<vip>compare : (A Left, A Right) -> compareResult CompareResult.</vip>

Comparison of two terms of the same domain, resturns the value of [[#compareResult|compareResult]] domain.

<vp>CompareResult</vp> = compare("<vp>bar</vp>", "<vp>foo</vp>")

==== convert ====

<vip>convert : (<type> Type, Term) -> <type> Converted.</vip>

Checked term conversion.

Call-template for this function is:

<vp>ReturnTerm</vp> = convert(returnDomain, <vp>InputTerm</vp>)

* <vpbnf>returnDomain</vpbnf>: Specifies a domain to which function <vp>convert/2-></vp> converts <vp>InputTerm</vp>. Here ''returnDomain'' must be a name of built-in Visual Prolog domain, an interface domain, a name of such user defined domain that is synonym to one of built-in Visual Prolog domains, a numeric domain, binary and pointer domains. The domain name ''returnDomain'' must be specified at compile-time, i.e. it cannot come from a variable.

* <vpbnf><InputTerm></vpbnf>: Specifies the value that must be converted. <vp>InputTerm</vp> may be any Prolog term or an expression. If <vp>InputTerm</vp> is an expression, then it will be evaluated before the conversion.

* <vpbnf><ReturnTerm></vpbnf>: Returned parameter <vp>ReturnTerm</vp> will be of ''returnDomain'' type.

The <vp>convert</vp> predicate performs a clean and genuine conversion of the given <vp>InputTerm</vp>, returning a new term <vp>ReturnTerm</vp> of the specified new domain ''returnDomain''. If <vp>convert</vp> cannot perform the required conversion, it rises errors. The similar functionality is provided by the [[#tryConvert|tryConvert/2->]] predicate, but <vp>tryConvert-></vp> fails and does not produce any runtime errors if it cannot perform the conversion.

===== Allowed conversions =====

* Between numerical domains.
* Between interface types.
* Between [[#string|string]] and [[#symbol|symbol]] domains.
* From [[#binary|binary]] to [[#pointer|pointer]].
* For synonyms of mentioned domains.
* Between [http://wiki.visual-prolog.com/index.php?title=How_To_Remove_Reference_Domains_from_a_Project reference] domains and corresponding non-reference domains.

The contrast to these is [[#uncheckedConvert|uncheckedConvert/2->]] predicate, which performs an unchecked conversion between terms from any domains, which have the same bit-size.

The <vp>convert/2-></vp> (or [[#tryConvert|tryConvert/2->]]) predicate accomplishes a checked explicit conversion, when the source and target domains are statically known during the compilation. The result of an explicit conversion can be one of the following:

* '''ok''' the successful conversion to the target domain;
* '''run-time-check''' the conversion to the target domain with generation of run-time checking for compatibility;
* '''error''' the conversion is impossible, error output.

===== Rules of Checked Explicit Conversions =====

* Synonyms of domains are converted using the same rules that are applied to the domains themselves.
* Numerical domains can be converted to the numerical domains only.
* Integral constants are the representatives of the anonymous integral domain: <vp>[const .. const]</vp>.
* Real constants are the representatives of the anonymous real domain: <vp>digits</vp> <vp>dig [const .. const]</vp>, where <vp>dig</vp> is the number of the digits in mantissa without insignificant zeroes.
* A value of the symbol domain can be converted to the string domain and vice versa.
* A value of binary domain can be converted to the pointer domain.
* The domains that are implicitly introduced for interfaces can be converted only to the interface domains according to the rules specified below.
* All other domains cannot be converted.

===== Conversions of Numerical Domains =====

* The range is considered first during such conversion. If the ranges of source and target do not intersect, then an error is produced. If the ranges of source and target only partially intersect, then run-time checking is generated. Also, if one of domains is real and another is an integral one, then the integer range is converted to the real range before the comparison.
* When input term in real and output is integer, then <vp>convert/2-></vp> and [[#tryConvert|tryConvert/2->]] predicates truncate the input value to the nearest integer value, which is nearer to zero.

===== Conversions of Interface Types =====

Predicate <vp>convert/2-></vp> allow to convert any object to any interface type. The actual correctness of such conversion is checked at runtime. When object is created, its type is internally stored, therefore when the object is passed as argument it still remember about its original type. This original type is used for checking allowed conversions. The example:

<vip>interface x
supports a, b
end interface x</vip>

If object is created by class, which implements <vp>x</vp> interface, and then object is passed as parameter of type <vp>a</vp> to some predicate, then it is allowed to convert the object to <vp>b</vp> type.

Exceptions:

* Check range error.
* Unsupported interface type.

==== digitsOf ====

<vip>digitsOf : (<real-domain> Domain) -> unsigned.</vip>

Returns precision of the specified floating-point domain.

Call-template for this function is:

<vip>Precision = digitsof(domainName)</vip>

The input parameter ''domainName'' of this compiling-time predicate is a floating-point domain, it should be explicitly specified at compile-time (that is, ''domainName'' cannot come from a variable). The predicate returns the number <vpbnf><Precision></vpbnf> that was determined by the <vp>digits</vp> attribute in the domain declaration.

The compiler guarantees that values of the domain ''domainName'' will have at least <vpbnf><Precision></vpbnf> number of significant decimal digits.

==== errorExit ====

<vip>errorExit : (unsigned ErrorNumber) erroneous.</vip>

Performs a run-time error with the specified return code <vp>ErrorNumber</vp>, which can be used in the [[#try-catch-finally|try-catch-finally]].

==== fail ====

<vip>fail : () failure.</vip>

The <vp>fail</vp> predicate forces failure and, hence, always causes backtracking. A clause that fails (with <vp>fail</vp> or for some other reason) cannot bind output arguments.

==== free ====

<vip>free : (<variableName> Variable) determ.</vip>

Check whether a variable is free.

Call-template for this predicate is:

<vip>free(Variable)</vip>

The <vp>free</vp> predicate succeeds if the specified <vp>Variable</vp> is free and fails if <vp>Variable</vp> is bound. The <vp>free</vp> predicate treats the specified <vp>Variable</vp> as bound if any of it's part are instantiated.

See also [[#bound|bound/1]].

==== fromEllipsis ====

<vip>fromEllipsis : (...) -> any* AnyTermList.</vip>

This predicate creates the list of terms of the universal type <vp>any</vp> from the ''EllipsisBlock'' '''...''' (i.e. from the special varying parameters block).

Call-template for this function is:

<vip>AnyTermList = fromEllipsis(EllipsisBlock )</vip>

See also [[#toEllipsis|toEllipsis/1->]].

==== hasDomain ====

<vp>hasDomain</vp> is not really a predicate, but more a type declaration/restriction. It has two forms a non-function for declaring/restricting the type of a variable and a function form for declaring/restricting the type of a value.

The non-function form is called with a type as first parmeter and a variable as second parameter.

<vip>hasDomain : (<type> Type, Type Variable).</vip>

The only effect of the call is that the <vp>Variable</vp> will be restricted to the type <vp>Type</vp>.

The variable can be free, bound or of some mixed flow and the binding of the variable will not change in any way.

The function form is called with a type as first argument and a value as second argument, and it returns the same value.

<vip>hasDomain : (<type> Type, Type Value) -> Type Value.</vip>

The only effect of the call is to ensure that the <vp>Value</vp> will be restricted to the type <vp>Type</vp>.

==== lowerBound ====

<vip>lowerBound : (<numeric-domain> NumericDomain) -> <numeric-domain> LowerBound.</vip>

Returns the lower bound of the specified <vp>NumericDomain</vp>.

Call-template for this function is:

<vip>LowerBoundValue = lowerBound(domainName)</vip>

The <vp>lowerBound</vp> is a compiling-time predicate. The <vp>lowerBound</vp> returns the lower bound value <vp>LowerBoundValue</vp> of the specified numeric domain ''domainName''. The return value <vp>LowerBoundValue</vp> belongs to the same domain ''domainName''. The ''domainName'' parameter should be the name of any numerical domain; this domain name should be explicitly specified at compile-time (that is, ''domainName'' cannot come from a variable). See also [[#upperBound|upperBound/1->]].

It will give a compile time error if the specified domain ''domainName'' is not numeric domain.

==== in ====

See [[Language_Reference/Terms#in|in/2]].

==== isErroneous ====

<vip>isErroneous : (<fact-variable> FactVariable) determ.</vip>

The predicate succeeds if the specified fact variable is <vp>erroneous</vp>.

Call-template for this predicate is:

<vip>isErroneous(factVariableName)</vip>

The predicate succeeds if the specified fact variable <vp>factVariableName</vp> has the <vp>erroneous</vp> value, otherwise it fails.

==== maxDigits ====

<vip>maxDigits : (<real-domain> RealDomain) -> unsigned MaxDigits</vip>

Retrieves the value of digits (precision) of the basic domain corresponding to the specified floating-point domain <vp>RealDomain</vp>.

Call-template for this function is:

<vip>MaxDigitsNumber = maxdigits(domainName)</vip>

The return maximal number of digits <vp>MaxDigitsNumber</vp> for the ''domainName'' parameter, which should be the name of a <vp>real</vp> domain.

==== not ====

See [[Language_Reference/Terms#not|not]].

==== or ====

See [[Language_Reference/Terms#or_.28.3B.29|or (;)]].

==== orelse ====

See [[Language_Reference/Terms#orelse|orelse]].

==== predicate_fullname ====

<vip>predicate_fullname : () -> string PredicateFullName.</vip>

This predicate returns the name <vp>PredicateFullName</vp> of the predicate in which it is invoked. The returned predicate name is qualified with a scope name.

<vp>predicate_fullname</vp> can only be used inside a clause. Use of <vp>predicate_fullname</vp> in other places causes a compile time error. See also [[#predicate_name|predicate_name]].

==== predicate_name ====

<vip>predicate_name : () -> string PredicateName.</vip>

This predicate returns the name <vp>PredicateName</vp> of the predicate in which it is invoked.

<vp>predicate_name</vp> can only be used inside a clause. Use of <vp>predicate_name</vp> in other places causes a compile time error. See also [[#predicate_fullname|predicate_fullname]]

==== programPoint ====

<vip>programPoint : () -> core::programPoint ProgramPoint.</vip>

This predicate returns the name <vp>programPoint</vp> corresponding to the place where it is invoked.

==== retract ====

<vip>retract : (<fact-term> FactTerm) nondeterm anyflow.</vip>

Successively removes the first matching fact from the facts database. Fails when no more facts match.

Call-template for this predicate is:

<vip>retract(FactTemplate)</vip>

Here <vp>FactTemplate</vp> should be a fact term. The <vp>retract/1</vp> predicate deletes the first fact that matches the <vp>FactTemplate</vp> in the appropriated facts database. During backtracking, the rest of the matching facts will be deleted.

Notice that <vp>FactTemplate</vp> can have any level of instantiation. The <vp>FactTemplate</vp> is matched with the facts in the facts database, which means that any free variables will be bound in the call to <vp>retract/1</vp>.

The <vp>FactTemplate</vp> can contain any anonymous variables. That is, variables with names consisting from the single underscore <vp>_</vp> or a variable with a name starting with an underscore <vp>_AnyValue</vp> if the variable occurs only once in the clause. For example.

<vip>retract(person("Hans", _Age)),</vip>

will retract the first matched person fact that has "<vp>Hans</vp>" as the first argument and anything as the second argument.

When retracting a fact, which is declared to be determ, the call to <vp>retract/1</vp> will be deterministic.

See also [[#retractall|retractall/1]] and [[#retractFactDb|retractFactDb]].

The <vp>retract/1</vp> predicate cannot be applied to single facts or fact variables.

Be careful calling <vp>retract/1</vp> with free <vp>FactTemplate</vp> variable if any single fact is declared in the project current scope. If you retract a single fact, then the run-time error is generated. The <vp>retract/1</vp> predicate fails when there are no more matches.

==== retractall ====

<vip>retractall : (<fact-term> FactTerm) .</vip>

Remove all matching facts from the facts database.

Call-template for this predicate is:

<vip>retractall(FactTemplate)</vip>

Here <vp>FactTemplate</vp> should be a fact term.

The <vp>retractall/1</vp> retracts all facts which match the given ''FactTemplate''. It always succeeds, even if no facts were retracted.

Attempting to retract a <vp>single</vp> fact will cause a compile time error.

It is not possible to obtain any output values from <vp>retractall/1</vp>. For this reason, the variables in the call must be bound or be a single underscores (anonymous). Notice that <vp>FactTemplate</vp> can have any level of instantiation, but free variables must be single underscores ("unconditionally anonymous"). In difference to [[#retract|retract/1]] "conditionally" anonymous variables with names starting from the underscore (like <vp>_AnyValue</vp>) cannot be used in <vp>retractall/1</vp>.

See also [[#retract|retract/1]] and [[#retractFactDb|retractFactDb/1]].

==== retractFactDb ====

<vip>retractFactDb : (factDB FactDB).</vip>

Remove all facts from the named internal facts database <vp>FactDB</vp>.

Call-template for this predicate is:

<vip>retractFactDb(FactDB)</vip>

The <vp>retractFactDb/1</vp> removes all facts from the named facts database <vp>FactDB</vp>.

Notice, it is impossible to retract <vp>single</vp> facts and fact variables, so the predicate leaves such ones as they are.

See also [[#retractall|retractall/1]] and [[#retract|retract/1]].

==== retractAll/2 ====

Obsolete predicate! Use [[#retractFactDb|retractFactDb/1]] instead.

==== sizeBitsOf ====

<vip>sizeBitsOf : (<domain> DomainName) -> unsigned BitSize.</vip>

Retrieves the number of bits occupied in memory by an entity of the specified domain <vp>DomainName</vp>.

Call-template for this function is:

<vip>BitSize = sizeBitsOf(DomainName)</vip>

This compiling-time predicate receives the domain <vp>DomainName</vp> as input parameter and return the size of memory that is occupied by the entity of the given domain. The result is measured in bits. For the integer domains <vp>sizeBitsOf/1-></vp> predicate returns the value that was defined for the size-field in a domain's declaration.

The following is always true for the integral domains:

<vip>sizeOfDomain(domain)*8 - 7 <= sizeBitsOf(domain) <= sizeOfDomain(domain)*8</vip>

See also [[#sizeOfDomain|sizeOfDomain]]/1->.

==== sizeOf ====

<vip>sizeOf : (Type Term) -> integer ByteSize.</vip>

Retrieves the number of bytes occupied in memory by the specified term <vp>Term</vp>.

Call-template for this function is:

<vip>ByteSize = sizeOf(Term)</vip>

The <vp>sizeOf/1-></vp> function receives a term as input parameter and returns value <vp>ByteSize</vp> that specifies the number of bytes occupied in memory by this term <vp>Term</vp>.

==== sizeOfDomain ====

<vip>sizeOfDomain : (<domain> Domain) -> integer ByteSize.</vip>

Retrieves the number of bytes occupied in memory by the entity of the specified domain <vp>DomainName</vp>.

Call-template for this function is:

<vip>ByteSize = sizeOfDomain(DomainName)</vip>

This compiling-time predicate receives the domain <vp>DomainName</vp> as input parameter and return the size of memory that is occupied by the entity of the given domain. The result is measured in bytes. The returned value <vp>ByteSize</vp> belongs to the integer domain. Compare with [[#sizeBitsOf|sizeBitsOf/1->]], which returns size of a domain measured in bits.

==== sourcefile_lineno ====

<vip>sourcefile_lineno : () -> unsigned LineNumber.</vip>

Returns the current line number in the source file processed by the compiler.

==== sourcefile_name ====

<vip>sourcefile_name : () -> string FileName.</vip>

Returns the name of the source file processed by the compiler.

==== sourcefile_timestamp ====

<vip>sourcefile_timestamp : () -> string TimeStamp..</vip>

Returns a string that represents the date and time of the currently compiled source file in format <vp>YYYY-MM-DD</vp> <vp>HH:MM:SS</vp>. Where:

* <vp>YYYY</vp> - Year.
* <vp>MM</vp> - Month.
* <vp>DD</vp> - Day.
* <vp>HH</vp> - Hour.
* <vp>MM</vp> - Minute.
* <vp>SS</vp> - Second.

==== succeed ====

<vip>succeed : ().</vip>

The predicate <vp>succeed/0</vp> will always succeed.

==== toAny ====

<vip>toAny : (Term) -> any UniversalTypeValue.</vip>

Converts the specified <vp>Term</vp> to the value of universal term type <vp>any</vp>.

Call-template for this function is:

<vip>UniversalTypeValue = toAny(Term)</vip>

A term of the <vp>any</vp> domain can be converted back to its original type using the <vp>toTerm</vp> predicates (see {{lang2|Built-in entities/Predicates|toTerm|toTerm}}).

==== toBinary ====

<vip>toBinary : (Term) -> binary Serialized.</vip>

Converts the specified <vp>Term</vp> to [[#binary|binary]] representation.

Call-template for this function is:

<vip>Serialized = toBinary(Term)</vip>

When a <vp>Term</vp> (of some domain ''domainName'') is converted into a binary, it can safely be stored in a file or sent over a network to another program. Later the obtained binary value <vp>Serialized</vp> can be converted back to a Visual Prolog term, using [[#toTerm|toTerm/1->]] function (the domain for the reversed term should be adequate to ''domainName'') for the reverse conversion.

==== toBoolean ====

<vip>toBoolean : (<term> SubGoal) -> boolean Succeed.</vip>

The purpose of this meta-predicate is to convert the deterministic call (to a predicate or fact) to the procedure that returns the value of [[#boolean|boolean]] domain.

Call-template for this meta-predicate is:

<vip>True_or_False = toBoolean(deterministic_call)</vip>

The <vp>toBoolean/1-></vp> meta-predicate returns [[#boolean|boolean]] value. The result is <vp>true</vp> if ''deterministic_call'' succeeds. The result is <vp>false</vp> if ''deterministic_call'' fails.

==== toEllipsis ====

<vip>toEllipsis : (any* AnyTermList) -> ....</vip>

This predicate creates ''EllipsisBlock'' '''...''' (i.e. the special varying parameters block) from the list of terms of the universal type <vp>any</vp>. Such ''EllipsisBlock'' can be later passed to a predicate which expects the varying number of arguments (i.e. is declared with the ellipsis (''...'')), like <vp>write/...</vp>, at the position of the ellipsis (''...'').

Call-template for this function is:

<vip>EllipsisBlock = toEllipsis(<any_term_list>), write(EllipsisBlock)</vip>

See also [[#fromEllipsis|fromEllipsis/1->]].

==== toString ====

<vip>toString : (Term) -> string Serialized.</vip>

Converts the specified <vp>Term</vp> to string representation.

Call-template for this function is:

<vip>Serialized = toString(Term)</vip>

When a <vp>Term</vp> (of some domain ''domainName'') is converted into a string, it can safely be stored in a file or sent over a network to another program. Later the obtained string value can be converted back to a Visual Prolog term, using [[#toTerm|toTerm/1->]] function (the domain of the return value should be adequate to ''domainName'') for the reverse conversion.

==== toTerm ====

<vip>toTerm : (string Serialized) -> Term.
toTerm : (binary Serialized) -> Term.
toTerm : (any Serialized) -> Term.
toTerm : (<domain> Type, string Serialized) -> Term.
toTerm : (<domain> Type, binary Serialized) -> Term.
toTerm : (<domain> Type, any Serialized) -> Term.</vip>

Converts the string/binary/any representation of the specified term <vp>Serialized</vp> into representation corresponding to the domain of <vp>Term</vp> variable of the return value. The domain can be stated explicitly or it can be left to the compiler to determine a suitable domain.

Call-template for this function is:

<vip>Term = toTerm(Serialized) % with implicit domain
Term = toTerm(domainName, Serialized) % with explicit domain, domainName</vip>

If the domain is not specified the compiler must be able to determine the domain for the returned value <vp>Term</vp> at compile-time. Notice that binary version of <vp>toTerm</vp> predicate performs almost byte to byte conversion and only checking general compatibility of <vp>Serialized</vp> data with the domain required to the return value <vp>Term</vp>. The programmer is wholly responsible for providing binary data of <vp>Serialized</vp> that can be correctly converted to the term of the desired domain. The <vp>toTerm</vp> predicates are counterparts to predicates [[#toBinary|toBinary/1->]] and [[#toString|toString/1->]]. When a ''Term'' (of some domain ''domainName'') is converted into a binary or string representation <vp>Serialized</vp> (by [[#toBinary|toBinary/1->]] or [[#toString|toString/1->]] or [[#toAny|toAny/1->]] correspondingly), it can safely be stored in a file or sent over a network to another program. Later the corresponding <vp>toTerm/1</vp>-> function can convert the obtained string/binary value <vp>Serialized</vp> back to a Visual Prolog term <vp>Term</vp>. For correctness of the reverse conversion the domain of the clause variable <vp>Term</vp> should be adequate to the initial domain ''domainName''.

See also [[#tryToTerm|tryToTerm]].

It gives a compile time error if the compiler cannot determine the return domain.

Exceptions

* Run time errors are generated when the <vp>toTerm</vp> predicate cannot convert the string or binary into a term of the specified domain.

==== tryToTerm ====

<vip>tryToTerm : (string Serialized) -> Term.
tryToTerm : (binary Serialized) -> Term.
tryToTerm : (any Serialized) -> Term.
tryToTerm : (<domain> Type, string Serialized) -> Term.
tryToTerm : (<domain> Type, binary Serialized) -> Term.
tryToTerm : (<domain> Type, any Serialized) -> Term.</vip>

Converts the string/binary/any representation <vp>Serialized</vp> into a term <vp>Term</vp> like [[#toTerm|toTerm]]. The only difference between the predicates is that <vp>tryToTerm</vp> fails if it cannot convert the string or binary or any into a term of the specified domain whereas toTerm raises an exception.

See also [[#toTerm|toTerm]].

==== tryConvert ====

<vip>tryConvert : (<type> Type, Value) -> <type> Converted determ.</vip>

Checks whether the input term <vp>Value</vp> can be strictly converted into the specified domain <vp>Type</vp> and returns the converted term <vp>Converted</vp>.

Call-template for this function is:

<vip>ReturnTerm = tryConvert(returnDomain, InputTerm)</vip>

Arguments:

* <vp>returnDomain</vp>: Specifies a domain to which <vp>tryConvert/2-></vp> predicate tries to convert the specified <vp>InputTerm</vp>. Here ''returnDomain'' can be any domain accessible in the current scope. The domain name ''returnDomain'' must be specified at compile-time, i.e. it cannot come from a variable.
* <vpbnf><InputTerm></vpbnf>: Specifies the term that must be converted. <vp>InputTerm</vp> may be any Prolog term or an expression. If <vp>InputTerm</vp> is an expression, then it will be evaluated before conversion.
* <vpbnf><ReturnTerm></vpbnf>: Returned term <vp>ReturnTerm</vp> will be of ''returnDomain'' domain.

The conversion rules are the same as of the embedded predicate [[#convert|convert/2->]], but <vp>tryConvert/2-></vp> fails when [[#convert|convert/2->]] generates conversion errors.

This predicate succeeds if the corresponding conversion succeeds. Otherwise it fails. The <vp>tryConvert/2-></vp> predicate tries to perform a clean and genuine conversion of the given <vp>InputTerm</vp> into a value of the specified domain ''returnDomain''. The <vp>tryConvert/2-></vp> predicate will fail if the required conversion cannot be performed. When <vp>tryConvert/2-></vp> predicate succeeds, it returns the term <vp>ReturnTerm</vp> converted to the specified domain ''returnDomain''.

For allowed conversions and rules of checked explicit conversions see [[#convert|convert/2->]] predicate.

See also [[#uncheckedConvert|uncheckedConvert/2->]].

==== uncheckedConvert ====

<vip>uncheckedConvert : (<type> Type, Value) -> <type> Converted.</vip>

Unchecked conversion of a value to another type.

Call-template for this function is:

<vip>ReturnTerm = uncheckedConvert(returnDomain, InputTerm)</vip>

Arguments:

* <vp>returnDomain</vp>: Specifies a domain to which <vp>uncheckedConvert</vp> predicate unsafely converts the specified <vp>InputTerm</vp>. Here ''returnDomain'' can be any domain accessible in the current scope, the <vp>ReturnTerm</vp> should has the same bit-size as the <vp>InputTerm</vp>. The domain name ''returnDomain'' must be specified at compile-time, i.e. it cannot come from a variable.
* <vpbnf><InputTerm></vpbnf>: Specifies the value that must be converted. <vp>InputTerm</vp> may be any Prolog term or an expression. If ''InputTerm'' is an expression, then it will be evaluated before conversion.
* <vpbnf><ReturnTerm></vpbnf>: Returned parameter <vp>ReturnTerm</vp> will be of ''returnDomain'' type.

<vp>uncheckedConvert</vp> evaluates <vp>InputTerm</vp>, change the type to ''returnDomain'' without any modification of the memory pattern and unifies with <vp>ReturnTerm</vp>. The <vp>uncheckedConvert</vp> predicate performs no runtime checks. It makes only compile time checking of bit-size equality of the converted domains. So almost any term may be quite recklessly converted to any other term. So quite disastrous results may occur if you try to use variables incorrectly converted by <vp>uncheckedConvert</vp>. Be extremely careful implementing <vp>uncheckedConvert</vp>; we strongly recommend you always, when it is possible, using of [[#convert|convert/2->]] and [[#tryConvert|tryConvert/2->]]. But notice that, when an object is returned by COM system it is necessary to convert it by <vp>uncheckedConvert</vp>, as Prolog program does not have information about its actual type.

==== upperBound ====

<vip>upperBound : (<numeric-domain> NumericDomain) -> <number-domain> UpperBound.</vip>

Returns the upper bound value of the specified numeric domain.

Call-template for this function is:

<vip>UpperBound = upperBound(domainName)</vip>

The <vp>upperBound</vp> is a compiling-time predicate. The <vp>upperBound</vp> returns the upper bound value of the specified numeric domain ''domainName''. The return value <vp>UpperBound</vp> belongs to the same domain ''domainName''. The ''domainName'' parameter should be the name of any numerical domain; this domain name should be explicitly specified at compile-time (that is, ''domainName'' cannot come from a variable).

See also [[#lowerBound|lowerBound/1->]].

Will cause a compile time error if the specified domain ''domainName'' is not numeric domain.
<noinclude>{{LanguageReferenceSubarticle|Built-in entities/Predicates}}</noinclude>

Logging

2015-11-19T13:44:20Z

SergeMukhin:

=Overview=

Logging in Prolog currently supports logging to console, file, event log, database table, PDC notification log (to be done). Logging is thread safe and even supported for several processes that are writing to the same log. Application can also simultaneously log to several logs including logging to several files and/or database tables. Logging performance does not depend on log type. It is very fast operation and done asynchronously meaning that logging message placed into the message queue, which is processed in background thread.

=Log configuration=

Log configuration file (has .XML format) defines where applications logs the information.
Here is the log configuration file example:

<syntaxhighlight lang=xml>
<?xml version="1.0" encoding="utf-8"?>
<LogConfigurations>
<LogConfig name="ConfigName0">
<Appenders>
<Appender name="AppenderName0">
<LogLevel>all</LogLevel>
<Type>console</Type>
<PatternLayout>%username: %thread - %msg</PatternLayout>
</Appender>
</Appenders>
</LogConfig>

<LogConfig name="ConfigName1">

<Appenders>

<Appender name="AppenderName1">

<LogLevel>all</LogLevel>

<Type>event</Type>

<Target>Helpdeskdashboard</Target>

<PatternLayout>\[%lineno\] %userid %proc:%thread %datetime %msg
</PatternLayout>
<filter>class:entityModel;method:aaa</filter>

</Appender>

<Appender name="AppenderName2">

<LogLevel>all</LogLevel>

<Type>file</Type>

<Target>log.txt</Target>

<PatternLayout>\[%lineno\] %userid(%username) \[%callerClassName/%callerPredicateName/%callerCursor\]%newline %proc:%thread time=%time dt=%datetime %msg(%msglevel)</PatternLayout>

<filter>class:entityModel;method:aaa</filter>

</Appender>

<Appender name="AppenderName3">

<LogLevel>all</LogLevel>

<Type>dbtable</Type>

<PatternLayout>%userid %proc:%thread %datetime %msg</PatternLayout>

<filter>class:entityModel;method:aaa</filter>

</Appender>

<Appender name="AppenderName4">

<LogLevel>all</LogLevel>

<Type>console</Type>

<PatternLayout>%userid %proc:%thread %datetime %msg</PatternLayout>

<filter>class:entityModel;method:aaa</filter>

</Appender>

</Appenders>

</LogConfig>

<LogConfig name="ODBCTable">

<Appenders>

<Appender name="AppenderName4">

<LogLevel>all</LogLevel>

<Type>odbcAsync</Type>

<Target>wwLogging</Target>

<ConnectionString>Driver=\{SQL Server\};Server=WEB1.dmz.hc\SQLEXPRESS;Database=Helpdesk_test;UID=xxx;PWD=yyy;app=HelpdeskDashboard</ConnectionString>

<ColumnInfo>

<Column name="level" attribute="msglevel"></Column>

<Column name="linenumber" attribute ="lineno"></Column>

<Column name="username" attribute ="username"></Column>

<Column name="userID" attribute ="userid"></Column>

<Column name="procid" attribute ="proc"></Column>

<Column name="thread" attribute ="thread"></Column>

<Column name="datetime" attribute ="datetime"></Column>

<Column name="time" attribute ="datetime"></Column>

<Column name="callerClassNameElem" attribute ="callerclassname"></Column>

<Column name="callerPredicateNameElem" attribute ="callerpredicatename"></Column>

<Column name="callerCursorElem" attribute ="callercursor"></Column>

<Column name="msg" attribute ="msg"></Column>

</ColumnInfo>

</Appender>

</Appenders>

</LogConfig>

<LogConfig name="DBTable">

<Appenders>

<Appender name="AppenderName5">

<Type>dbTableAsync</Type>

</Appender>

</Appenders>

</LogConfig>

<LogConfig name="PDCNotification">

<Appenders>

<Appender name="AppenderName6">

<Type>service</Type>

<PatternLayout>%thread - %msg</PatternLayout>

</Appender>

</Appenders>

</LogConfig>

</LogConfigurations>
</syntaxhighlight>

Log configuration file may contain one or more named configurations:

<LogConfig name="ConfigName0">

...

</LogConfig>

Each configuration contains one or more appenders. Appender defines the log target and has the following parameters: '''LogLevel, Type, Target, PatternLayout, Filter, ConnectionString, ColumnInfo'''

'''<Loglevel>''' can be one of the following:
* all
* debug
* info
* warn
* error
* fatal
* off

'''<Type>''' can be one of the following:
* console logging to console
* event logging to the event log
* file or fileAsync logging to file synchronously or asynchronously
* dbTable or dbTableAsync logging errors to the internal database synchronously or asynchronously
* odbc or odbcAsync logging to the database synchronously or asynchronously
* service logging to the PDC Notification log

'''<Target>''' defines where to log for every log <Type> and has the following values:
* <EventSource> if logging to the event log. Event source is usually application name
* <file name> if logging to a file (environment variable allowed, ex: %TEMP%\my.log).
* <table name> if logging to the ODBC db.

The <Target> parameter may be omitted for everything else.

'''<PatternLayout>''' parameter defines message-formatting rules. It can contain the following keys:
* %lineno Line number of logged message (starts from zero)
* %userid user ID (unknown if not logged in)
* %username user name (unknown if not logged in)
* %proc Process ID
* %thread Thread ID
* %time Time stamp
* %datetime Date/time stamp
* %msg Message itself
* %msglevel Message level
* %newline New line
* %callerClassName Caller class name
* %callerPredicateName Caller predicate name
* %callerCursor Caller module name with line/position values

For example: <PatternLayout>%userid(%username) \[%callerClassName/%callerPredicateName/%callerCursor\]%newline %proc:%thread time=%time dt=%datetime %msg(%msglevel)</PatternLayout>
Logged message (2 lines):
145(Test User) \[0x600260 "serviceLog"/anonymous$o0$1$setproc_name/2np$serviceLog/sourceCursor("tools\\dashboard\\common\\Service.pro", 14, 17)\]

18244:4660 time=16:35:51.935 dt=2015/08/06 - 16:35:51.935 Call: workspace_GetDefaultDirContent(\{\})(debug)

'''<Filter>''' defines what messages will be filtered out (excluded) from the log. It can contain zero or more class names and/or zero or more method names separated by semicolon: '''class:<class name>;method:<method name>'''

For example:
if filter is defined as following class:entityModel;method:getList all logging for class '''entityModel''' and method '''getList''' (no matter from which class) will be skipped.

'''<ConnectionString>''' defines connection string for ODBC logging.

'''<ColumnInfo>''' defines set of columns where to log some information. The '''Name''' attribute defines column name, the '''Attribute''' defines what to log. Attributes can have the same values described in '''<PatternLayout>''' section, except for skipped percentage sign (%) in the beginning.

===Notes:===
* Log configuration file can have more than one appender that logs to a file or database table. Of course, in this case file names/database table names should be different. For example, critical errors can be logged to separate file and/or database table.

=Activating pfc\log from command line=

To use log package it is enough to specify one of the command lines parameters:

'''-LogConfig <Log Configuration File Name> <Configuration Name>'''
For example: -LogConfig LogConfig.xml ConfigName1

=Using pfc\log programmatically=

==Loading log configuration file
'''=='''

Make the following calls:
'''logConfig::loadConfig(ConfigFileName, ConfigName).'''

Where:
ConfigFileName: log configuration file;
ConfigName: configuration name define in log configuration;

If it is necessary to pass connection string (for db/odbc appenders) it is enough to enumerate activated appenders by name and set the connection string (in this example connection string is set for pfc\log\dbTable appender):

LogAppenders = log::getAcivatedAppenders(@"pfc\log\dbTableAppender"),
foreach LogAppender in LogAppenders do
LogAppender:connectionString := db_connectionString
end foreach

==
Logging messages==

===
Use '''log::write(level Level, ...)''' and/or '''log::writef(level Level, string Format '''\['''formatString'''\]''', ...)''' predicates to log messages.

For example:
Log message "Start" with log level "all":
log::write(log::all, "Start").

Log fatal error using formatted log:
log::writef(log::fatal, "SQL ERROR during startup: %", NativeMessage).

'''Using log programmatically without log configuration file'''

Here is an example of using ODBC appender:
'''==='''

ODBC = odbcAppender::new(), <-- constructor
ODBC:loglevel := log::all, <-- log level
ODBC:columninfo := \[tuple("username", "username"), tuple("msg", "msg")\], <-- column info (write 'username' to the 'username' column, write 'msg' to the 'msg' column,
ODBC:connectionString := @"Driver=\{SQL Server\};Server=WEB1.dmz.hc\SQLEXPRESS;Database=Helpdesk_test;UID=leo;PWD=PdcPdcPdc1;app=HelpdeskDashboard",
log::activateAppender(true, ODBC), <-- activate appender
log::write(log::debug, "Example"), <-- log

=List of ideas=

* For critical errors - when we want to call PDC notification log, then we do also need:
%siteURL (URL of the service)
%applicationName
%projectName
%programVersion
%customerName
%machineName

* Expressions: In log4j, there are a number of filtering facilities: [http://logging.apache.org/log4j/2.x/log4j-users-guide.pdf http://logging.apache.org/log4j/2.x/log4j-users-guide.pdf]
I guess we should implement an expression is logging should be done, something like
UserName in \["Leo","Alexander"\] and Time>17:00 or Level>info or Message %= "dfhj"
- Where the Upper case names refer to the Variable.

* Reload log configuration from UI (App settings/utility/etc.) '''\[DONE\]'''

* PDC Notification Log: '''\[DONE\]'''
- analyze;

* Also I think there should be a state variable something like:

Enablelogging_if User="Leo" and Message contains "login"

Disablelogging_if User="Leo" and Message contains "logout"

This is not precise; I just thought it is needed with a mechanism to start and stop logging based on logical condition...

*

Logging

2015-11-19T13:42:51Z

SergeMukhin: /* Log configuration */

=Overview=

Logging in Prolog currently supports logging to console, file, event log, database table, PDC notification log (to be done). Logging is thread safe and even supported for several processes that are writing to the same log. Application can also simultaneously log to several logs including logging to several files and/or database tables. Logging performance does not depend on log type. It is very fast operation and done asynchronously meaning that logging message placed into the message queue, which is processed in background thread.

=Log configuration=

Log configuration file (has .XML format) defines where applications logs the information.
Here is the log configuration file example:

<syntaxhighlight lang=c>
<?xml version="1.0" encoding="utf-8"?>
<LogConfigurations>
<LogConfig name="ConfigName0">
<Appenders>
<Appender name="AppenderName0">
<LogLevel>all</LogLevel>
<Type>console</Type>
<PatternLayout>%username: %thread - %msg</PatternLayout>
</Appender>
</Appenders>
</LogConfig>

<LogConfig name="ConfigName1">

<Appenders>

<Appender name="AppenderName1">

<LogLevel>all</LogLevel>

<Type>event</Type>

<Target>Helpdeskdashboard</Target>

<PatternLayout>\[%lineno\] %userid %proc:%thread %datetime %msg
</PatternLayout>
<filter>class:entityModel;method:aaa</filter>

</Appender>

<Appender name="AppenderName2">

<LogLevel>all</LogLevel>

<Type>file</Type>

<Target>log.txt</Target>

<PatternLayout>\[%lineno\] %userid(%username) \[%callerClassName/%callerPredicateName/%callerCursor\]%newline %proc:%thread time=%time dt=%datetime %msg(%msglevel)</PatternLayout>

<filter>class:entityModel;method:aaa</filter>

</Appender>

<Appender name="AppenderName3">

<LogLevel>all</LogLevel>

<Type>dbtable</Type>

<PatternLayout>%userid %proc:%thread %datetime %msg</PatternLayout>

<filter>class:entityModel;method:aaa</filter>

</Appender>

<Appender name="AppenderName4">

<LogLevel>all</LogLevel>

<Type>console</Type>

<PatternLayout>%userid %proc:%thread %datetime %msg</PatternLayout>

<filter>class:entityModel;method:aaa</filter>

</Appender>

</Appenders>

</LogConfig>

<LogConfig name="ODBCTable">

<Appenders>

<Appender name="AppenderName4">

<LogLevel>all</LogLevel>

<Type>odbcAsync</Type>

<Target>wwLogging</Target>

<ConnectionString>Driver=\{SQL Server\};Server=WEB1.dmz.hc\SQLEXPRESS;Database=Helpdesk_test;UID=xxx;PWD=yyy;app=HelpdeskDashboard</ConnectionString>

<ColumnInfo>

<Column name="level" attribute="msglevel"></Column>

<Column name="linenumber" attribute ="lineno"></Column>

<Column name="username" attribute ="username"></Column>

<Column name="userID" attribute ="userid"></Column>

<Column name="procid" attribute ="proc"></Column>

<Column name="thread" attribute ="thread"></Column>

<Column name="datetime" attribute ="datetime"></Column>

<Column name="time" attribute ="datetime"></Column>

<Column name="callerClassNameElem" attribute ="callerclassname"></Column>

<Column name="callerPredicateNameElem" attribute ="callerpredicatename"></Column>

<Column name="callerCursorElem" attribute ="callercursor"></Column>

<Column name="msg" attribute ="msg"></Column>

</ColumnInfo>

</Appender>

</Appenders>

</LogConfig>

<LogConfig name="DBTable">

<Appenders>

<Appender name="AppenderName5">

<Type>dbTableAsync</Type>

</Appender>

</Appenders>

</LogConfig>

<LogConfig name="PDCNotification">

<Appenders>

<Appender name="AppenderName6">

<Type>service</Type>

<PatternLayout>%thread - %msg</PatternLayout>

</Appender>

</Appenders>

</LogConfig>

</LogConfigurations>
</syntaxhighlight>

Log configuration file may contain one or more named configurations:

<LogConfig name="ConfigName0">

...

</LogConfig>

Each configuration contains one or more appenders. Appender defines the log target and has the following parameters: '''LogLevel, Type, Target, PatternLayout, Filter, ConnectionString, ColumnInfo'''

'''<Loglevel>''' can be one of the following:
* all
* debug
* info
* warn
* error
* fatal
* off

'''<Type>''' can be one of the following:
* console logging to console
* event logging to the event log
* file or fileAsync logging to file synchronously or asynchronously
* dbTable or dbTableAsync logging errors to the internal database synchronously or asynchronously
* odbc or odbcAsync logging to the database synchronously or asynchronously
* service logging to the PDC Notification log

'''<Target>''' defines where to log for every log <Type> and has the following values:
* <EventSource> if logging to the event log. Event source is usually application name
* <file name> if logging to a file (environment variable allowed, ex: %TEMP%\my.log).
* <table name> if logging to the ODBC db.

The <Target> parameter may be omitted for everything else.

'''<PatternLayout>''' parameter defines message-formatting rules. It can contain the following keys:
* %lineno Line number of logged message (starts from zero)
* %userid user ID (unknown if not logged in)
* %username user name (unknown if not logged in)
* %proc Process ID
* %thread Thread ID
* %time Time stamp
* %datetime Date/time stamp
* %msg Message itself
* %msglevel Message level
* %newline New line
* %callerClassName Caller class name
* %callerPredicateName Caller predicate name
* %callerCursor Caller module name with line/position values

For example: <PatternLayout>%userid(%username) \[%callerClassName/%callerPredicateName/%callerCursor\]%newline %proc:%thread time=%time dt=%datetime %msg(%msglevel)</PatternLayout>
Logged message (2 lines):
145(Test User) \[0x600260 "serviceLog"/anonymous$o0$1$setproc_name/2np$serviceLog/sourceCursor("tools\\dashboard\\common\\Service.pro", 14, 17)\]

18244:4660 time=16:35:51.935 dt=2015/08/06 - 16:35:51.935 Call: workspace_GetDefaultDirContent(\{\})(debug)

'''<Filter>''' defines what messages will be filtered out (excluded) from the log. It can contain zero or more class names and/or zero or more method names separated by semicolon: '''class:<class name>;method:<method name>'''

For example:
if filter is defined as following class:entityModel;method:getList all logging for class '''entityModel''' and method '''getList''' (no matter from which class) will be skipped.

'''<ConnectionString>''' defines connection string for ODBC logging.

'''<ColumnInfo>''' defines set of columns where to log some information. The '''Name''' attribute defines column name, the '''Attribute''' defines what to log. Attributes can have the same values described in '''<PatternLayout>''' section, except for skipped percentage sign (%) in the beginning.

===Notes:===
* Log configuration file can have more than one appender that logs to a file or database table. Of course, in this case file names/database table names should be different. For example, critical errors can be logged to separate file and/or database table.

=Activating pfc\log from command line=

To use log package it is enough to specify one of the command lines parameters:

'''-LogConfig <Log Configuration File Name> <Configuration Name>'''
For example: -LogConfig LogConfig.xml ConfigName1

=Using pfc\log programmatically=

==Loading log configuration file
'''=='''

Make the following calls:
'''logConfig::loadConfig(ConfigFileName, ConfigName).'''

Where:
ConfigFileName: log configuration file;
ConfigName: configuration name define in log configuration;

If it is necessary to pass connection string (for db/odbc appenders) it is enough to enumerate activated appenders by name and set the connection string (in this example connection string is set for pfc\log\dbTable appender):

LogAppenders = log::getAcivatedAppenders(@"pfc\log\dbTableAppender"),
foreach LogAppender in LogAppenders do
LogAppender:connectionString := db_connectionString
end foreach

==
Logging messages==

===
Use '''log::write(level Level, ...)''' and/or '''log::writef(level Level, string Format '''\['''formatString'''\]''', ...)''' predicates to log messages.

For example:
Log message "Start" with log level "all":
log::write(log::all, "Start").

Log fatal error using formatted log:
log::writef(log::fatal, "SQL ERROR during startup: %", NativeMessage).

'''Using log programmatically without log configuration file'''

Here is an example of using ODBC appender:
'''==='''

ODBC = odbcAppender::new(), <-- constructor
ODBC:loglevel := log::all, <-- log level
ODBC:columninfo := \[tuple("username", "username"), tuple("msg", "msg")\], <-- column info (write 'username' to the 'username' column, write 'msg' to the 'msg' column,
ODBC:connectionString := @"Driver=\{SQL Server\};Server=WEB1.dmz.hc\SQLEXPRESS;Database=Helpdesk_test;UID=leo;PWD=PdcPdcPdc1;app=HelpdeskDashboard",
log::activateAppender(true, ODBC), <-- activate appender
log::write(log::debug, "Example"), <-- log

=List of ideas=

* For critical errors - when we want to call PDC notification log, then we do also need:
%siteURL (URL of the service)
%applicationName
%projectName
%programVersion
%customerName
%machineName

* Expressions: In log4j, there are a number of filtering facilities: [http://logging.apache.org/log4j/2.x/log4j-users-guide.pdf http://logging.apache.org/log4j/2.x/log4j-users-guide.pdf]
I guess we should implement an expression is logging should be done, something like
UserName in \["Leo","Alexander"\] and Time>17:00 or Level>info or Message %= "dfhj"
- Where the Upper case names refer to the Variable.

* Reload log configuration from UI (App settings/utility/etc.) '''\[DONE\]'''

* PDC Notification Log: '''\[DONE\]'''
- analyze;

* Also I think there should be a state variable something like:

Enablelogging_if User="Leo" and Message contains "login"

Disablelogging_if User="Leo" and Message contains "logout"

This is not precise; I just thought it is needed with a mechanism to start and stop logging based on logical condition...

*

[[Category:Tutorials]]

Logging

2015-11-19T13:36:39Z

SergeMukhin:

=Overview=

Logging in Prolog currently supports logging to console, file, event log, database table, PDC notification log (to be done). Logging is thread safe and even supported for several processes that are writing to the same log. Application can also simultaneously log to several logs including logging to several files and/or database tables. Logging performance does not depend on log type. It is very fast operation and done asynchronously meaning that logging message placed into the message queue, which is processed in background thread.

=Log configuration=

Log configuration file (has .XML format) defines where applications logs the information.
Here is the log configuration file example:

<?xml version="1.0" encoding="utf-8"?>
<LogConfigurations>
<LogConfig name="ConfigName0">
<Appenders>
<Appender name="AppenderName0">
<LogLevel>all</LogLevel>
<Type>console</Type>
<PatternLayout>%username: %thread - %msg</PatternLayout>
</Appender>
</Appenders>
</LogConfig>

<LogConfig name="ConfigName1">

<Appenders>

<Appender name="AppenderName1">

<LogLevel>all</LogLevel>

<Type>event</Type>

<Target>Helpdeskdashboard</Target>

<PatternLayout>\[%lineno\] %userid %proc:%thread %datetime %msg
</PatternLayout>
<filter>class:entityModel;method:aaa</filter>

</Appender>

<Appender name="AppenderName2">

<LogLevel>all</LogLevel>

<Type>file</Type>

<Target>log.txt</Target>

<PatternLayout>\[%lineno\] %userid(%username) \[%callerClassName/%callerPredicateName/%callerCursor\]%newline %proc:%thread time=%time dt=%datetime %msg(%msglevel)</PatternLayout>

<filter>class:entityModel;method:aaa</filter>

</Appender>

<Appender name="AppenderName3">

<LogLevel>all</LogLevel>

<Type>dbtable</Type>

<PatternLayout>%userid %proc:%thread %datetime %msg</PatternLayout>

<filter>class:entityModel;method:aaa</filter>

</Appender>

<Appender name="AppenderName4">

<LogLevel>all</LogLevel>

<Type>console</Type>

<PatternLayout>%userid %proc:%thread %datetime %msg</PatternLayout>

<filter>class:entityModel;method:aaa</filter>

</Appender>

</Appenders>

</LogConfig>

<LogConfig name="ODBCTable">

<Appenders>

<Appender name="AppenderName4">

<LogLevel>all</LogLevel>

<Type>odbcAsync</Type>

<Target>wwLogging</Target>

<ConnectionString>Driver=\{SQL Server\};Server=WEB1.dmz.hc\SQLEXPRESS;Database=Helpdesk_test;UID=xxx;PWD=yyy;app=HelpdeskDashboard</ConnectionString>

<ColumnInfo>

<Column name="level" attribute="msglevel"></Column>

<Column name="linenumber" attribute ="lineno"></Column>

<Column name="username" attribute ="username"></Column>

<Column name="userID" attribute ="userid"></Column>

<Column name="procid" attribute ="proc"></Column>

<Column name="thread" attribute ="thread"></Column>

<Column name="datetime" attribute ="datetime"></Column>

<Column name="time" attribute ="datetime"></Column>

<Column name="callerClassNameElem" attribute ="callerclassname"></Column>

<Column name="callerPredicateNameElem" attribute ="callerpredicatename"></Column>

<Column name="callerCursorElem" attribute ="callercursor"></Column>

<Column name="msg" attribute ="msg"></Column>

</ColumnInfo>

</Appender>

</Appenders>

</LogConfig>

<LogConfig name="DBTable">

<Appenders>

<Appender name="AppenderName5">

<Type>dbTableAsync</Type>

</Appender>

</Appenders>

</LogConfig>

<LogConfig name="PDCNotification">

<Appenders>

<Appender name="AppenderName6">

<Type>service</Type>

<PatternLayout>%thread - %msg</PatternLayout>

</Appender>

</Appenders>

</LogConfig>

</LogConfigurations>

Log configuration file may contain one or more named configurations:

<LogConfig name="ConfigName0">

...

</LogConfig>

Each configuration contains one or more appenders. Appender defines the log target and has the following parameters: '''LogLevel, Type, Target, PatternLayout, Filter, ConnectionString, ColumnInfo'''

'''<Loglevel>''' can be one of the following:
* all
* debug
* info
* warn
* error
* fatal
* off

'''<Type>''' can be one of the following:
* console logging to console
* event logging to the event log
* file or fileAsync logging to file synchronously or asynchronously
* dbTable or dbTableAsync logging errors to the internal database synchronously or asynchronously
* odbc or odbcAsync logging to the database synchronously or asynchronously
* service logging to the PDC Notification log

'''<Target>''' defines where to log for every log <Type> and has the following values:
* <EventSource> if logging to the event log. Event source is usually application name
* <file name> if logging to a file (environment variable allowed, ex: %TEMP%\my.log).
* <table name> if logging to the ODBC db.

The <Target> parameter may be omitted for everything else.

'''<PatternLayout>''' parameter defines message-formatting rules. It can contain the following keys:
* %lineno Line number of logged message (starts from zero)
* %userid user ID (unknown if not logged in)
* %username user name (unknown if not logged in)
* %proc Process ID
* %thread Thread ID
* %time Time stamp
* %datetime Date/time stamp
* %msg Message itself
* %msglevel Message level
* %newline New line
* %callerClassName Caller class name
* %callerPredicateName Caller predicate name
* %callerCursor Caller module name with line/position values

For example: <PatternLayout>%userid(%username) \[%callerClassName/%callerPredicateName/%callerCursor\]%newline %proc:%thread time=%time dt=%datetime %msg(%msglevel)</PatternLayout>
Logged message (2 lines):
145(Test User) \[0x600260 "serviceLog"/anonymous$o0$1$setproc_name/2np$serviceLog/sourceCursor("tools\\dashboard\\common\\Service.pro", 14, 17)\]

18244:4660 time=16:35:51.935 dt=2015/08/06 - 16:35:51.935 Call: workspace_GetDefaultDirContent(\{\})(debug)

'''<Filter>''' defines what messages will be filtered out (excluded) from the log. It can contain zero or more class names and/or zero or more method names separated by semicolon: '''class:<class name>;method:<method name>'''

For example:
if filter is defined as following class:entityModel;method:getList all logging for class '''entityModel''' and method '''getList''' (no matter from which class) will be skipped.

'''<ConnectionString>''' defines connection string for ODBC logging.

'''<ColumnInfo>''' defines set of columns where to log some information. The '''Name''' attribute defines column name, the '''Attribute''' defines what to log. Attributes can have the same values described in '''<PatternLayout>''' section, except for skipped percentage sign (%) in the beginning.

===Notes:===
* Log configuration file can have more than one appender that logs to a file or database table. Of course, in this case file names/database table names should be different. For example, critical errors can be logged to separate file and/or database table.

=Activating pfc\log from command line=

To use log package it is enough to specify one of the command lines parameters:

'''-LogConfig <Log Configuration File Name> <Configuration Name>'''
For example: -LogConfig LogConfig.xml ConfigName1

=Using pfc\log programmatically=

==Loading log configuration file
'''=='''

Make the following calls:
'''logConfig::loadConfig(ConfigFileName, ConfigName).'''

Where:
ConfigFileName: log configuration file;
ConfigName: configuration name define in log configuration;

If it is necessary to pass connection string (for db/odbc appenders) it is enough to enumerate activated appenders by name and set the connection string (in this example connection string is set for pfc\log\dbTable appender):

LogAppenders = log::getAcivatedAppenders(@"pfc\log\dbTableAppender"),
foreach LogAppender in LogAppenders do
LogAppender:connectionString := db_connectionString
end foreach

==
Logging messages==

===
Use '''log::write(level Level, ...)''' and/or '''log::writef(level Level, string Format '''\['''formatString'''\]''', ...)''' predicates to log messages.

For example:
Log message "Start" with log level "all":
log::write(log::all, "Start").

Log fatal error using formatted log:
log::writef(log::fatal, "SQL ERROR during startup: %", NativeMessage).

'''Using log programmatically without log configuration file'''

Here is an example of using ODBC appender:
'''==='''

ODBC = odbcAppender::new(), <-- constructor
ODBC:loglevel := log::all, <-- log level
ODBC:columninfo := \[tuple("username", "username"), tuple("msg", "msg")\], <-- column info (write 'username' to the 'username' column, write 'msg' to the 'msg' column,
ODBC:connectionString := @"Driver=\{SQL Server\};Server=WEB1.dmz.hc\SQLEXPRESS;Database=Helpdesk_test;UID=leo;PWD=PdcPdcPdc1;app=HelpdeskDashboard",
log::activateAppender(true, ODBC), <-- activate appender
log::write(log::debug, "Example"), <-- log

=List of ideas=

* For critical errors - when we want to call PDC notification log, then we do also need:
%siteURL (URL of the service)
%applicationName
%projectName
%programVersion
%customerName
%machineName

* Expressions: In log4j, there are a number of filtering facilities: [http://logging.apache.org/log4j/2.x/log4j-users-guide.pdf http://logging.apache.org/log4j/2.x/log4j-users-guide.pdf]
I guess we should implement an expression is logging should be done, something like
UserName in \["Leo","Alexander"\] and Time>17:00 or Level>info or Message %= "dfhj"
- Where the Upper case names refer to the Variable.

* Reload log configuration from UI (App settings/utility/etc.) '''\[DONE\]'''

* PDC Notification Log: '''\[DONE\]'''
- analyze;

* Also I think there should be a state variable something like:

Enablelogging_if User="Leo" and Message contains "login"

Disablelogging_if User="Leo" and Message contains "logout"

This is not precise; I just thought it is needed with a mechanism to start and stop logging based on logical condition...

*

[[Category:Tutorials]]

Logging

2015-11-19T13:36:12Z

SergeMukhin: /* Log configuration */

=Overview=

Logging in Prolog currently supports logging to console, file, event log, database table, PDC notification log (to be done). Logging is thread safe and even supported for several processes that are writing to the same log. Application can also simultaneously log to several logs including logging to several files and/or database tables. Logging performance does not depend on log type. It is very fast operation and done asynchronously meaning that logging message placed into the message queue, which is processed in background thread.

=Log configuration=

Log configuration file (has .XML format) defines where applications logs the information.
Here is the log configuration file example:

<?xml version="1.0" encoding="utf-8"?>
<LogConfigurations>
<LogConfig name="ConfigName0">

<Appenders>

<Appender name="AppenderName0">

<LogLevel>all</LogLevel>

<Type>console</Type>

<PatternLayout>%username: %thread - %msg</PatternLayout>

</Appender>
</Appenders>

</LogConfig>

<LogConfig name="ConfigName1">

<Appenders>

<Appender name="AppenderName1">

<LogLevel>all</LogLevel>

<Type>event</Type>

<Target>Helpdeskdashboard</Target>

<PatternLayout>\[%lineno\] %userid %proc:%thread %datetime %msg
</PatternLayout>
<filter>class:entityModel;method:aaa</filter>

</Appender>

<Appender name="AppenderName2">

<LogLevel>all</LogLevel>

<Type>file</Type>

<Target>log.txt</Target>

<PatternLayout>\[%lineno\] %userid(%username) \[%callerClassName/%callerPredicateName/%callerCursor\]%newline %proc:%thread time=%time dt=%datetime %msg(%msglevel)</PatternLayout>

<filter>class:entityModel;method:aaa</filter>

</Appender>

<Appender name="AppenderName3">

<LogLevel>all</LogLevel>

<Type>dbtable</Type>

<PatternLayout>%userid %proc:%thread %datetime %msg</PatternLayout>

<filter>class:entityModel;method:aaa</filter>

</Appender>

<Appender name="AppenderName4">

<LogLevel>all</LogLevel>

<Type>console</Type>

<PatternLayout>%userid %proc:%thread %datetime %msg</PatternLayout>

<filter>class:entityModel;method:aaa</filter>

</Appender>

</Appenders>

</LogConfig>

<LogConfig name="ODBCTable">

<Appenders>

<Appender name="AppenderName4">

<LogLevel>all</LogLevel>

<Type>odbcAsync</Type>

<Target>wwLogging</Target>

<ConnectionString>Driver=\{SQL Server\};Server=WEB1.dmz.hc\SQLEXPRESS;Database=Helpdesk_test;UID=xxx;PWD=yyy;app=HelpdeskDashboard</ConnectionString>

<ColumnInfo>

<Column name="level" attribute="msglevel"></Column>

<Column name="linenumber" attribute ="lineno"></Column>

<Column name="username" attribute ="username"></Column>

<Column name="userID" attribute ="userid"></Column>

<Column name="procid" attribute ="proc"></Column>

<Column name="thread" attribute ="thread"></Column>

<Column name="datetime" attribute ="datetime"></Column>

<Column name="time" attribute ="datetime"></Column>

<Column name="callerClassNameElem" attribute ="callerclassname"></Column>

<Column name="callerPredicateNameElem" attribute ="callerpredicatename"></Column>

<Column name="callerCursorElem" attribute ="callercursor"></Column>

<Column name="msg" attribute ="msg"></Column>

</ColumnInfo>

</Appender>

</Appenders>

</LogConfig>

<LogConfig name="DBTable">

<Appenders>

<Appender name="AppenderName5">

<Type>dbTableAsync</Type>

</Appender>

</Appenders>

</LogConfig>

<LogConfig name="PDCNotification">

<Appenders>

<Appender name="AppenderName6">

<Type>service</Type>

<PatternLayout>%thread - %msg</PatternLayout>

</Appender>

</Appenders>

</LogConfig>

</LogConfigurations>

Log configuration file may contain one or more named configurations:

<LogConfig name="ConfigName0">

...

</LogConfig>

Each configuration contains one or more appenders. Appender defines the log target and has the following parameters: '''LogLevel, Type, Target, PatternLayout, Filter, ConnectionString, ColumnInfo'''

'''<Loglevel>''' can be one of the following:
* all
* debug
* info
* warn
* error
* fatal
* off

'''<Type>''' can be one of the following:
* console logging to console
* event logging to the event log
* file or fileAsync logging to file synchronously or asynchronously
* dbTable or dbTableAsync logging errors to the internal database synchronously or asynchronously
* odbc or odbcAsync logging to the database synchronously or asynchronously
* service logging to the PDC Notification log

'''<Target>''' defines where to log for every log <Type> and has the following values:
* <EventSource> if logging to the event log. Event source is usually application name
* <file name> if logging to a file (environment variable allowed, ex: %TEMP%\my.log).
* <table name> if logging to the ODBC db.

The <Target> parameter may be omitted for everything else.

'''<PatternLayout>''' parameter defines message-formatting rules. It can contain the following keys:
* %lineno Line number of logged message (starts from zero)
* %userid user ID (unknown if not logged in)
* %username user name (unknown if not logged in)
* %proc Process ID
* %thread Thread ID
* %time Time stamp
* %datetime Date/time stamp
* %msg Message itself
* %msglevel Message level
* %newline New line
* %callerClassName Caller class name
* %callerPredicateName Caller predicate name
* %callerCursor Caller module name with line/position values

For example: <PatternLayout>%userid(%username) \[%callerClassName/%callerPredicateName/%callerCursor\]%newline %proc:%thread time=%time dt=%datetime %msg(%msglevel)</PatternLayout>
Logged message (2 lines):
145(Test User) \[0x600260 "serviceLog"/anonymous$o0$1$setproc_name/2np$serviceLog/sourceCursor("tools\\dashboard\\common\\Service.pro", 14, 17)\]

18244:4660 time=16:35:51.935 dt=2015/08/06 - 16:35:51.935 Call: workspace_GetDefaultDirContent(\{\})(debug)

'''<Filter>''' defines what messages will be filtered out (excluded) from the log. It can contain zero or more class names and/or zero or more method names separated by semicolon: '''class:<class name>;method:<method name>'''

For example:
if filter is defined as following class:entityModel;method:getList all logging for class '''entityModel''' and method '''getList''' (no matter from which class) will be skipped.

'''<ConnectionString>''' defines connection string for ODBC logging.

'''<ColumnInfo>''' defines set of columns where to log some information. The '''Name''' attribute defines column name, the '''Attribute''' defines what to log. Attributes can have the same values described in '''<PatternLayout>''' section, except for skipped percentage sign (%) in the beginning.

===Notes:===
* Log configuration file can have more than one appender that logs to a file or database table. Of course, in this case file names/database table names should be different. For example, critical errors can be logged to separate file and/or database table.

=Activating pfc\log from command line=

To use log package it is enough to specify one of the command lines parameters:

'''-LogConfig <Log Configuration File Name> <Configuration Name>'''
For example: -LogConfig LogConfig.xml ConfigName1

=Using pfc\log programmatically=

==Loading log configuration file
'''=='''

Make the following calls:
'''logConfig::loadConfig(ConfigFileName, ConfigName).'''

Where:
ConfigFileName: log configuration file;
ConfigName: configuration name define in log configuration;

If it is necessary to pass connection string (for db/odbc appenders) it is enough to enumerate activated appenders by name and set the connection string (in this example connection string is set for pfc\log\dbTable appender):

LogAppenders = log::getAcivatedAppenders(@"pfc\log\dbTableAppender"),
foreach LogAppender in LogAppenders do
LogAppender:connectionString := db_connectionString
end foreach

==
Logging messages==

===
Use '''log::write(level Level, ...)''' and/or '''log::writef(level Level, string Format '''\['''formatString'''\]''', ...)''' predicates to log messages.

For example:
Log message "Start" with log level "all":
log::write(log::all, "Start").

Log fatal error using formatted log:
log::writef(log::fatal, "SQL ERROR during startup: %", NativeMessage).

'''Using log programmatically without log configuration file'''

Here is an example of using ODBC appender:
'''==='''

ODBC = odbcAppender::new(), <-- constructor
ODBC:loglevel := log::all, <-- log level
ODBC:columninfo := \[tuple("username", "username"), tuple("msg", "msg")\], <-- column info (write 'username' to the 'username' column, write 'msg' to the 'msg' column,
ODBC:connectionString := @"Driver=\{SQL Server\};Server=WEB1.dmz.hc\SQLEXPRESS;Database=Helpdesk_test;UID=leo;PWD=PdcPdcPdc1;app=HelpdeskDashboard",
log::activateAppender(true, ODBC), <-- activate appender
log::write(log::debug, "Example"), <-- log

=List of ideas=

* For critical errors - when we want to call PDC notification log, then we do also need:
%siteURL (URL of the service)
%applicationName
%projectName
%programVersion
%customerName
%machineName

* Expressions: In log4j, there are a number of filtering facilities: [http://logging.apache.org/log4j/2.x/log4j-users-guide.pdf http://logging.apache.org/log4j/2.x/log4j-users-guide.pdf]
I guess we should implement an expression is logging should be done, something like
UserName in \["Leo","Alexander"\] and Time>17:00 or Level>info or Message %= "dfhj"
- Where the Upper case names refer to the Variable.

* Reload log configuration from UI (App settings/utility/etc.) '''\[DONE\]'''

* PDC Notification Log: '''\[DONE\]'''
- analyze;

* Also I think there should be a state variable something like:

Enablelogging_if User="Leo" and Message contains "login"

Disablelogging_if User="Leo" and Message contains "logout"

This is not precise; I just thought it is needed with a mechanism to start and stop logging based on logical condition...

*

[[Category:Tutorials]]

Logging

2015-11-19T13:35:19Z

SergeMukhin:

=Overview=

Logging in Prolog currently supports logging to console, file, event log, database table, PDC notification log (to be done). Logging is thread safe and even supported for several processes that are writing to the same log. Application can also simultaneously log to several logs including logging to several files and/or database tables. Logging performance does not depend on log type. It is very fast operation and done asynchronously meaning that logging message placed into the message queue, which is processed in background thread.

=Log configuration=

Log configuration file (has .XML format) defines where applications logs the information.
Here is the log configuration file example:

<?xml version="1.0" encoding="utf-8"?>

<LogConfigurations>

<LogConfig name="ConfigName0">

<Appenders>

<Appender name="AppenderName0">

<LogLevel>all</LogLevel>

<Type>console</Type>

<PatternLayout>%username: %thread - %msg</PatternLayout>

</Appender>
</Appenders>

</LogConfig>

<LogConfig name="ConfigName1">

<Appenders>

<Appender name="AppenderName1">

<LogLevel>all</LogLevel>

<Type>event</Type>

<Target>Helpdeskdashboard</Target>

<PatternLayout>\[%lineno\] %userid %proc:%thread %datetime %msg
</PatternLayout>
<filter>class:entityModel;method:aaa</filter>

</Appender>

<Appender name="AppenderName2">

<LogLevel>all</LogLevel>

<Type>file</Type>

<Target>log.txt</Target>

<PatternLayout>\[%lineno\] %userid(%username) \[%callerClassName/%callerPredicateName/%callerCursor\]%newline %proc:%thread time=%time dt=%datetime %msg(%msglevel)</PatternLayout>

<filter>class:entityModel;method:aaa</filter>

</Appender>

<Appender name="AppenderName3">

<LogLevel>all</LogLevel>

<Type>dbtable</Type>

<PatternLayout>%userid %proc:%thread %datetime %msg</PatternLayout>

<filter>class:entityModel;method:aaa</filter>

</Appender>

<Appender name="AppenderName4">

<LogLevel>all</LogLevel>

<Type>console</Type>

<PatternLayout>%userid %proc:%thread %datetime %msg</PatternLayout>

<filter>class:entityModel;method:aaa</filter>

</Appender>

</Appenders>

</LogConfig>

<LogConfig name="ODBCTable">

<Appenders>

<Appender name="AppenderName4">

<LogLevel>all</LogLevel>

<Type>odbcAsync</Type>

<Target>wwLogging</Target>

<ConnectionString>Driver=\{SQL Server\};Server=WEB1.dmz.hc\SQLEXPRESS;Database=Helpdesk_test;UID=xxx;PWD=yyy;app=HelpdeskDashboard</ConnectionString>

<ColumnInfo>

<Column name="level" attribute="msglevel"></Column>

<Column name="linenumber" attribute ="lineno"></Column>

<Column name="username" attribute ="username"></Column>

<Column name="userID" attribute ="userid"></Column>

<Column name="procid" attribute ="proc"></Column>

<Column name="thread" attribute ="thread"></Column>

<Column name="datetime" attribute ="datetime"></Column>

<Column name="time" attribute ="datetime"></Column>

<Column name="callerClassNameElem" attribute ="callerclassname"></Column>

<Column name="callerPredicateNameElem" attribute ="callerpredicatename"></Column>

<Column name="callerCursorElem" attribute ="callercursor"></Column>

<Column name="msg" attribute ="msg"></Column>

</ColumnInfo>

</Appender>

</Appenders>

</LogConfig>

<LogConfig name="DBTable">

<Appenders>

<Appender name="AppenderName5">

<Type>dbTableAsync</Type>

</Appender>

</Appenders>

</LogConfig>

<LogConfig name="PDCNotification">

<Appenders>

<Appender name="AppenderName6">

<Type>service</Type>

<PatternLayout>%thread - %msg</PatternLayout>

</Appender>

</Appenders>

</LogConfig>

</LogConfigurations>

Log configuration file may contain one or more named configurations:

<LogConfig name="ConfigName0">

...

</LogConfig>

Each configuration contains one or more appenders. Appender defines the log target and has the following parameters: '''LogLevel, Type, Target, PatternLayout, Filter, ConnectionString, ColumnInfo'''

'''<Loglevel>''' can be one of the following:
* all
* debug
* info
* warn
* error
* fatal
* off

'''<Type>''' can be one of the following:
* console logging to console
* event logging to the event log
* file or fileAsync logging to file synchronously or asynchronously
* dbTable or dbTableAsync logging errors to the internal database synchronously or asynchronously
* odbc or odbcAsync logging to the database synchronously or asynchronously
* service logging to the PDC Notification log

'''<Target>''' defines where to log for every log <Type> and has the following values:
* <EventSource> if logging to the event log. Event source is usually application name
* <file name> if logging to a file (environment variable allowed, ex: %TEMP%\my.log).
* <table name> if logging to the ODBC db.

The <Target> parameter may be omitted for everything else.

'''<PatternLayout>''' parameter defines message-formatting rules. It can contain the following keys:
* %lineno Line number of logged message (starts from zero)
* %userid user ID (unknown if not logged in)
* %username user name (unknown if not logged in)
* %proc Process ID
* %thread Thread ID
* %time Time stamp
* %datetime Date/time stamp
* %msg Message itself
* %msglevel Message level
* %newline New line
* %callerClassName Caller class name
* %callerPredicateName Caller predicate name
* %callerCursor Caller module name with line/position values

For example: <PatternLayout>%userid(%username) \[%callerClassName/%callerPredicateName/%callerCursor\]%newline %proc:%thread time=%time dt=%datetime %msg(%msglevel)</PatternLayout>
Logged message (2 lines):
145(Test User) \[0x600260 "serviceLog"/anonymous$o0$1$setproc_name/2np$serviceLog/sourceCursor("tools\\dashboard\\common\\Service.pro", 14, 17)\]

18244:4660 time=16:35:51.935 dt=2015/08/06 - 16:35:51.935 Call: workspace_GetDefaultDirContent(\{\})(debug)

'''<Filter>''' defines what messages will be filtered out (excluded) from the log. It can contain zero or more class names and/or zero or more method names separated by semicolon: '''class:<class name>;method:<method name>'''

For example:
if filter is defined as following class:entityModel;method:getList all logging for class '''entityModel''' and method '''getList''' (no matter from which class) will be skipped.

'''<ConnectionString>''' defines connection string for ODBC logging.

'''<ColumnInfo>''' defines set of columns where to log some information. The '''Name''' attribute defines column name, the '''Attribute''' defines what to log. Attributes can have the same values described in '''<PatternLayout>''' section, except for skipped percentage sign (%) in the beginning.

===Notes:===
* Log configuration file can have more than one appender that logs to a file or database table. Of course, in this case file names/database table names should be different. For example, critical errors can be logged to separate file and/or database table.

=Activating pfc\log from command line=

To use log package it is enough to specify one of the command lines parameters:

'''-LogConfig <Log Configuration File Name> <Configuration Name>'''
For example: -LogConfig LogConfig.xml ConfigName1

=Using pfc\log programmatically=

==Loading log configuration file
'''=='''

Make the following calls:
'''logConfig::loadConfig(ConfigFileName, ConfigName).'''

Where:
ConfigFileName: log configuration file;
ConfigName: configuration name define in log configuration;

If it is necessary to pass connection string (for db/odbc appenders) it is enough to enumerate activated appenders by name and set the connection string (in this example connection string is set for pfc\log\dbTable appender):

LogAppenders = log::getAcivatedAppenders(@"pfc\log\dbTableAppender"),
foreach LogAppender in LogAppenders do
LogAppender:connectionString := db_connectionString
end foreach

==
Logging messages==

===
Use '''log::write(level Level, ...)''' and/or '''log::writef(level Level, string Format '''\['''formatString'''\]''', ...)''' predicates to log messages.

For example:
Log message "Start" with log level "all":
log::write(log::all, "Start").

Log fatal error using formatted log:
log::writef(log::fatal, "SQL ERROR during startup: %", NativeMessage).

'''Using log programmatically without log configuration file'''

Here is an example of using ODBC appender:
'''==='''

ODBC = odbcAppender::new(), <-- constructor
ODBC:loglevel := log::all, <-- log level
ODBC:columninfo := \[tuple("username", "username"), tuple("msg", "msg")\], <-- column info (write 'username' to the 'username' column, write 'msg' to the 'msg' column,
ODBC:connectionString := @"Driver=\{SQL Server\};Server=WEB1.dmz.hc\SQLEXPRESS;Database=Helpdesk_test;UID=leo;PWD=PdcPdcPdc1;app=HelpdeskDashboard",
log::activateAppender(true, ODBC), <-- activate appender
log::write(log::debug, "Example"), <-- log

=List of ideas=

* For critical errors - when we want to call PDC notification log, then we do also need:
%siteURL (URL of the service)
%applicationName
%projectName
%programVersion
%customerName
%machineName

* Expressions: In log4j, there are a number of filtering facilities: [http://logging.apache.org/log4j/2.x/log4j-users-guide.pdf http://logging.apache.org/log4j/2.x/log4j-users-guide.pdf]
I guess we should implement an expression is logging should be done, something like
UserName in \["Leo","Alexander"\] and Time>17:00 or Level>info or Message %= "dfhj"
- Where the Upper case names refer to the Variable.

* Reload log configuration from UI (App settings/utility/etc.) '''\[DONE\]'''

* PDC Notification Log: '''\[DONE\]'''
- analyze;

* Also I think there should be a state variable something like:

Enablelogging_if User="Leo" and Message contains "login"

Disablelogging_if User="Leo" and Message contains "logout"

This is not precise; I just thought it is needed with a mechanism to start and stop logging based on logical condition...

*

[[Category:Tutorials]]

Logging

2015-11-19T13:32:46Z

SergeMukhin:

=Overview=

Logging in Prolog currently supports logging to console, file, event log, database table, PDC notification log (to be done). Logging is thread safe and even supported for several processes that are writing to the same log. Application can also simultaneously log to several logs including logging to several files and/or database tables. Logging performance does not depend on log type. It is very fast operation and done asynchronously meaning that logging message placed into the message queue, which is processed in background thread.

=Log configuration=

Log configuration file (has .XML format) defines where applications logs the information.
Here is the log configuration file example:

<?xml version="1.0" encoding="utf-8"?>

<LogConfigurations>

<LogConfig name="ConfigName0">

<Appenders>

<Appender name="AppenderName0">

<LogLevel>all</LogLevel>

<Type>console</Type>

<PatternLayout>%username: %thread - %msg</PatternLayout>

</Appender>
</Appenders>

</LogConfig>

<LogConfig name="ConfigName1">

<Appenders>

<Appender name="AppenderName1">

<LogLevel>all</LogLevel>

<Type>event</Type>

<Target>Helpdeskdashboard</Target>

<PatternLayout>\[%lineno\] %userid %proc:%thread %datetime %msg
</PatternLayout>
<filter>class:entityModel;method:aaa</filter>

</Appender>

<Appender name="AppenderName2">

<LogLevel>all</LogLevel>

<Type>file</Type>

<Target>log.txt</Target>

<PatternLayout>\[%lineno\] %userid(%username) \[%callerClassName/%callerPredicateName/%callerCursor\]%newline %proc:%thread time=%time dt=%datetime %msg(%msglevel)</PatternLayout>

<filter>class:entityModel;method:aaa</filter>

</Appender>

<Appender name="AppenderName3">

<LogLevel>all</LogLevel>

<Type>dbtable</Type>

<PatternLayout>%userid %proc:%thread %datetime %msg</PatternLayout>

<filter>class:entityModel;method:aaa</filter>

</Appender>

<Appender name="AppenderName4">

<LogLevel>all</LogLevel>

<Type>console</Type>

<PatternLayout>%userid %proc:%thread %datetime %msg</PatternLayout>

<filter>class:entityModel;method:aaa</filter>

</Appender>

</Appenders>

</LogConfig>

<LogConfig name="ODBCTable">

<Appenders>

<Appender name="AppenderName4">

<LogLevel>all</LogLevel>

<Type>odbcAsync</Type>

<Target>wwLogging</Target>

<ConnectionString>Driver=\{SQL Server\};Server=WEB1.dmz.hc\SQLEXPRESS;Database=Helpdesk_test;UID=xxx;PWD=yyy;app=HelpdeskDashboard</ConnectionString>

<ColumnInfo>

<Column name="level" attribute="msglevel"></Column>

<Column name="linenumber" attribute ="lineno"></Column>

<Column name="username" attribute ="username"></Column>

<Column name="userID" attribute ="userid"></Column>

<Column name="procid" attribute ="proc"></Column>

<Column name="thread" attribute ="thread"></Column>

<Column name="datetime" attribute ="datetime"></Column>

<Column name="time" attribute ="datetime"></Column>

<Column name="callerClassNameElem" attribute ="callerclassname"></Column>

<Column name="callerPredicateNameElem" attribute ="callerpredicatename"></Column>

<Column name="callerCursorElem" attribute ="callercursor"></Column>

<Column name="msg" attribute ="msg"></Column>

</ColumnInfo>

</Appender>

</Appenders>

</LogConfig>

<LogConfig name="DBTable">

<Appenders>

<Appender name="AppenderName5">

<Type>dbTableAsync</Type>

</Appender>

</Appenders>

</LogConfig>

<LogConfig name="PDCNotification">

<Appenders>

<Appender name="AppenderName6">

<Type>service</Type>

<PatternLayout>%thread - %msg</PatternLayout>

</Appender>

</Appenders>

</LogConfig>

</LogConfigurations>

Log configuration file may contain one or more named configurations:

<LogConfig name="ConfigName0">

...

</LogConfig>

Each configuration contains one or more appenders. Appender defines the log target and has the following parameters: '''LogLevel, Type, Target, PatternLayout, Filter, ConnectionString, ColumnInfo'''

'''<Loglevel>''' can be one of the following:
* all
* debug
* info
* warn
* error
* fatal
* off

'''<Type>''' can be one of the following:
* console logging to console
* event logging to the event log
* file or fileAsync logging to file synchronously or asynchronously
* dbTable or dbTableAsync logging errors to the internal database synchronously or asynchronously
* odbc or odbcAsync logging to the database synchronously or asynchronously
* service logging to the PDC Notification log

'''<Target>''' defines where to log for every log <Type> and has the following values:
* <EventSource> if logging to the event log. Event source is usually application name
* <file name> if logging to a file (environment variable allowed, ex: %TEMP%\my.log).
* <table name> if logging to the ODBC db.

The <Target> parameter may be omitted for everything else.

'''<PatternLayout>''' parameter defines message-formatting rules. It can contain the following keys:
* %lineno Line number of logged message (starts from zero)
* %userid user ID (unknown if not logged in)
* %username user name (unknown if not logged in)
* %proc Process ID
* %thread Thread ID
* %time Time stamp
* %datetime Date/time stamp
* %msg Message itself
* %msglevel Message level
* %newline New line
* %callerClassName Caller class name
* %callerPredicateName Caller predicate name
* %callerCursor Caller module name with line/position values

For example: <PatternLayout>%userid(%username) \[%callerClassName/%callerPredicateName/%callerCursor\]%newline %proc:%thread time=%time dt=%datetime %msg(%msglevel)</PatternLayout>
Logged message (2 lines):
145(Test User) \[0x600260 "serviceLog"/anonymous$o0$1$setproc_name/2np$serviceLog/sourceCursor("tools\\dashboard\\common\\Service.pro", 14, 17)\]

18244:4660 time=16:35:51.935 dt=2015/08/06 - 16:35:51.935 Call: workspace_GetDefaultDirContent(\{\})(debug)

'''<Filter>''' defines what messages will be filtered out (excluded) from the log. It can contain zero or more class names and/or zero or more method names separated by semicolon: '''class:<class name>;method:<method name>'''

For example:
if filter is defined as following class:entityModel;method:getList all logging for class '''entityModel''' and method '''getList''' (no matter from which class) will be skipped.

'''<ConnectionString>''' defines connection string for ODBC logging.

'''<ColumnInfo>''' defines set of columns where to log some information. The '''Name''' attribute defines column name, the '''Attribute''' defines what to log. Attributes can have the same values described in '''<PatternLayout>''' section, except for skipped percentage sign (%) in the beginning.

===Notes:===
* Log configuration file can have more than one appender that logs to a file or database table. Of course, in this case file names/database table names should be different. For example, critical errors can be logged to separate file and/or database table.

=Activating pfc\log from command line=

To use log package it is enough to specify one of the command lines parameters:

'''-LogConfig <Log Configuration File Name> <Configuration Name>'''
For example: -LogConfig LogConfig.xml ConfigName1

=
Using pfc\log programmatically=

==Loading log configuration file
'''=='''

Make the following calls:
'''logConfig::loadConfig(ConfigFileName, ConfigName).'''

Where:
ConfigFileName: log configuration file;
ConfigName: configuration name define in log configuration;

If it is necessary to pass connection string (for db/odbc appenders) it is enough to enumerate activated appenders by name and set the connection string (in this example connection string is set for pfc\log\dbTable appender):

LogAppenders = log::getAcivatedAppenders(@"pfc\log\dbTableAppender"),
foreach LogAppender in LogAppenders do
LogAppender:connectionString := db_connectionString
end foreach

==
Logging messages==

===
Use '''log::write(level Level, ...)''' and/or '''log::writef(level Level, string Format '''\['''formatString'''\]''', ...)''' predicates to log messages.

For example:
Log message "Start" with log level "all":
log::write(log::all, "Start").

Log fatal error using formatted log:
log::writef(log::fatal, "SQL ERROR during startup: %", NativeMessage).

'''Using log programmatically without log configuration file'''

Here is an example of using ODBC appender:
'''==='''

ODBC = odbcAppender::new(), <-- constructor
ODBC:loglevel := log::all, <-- log level
ODBC:columninfo := \[tuple("username", "username"), tuple("msg", "msg")\], <-- column info (write 'username' to the 'username' column, write 'msg' to the 'msg' column,
ODBC:connectionString := @"Driver=\{SQL Server\};Server=WEB1.dmz.hc\SQLEXPRESS;Database=Helpdesk_test;UID=leo;PWD=PdcPdcPdc1;app=HelpdeskDashboard",
log::activateAppender(true, ODBC), <-- activate appender
log::write(log::debug, "Example"), <-- log

=List of ideas=

* For critical errors - when we want to call PDC notification log, then we do also need:
%siteURL (URL of the service)
%applicationName
%projectName
%programVersion
%customerName
%machineName

* Expressions: In log4j, there are a number of filtering facilities: [http://logging.apache.org/log4j/2.x/log4j-users-guide.pdf http://logging.apache.org/log4j/2.x/log4j-users-guide.pdf]
I guess we should implement an expression is logging should be done, something like
UserName in \["Leo","Alexander"\] and Time>17:00 or Level>info or Message %= "dfhj"
- Where the Upper case names refer to the Variable.

* Reload log configuration from UI (App settings/utility/etc.) '''\[DONE\]'''

* PDC Notification Log: '''\[DONE\]'''
- analyze;

* Also I think there should be a state variable something like:

Enablelogging_if User="Leo" and Message contains "login"

Disablelogging_if User="Leo" and Message contains "logout"

This is not precise; I just thought it is needed with a mechanism to start and stop logging based on logical condition...

*

[[Category:Tutorials]]

Logging

2015-11-19T13:26:05Z

SergeMukhin:

=== Logging ===
=== Logging for Prolog (pfc\log) package ===

=Overview=

Logging in Prolog currently supports logging to console, file, event log, database table, PDC notification log (to be done). Logging is thread safe and even supported for several processes that are writing to the same log. Application can also simultaneously log to several logs including logging to several files and/or database tables. Logging performance does not depend on log type. It is very fast operation and done asynchronously meaning that logging message placed into the message queue, which is processed in background thread.

=Log configuration=

Log configuration file (has .XML format) defines where applications logs the information.
Here is the log configuration file example:

<?xml version="1.0" encoding="utf-8"?>

<LogConfigurations>

<LogConfig name="ConfigName0">

<Appenders>

<Appender name="AppenderName0">

<LogLevel>all</LogLevel>

<Type>console</Type>

<PatternLayout>%username: %thread - %msg</PatternLayout>

</Appender>
</Appenders>

</LogConfig>

<LogConfig name="ConfigName1">

<Appenders>

<Appender name="AppenderName1">

<LogLevel>all</LogLevel>

<Type>event</Type>

<Target>Helpdeskdashboard</Target>

<PatternLayout>\[%lineno\] %userid %proc:%thread %datetime %msg
</PatternLayout>
<filter>class:entityModel;method:aaa</filter>

</Appender>

<Appender name="AppenderName2">

<LogLevel>all</LogLevel>

<Type>file</Type>

<Target>log.txt</Target>

<PatternLayout>\[%lineno\] %userid(%username) \[%callerClassName/%callerPredicateName/%callerCursor\]%newline %proc:%thread time=%time dt=%datetime %msg(%msglevel)</PatternLayout>

<filter>class:entityModel;method:aaa</filter>

</Appender>

<Appender name="AppenderName3">

<LogLevel>all</LogLevel>

<Type>dbtable</Type>

<PatternLayout>%userid %proc:%thread %datetime %msg</PatternLayout>

<filter>class:entityModel;method:aaa</filter>

</Appender>

<Appender name="AppenderName4">

<LogLevel>all</LogLevel>

<Type>console</Type>

<PatternLayout>%userid %proc:%thread %datetime %msg</PatternLayout>

<filter>class:entityModel;method:aaa</filter>

</Appender>

</Appenders>

</LogConfig>

<LogConfig name="ODBCTable">

<Appenders>

<Appender name="AppenderName4">

<LogLevel>all</LogLevel>

<Type>odbcAsync</Type>

<Target>wwLogging</Target>

<ConnectionString>Driver=\{SQL Server\};Server=WEB1.dmz.hc\SQLEXPRESS;Database=Helpdesk_test;UID=xxx;PWD=yyy;app=HelpdeskDashboard</ConnectionString>

<ColumnInfo>

<Column name="level" attribute="msglevel"></Column>

<Column name="linenumber" attribute ="lineno"></Column>

<Column name="username" attribute ="username"></Column>

<Column name="userID" attribute ="userid"></Column>

<Column name="procid" attribute ="proc"></Column>

<Column name="thread" attribute ="thread"></Column>

<Column name="datetime" attribute ="datetime"></Column>

<Column name="time" attribute ="datetime"></Column>

<Column name="callerClassNameElem" attribute ="callerclassname"></Column>

<Column name="callerPredicateNameElem" attribute ="callerpredicatename"></Column>

<Column name="callerCursorElem" attribute ="callercursor"></Column>

<Column name="msg" attribute ="msg"></Column>

</ColumnInfo>

</Appender>

</Appenders>

</LogConfig>

<LogConfig name="DBTable">

<Appenders>

<Appender name="AppenderName5">

<Type>dbTableAsync</Type>

</Appender>

</Appenders>

</LogConfig>

<LogConfig name="PDCNotification">

<Appenders>

<Appender name="AppenderName6">

<Type>service</Type>

<PatternLayout>%thread - %msg</PatternLayout>

</Appender>

</Appenders>

</LogConfig>

</LogConfigurations>

Log configuration file may contain one or more named configurations:

<LogConfig name="ConfigName0">

...

</LogConfig>

Each configuration contains one or more appenders. Appender defines the log target and has the following parameters: '''LogLevel, Type, Target, PatternLayout, Filter, ConnectionString, ColumnInfo'''

'''<Loglevel>''' can be one of the following:
* all
* debug
* info
* warn
* error
* fatal
* off

'''<Type>''' can be one of the following:
* console logging to console
* event logging to the event log
* file or fileAsync logging to file synchronously or asynchronously
* dbTable or dbTableAsync logging errors to the internal database synchronously or asynchronously
* odbc or odbcAsync logging to the database synchronously or asynchronously
* service logging to the PDC Notification log

'''<Target>''' defines where to log for every log <Type> and has the following values:
* <EventSource> if logging to the event log. Event source is usually application name
* <file name> if logging to a file (environment variable allowed, ex: %TEMP%\my.log).
* <table name> if logging to the ODBC db.

The <Target> parameter may be omitted for everything else.

'''<PatternLayout>''' parameter defines message-formatting rules. It can contain the following keys:
* %lineno Line number of logged message (starts from zero)
* %userid user ID (unknown if not logged in)
* %username user name (unknown if not logged in)
* %proc Process ID
* %thread Thread ID
* %time Time stamp
* %datetime Date/time stamp
* %msg Message itself
* %msglevel Message level
* %newline New line
* %callerClassName Caller class name
* %callerPredicateName Caller predicate name
* %callerCursor Caller module name with line/position values

For example: <PatternLayout>%userid(%username) \[%callerClassName/%callerPredicateName/%callerCursor\]%newline %proc:%thread time=%time dt=%datetime %msg(%msglevel)</PatternLayout>
Logged message (2 lines):
145(Test User) \[0x600260 "serviceLog"/anonymous$o0$1$setproc_name/2np$serviceLog/sourceCursor("tools\\dashboard\\common\\Service.pro", 14, 17)\]

18244:4660 time=16:35:51.935 dt=2015/08/06 - 16:35:51.935 Call: workspace_GetDefaultDirContent(\{\})(debug)

'''<Filter>''' defines what messages will be filtered out (excluded) from the log. It can contain zero or more class names and/or zero or more method names separated by semicolon: '''class:<class name>;method:<method name>'''

For example:
if filter is defined as following class:entityModel;method:getList all logging for class '''entityModel''' and method '''getList''' (no matter from which class) will be skipped.

'''<ConnectionString>''' defines connection string for ODBC logging.

'''<ColumnInfo>''' defines set of columns where to log some information. The '''Name''' attribute defines column name, the '''Attribute''' defines what to log. Attributes can have the same values described in '''<PatternLayout>''' section, except for skipped percentage sign (%) in the beginning.

===Notes:===
* Log configuration file can have more than one appender that logs to a file or database table. Of course, in this case file names/database table names should be different. For example, critical errors can be logged to separate file and/or database table.

=Activating pfc\log from command line=

To use log package it is enough to specify one of the command lines parameters:

'''-LogConfig <Log Configuration File Name> <Configuration Name>'''
For example: -LogConfig LogConfig.xml ConfigName1

=
Using pfc\log programmatically=

==Loading log configuration file
'''=='''

Make the following calls:
'''logConfig::loadConfig(ConfigFileName, ConfigName).'''

Where:
ConfigFileName: log configuration file;
ConfigName: configuration name define in log configuration;

If it is necessary to pass connection string (for db/odbc appenders) it is enough to enumerate activated appenders by name and set the connection string (in this example connection string is set for pfc\log\dbTable appender):

LogAppenders = log::getAcivatedAppenders(@"pfc\log\dbTableAppender"),
foreach LogAppender in LogAppenders do
LogAppender:connectionString := db_connectionString
end foreach

==
Logging messages==

===
Use '''log::write(level Level, ...)''' and/or '''log::writef(level Level, string Format '''\['''formatString'''\]''', ...)''' predicates to log messages.

For example:
Log message "Start" with log level "all":
log::write(log::all, "Start").

Log fatal error using formatted log:
log::writef(log::fatal, "SQL ERROR during startup: %", NativeMessage).

'''Using log programmatically without log configuration file'''

Here is an example of using ODBC appender:
'''==='''

ODBC = odbcAppender::new(), <-- constructor
ODBC:loglevel := log::all, <-- log level
ODBC:columninfo := \[tuple("username", "username"), tuple("msg", "msg")\], <-- column info (write 'username' to the 'username' column, write 'msg' to the 'msg' column,
ODBC:connectionString := @"Driver=\{SQL Server\};Server=WEB1.dmz.hc\SQLEXPRESS;Database=Helpdesk_test;UID=leo;PWD=PdcPdcPdc1;app=HelpdeskDashboard",
log::activateAppender(true, ODBC), <-- activate appender
log::write(log::debug, "Example"), <-- log

=List of ideas=

* For critical errors - when we want to call PDC notification log, then we do also need:
%siteURL (URL of the service)
%applicationName
%projectName
%programVersion
%customerName
%machineName

* Expressions: In log4j, there are a number of filtering facilities: [http://logging.apache.org/log4j/2.x/log4j-users-guide.pdf http://logging.apache.org/log4j/2.x/log4j-users-guide.pdf]
I guess we should implement an expression is logging should be done, something like
UserName in \["Leo","Alexander"\] and Time>17:00 or Level>info or Message %= "dfhj"
- Where the Upper case names refer to the Variable.

* Reload log configuration from UI (App settings/utility/etc.) '''\[DONE\]'''

* PDC Notification Log: '''\[DONE\]'''
- analyze;

* Also I think there should be a state variable something like:

Enablelogging_if User="Leo" and Message contains "login"

Disablelogging_if User="Leo" and Message contains "logout"

This is not precise; I just thought it is needed with a mechanism to start and stop logging based on logical condition...

*

[[Category:Tutorials]]

Logging

2015-11-19T13:25:22Z

SergeMukhin:

=== Logging ===
Logging for Prolog (pfc\log) package

=Overview=

Logging in Prolog currently supports logging to console, file, event log, database table, PDC notification log (to be done). Logging is thread safe and even supported for several processes that are writing to the same log. Application can also simultaneously log to several logs including logging to several files and/or database tables. Logging performance does not depend on log type. It is very fast operation and done asynchronously meaning that logging message placed into the message queue, which is processed in background thread.

=Log configuration=

Log configuration file (has .XML format) defines where applications logs the information.
Here is the log configuration file example:

<?xml version="1.0" encoding="utf-8"?>

<LogConfigurations>

<LogConfig name="ConfigName0">

<Appenders>

<Appender name="AppenderName0">

<LogLevel>all</LogLevel>

<Type>console</Type>

<PatternLayout>%username: %thread - %msg</PatternLayout>

</Appender>
</Appenders>

</LogConfig>

<LogConfig name="ConfigName1">

<Appenders>

<Appender name="AppenderName1">

<LogLevel>all</LogLevel>

<Type>event</Type>

<Target>Helpdeskdashboard</Target>

<PatternLayout>\[%lineno\] %userid %proc:%thread %datetime %msg
</PatternLayout>
<filter>class:entityModel;method:aaa</filter>

</Appender>

<Appender name="AppenderName2">

<LogLevel>all</LogLevel>

<Type>file</Type>

<Target>log.txt</Target>

<PatternLayout>\[%lineno\] %userid(%username) \[%callerClassName/%callerPredicateName/%callerCursor\]%newline %proc:%thread time=%time dt=%datetime %msg(%msglevel)</PatternLayout>

<filter>class:entityModel;method:aaa</filter>

</Appender>

<Appender name="AppenderName3">

<LogLevel>all</LogLevel>

<Type>dbtable</Type>

<PatternLayout>%userid %proc:%thread %datetime %msg</PatternLayout>

<filter>class:entityModel;method:aaa</filter>

</Appender>

<Appender name="AppenderName4">

<LogLevel>all</LogLevel>

<Type>console</Type>

<PatternLayout>%userid %proc:%thread %datetime %msg</PatternLayout>

<filter>class:entityModel;method:aaa</filter>

</Appender>

</Appenders>

</LogConfig>

<LogConfig name="ODBCTable">

<Appenders>

<Appender name="AppenderName4">

<LogLevel>all</LogLevel>

<Type>odbcAsync</Type>

<Target>wwLogging</Target>

<ConnectionString>Driver=\{SQL Server\};Server=WEB1.dmz.hc\SQLEXPRESS;Database=Helpdesk_test;UID=xxx;PWD=yyy;app=HelpdeskDashboard</ConnectionString>

<ColumnInfo>

<Column name="level" attribute="msglevel"></Column>

<Column name="linenumber" attribute ="lineno"></Column>

<Column name="username" attribute ="username"></Column>

<Column name="userID" attribute ="userid"></Column>

<Column name="procid" attribute ="proc"></Column>

<Column name="thread" attribute ="thread"></Column>

<Column name="datetime" attribute ="datetime"></Column>

<Column name="time" attribute ="datetime"></Column>

<Column name="callerClassNameElem" attribute ="callerclassname"></Column>

<Column name="callerPredicateNameElem" attribute ="callerpredicatename"></Column>

<Column name="callerCursorElem" attribute ="callercursor"></Column>

<Column name="msg" attribute ="msg"></Column>

</ColumnInfo>

</Appender>

</Appenders>

</LogConfig>

<LogConfig name="DBTable">

<Appenders>

<Appender name="AppenderName5">

<Type>dbTableAsync</Type>

</Appender>

</Appenders>

</LogConfig>

<LogConfig name="PDCNotification">

<Appenders>

<Appender name="AppenderName6">

<Type>service</Type>

<PatternLayout>%thread - %msg</PatternLayout>

</Appender>

</Appenders>

</LogConfig>

</LogConfigurations>

Log configuration file may contain one or more named configurations:

<LogConfig name="ConfigName0">

...

</LogConfig>

Each configuration contains one or more appenders. Appender defines the log target and has the following parameters: '''LogLevel, Type, Target, PatternLayout, Filter, ConnectionString, ColumnInfo'''

'''<Loglevel>''' can be one of the following:
* all
* debug
* info
* warn
* error
* fatal
* off

'''<Type>''' can be one of the following:
* console logging to console
* event logging to the event log
* file or fileAsync logging to file synchronously or asynchronously
* dbTable or dbTableAsync logging errors to the internal database synchronously or asynchronously
* odbc or odbcAsync logging to the database synchronously or asynchronously
* service logging to the PDC Notification log

'''<Target>''' defines where to log for every log <Type> and has the following values:
* <EventSource> if logging to the event log. Event source is usually application name
* <file name> if logging to a file (environment variable allowed, ex: %TEMP%\my.log).
* <table name> if logging to the ODBC db.

The <Target> parameter may be omitted for everything else.

'''<PatternLayout>''' parameter defines message-formatting rules. It can contain the following keys:
* %lineno Line number of logged message (starts from zero)
* %userid user ID (unknown if not logged in)
* %username user name (unknown if not logged in)
* %proc Process ID
* %thread Thread ID
* %time Time stamp
* %datetime Date/time stamp
* %msg Message itself
* %msglevel Message level
* %newline New line
* %callerClassName Caller class name
* %callerPredicateName Caller predicate name
* %callerCursor Caller module name with line/position values

For example: <PatternLayout>%userid(%username) \[%callerClassName/%callerPredicateName/%callerCursor\]%newline %proc:%thread time=%time dt=%datetime %msg(%msglevel)</PatternLayout>
Logged message (2 lines):
145(Test User) \[0x600260 "serviceLog"/anonymous$o0$1$setproc_name/2np$serviceLog/sourceCursor("tools\\dashboard\\common\\Service.pro", 14, 17)\]

18244:4660 time=16:35:51.935 dt=2015/08/06 - 16:35:51.935 Call: workspace_GetDefaultDirContent(\{\})(debug)

'''<Filter>''' defines what messages will be filtered out (excluded) from the log. It can contain zero or more class names and/or zero or more method names separated by semicolon: '''class:<class name>;method:<method name>'''

For example:
if filter is defined as following class:entityModel;method:getList all logging for class '''entityModel''' and method '''getList''' (no matter from which class) will be skipped.

'''<ConnectionString>''' defines connection string for ODBC logging.

'''<ColumnInfo>''' defines set of columns where to log some information. The '''Name''' attribute defines column name, the '''Attribute''' defines what to log. Attributes can have the same values described in '''<PatternLayout>''' section, except for skipped percentage sign (%) in the beginning.

===Notes:===
* Log configuration file can have more than one appender that logs to a file or database table. Of course, in this case file names/database table names should be different. For example, critical errors can be logged to separate file and/or database table.

=Activating pfc\log from command line=

To use log package it is enough to specify one of the command lines parameters:

'''-LogConfig <Log Configuration File Name> <Configuration Name>'''
For example: -LogConfig LogConfig.xml ConfigName1

=
Using pfc\log programmatically=

==Loading log configuration file
'''=='''

Make the following calls:
'''logConfig::loadConfig(ConfigFileName, ConfigName).'''

Where:
ConfigFileName: log configuration file;
ConfigName: configuration name define in log configuration;

If it is necessary to pass connection string (for db/odbc appenders) it is enough to enumerate activated appenders by name and set the connection string (in this example connection string is set for pfc\log\dbTable appender):

LogAppenders = log::getAcivatedAppenders(@"pfc\log\dbTableAppender"),
foreach LogAppender in LogAppenders do
LogAppender:connectionString := db_connectionString
end foreach

==
Logging messages==

===
Use '''log::write(level Level, ...)''' and/or '''log::writef(level Level, string Format '''\['''formatString'''\]''', ...)''' predicates to log messages.

For example:
Log message "Start" with log level "all":
log::write(log::all, "Start").

Log fatal error using formatted log:
log::writef(log::fatal, "SQL ERROR during startup: %", NativeMessage).

'''Using log programmatically without log configuration file'''

Here is an example of using ODBC appender:
'''==='''

ODBC = odbcAppender::new(), <-- constructor
ODBC:loglevel := log::all, <-- log level
ODBC:columninfo := \[tuple("username", "username"), tuple("msg", "msg")\], <-- column info (write 'username' to the 'username' column, write 'msg' to the 'msg' column,
ODBC:connectionString := @"Driver=\{SQL Server\};Server=WEB1.dmz.hc\SQLEXPRESS;Database=Helpdesk_test;UID=leo;PWD=PdcPdcPdc1;app=HelpdeskDashboard",
log::activateAppender(true, ODBC), <-- activate appender
log::write(log::debug, "Example"), <-- log

=List of ideas=

* For critical errors - when we want to call PDC notification log, then we do also need:
%siteURL (URL of the service)
%applicationName
%projectName
%programVersion
%customerName
%machineName

* Expressions: In log4j, there are a number of filtering facilities: [http://logging.apache.org/log4j/2.x/log4j-users-guide.pdf http://logging.apache.org/log4j/2.x/log4j-users-guide.pdf]
I guess we should implement an expression is logging should be done, something like
UserName in \["Leo","Alexander"\] and Time>17:00 or Level>info or Message %= "dfhj"
- Where the Upper case names refer to the Variable.

* Reload log configuration from UI (App settings/utility/etc.) '''\[DONE\]'''

* PDC Notification Log: '''\[DONE\]'''
- analyze;

* Also I think there should be a state variable something like:

Enablelogging_if User="Leo" and Message contains "login"

Disablelogging_if User="Leo" and Message contains "logout"

This is not precise; I just thought it is needed with a mechanism to start and stop logging based on logical condition...

*

[[Category:Tutorials]]

Logging

2015-11-19T13:01:04Z

SergeMukhin:

=== Logging ===

[[Category:Tutorials]]

Logging

2015-11-19T12:59:16Z

SergeMukhin: Created page with "=== Logging ==="

=== Logging ===

Ide/Debugger/Debugger Views

2015-03-18T15:25:56Z

SergeMukhin: /* Memory Dump Window */

<noinclude>[[Category:Ide/Debugger]]</noinclude>
== Debugger Views ==

=== Run Stack Window ===

The '''Run Stack''' consists of three kinds of items:
*'''Continue''' item – marked with [[Image:Ide_db_RunStack_up.png]]. It describes ordinary executable clauses, which do not produce backtrack points and are not trapped.
*'''BackTrack''' item – marked with [[Image:Ide_db_RunStack_dn.png]].It describes a clause of a nondeterministic predicate. The next clause of this predicate can be executed when a program failure of this clause occurs. Such items occur when a clause of a predicate, which creates a '''backtrack''' point (can produce more than one solution) is called.
*'''TrapTrack''' item – marked with [[Image:Ide_db_RunStack_rh.png]] or [[Image:Ide_db_RunStack_dn_rh.png]]. They describe a continue item (clause), which will be resumed in any case independently whether an error condition occurs or no. For example, such item is created when a predicate call is trapped with the <vp>trap/3</vp> predicate. The [[Image:Ide_db_RunStack_rh.png]] icon is used to mark trapped clauses of deterministic predicates. The [[Image:Ide_db_RunStack_dn_rh.png]] icon is used to mark trapped clauses of nondeterministic predicates.

The '''BackTrack''' (marked with [[Image:Ide_db_RunStack_dn.png]]) and '''TrapTrack''' items (marked with [[Image:Ide_db_RunStack_dn_rh.png]]) are backtracking points. The clause, marked by one of these items, will be resumed and the program execution will be continued after the corresponding failure or an error occurs.

The typical example of the '''Run Stack''' window is presented in the following picture:

[[Image:Ide_db_RunStack.png]]

'''Pop-up Menu'''

The '''Run Stack''' window has the pop-up context menu:

[[Image:Ide_db_RunStack_menu.png]]

For each selected item in the tree, this menu contains items:

*'''Refresh'''
*:It refreshes all the '''Run Stack''' window contents, rebuilds the tree.
*: It also refreshes the {{ide|Debugger#Variables Window|'''Variables'''}} window (if it is displayed).

*'''Go To Code'''
*:Activates the Prolog source editor and places the cursor at the Prolog clause corresponding to the item selected in the '''Run Stack''' window. If the item does not correspond to a Prolog module with debug information, then the '''Disassembly''' window will be opened and the cursor will be placed onto the corresponding assembler instruction. The same action is caused by double-click a predicate call in the '''Run Stack''' window.

*'''Copy Line'''
*:It copies the selected line contents to the clipboard.

*'''Show Domains'''
*:This option turns ON/OFF displaying domains of variables.

*'''Show Values'''
*:This option turns ON/OFF displaying values of variables.

The '''Run Stack''' window can be activated by the IDE menu '''View | Run Stack'''.

=== Variables Window ===

The '''Variables''' window can be activated either by '''Ctrl+Alt+V''' or from the IDE menu '''View | Variables for Current Clause'''.

'''Variables Window Contents'''

The '''Variables''' window displays the tree of all program variables and facts from the traced clause, which are already created by the program at the current tracing step. These are: all variables and all object facts (fact variables), which are created in the clause before the executing instruction, and all class facts (fact variables), which can be used in this clause (declared in this class implementation).

The top line of the window displays the declaration of the predicate, whose clause is executed.

[[Image:Ide_db_Vars_Top.png]]

The '''Variables''' window content is updated after every trace step.

'''Pop-up Context Menu'''

The '''Variables in the Current Clause''' window has the following pop-up context menu:

[[Image:Ide_db_Vars_Menu.png]]

This menu contains items:

*''Insert into Watch Window''
*:Opens the '''Watch Window''' and moves there selected variable.

*''Copy''
*:This command copies the contents of the line selected in the '''Variables''' window to the clipboard.

*''Show as Hexadecimal''
*:Shows integral values in the hexadecimal format.

*''Show as Decimal''
*:Shows integral values in the decimal format.

*''Show as Octal''
*:Shows integral values in the octal format.

*''Show Domains''
*:This option turns '''ON/OFF''' displaying the domains after variable names.

*''Show Variable Addresses''
*:This option turns '''ON/OFF''' displaying the addresses after variable names.

*''Find''
*:This command allows search variable by name.

*''Copy Tree''
*:This command copies the contents of the window to the clipboard.

=== Facts Window ===

'''Class Facts'''

The '''Facts''' window always shows the current contents of all '''class''' fact databases defined in the program being debugged.

Simple example:

[[Image:Ide_db_Facts_View.png]]

Pressing '''CTRL+ALT+F''' opens '''Facts''' window:

[[Image:Ide_db_Facts_View3.png]]

Clicking icons opens sub-trees:

[[Image:Ide_db_Facts_View4.png]]

'''Facts''' window automatically goes to the fact that is selected in the text editor (if any):

[[Image:Ide_db_Facts_View11.png]]

[[Image:Ide_db_Facts_View41.png]]

'''Objects Facts''' you cat look like a components of object variables in the {{ide|Debugger#Variables Window|'''Variables''' window}}

'''Pop-up Context Menu'''

The '''Facts Window''' has the following pop-up context menu:

[[Image:Ide_db_Vars_Menu.png]]

This menu contains items:

*''Insert into Watch Window''
*:Opens the '''Watch Window''' and moves there selected fact.

*''Copy''
*:This command copies the contents of the line selected in the '''Facts''' window to the clipboard.

*''Show as Hexadecimal''
*:Shows integral values in the hexadecimal format.

*''Show as Decimal''
*:Shows integral values in the decimal format.

*''Show as Octal''
*:Shows integral values in the octal format.

*''Show Domains''
*:This option turns '''ON/OFF''' displaying the domains after facts names.

*''Show Addresses''
*:This option turns '''ON/OFF''' displaying the addresses after facts names.

*''Find''
*:This command allows search fact by name.

*''Copy Tree''
*:This command copies the contents of the window to the clipboard.

=== Breakpoints Window ===

The '''Breakpoints''' window shows all breakpoints, which have been set in the program being debugged.

You can set a breakpoint onto any executable line in program source files (or in the '''Disassembly''' window, where a breakpoint can be set on any instruction of the program being debugged).

There are two kinds of breakpoints: hard and soft. Hard breakpoints are active in any debugging mode. Soft breakpoints are active in normal debugging mode but disabled in a special mode of quick debugging, called ''Fast Forward Mode''.

==== Breakpoints Window Contents ====

The '''Breakpoints''' window for each breakpoint includes '''Status''', '''Source''', '''Line''', '''Count''', '''Comment''' and '''Action''', where:

*'''''Status'''''
*:Shows whether the breakpoint is ''hard'' or ''soft''.
**''Hard''
**:If a breakpoint is ''hard'' then it will be activated in any debugging mode. A hard breakpoint is marked with the filled circle [[Image:Ide_db_BreakPoints_en.png]] or [[Image:Ide_db_BreakPoints_assembler.png]] (for assembler) or [[Image:Ide_db_BreakPoints_shifted.png]] (for relocated breakpoint).
**''Soft''
**:If a breakpoint is ''soft'' then it will be activated only in normal (not Fast Forward) debugging mode. A soft breakpoint is marked with the hollow circle [[Image:Ide_db_BreakPoints_dis.png]] or [[Image:Ide_db_BreakPoints_assembler_disabled.png]] (for assembler).
**''Invalid''
**:A breakpoint is invalid when it is set on a line, which does not contain executable code. An invalid breakpoint is marked with the crossed hollow circle [[Image:Ide_db_BreakPoints_invalid.png]].

*'''''Source'''''
*:This column shows the source string:
*:<vipbnf><SourceName></vipbnf>
*:where:
*:''SourceName''
*:The description of a predicate in the address space of whose clauses the breakpoint is set:
*:*If the breakpoint is set in Prolog sources, then ''SourceName'' is the filename in which the breakpoint is set. It is displayed with the format:
*::<vipbnf><FileName> '(' <Path> ')'</vipbnf>
*::The ''Path'' can use {{ide|Make Facility#Build Symbols|Build script symbols}}.
*:* If the breakpoint is set in the '''Disassembly''' window, then ''SourceName'' has the format:
*::<vipbnf>--- assembler: <AddressValue></vipbnf>
*::''AddressValue'' is the hexadecimal address of the breakpoint in the assembler code of the predicate in which the breakpoint is set.

*'''''Line'''''
*:When the breakpoint is set in a Prolog source file, then this column displays the number of the line the breakpoint is set on. When the breakpoint is set in the Disassembly window, then the number of the line is equal to 0.

*'''''Count'''''
*:This column displays {{ide|Debugger#Breakpoint Properties|counts}} of breakpoints.

*'''''Comment'''''
*:This column displays {{ide|Debugger#Breakpoint Properties|comment strings}} of breakpoints.

*'''''Action'''''
*:This column displays the script text of a breakpoint. The script is performed each time the program reaches the breakpoint.

==== Breakpoints in Prolog and Disassembly Windows ====

Breakpoints can be set in Prolog source files and in the '''Disassembly''' window:

* In Prolog sources valid breakpoints can be set only on lines containing executable instructions. That is, breakpoints can be set only in predicate clauses on lines containing predicate calls, otherwise the breakpoints that are set on non-clause lines would be marked as invalid. The breakpoints that are set on clause lines that do not contain predicate calls would be shifted to the lines containing such calls (if any), but the initial line would be marked with [[Image:Ide_db_BreakPoints_shifted.png]]. Valid breakpoints are marked with red circles [[Image:Ide_db_BreakPoints_en.png]] or [[Image:Ide_db_BreakPoints_dis.png]] in Prolog sources and are shown in the '''Disassembly''' window as blue circles [[Image:Ide_db_BreakPoints_assembler.png]] or [[Image:Ide_db_BreakPoints_assembler_disabled.png]]. If a Prolog clause has several assembler implementations (when the clause has several flow patterns), then each breakpoint in Prolog sources can generate several breakpoints in the '''Disassembly''' window.
* Breakpoints that are set in the '''Disassembly''' window are marked with red circles [[Image:Ide_db_BreakPoints_en.png]] or [[Image:Ide_db_BreakPoints_dis.png]]. Such breakpoint can be later overwritten by a breakpoint (marked with blue circles [[Image:Ide_db_BreakPoints_assembler.png]] or [[Image:Ide_db_BreakPoints_assembler_disabled.png]]) that is set in Prolog sources on the same address as the breakpoint set in the '''Disassembly''' window. Notice that after modification and recompilation of the project some breakpoints that are set in the '''Disassembly''' window can be cleared (if other instructions are placed at breakpoint addresses.)

All breakpoints which are set in a program are seen in the '''Breakpoints''' window.

==== Breakpoint Properties ====

Each breakpoint has properties, which can be modified in the '''Breakpoint Properties''' dialog:

[[Image:Ide_db_BreakPoint_Properties.png]]

In this dialog:

The top line contains:

* If the breakpoint is set in Prolog sources, then the top line has format:
*:'''<vipbnf>File: <FileName> Line: <LineNumber></vipbnf>'''
*:''FileName'' is the name of the Prolog source file in which the breakpoint is set.
*:''LineNumber'' is the number of the line on which the breakpoint is set.

* If the breakpoint is set in the '''Disassembly''' window, then the top line has format:
*:'''<vipbnf>Breakpoint Address:<Address></vipbnf>
*:''Address'' is the breakpoint address in the program memory as it is seen in the '''Disassembly''' window.

'''Hard'''
:This check box controls the ''Hard/Soft'' state of the breakpoint. When you turn a breakpoint to Hard, then it will be activated in any debugging mode. When you turn a breakpoint to Soft, then it will be activated only in normal (not Fast Forward) debugging mode.

'''Counter''' ''Value''
:Shows the current number of activations of the breakpoint since its creation. The user cannot modify this value. This value increases by 1 each time when the program reaches the breakpoint. And resets to 0 at the beginning of the debug session.

'''Comment''' ''Comment string''
:In this edit box you can type in a ''Comment string''. By default it has the value of the corresponding line in the source file.

'''Action''' ''Script text''
:In this box you can type in a ''Script text''.

==== Pop-up Menu ====

The '''Breakpoints''' window has the pop-up context menu:

[[Image:Ide_db_BreakPoints_pop_up.png]]

To activate this menu, select a breakpoint and press the right mouse button. This menu contains items:

*'''Go to Source'''
*:If the breakpoint is set in the Prolog sources, then the '''Go to Code''' activates the Prolog source code editor, and moves the cursor to the Prolog code corresponding to the specified breakpoint. If the breakpoint is set in the '''Disassembly''' window, then the '''Go to Code''' moves the view to this breakpoint in the '''Disassembly''' window. The same action is performed by double-click the breakpoint or by pressing the '''Enter''' on the breakpoint.

*'''Properties'''
*:Invokes the {{ide|Debugger#Breakpoint Properties|'''Breakpoint Properties'''}} dialog for the selected breakpoint.

*'''Toggle (Turn to Hard/Soft)'''
*:Switches the ''Hard/Soft'' state of the selected breakpoints.

*'''Delete'''
*:Deletes the selected breakpoints.

*'''Turn to Hard All'''
*:Sets the state of all breakpoints that are set in the program to ''Hard''.

*'''Turn to Soft All'''
*:Sets the state of all breakpoints that are set in the program to ''Soft''.

*'''Remove All'''
*:Removes all breakpoints that are set in the program.

The '''Breakpoints''' window is auto-updated for any breakpoint updating.

The '''Breakpoints''' window can be activated either by '''Ctrl+Alt+B''' or from the IDE menu '''View | Breakpoints'''.

=== Threads Window ===
----
The '''Threads''' window shows information about the process being debugged and its threads.

The '''Threads''' window looks like following:

[[Image:Ide_db_Threads.png]]

Names displayed in the header of the window columns are the following:

*'''TID'''
*:This column displays thread identifiers of all threads created by the process being debugged.
*'''Current'''
*:This column identifies the current thread by the <vp>*</vp> sign. In the {{ide|Debugger#Variables Window|Variables}} window you can see only variables of predicates executed in the current thread.
*'''State'''
*:Displays states of threads. States can be '''''Running''''', '''''Stopped''''', and '''''Suspend'''''.
*: '''''Running''''' The thread has been started, it is not suspended (see <vp>thread::suspend/0-></vp>, <vp> syncObject::wait/0-></vp>, <vp>syncObject::wait/1-></vp>) or terminated (see <vp>thread::terminate/1</vp>).
*: '''''Suspend''''' The thread is in suspended state (see <vp>thread::createSuspended/3</vp>, <vp>thread::suspend/0-></vp>, <vp>syncObject::wait/0-></vp>, <vp>syncObject::wait/1-></vp>).
*: '''''Stopped''''' The thread was created and then stopped on a breakpoint, but it is not suspended (see <vp>thread::suspend/0-></vp>, <vp>syncObject::wait/0-></vp>, <vp>syncObject::wait/1-></vp>). If you set suspended state to a '''''Stopped''''' thread, then it turns into the '''''Suspend''''' state.
*'''Time'''
*:Thread creation time.
*'''User time'''
*:Processor time in the user-mode used by the thread.
*'''Kernel Time'''
*:Processor time in the kernel-mode used by the thread.
*'''Priority'''
*:The priority level of the thread. Here can be displayed the following numbers <vp>2, 1, 0, -1, -2</vp>.
*'''Predicate'''
*:This field contains the name of the currently executed thread's predicate (if it is possible to determine it).

{|{{prettytable}}
|-
! Displayed Number
! Priority Name
! Description
|-
| 2
| '''Highest'''
| The thread can be scheduled before threads with any other priority.
|-
| 1
| '''AboveNormal'''
| The thread can be scheduled after threads with '''Highest''' priority and before those with '''Normal''' priority.
|-
| 0
| '''Normal'''
| The thread can be scheduled after threads with '''AboveNormal''' priority and before those with '''BelowNormal''' priority. Threads have Normal priority by default.
|-
| -1
| '''BelowNormal'''
| The thread can be scheduled after threads with '''Normal''' priority and before those with '''Lowest''' priority.
|-
| -2
| '''Lowest'''
| The thread can be scheduled after threads with any other priority.
|}

'''Pop-up Menu'''

The '''Threads''' window has the pop-up context menu. The same commands can be activated from the '''Thread''' sub-menu of the IDE task menu.

[[Image:Ide_db_Threads_popup.png]]

*'''Goto Source'''
*:Opens the text editor and places the cursor onto the predicate, which created the selected thread.
*'''Set Current'''
*:Sets the selected thread as current.
*'''Resume'''
*:Resumes the run of the selected thread.
*'''Suspend'''
*:Suspends the selected thread.
*'''Copy'''
*:Copies the contents of the line selected in the '''Threads''' window to the clipboard.
*'''Copy All'''
*:Copies the contents of the '''Threads''' window to the clipboard.

The '''Threads''' window is updated after changing any displayed parameter.

The '''Threads''' window can be activated either by '''CTRL+Alt+H''' or from the IDE menu '''View | Threads'''.

=== Disassembly Window ===

The '''Disassembly''' window shows the assembly language interpretation of the inspected code.

The disassembly starts from the specified top address toward the upper memory and prints each instruction on a new line.

Each line is printed by the pattern:

<vipbnf><LineMarkers> <Address> [ <HexCode> ] <AssemblerCommand></vipbnf>

where:

''LineMarkers''
:Are the {{ide|Debugger#Debug Menu Commands|''instruction pointer''}} [[Image:Ide_db_InstructionPointer.png]] and the breakpoint[[Image:Ide_db_BreakPoints_en.png]] (or [[Image:Ide_db_BreakPoints_dis.png]]) markers, which can mark this line.
''Address''
:The start address of the instruction code.
''HexCode''
:This is the hexadecimal instruction code. This field can be shown/hidden from the pop-up menu of the '''Disassembly''' window by checking the '''Show OpCodes''' item.
''AssemblerCommand''
:This is the assembler command corresponding to the instruction code. Assembler commands have the Intel standard assembler abbreviation. If a certain address is resolved to an external name, then this name will be printed in the command column.
: The instruction, which will be executed at the next trace step, is marked with the [[Image:Ide_db_InstructionPointer.png]] ''Instruction pointer'' in the ''LineMarkers'' field.

Example:

[[Image:Ide_db_DisAsm_View.png]]

==== Pop-up Menu ====

The '''Disassembly''' window has the pop-up context menu with the followin commands:

*'''Go To Address'''
*:Invokes the '''Go to Address''' dialog
*:[[Image:Ide_db_DisAsm_Go2Address.png]]
*:to type in the address of the instruction, which should be displayed in the top line of the '''Disassembly''' window. The ''Address'' should be specified in the hexadecimal format. This dialog allows typing symbolic external link names and symbolic CPU register names.
*'''Go To EIP'''
*:Updates the '''Disassembly''' window and places the cursor at the address of the instruction on which the program execution is suspended.
*'''Breakpoint…'''
*:Allows handling the breakpoint [[Image:Ide_db_BreakPoints_en.png]] (or [[Image:Ide_db_BreakPoints_dis.png]]) for the assembler instruction pointed by the cursor. It has the following sub-commands:
*:[[Image:Ide_db_DisAsm_PopUp.png]]
*:*'''Toggle Breakpoint'''
*:*:Sets or removes a breakpoint at the instruction with the address pointed by the cursor.
*:*'''Enable / Disable'''
*:*:''Enables / Disables'' the breakpoint pointed by the cursor. This item is disabled if there is no breakpoint at the address pointed by the cursor.
*:*'''Properties'''
*:*:Invokes the '''Breakpoint Properties''' dialog for the breakpoint pointed by the cursor. This item is disabled if there is no breakpoint at the address pointed by the cursor.
*'''Go To Source'''
*:Activates the IDE source code editor and sets the cursor at the predicate whose assembler instruction is pointed by the cursor in the '''Disassembly''' window. (When it is possible.)
*'''Copy'''
*:Copies lines selected in the '''Disassembly''' window to the clipboard. A selection can be performed with the '''Shift+Up Arrow''' and '''Shift+Down Arrow''' key combinations.
*'''Show OpCodes'''
*:Checking and unchecking this item hides/shows hex images of operation (instruction) codes ('''OpCodes'''). These hex instruction codes are shown in the ''HexCode'' field.
*'''Source Annotation'''
*:Checking OFF/ON this item hides/shows object names, corresponding to predicate entry points. Each object name is printed on a new line before the corresponding instruction line.
*'''Show Hints'''
*:Shows additional information about the instruction being executed.

The '''Disassembly''' window is updated after each trace step of the debugger.

==== Disassembly Window Commands ====

*'''Trace Into''' command
*:Tracing in the '''Disassembly''' window with the '''Step Into''' command performs execution of one assembler instruction (including entering into procedures if any). That is, if the '''Step Over''' command will execute a <vp>call</vp> instruction as one trace step, then the '''Step Into''' command will go into the called procedure. It usually executes disassembler instructions line after line.
*'''Step Over''' command
*:Tracing in the '''Disassembly''' window with the '''Step Over''' command performs execution of one assembler instruction (including execution of <vp>call</vp> instructions). So the '''Step Over''' command works almost the same way as the '''Trace Into''' command except for execution of <vp>call</vp> instructions. In difference to the '''Trace Into''' command, it tries to perform <vp >call</vp> instructions as one step and reaches the next line only if the called code returns to that line.
*'''Run to Cursor''' command
*:Tracing in the '''Disassembly''' window with the '''Run to Cursor''' command works in the following way. The debugger places an invisible breakpoint at the address corresponding to the instruction specified by the cursor and performs the '''Debug Run''' command. It depends only upon the program code whether the program will reach this instruction or will never reach it.

If the tracing code has no debug information, then the '''Disassembly''' window is opened initially (when the debugger starts) and the instruction pointer [[Image:Ide_db_InstructionPointer.png]] points to the executing assembler instruction.

=== Registers Window ===

The '''Registers''' window shows current values of the CPU (Central Processor Unit) registers:

* General registers
* Segment registers
* Flags
* Floating-point registers

A register value is printed:

* '''red''', if it is changed from the last program trace step
* '''blue''', otherwise.

For example:

[[Image:Ide_db_Registers_fpu.png]]

The '''Floating Point''' command from context pop-up menu can be used to turn ON/OFF the displaying of Floating-point registers.

The '''Registers''' window can be activated either by '''Ctr+ Alt+G''' or from the IDE menu '''View | Registers'''.

=== Modules Window ===
----
The Modules Window shows all the modules currently loaded in this debug session. It shows the filename, path, the base address range, the code address range and the type of debug information.

[[Image:Ide_db_Modules.png]]

=== Memory Dump Window ===

The '''Memory Dump''' window shows the virtual memory dump of the program being debugged. Memory dump lines have the length, which is determined by the window width. The number of printed lines window height.

'''Information Displayed in the Memory Dump Window'''

Each line in the '''Memory Dump''' window is printed by the pattern:

<vipbnf><Address> | [ <HexValues> ] [ <ASCIIcharacters> ] [ <UnicodeCharacters>]</vipbnf>

where:

''Address''
:This is the hexadecimal address of the first byte of the memory displayed in this line.
''HexValues''
:<vipbnf><HexValues> : <HexValue> [ <HexValues> ]</vipbnf>
:This is the hexadecimal format of the memory dump. Each hex value can be an image of one, two, four or eight continued memory bytes (this is contolled by the '''Memory Dump''' window content pop-up menu).
''ASCIIcharacters''
:<vipbnf><ASCIIcharacters> : <ASCIIcharacter> [ <ASCIIcharacters> ]</vipbnf>
:This is the same memory dump but in the format of ASCII characters (a character represenrs one byte). Unprintable characters are printed as dots.
''UnicodeCharacters''
:<vipbnf><UnicodeCharacters> : <UnicodeCharacter> [ <UnicodeCharacters> ]</vipbnf>
:This is the same memory dump in the format of Unicode characters (a character represents two bytes). Unprintable characters are printed as dots.

Example:

[[Image:Ide_db_Memory_view1.png]]

The '''Memory Dump''' window title shows the module name, which memory is displayed in the window. If the module name cannot be determined, then the title displays ''Unknown module''.

If memory is inaccessible then its state will be represented by following symbol:
* 'R' - memory reserved
* 'G' - guard page
* 'X' - unknown state
* '?' - memory free.

'''Content Pop-up Menu'''

The '''Memory Dump''' window has the pop-up context menu which contains commands:
*'''Go To Address'''
*:'''Ctrl+G'''. Invokes the '''Go to Address''' dialog
*:[[Image:Ide_db_DisAsm_Go2Address.png]]
*: to type a new top address in hex format. This dialog allows typing symbolic external link names and symbolic CPU register names. Double-click in the '''Memory Dump''' window area also activates the '''Go to Address''' dialog.
*'''Go To ''Ptr'''''
*:'''Ctrl+Shift+G'''. Updates the '''Memory Dump''' window starting the first line from the address shown as ''Ptr'' (address defined by the memory contents of four or eight continued bytes at which the cursor is pointing if one of '''4-byte Integer''' or '''8-byte Integer''' is selected).
*'''Undo Go to'''
*:'''Alt+Left Arrow'''. Updates the '''Memory Dump''' window view to start from the previously used top (the first line) address.
*'''Redo Go to'''
*:'''Alt+Right Arrow'''. This operation is the counterpart to the '''Undo Go to'''. It updates the '''Memory Dump''' window view to start from the "next" top address, which was used before the '''Undo Go to''' command was implemented.
*'''Set Memory Breakpoint'''
*:This operation sets a memory breakpoint at address from the left pane.
*'''Remove Memory Breakpoint'''
*:This operation removes a previously set a memory breakpoint.
*'''Copy'''
*:Copies the selected lines to the clipboard. To select a line, click on it while holding the '''shift''' key. You can select multiple lines at one time.
*'''Copy ''Ptr'''''
*:'''Ctrl+C'''. Copies hexadecimal representation of the specified address (four or eight bytes) to the clipboard.
*'''Refresh'''
*:Refresh the '''Memory Dump''' window contents.
*'''Write Block'''
*:This command opens the '''Write Memory Block''' dialog:
*:[[Image:Ide_db_Memory_BlockWrite.png]]
*:*'''Filename'''
*:*:Here you should type in the name of a file in which the specified memory block should be saved.
*:*'''Start Address'''
*:*:Here you should specify a hexadecimal start address of the memory block.
*:*'''Length'''
*:*:Here you should specify a hexadecimal length in bytes of the memory block.
*'''Show Hex'''
*:Shows the column, which displays the memory dump in the hexadecimal format. This is the {{ide|Debugger#Debugger Views|''HexValues''}} column in the right pane.
*'''Show ASCII'''
*:Shows the column, which displays the '''''ASCII''''' format of the memory dump. This is the {{ide|Debugger#Debugger Views|''ASCIIcharacters''}} column in the right pane.
*'''Show Unicode'''
*:Shows the column, which displays the '''''Unicode''''' format of the memory dump. This is the {{ide|Debugger#Debugger Views|''UnicodeCharacters''}} column in the right pane.
*'''Update Speed...'''
*:Defines the rate of the Memory Dump window updating:
*:[[Image:iDE_db_Memory_menu1.png]]
*:*'''High'''
*:*:Performs automatic updating with the high rate.
*:*'''Normal'''
*:*:Performs automatic updating with normal rate.
*:*'''Low'''
*:*:Performs automatic updating with low rate.
*:*'''Manual'''
*:*:No automatic updating.
The '''Memory Dump''' window can be activated either by '''CTRL+Alt+M''' or from the IDE menu '''View | Memory Dump'''.

Language Reference/Generic Interfaces and Classes

2015-01-16T13:53:35Z

SergeMukhin: /* Restrictions */

{{languageReferenceNavbar|Generic Interfaces and Classes}}

{{lang|Interfaces|Interfaces}} and {{lang|Classes|classes}} can be parametrized with type parameters so that they can be used in different instantiations in different contexts.

This section must be considered as an extension to the individual sections about:
* {{lang|Interfaces|Interfaces}}
* {{lang|Classes|Classes}}
* {{lang|Implementations|Implementations}}

The pragmatic reason to use generic classes and interfaces is to declare '''parametrized object facts''' and implement operations on these facts. As illustrated in the Queue example below.

=== Example: Queue ===

Consider this interface

<vip>interface queue_integer
predicates
insert : (integer Value).
tryGet : () -> integer Value.
end interface queue_integer</vip>

An object of this type is a queue of integers, if you replace "integer" with "string" you would have a type describing queues of strings.

A generic interface can be used to describe all such interfaces in a single interface definition:

<vip>interface queue{@Elem}
predicates
insert : (@Elem Value).
tryGet : () -> @Elem Value determ.
end interface queue</vip>

<vp>@Elem</vp> is a ''scope type variable'' (distinguished from local type variables by the <vp>@</vp>).

<vp>queue{integer}</vp> represents integer-queues; <vp>queue{string}</vp> represents string-queues; and so forth.

We can declare a generic queue class like this:

<vip>class queueClass{@Elem} : queue{@Elem}
end class queueClass</vip>

<vp>queueClass{@Elem}</vp> constructs objects type <vp>queue{@Elem}</vp> for any instantiation of <vp>@Elem</vp>.

The implementation can look like this:

<vip>implement queueClass{@Elem}
facts
queue_fact : (@Elem Value).
clauses
insert(Value) :-
assert(queue_fact(Value)).
clauses
tryGet() = Value :-
retract(queue_fact(Value)),
!.
end implement queueClass</vip>

This piece of code illustrates how to create an integer queue and insert an element in it:

<vip>..., Q = queueClass{integer}::new(), Q:insert(17), ...</vip>

It is not necessary to apply the type explicitly, instead the compiler can infer it from the context:

<vip>..., Q = queueClass::new(), Q:insert(17), ...</vip>

The compiler sees that <vp>Q</vp> must be an integer queue, because we insert 17 into it.

=== Generic Interfaces ===

==== Syntax ====

Generic interfaces have a list of type parameters:

<vipbnf><InterfaceDeclaration> :
interface <InterfaceName> { <ScopeTypeVariable>-comma-sep-list-opt }
<ScopeQualifications>
<Sections>
end interface <InterfaceName>-opt

<ScopeTypeVariable> :
@ <UppercaseName></vipbnf>

The scope type parameters can be used in any declaration/definition in the interface.

==== Semantics ====

A generic interface defines all the interfaces that can be obtained by instantiating the type parameters with actual types. The scope type parameters from the opening are bound in the entire interface.

==== Restrictions ====

Then closing name should not have parameters:

<vip>interface xxx{@A}
...
end interface xxx % no parameters here</vip>

It is illegal to use same interface name for interfaces with different arity (in the same namespace):

<vip>interface xxx % xxx/0
...
end interface xxx

interface xxx{@A, @B} % error: Several classes, interfaces and/or namespaces have the same name 'xxx'
...
end interface xxx</vip>

Parameters can be used in supported interfaces:

<vip>interface xxx{@P} supports yyy{@P} % legal: @P is bound
...
end interface xxx

interface xxx supports yyy{@P} % illegal: @P must be bound
...
end interface xxx</vip>

Supported interfaces can be instantiated with any type expressions (as long as parameters are bound):

<vip>interface xxx{@A} supports yyy{integer, @A*}
...</vip>

=== Generic Classes ===

==== Syntax ====

Generic classes have a list of type parameters, and constructs objects of an interface type uses the these parameters.

<vipbnf><ClassDeclaration> :
class <ClassName> { <ScopeTypeVariable>-comma-sep-list-opt } <ConstructionType>
<ScopeQualifications>
<Sections>
end class <ClassName>-opt

<ScopeTypeVariable> :
@ <UppercaseName>

<ConstructionType> :
: <TypeExpression></vipbnf>

The construction type must be generic (i.e. a generic interface).

==== Semantics ====

A generic class declares a class with a generic constructor. The type of the constructed object will be inferred from the usage of the constructor.

==== Restrictions ====

Then closing name should not have parameters:

<vip>class xxx{@A} : xxx{@A}
...
end class xxx % no parameters here</vip>

It is illegal to use same class name for class with different arity (in the same namespace):

<vip>class xxx % xxx/0
...
end class xxx

class xxx{@A} : yyy{@A} % error: Several classes, interfaces and/or namespaces have the same name 'xxx'
...
end class xxx</vip>

If a class and interface can have the same name, the class must construct objects of that interface.

<vip>interface xxx{@A}
...
end interface xxx

class xxx{@Q, @P} : object % error: Several classes, interfaces and/or namespaces have the same name 'xxx'
...
end class xxx</vip>

Parameters in the construction type, etc must be bound:

<vip>class bbb : xxx{@Q} % error: Free parameter '@Q' is used in type expression
...</vip>

All the parameters from the class must be used in the construction type:

<vip>class xxx{@P} : object % error: Unused type parameter '@P'
...</vip>

In class declarations scope parameter can only be used in constructors, domains and constants.

<vip>class xxx{@P} : xxx{@P}
domains
list = @P*. % legal
constants
empty : @P* = []. % legal
constructors
new : (@P Init). % legal
predicates
p : (@P X). % error: Scope parameter '@P' used in a class entity
end class xxx</vip>

=== Generic Implmentations ===

==== Syntax ====

Generic implementations have a list of type parameters.

<vipbnf><ClassImplementation> :
implement <ClassName> { <ScopeTypeVariable>-comma-sep-list-opt }
<ScopeQualifications>
<Sections>
end implement <ClassName>-opt

<ScopeTypeVariable> :
@ <UppercaseName></vipbnf>

==== Semantics ====

A generic class declares a class with a generic constructor. The type of the constructed object will be inferred from the usage of the constructor.

==== Restrictions ====

Then closing name should not have parameters:

<vip>implement xxx{@A}
...
end implement xxx % no parameters here</vip>

The parameters must be the same as in the corresponding class declaration and have same order.

<vip>class xxx{@A} : aaa{@A}
...
end class xxx

implement xxx{@B} % error: The parameter '@B' is not the same as in the declaration '@A'
...
end implement xxx</vip>

In class implementations scope parameter can be used in constructors, domains, constants and in object entities (i.e. object facts, object predicates and object properties).

<vip>implement xxx{@P}
domains
list = @P*. % legal
constants
empty : @P* = []. % legal
constructors
new : (@P Init). % legal
predicates
op : (@P X). % legal
class predicates
cp : (@P X). % error: Scope parameter '@P' used in a class entity
facts
ofct : (@P). % legal
class facts
cfct : (@P). % error: Scope parameter '@P' used in a class entity
...
end implement xxx</vip>

Language Reference/Terms/Anonymous Predicates

2015-01-01T22:04:52Z

SergeMukhin: remove filterPredicate

An anonymous predicate is an expression that evaluates to a predicate value. The predicate value can be bound to a variable, passed as arguments or returned as result, but the value does not have a 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 rather powerful ability that can be used to avoid 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.

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

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. ...):

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

<vp>W</vp> captures the ellipsis variable. <vp>qqq</vp> receives a zero-arity 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 count, 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> comes from two different objects, which each have a count fact, so the output will be:

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

Technically, the class version actually doesn't capture anything, it merely have access to the fact. Likewise, the object version doesn't actually capture the fact, instead it captures This and through This it obtains access to the object facts.

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

As described above it is possible to capture <vp>This</vp> and thereby gaining access to objects 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 R becomes <vp>{ (B) = 2200+B } }</vp>. So, the output is:

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

==== Syntactic Sugar ====

If you don't need the arguments they can be skipped.
So this code-fragment:

<vip>P = { (_) :- succeed },
Q = { (_, _) = 0 },
R = { (_, _, _) = _ :- fail }
Can be shortened down to this:
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 ====

This section shows some cases where anonymous predicates are very handy. The examples assume that the PFC scopes core, std, stdio, list and string are open.

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

Anonymous predicates are good for creating dummy predicate values:

<vip>ppp( { = true } ), % don't filter (boolean)
qqq( { :- succeed } ), % don't 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>

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

<vip>% myArray is 0-based, write3 requires 1-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 "<vp>C</vp> is the child of <vp>P</vp>"-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 "<vp>P</vp> is the parent of <vp>C</vp>" 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 out 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 <vp>P</vp>". Since each invocation corresponds to one child we will call <vp>addChild</vp> supplying <vp>1</vp> as a "dummy" argument. The More 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>

Filter is used to filter the list <vp>[1,2,3,4,5,6,7,8,9]</vp>; the filtered list and the Label 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 dividable 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 sortBy, 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 compare 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 =====

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 null-ary predicate and run 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) use this method.
The project has a form that can start 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 jobLog 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 completion property (range <vp>0</vp> to <vp>1</vp>). Likewise, the status 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 null-ary 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 null-ary 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> pass 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 make transfer the 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 null-ary 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 that 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 are finished.
Our script executer 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/Lexical Elements

2014-10-22T08:45:47Z

SergeMukhin: " -> '

{{languageReferenceNavbar|Lexical Elements}}

The Visual Prolog Compiler is applied to a source file. This source file may include other source files, which are (conceptually) inserted into the original source file to constitute one '''''compilation unit'''''. The compilation of a compilation unit is done in two conceptual steps:
*first the input is transformed into a sequence of tokens;
*and then these tokens are syntactically analyzed and transformed into executable code.

The lexical analysis of the program will break the compilation unit <vpbnf><CompilationUnit></vpbnf> into a list of input elements <vpbnf><InputElement></vpbnf>

<vipbnf><CompilationUnit>:
<InputElement>-list</vipbnf>

<vipbnf><InputElement>:
<Comment>
<WhiteSpace>
<Token></vipbnf>

Only tokens are significant to the subsequent syntax analysis.

=== Comments ===

A Visual Prolog comment is written in one of the following ways:
*The <vpbnf>/*</vpbnf> (slash, asterisk) characters, followed by any sequence of characters (including new lines), terminated by the <vpbnf>*/</vpbnf> (asterisk, slash) characters. These comments can be multi-lined. They can also be nested.
*The <vpbnf>%</vpbnf> (percent sign) character, followed by any sequence of characters. Comments that begin with character <vpbnf>%</vpbnf> (percent sign) continue until the end of the line. Therefore, they are commonly called ''single-line comments''.

Notice the following comment example:

<pre style="color: #AA77BD">/* Begin of Comment1
% Nested Comment2 */ Comment 1 is not terminated (single-line comment)
This is the real termination of Comment1 */</pre>

=== Whitespace ===

<vipbnf><WhiteSpace>:
<Space>
<Tab>
<NewLine></vipbnf>

Here <vpbnf><Space></vpbnf> is a space character, <vpbnf><Tab></vpbnf> is a tabulation character and <vpbnf><NewLine></vpbnf> is a new line character.

=== Tokens ===

<vipbnf><Token>:
<Identifier>
<Keyword>
<Punctuator>
<Operator>
<Literal></vipbnf>

==== Identifiers ====

<vipbnf><Identifier>:
<LowercaseIdentifier>
<UppercaseIdentifier>
<AnonymousIdentifier>
<Ellipsis></vipbnf>

A <vpbnf><LowercaseIdentifier></vpbnf> is a sequence of letters, digits, and underscores that starts with a small letter. An <vpbnf><UppercaseIdentifier></vpbnf> is a sequence of letters, digits, and underscores that starts either with a capital letter or with an underscore.

<vipbnf><AnonymousIdentifier> : _</vipbnf>

<vipbnf><Ellipsis> :
...</vipbnf>

==== Keywords ====

Keywords are divided into major and minor keywords, this division is only cosmetic however, there is no formal difference between major and minor keywords. In the sequel we will however use different coloring for them.

<vipbnf><Keyword> :
<MajorKeyword>
<MinorKeyword></vipbnf>

<vipbnf><MajorKeyword> : one of
class clauses constants constructors
delegate domains
end
facts
goal
implement inherits interface
monitor
namespace
open
predicates
properties
resolve
supports</vipbnf>

<vipbnf><MinorKeyword> : one of
align and anyflow as
bitsize
catch
determ digits div do
else elseif erroneous externally
failure finally foreach from
guard
if in
language
mod multi
nondeterm
or orelse
procedure
quot
rem
single
then to try</vipbnf>

All keywords except <vp>as</vp> and <vp>language</vp> are reserved words.

<vp>end</vp> is always combined with another key word:

<vip>end class
end implement
end interface
end if
end foreach
end try</vip>

==== Punctuation Marks ====

Punctuation marks in Visual Prolog have syntactic and semantic meaning to the compiler, but do not specify by themselves an operation that yields a value. Some punctuation marks, either alone or in combinations, can also be Visual Prolog operators.

Punctuation marks are:

<vipbnf><PunctuationMarks>: one of
; ! , . # [ ] | ( ) { } :- : ::</vipbnf>

==== Operators ====

{{lang2|Terms|Operators|Operators}} specify an evaluation to be performed on involved operands.
<vipbnf><Operators>: one of
^
/ * div mod quot rem
+ -
= < > <> >< <= >= :=
</vipbnf>

All operators are {{lang2|Terms|Operators|binary}}, but <vp>-</vp> and <vp>+</vp> also exist as {{lang2|Terms|Operators|unary}} operators.

<vp>div</vp>, <vp>mod</vp>, <vp>quot</vp> and <vp>rem</vp> are reserved words.

=== Literals ===

Literals fall into following categories: integer, character, floating-point, string, binary and list.

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

==== Integral Literals ====

<vipbnf><IntegerLiteral>:
<UnaryPlus>-opt <DecimalDigit>-list
<UnaryMinus>-opt <DecimalDigit>-list
<UnaryPlus>-opt <OctalPrefix> <OctalDigit>-list
<UnaryMinus>-opt <OctalPrefix> <OctalDigit>-list
<UnaryPlus>-opt <HexadecimalPrefix> <HexadecimalDigit>-list
<UnaryMinus>-opt <HexadecimalPrefix> <HexadecimalDigit>-list

<UnaryPlus>:
+

<UnaryMinus>:
-

<OctalPrefix>:
0o

<OctalDigit>: one of
0 1 2 3 4 5 6 7

<DecimalDigit>: one of
0 1 2 3 4 5 6 7 8 9

<HexadecimalPrefix>:
0x

<HexadecimalDigit>: one of
0 1 2 3 4 5 6 7 8 9 A a B b C c D d E e F f</vipbnf>

An integral literal can belong to {{lang2|Built-in_entities|integer|integer}} or {{lang2|Built-in_entities|unsigned|unsigned}} domains and it should not exceed maximum and minimum {{lang2|Built-in_entities|integer|integer}} or {{lang2|Built-in_entities|unsigned|unsigned}} values.

==== Real Literal ====

<vipbnf><RealLiteral>:
<UnaryMinus>-opt <DecimalDigit>-list <FractionOfFloat>-opt <Exponent>-opt

<FractionOfFloat>:
. <DecimalDigit>-list

<Exponent>:
<ExponentSymbol> <ExponentSign>-opt <DecimalDigit>-list

<ExponentSymbol>: one of
e E

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

A floating literal should not exceed maximum and minimum real values.

==== Character Literals ====

<vipbnf><CharacterLiteral>:
' <CharacterValue> '</vipbnf>

<vpbnf><CharacterValue></vpbnf> can be any printable character or an escape sequence:

*<vpbnf>\\</vpbnf> representing <vp>\</vp>
*<vp>\t</vp> representing Tab character
*<vp>\n</vp> representing New Line character
*<vp>\r</vp> representing carriage return
*<vp>\'</vp> representing single quote
*<vp>\"</vp> representing double quote
*<vp>\u</vp><vpbnf><XXXX></vpbnf>, here <vpbnf><XXXX></vpbnf> should be exactly four <vpbnf><HexadecimalDigit></vpbnf>'s representing the Unicode character corresponding to the digits.

==== String Literals ====

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

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

A string literal consists of one or more <vpbnf><StringLiteralPart></vpbnf>'s, which are concatenated.

The first two forms (the ' and " forms) uses escape sequences to express certain characters

*<vp>\\</vp> representing <vp>\</vp>
*<vp>\t</vp> representing Tab character
*<vp>\n</vp> representing New Line character
*<vp>\r</vp> representing carriage return
*<vp>\</vp><vp>"</vp> representing double quote
*<vp>\</vp><vp>'</vp> representing single quote
*<vp>\u</vp><vpbnf><XXXX></vpbnf>, here <vpbnf><XXXX></vpbnf> should be exactly four <vpbnf><HexadecimalDigit></vpbnf>'s representing the Unicode character corresponding to the digits.

In single quoted strings it is optional to escape double quotes, and likewise it is optional to escape single quotes in double quoted strings.

Single quoted strings must contain at least two characters otherwise they will be assumed to be a character literal.

The @-literals can be used to avoid obscuring the string literals with escape characters. The literals starts with @ followed by some non-letter character <vpbnf><AtOpenChar></vpbnf>. And it terminates when the close character <vpbnf><AtCloseChar></vpbnf> is met. For most characters the close character is the same as the opening character, but for diverse paranthesis charactes the close character is the corresponding opposite paranthesis.

{|border="2" cellspacing="0" cellpadding="5" rules="all" style="border:solid 1px #AAAAAA; border-collapse:collapse; empty-cells:show; text-align: center;"
|-
| Open
| Close
| Open
| Close
|-
| @(
| )
| @)
| (
|-
| @[
| ]
| @]
| [
|-
| @{
| }
| @}
| {
|-
| @<
| >
| @>
| <
|}

For all non-paranthesis opening character the close character is the same as the open character, for example @" is closed by ".

For all @-strings it is the case the twice the closing character does not close the string, but means one occurence of the closing character in the string.

{{Example|
This example uses @[ as opening and ] as closing, inside the string literal both " and ' can be used unescaped:
[[Image:AtString.png]]
}}

==== Binary Literals ====

<vipbnf><BinaryLiteral>:
$[ <ElementValue>-comma-sep-list-opt ]
<ElementValue>:
<IntegerLiteral></vipbnf>

<vpbnf><ElementValue></vpbnf> should be any integral arithmetic expression (for example, constant), which should be calculated while compilation-time and be in the range from <vp>0</vp> till <vp>255.</vp>

==== List Literals ====

All elements in a list literal must belong to the same domain (or to compatible domains). This domain can be any {{lang2|Built-in_entities|Domains|built-in}} or {{lang|Domains|user defined domain}}, for example, it can be {{lang2|Lexical_Elements|Integral_Literals|integral}}, {{lang2|Lexical_Elements|Character_Literals|character}}, {{lang2|Lexical_Elements|Binary_Literals|binary}}, {{lang2|Lexical_Elements|Compound_Domain_Literals|compound domain}}, etc.

<vipbnf><ListLiteral>:
[ <SimpleLiteral>-comma-sep-list-opt ]
[ <SimpleLiteral>-comma-sep-list | <ListLiteral> ]</vipbnf>

Here <vpbnf><SimpleLiteral></vpbnf> can be:

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

{{Example| These are all valid list literals:
<vip>
[] % empty list
[1,2,3] % list of integers
["abc", "defg"] % list of strings</vip>
}}

{{Example| This is invalid because the elements in a list must all have same type:
<vip>
[1,"abc"] % this is INVALID list</vip>
}}

==== Compound Domain Literals ====

Terms of {{lang2|Domains|Compound_Domains|user defined compound}} domains can be treated as literals if all their arguments are literals.

Language Reference/Built-in entities/Predicates

2014-06-24T11:31:04Z

SergeMukhin: try-catch-finally

<noinclude>__NOTOC__</noinclude>

{|{{prettytable}}
|-
|[[Language_Reference/Terms#and_.28.2C.29|and/2]] [[Language_Reference/Terms#and_.28.2C.29|,/2]]
|Term "and"
|-
|[[#assert|assert/1]]
|Insert the specified fact at the end of the matched internal facts database.
|-
|[[#asserta|asserta/1]]
|Insert a fact at the beginning of the matched internal facts database.
|-
|[[#assertz|assertz/1]]
|Insert a fact at the end of the matched internal facts database.
|-
|[[#bound|bound/1]] <vp>determ</vp>
|Test whether the specified variable is bound to a value.
|-
|[[#class_name|class_name/0->]]
|This compile time predicate returns the string ''ClassName'' that represents the name of the current interface or class.
|-
|[[#compare|compare/2->]]
|Returns the result of the variables' comparison.
|-
|[[#convert|convert/2->]]
|Checked term conversion.
|-
|[[#digitsOf|digitsOf/1->]]
|Returns precision of the specified floating-point domain.
|-
|[[#errorExit|errorExit/1]] <vp>erroneous</vp>
|Performs a run-time error with the specified return code ''ErrorNumber'' and sets the internal error information.
|-
|[[#fail|fail/0]] <vp>failure</vp>
|Invoke backtracking.
|-
|[[#free|free/1]] <vp>determ</vp>
|Check whether a variable is free.
|-
|[[#fromEllipsis|fromEllipsis/1->]]
|Creates the list of terms of the universal type <vp>any</vp> from the ''EllipsisBlock''.
|-
|[[#hasDomain|hasDomain/2]] [[#hasDomain|hasDomain/2->]]
|Declares/restricts the type of a variable or value.
|-
|[[Language_Reference/Terms#in|in/2]] <vp>determ</vp> [[Language_Reference/Terms#in|in/2]] <vp>nondeterm</vp>
|Infix operator "in" (in-test and in-iterator).
|-
|[[#isErroneous|isErroneous/1]] <vp>determ</vp>
|Returns the lower bound value of the specified numeric domain.
|-
|[[#lowerBound|lowerBound/1->]]
|Returns the lower bound value of the specified numeric domain.
|-
|[[#maxDigits|maxDigits/1->]]
|Retrieves the value of digits (precision) of the basic domain corresponding to the specified floating-point domain ''domainName''.
|-
|[[#not|not/1]] <vp>determ</vp>
|Negate the result (success/fail) of subgoal.
|-
|[[Language_Reference/Terms#or_.28.3B.29|or/2]] [[Language_Reference/Terms#and_.28.3B.29|;/2]]
|Nondeterministic term "or"
|-
|[[Language_Reference/Terms#orelse|orelse]]
|Deterministic term "or"
|-
|[[#predicate_fullname|predicate_fullname/1->]]
|This compile time predicate returns the string ''PredicateFullName'' that represent the name of the predicate in which clause body <vp>predicate_name</vp> is called. The returned predicate name is qualified with a scope name.
|-
|[[#predicate_name|predicate_name/1->]]
|This compile time predicate returns the string ''PredicateName'' that represent the name of the predicate in which clause body <vp>predicate_name</vp> is called. The returned predicate name is not qualified with a scope name.
|-
|[[#programPoint|programPoint/0->]]
|This compile time predicate returns the <vp>programPoint</vp> corresponding to the place where it is called.
|-
|[[#retract|retract/1]] <vp>nondeterm</vp>
|Remove a matched fact from the matched internal facts database.
|-
|[[#retractall|retractall/1]]
|Remove all matching facts from the matched internal facts database.
|-
|[[#retractFactDb|retractFactDb/1]]
|Remove all facts from the specified named internal facts database.
|-
|[[#sizeBitsOf|sizeBitsOf/1->]]
|Retrieves the number of bits occupied in memory by an entity of the specified domain ''DomainName''.
|-
|[[#sizeOf|sizeOf/1->]]
|Retrieves the number of bytes occupied in memory by the specified term.
|-
|[[#sizeOfDomain|sizeOfDomain/1->]]
|Retrieves the number of bytes occupied in memory by the entity of the specified domain ''DomainName''.
|-
|[[#sourcefile_lineno|sourcefile_lineno/0->]]
|Returns the current line number in the source file processed by the compiler .
|-
|[[#sourcefile_name|sourcefile_name/0->]]
|Returns the name of the source file processed by the compiler.
|-
|[[#sourcefile_timestamp|sourcefile_timestamp/0->]]
|Returns the string representing the date and time of the source file processed by the compiler.
|-
|[[#succeed|succeed/0]]
|The predicate <vp>succeed/0</vp> will always succeed.
|-
|[[#toAny|toAny/1->]]
|Converts the specified ''Term'' to the value of the universal term type <vp>any</vp>.
|-
|[[#toBinary|toBinary/1->]]
|Converts the specified Term to the binary representation.
|-
|[[#toBoolean|toBoolean/1->]]
|The purpose of this meta-predicate is to convert the deterministic call (to a predicate or fact) to the procedure that returns the value of <vp>boolean</vp> domain.
|-
|[[#toEllipsis|toEllipsis/1->]]
|Creates the ''EllipsisBlock'' from the list of <vp>any</vp> type values.
|-
|[[#toString|toString/1->]]
|Converts the specified ''Term'' to the string representation.
|-
|[[#toTerm|toTerm/1->]] [[#toTerm|toTerm/2->]]
|Converts the string/binary representation of the specified term ''SrcTerm'' into representation corresponding to the domain of ''PrologTerm'' variable of the return value.
|-
|[[#tryToTerm|tryToTerm/1->]] <vp>determ</vp> [[#tryToTerm|tryToTerm/2->]] <vp>determ</vp>
|Converts the string/binary representation of the specified term ''SrcTerm'' into representation corresponding to the domain of ''PrologTerm'' variable of the return value.
|-
|[[#tryConvert|tryConvert/2->]] <vp>determ</vp>
|Checks whether the input term ''InputTerm'' can be strictly converted into the specified domain ''returnDomain'' and returns the converted term ''ReturnTerm''.
|-
|[[#uncheckedConvert|uncheckedConvert/2->]]
|Unchecked conversion of domains.
|-
|[[#upperBound|upperBound/1->]]
|Returns the upper bound value of the specified numeric domain.
|}

The following predicates are deprecated:
{|{{prettytable}}
|-
| finally/2
| Use [[Language_Reference/Terms#try-finally| <vp>try-finally</vp>]] constuction instead.
|-
| findall/3
| Use list comprehension [[Language_Reference/Terms#List_Comprehension| <vp>[ ... || ... ]</vp>]] instead
|-
| trap/3 <vp>determ</vp>
| Use [[Language_Reference/Terms#try-catch| <vp>try-catch</vp>]] constuction instead.
|}

==== and ====

See [[Language_Reference/Terms#and_.28.2C.29|and (,)]].

==== assert ====

<vip>assert : (<fact-term> FactTerm).</vip>

Insert the specified fact at the end of the matched internal facts database

<vp>assert(Fact)</vp> inserts <vp>Fact</vp> in the matched internal facts database after any other stored facts for the corresponding database predicate. <vp>Fact</vp> must be a term belonging to the domain of an internal facts database. <vp>assert/1</vp> applied to a single fact changes the existing instance of a fact to the specified one. <vp>assert/1</vp> has the same effect as [[#assertz|assertz/1]]. See also [[#asserta|asserta/1]].

Notice that the combination of [[#retract|retract/1]] and <vp>assert/1</vp> like the following can lead to endless loop:

<vip>loop() :-
retract(fct(X)),
... % creating Y from X
assert(fct(Y)),
fail.</vip>

The problem is that the retract in first line will eventually retract the fact asserted in the last line, because that fact is inserted ''last'' in the fact chain.

Exceptions:

* Attempt to assert a second instance to a fact declared as determ.

==== asserta ====

<vip>asserta : (<fact-term> FactTerm).</vip>

Insert a fact at the beginning of the matched internal facts database.

The <vp>asserta(Fact)</vp> predicate inserts a <vp>Fact</vp> in the matched internal facts database before any other stored facts for the corresponding predicate. The <vp>Fact</vp> must be a term belonging to the domain of an internal facts database. The <vp>asserta/1</vp> applied to a single fact changes the existing instance of a fact to the specified one. See also [[#assert|assert/1]] and [[#assertz|assertz/1]].

Exceptions:

* Attempt to a fact declared as determ, but the fact instance already exists.

==== assertz ====

<vip>assertz : (<fact-term> FactTerm).</vip>

<vp>assertz</vp> does exactly the same as the [[#assert|assert/1]] predicate.

==== bound ====

<vip>bound : (<variable> Variable) determ.</vip>

Test whether the specified variable is bound to a value.

The <vp>bound(Variable)</vp> succeeds if <vp>Variable</vp> is bound and fails if it is free. The <vp>bound</vp> predicate is used to control flow patterns and to check the binding of reference variables. The <vp>bound</vp> predicate treats the specified <vp>Variable</vp> as bound if any of it's part is instantiated.

See also [[#free|free/1]].

==== class_name ====

<vip>class_Name : () -> string ClassName.</vip>

This compile time predicate returns the string <vp>ClassName</vp> that represents the name of the current interface or class.

==== compare ====

<vip>compare : (A Left, A Right) -> compareResult CompareResult.</vip>

Comparison of two terms of the same domain, resturns the value of [[#compareResult|compareResult]] domain.

<vp>CompareResult</vp> = compare("<vp>bar</vp>", "<vp>foo</vp>")

==== convert ====

<vip>convert : (<type> Type, Term) -> <type> Converted.</vip>

Checked term conversion.

Call-template for this function is:

<vp>ReturnTerm</vp> = convert(returnDomain, <vp>InputTerm</vp>)

* <vpbnf>returnDomain</vpbnf>: Specifies a domain to which function <vp>convert/2-></vp> converts <vp>InputTerm</vp>. Here ''returnDomain'' must be a name of built-in Visual Prolog domain, an interface domain, a name of such user defined domain that is synonym to one of built-in Visual Prolog domains, a numeric domain, binary and pointer domains. The domain name ''returnDomain'' must be specified at compile-time, i.e. it cannot come from a variable.

* <vpbnf><InputTerm></vpbnf>: Specifies the value that must be converted. <vp>InputTerm</vp> may be any Prolog term or an expression. If <vp>InputTerm</vp> is an expression, then it will be evaluated before the conversion.

* <vpbnf><ReturnTerm></vpbnf>: Returned parameter <vp>ReturnTerm</vp> will be of ''returnDomain'' type.

The <vp>convert</vp> predicate performs a clean and genuine conversion of the given <vp>InputTerm</vp>, returning a new term <vp>ReturnTerm</vp> of the specified new domain ''returnDomain''. If <vp>convert</vp> cannot perform the required conversion, it rises errors. The similar functionality is provided by the [[#tryConvert|tryConvert/2->]] predicate, but <vp>tryConvert-></vp> fails and does not produce any runtime errors if it cannot perform the conversion.

===== Allowed conversions =====

* Between numerical domains.
* Between interface types.
* Between [[#string|string]] and [[#symbol|symbol]] domains.
* From [[#binary|binary]] to [[#pointer|pointer]].
* For synonyms of mentioned domains.
* Between [http://wiki.visual-prolog.com/index.php?title=How_To_Remove_Reference_Domains_from_a_Project reference] domains and corresponding non-reference domains.

The contrast to these is [[#uncheckedConvert|uncheckedConvert/2->]] predicate, which performs an unchecked conversion between terms from any domains, which have the same bit-size.

The <vp>convert/2-></vp> (or [[#tryConvert|tryConvert/2->]]) predicate accomplishes a checked explicit conversion, when the source and target domains are statically known during the compilation. The result of an explicit conversion can be one of the following:

* '''ok''' the successful conversion to the target domain;
* '''run-time-check''' the conversion to the target domain with generation of run-time checking for compatibility;
* '''error''' the conversion is impossible, error output.

===== Rules of Checked Explicit Conversions =====

* Synonyms of domains are converted using the same rules that are applied to the domains themselves.
* Numerical domains can be converted to the numerical domains only.
* Integral constants are the representatives of the anonymous integral domain: <vp>[const .. const]</vp>.
* Real constants are the representatives of the anonymous real domain: <vp>digits</vp> <vp>dig [const .. const]</vp>, where <vp>dig</vp> is the number of the digits in mantissa without insignificant zeroes.
* A value of the symbol domain can be converted to the string domain and vice versa.
* A value of binary domain can be converted to the pointer domain.
* The domains that are implicitly introduced for interfaces can be converted only to the interface domains according to the rules specified below.
* All other domains cannot be converted.

===== Conversions of Numerical Domains =====

* The range is considered first during such conversion. If the ranges of source and target do not intersect, then an error is produced. If the ranges of source and target only partially intersect, then run-time checking is generated. Also, if one of domains is real and another is an integral one, then the integer range is converted to the real range before the comparison.
* When input term in real and output is integer, then <vp>convert/2-></vp> and [[#tryConvert|tryConvert/2->]] predicates truncate the input value to the nearest integer value, which is nearer to zero.

===== Conversions of Interface Types =====

Predicate <vp>convert/2-></vp> allow to convert any object to any interface type. The actual correctness of such conversion is checked at runtime. When object is created, its type is internally stored, therefore when the object is passed as argument it still remember about its original type. This original type is used for checking allowed conversions. The example:

<vip>interface x
supports a, b
end interface x</vip>

If object is created by class, which implements <vp>x</vp> interface, and then object is passed as parameter of type <vp>a</vp> to some predicate, then it is allowed to convert the object to <vp>b</vp> type.

Exceptions:

* Check range error.
* Unsupported interface type.

==== digitsOf ====

<vip>digitsOf : (<real-domain> Domain) -> unsigned.</vip>

Returns precision of the specified floating-point domain.

Call-template for this function is:

<vip>Precision = digitsof(domainName)</vip>

The input parameter ''domainName'' of this compiling-time predicate is a floating-point domain, it should be explicitly specified at compile-time (that is, ''domainName'' cannot come from a variable). The predicate returns the number <vpbnf><Precision></vpbnf> that was determined by the <vp>digits</vp> attribute in the domain declaration.

The compiler guarantees that values of the domain ''domainName'' will have at least <vpbnf><Precision></vpbnf> number of significant decimal digits.

==== errorExit ====

<vip>errorExit : (unsigned ErrorNumber) erroneous.</vip>

Performs a run-time error with the specified return code <vp>ErrorNumber</vp>, which can be used in the [[#try-catch-finally|try-catch-finally]].

==== fail ====

<vip>fail : () failure.</vip>

The <vp>fail</vp> predicate forces failure and, hence, always causes backtracking. A clause that fails (with <vp>fail</vp> or for some other reason) cannot bind output arguments.

==== free ====

<vip>free : (<variableName> Variable) determ.</vip>

Check whether a variable is free.

Call-template for this predicate is:

<vip>free(Variable)</vip>

The <vp>free</vp> predicate succeeds if the specified <vp>Variable</vp> is free and fails if <vp>Variable</vp> is bound. The <vp>free</vp> predicate treats the specified <vp>Variable</vp> as bound if any of it's part are instantiated.

See also [[#bound|bound/1]].

==== fromEllipsis ====

<vip>fromEllipsis : (...) -> any* AnyTermList.</vip>

This predicate creates the list of terms of the universal type <vp>any</vp> from the ''EllipsisBlock'' '''...''' (i.e. from the special varying parameters block).

Call-template for this function is:

<vip>AnyTermList = fromEllipsis(EllipsisBlock )</vip>

See also [[#toEllipsis|toEllipsis/1->]].

==== hasDomain ====

{{Template:NonReleased}}

<vp>hasDomain</vp> is not really a predicate, but more a type declaration/restriction. It has two forms a non-function for declaring/restricting the type of a variable and a function form for declaring/restricting the type of a value.

The non-function form is called with a type as first parmeter and a variable as second parameter.

<vip>hasDomain : (<type> Type, Type Variable).</vip>

The only effect of the call is that the <vp>Variable</vp> will be restricted to the type <vp>Type</vp>.

The variable can be free, bound or of some mixed flow and the binding of the variable will not change in any way.

The function form is called with a type as first argument and a value as second argument, and it returns the same value.

<vip>hasDomain : (<type> Type, Type Value) -> Type Value.</vip>

The only effect of the call is to ensure that the <vp>Value</vp> will be restricted to the type <vp>Type</vp>.

==== lowerBound ====

<vip>lowerBound : (<numeric-domain> NumericDomain) -> <numeric-domain> LowerBound.</vip>

Returns the lower bound of the specified <vp>NumericDomain</vp>.

Call-template for this function is:

<vip>LowerBoundValue = lowerBound(domainName)</vip>

The <vp>lowerBound</vp> is a compiling-time predicate. The <vp>lowerBound</vp> returns the lower bound value <vp>LowerBoundValue</vp> of the specified numeric domain ''domainName''. The return value <vp>LowerBoundValue</vp> belongs to the same domain ''domainName''. The ''domainName'' parameter should be the name of any numerical domain; this domain name should be explicitly specified at compile-time (that is, ''domainName'' cannot come from a variable). See also [[#upperBound|upperBound/1->]].

It will give a compile time error if the specified domain ''domainName'' is not numeric domain.

==== in ====

See [[Language_Reference/Terms#in|in/2]].

==== isErroneous ====

<vip>isErroneous : (<fact-variable> FactVariable) determ.</vip>

The predicate succeeds if the specified fact variable is <vp>erroneous</vp>.

Call-template for this predicate is:

<vip>isErroneous(factVariableName)</vip>

The predicate succeeds if the specified fact variable <vp>factVariableName</vp> has the <vp>erroneous</vp> value, otherwise it fails.

==== maxDigits ====

<vip>maxDigits : (<real-domain> RealDomain) -> unsigned MaxDigits</vip>

Retrieves the value of digits (precision) of the basic domain corresponding to the specified floating-point domain ''domainName''.

Call-template for this function is:

<vip>MaxDigitsNumber = maxdigits(domainName)</vip>

The return maximal number of digits <vp>MaxDigitsNumber</vp> for the ''domainName'' parameter, which should be the name of a <vp>real</vp> domain.

==== not ====

See [[Language_Reference/Terms#not|not]].

==== or ====

See [[Language_Reference/Terms#or_.28.3B.29|or (;)]].

==== orelse ====

See [[Language_Reference/Terms#orelse|orelse]].

==== predicate_fullname ====

<vip>predicate_fullname : () -> string PredicateFullName.</vip>

This predicate returns the name <vp>PredicateFullName</vp> of the predicate in which it is invoked. The returned predicate name is qualified with a scope name.

<vp>predicate_fullname</vp> can only be used inside a clause. Use of <vp>predicate_fullname</vp> in other places causes a compile time error. See also [[#predicate_name|predicate_name]].

==== predicate_name ====

<vip>predicate_name : () -> string PredicateName.</vip>

This predicate returns the name <vp>PredicateName</vp> of the predicate in which it is invoked.

<vp>predicate_name</vp> can only be used inside a clause. Use of <vp>predicate_name</vp> in other places causes a compile time error. See also [[#predicate_fullname|predicate_fullname]]

==== programPoint ====

<vip>programPoint : () -> core::programPoint ProgramPoint.</vip>

This predicate returns the name <vp>programPoint</vp> corresponding to the place where it is invoked.

==== retract ====

<vip>retract : (<fact-term> FactTerm) nondeterm anyflow.</vip>

Successively removes the first matching fact from the facts database. Fails when no more facts match.

Call-template for this predicate is:

<vip>retract(FactTemplate)</vip>

Here <vp>FactTemplate</vp> should be a fact term. The <vp>retract/1</vp> predicate deletes the first fact that matches the <vp>FactTemplate</vp> in the appropriated facts database. During backtracking, the rest of the matching facts will be deleted.

Notice that <vp>FactTemplate</vp> can have any level of instantiation. The <vp>FactTemplate</vp> is matched with the facts in the facts database, which means that any free variables will be bound in the call to <vp>retract/1</vp>.

The <vp>FactTemplate</vp> can contain any anonymous variables. That is, variables with names consisting from the single underscore <vp>_</vp> or a variable with a name starting with an underscore <vp>_AnyValue</vp> if the variable occurs only once in the clause. For example.

<vip>retract(person("Hans", _Age)),</vip>

will retract the first matched person fact that has "<vp>Hans</vp>" as the first argument and anything as the second argument.

When retracting a fact, which is declared to be determ, the call to <vp>retract/1</vp> will be deterministic.

See also [[#retractall|retractall/1]] and [[#retractFactDb|retractFactDb]].

The <vp>retract/1</vp> predicate cannot be applied to single facts or fact variables.

Be careful calling <vp>retract/1</vp> with free <vp>FactTemplate</vp> variable if any single fact is declared in the project current scope. If you retract a single fact, then the run-time error is generated. The <vp>retract/1</vp> predicate fails when there are no more matches.

==== retractall ====

<vip>retractall : (<fact-term> FactTerm) .</vip>

Remove all matching facts from the facts database.

Call-template for this predicate is:

<vip>retractall(FactTemplate)</vip>

Here <vp>FactTemplate</vp> should be a fact term.

The <vp>retractall/1</vp> retracts all facts which match the given ''FactTemplate''. It always succeeds, even if no facts were retracted.

Attempting to retract a <vp>single</vp> fact will cause a compile time error.

It is not possible to obtain any output values from <vp>retractall/1</vp>. For this reason, the variables in the call must be bound or be a single underscores (anonymous). Notice that <vp>FactTemplate</vp> can have any level of instantiation, but free variables must be single underscores ("unconditionally anonymous"). In difference to [[#retract|retract/1]] "conditionally" anonymous variables with names starting from the underscore (like <vp>_AnyValue</vp>) cannot be used in <vp>retractall/1</vp>.

See also [[#retract|retract/1]] and [[#retractFactDb|retractFactDb/1]].

==== retractFactDb ====

<vip>retractFactDb : (factDB FactDB).</vip>

Remove all facts from the named internal facts database <vp>FactDB</vp>.

Call-template for this predicate is:

<vip>retractFactDb(FactDB)</vip>

The <vp>retractFactDb/1</vp> removes all facts from the named facts database <vp>FactDB</vp>.

Notice, it is impossible to retract <vp>single</vp> facts and fact variables, so the predicate leaves such ones as they are.

See also [[#retractall|retractall/1]] and [[#retract|retract/1]].

==== retractAll/2 ====

Obsolete predicate! Use [[#retractFactDb|retractFactDb/1]] instead.

==== sizeBitsOf ====

<vip>sizeBitsOf : (<domain> DomainName) -> unsigned BitSize.</vip>

Retrieves the number of bits occupied in memory by an entity of the specified domain <vp>DomainName</vp>.

Call-template for this function is:

<vip>BitSize = sizeBitsOf(DomainName)</vip>

This compiling-time predicate receives the domain <vp>DomainName</vp> as input parameter and return the size of memory that is occupied by the entity of the given domain. The result is measured in bits. For the integer domains <vp>sizeBitsOf/1-></vp> predicate returns the value that was defined for the size-field in a domain's declaration.

The following is always true for the integral domains:

<vip>sizeOfDomain(domain)*8 - 7 <= sizeBitsOf(domain) <= sizeOfDomain(domain)*8</vip>

See also [[#sizeOfDomain|sizeOfDomain]]/1->.

==== sizeOf ====

<vip>sizeOf : (<term> Term) -> integer ByteSize.</vip>

Retrieves the number of bytes occupied in memory by the specified term <vp>Term</vp>.

Call-template for this function is:

<vip>ByteSize = sizeOf(Term)</vip>

The <vp>sizeOf/1-></vp> function receives a term as input parameter and returns value <vp>ByteSize</vp> that specifies the number of bytes occupied in memory by this term <vp>Term</vp>.

==== sizeOfDomain ====

<vip>sizeOfDomain : (<domain> Domain) -> integer ByteSize.</vip>

Retrieves the number of bytes occupied in memory by the entity of the specified domain <vp>DomainName</vp>.

Call-template for this function is:

<vip>ByteSize = sizeOfDomain(DomainName)</vip>

This compiling-time predicate receives the domain <vp>DomainName</vp> as input parameter and return the size of memory that is occupied by the entity of the given domain. The result is measured in bytes. The returned value <vp>ByteSize</vp> belongs to the integer domain. Compare with [[#sizeBitsOf|sizeBitsOf/1->]], which returns size of a domain measured in bits.

==== sourcefile_lineno ====

<vip>sourcefile_lineno : () -> unsigned LineNumber.</vip>

Returns the current line number in the source file processed by the compiler.

==== sourcefile_name ====

<vip>sourcefile_name : () -> string FileName.</vip>

Returns the name of the source file processed by the compiler.

==== sourcefile_timestamp ====

<vip>sourcefile_timestamp : () -> string TimeStamp..</vip>

Returns a string that represents the date and time of the currently compiled source file in format <vp>YYYY-MM-DD</vp> <vp>HH:MM:SS</vp>. Where:

* <vp>YYYY</vp> - Year.
* <vp>MM</vp> - Month.
* <vp>DD</vp> - Day.
* <vp>HH</vp> - Hour.
* <vp>MM</vp> - Minute.
* <vp>SS</vp> - Second.

==== succeed ====

<vip>succeed : ().</vip>

The predicate <vp>succeed/0</vp> will always succeed.

==== toAny ====

<vip>toAny : (Term) -> any UniversalTypeValue.</vip>

Converts the specified <vp>Term</vp> to the value of universal term type <vp>any</vp>.

Call-template for this function is:

<vip>UniversalTypeValue = toAny(Term)</vip>

==== toBinary ====

<vip>toBinary : (Term) -> binary Serialized.</vip>

Converts the specified <vp>Term</vp> to [[#binary|binary]] representation.

Call-template for this function is:

<vip>Serialized = toBinary(Term)</vip>

When a <vp>Term</vp> (of some domain ''domainName'') is converted into a binary, it can safely be stored in a file or sent over a network to another program. Later the obtained binary value <vp>Serialized</vp> can be converted back to a Visual Prolog term, using [[#toTerm|toTerm/1->]] function (the domain for the reversed term should be adequate to ''domainName'') for the reverse conversion.

==== toBoolean ====

<vip>toBoolean : (<term> SubGoal) -> boolean Succeed.</vip>

The purpose of this meta-predicate is to convert the deterministic call (to a predicate or fact) to the procedure that returns the value of [[#boolean|boolean]] domain.

Call-template for this meta-predicate is:

<vip>True_or_False = toBoolean(deterministic_call)</vip>

The <vp>toBoolean/1-></vp> meta-predicate returns [[#boolean|boolean]] value. The result is <vp>true</vp> if ''deterministic_call'' succeeds. The result is <vp>false</vp> if ''deterministic_call'' fails.

==== toEllipsis ====

<vip>toEllipsis : (any* AnyTermList) -> ....</vip>

This predicate creates ''EllipsisBlock'' '''...''' (i.e. the special varying parameters block) from the list of terms of the universal type <vp>any</vp>. Such ''EllipsisBlock'' can be later passed to a predicate which expects the varying number of arguments (i.e. is declared with the ellipsis (''...'')), like <vp>write/...</vp>, at the position of the ellipsis (''...'').

Call-template for this function is:

<vip>EllipsisBlock = toEllipsis(<any_term_list>), write(EllipsisBlock )</vip>

See also [[#fromEllipsis|fromEllipsis/1->]].

==== toString ====

<vip>toString : (Term) -> string Serialized.</vip>

Converts the specified <vp>Term</vp> to string representation.

Call-template for this function is:

<vip>Serialized = toString(Term)</vip>

When a <vp>Term</vp> (of some domain ''domainName'') is converted into a string, it can safely be stored in a file or sent over a network to another program. Later the obtained string value can be converted back to a Visual Prolog term, using [[#toTerm|toTerm/1->]] function (the domain of the return value should be adequate to ''domainName'') for the reverse conversion.

==== toTerm ====

<vip>toTerm : (string Serialized) -> Term.
toTerm : (binary Serialized) -> Term.
toTerm : (any Serialized) -> Term.
toTerm : (<domain> Type, string Serialized) -> Term.
toTerm : (<domain> Type, binary Serialized) -> Term.
toTerm : (<domain> Type, any Serialized) -> Term.</vip>

Converts the string/binary/any representation of the specified term <vp>Serialized</vp> into representation corresponding to the domain of <vp>Term</vp> variable of the return value. The domain can be stated explicitly or it can be left to the compiler to determine a suitable domain.

Call-template for this function is:

<vip>Term = toTerm(Serialized) % with implicit domain
Term = toTerm(domainName, Serialized) % with explicit domain, domainName</vip>

If the domain is not specified the compiler must be able to determine the domain for the returned value <vp>Term</vp> at compile-time. Notice that binary version of <vp>toTerm</vp> predicate performs almost byte to byte conversion and only checking general compatibility of <vp>Serialized</vp> data with the domain required to the return value <vp>Term</vp>. The programmer is wholly responsible for providing binary data of <vp>Serialized</vp> that can be correctly converted to the term of the desired domain. The <vp>toTerm</vp> predicates are counterparts to predicates [[#toBinary|toBinary/1->]] and [[#toString|toString/1->]]. When a ''Term'' (of some domain ''domainName'') is converted into a binary or string representation <vp>Serialized</vp> (by [[#toBinary|toBinary/1->]] or [[#toString|toString/1->]] or [[#toAny|toAny/1->]] correspondingly), it can safely be stored in a file or sent over a network to another program. Later the corresponding <vp>toTerm/1</vp>-> function can convert the obtained string/binary value <vp>Serialized</vp> back to a Visual Prolog term <vp>Term</vp>. For correctness of the reverse conversion the domain of the clause variable <vp>Term</vp> should be adequate to the initial domain ''domainName''.

See also [[#tryToTerm|tryToTerm]].

It gives a compile time error if the compiler cannot determine the return domain.

Exceptions

* Run time errors are generated when the <vp>toTerm</vp> predicate cannot convert the string or binary into a term of the specified domain.

==== tryToTerm ====

<vip>tryToTerm : (string Serialized) -> Term.
tryToTerm : (binary Serialized) -> Term.
tryToTerm : (any Serialized) -> Term.
tryToTerm : (<domain> Type, string Serialized) -> Term.
tryToTerm : (<domain> Type, binary Serialized) -> Term.
tryToTerm : (<domain> Type, any Serialized) -> Term.</vip>

Converts the string/binary/any representation <vp>Serialized</vp> into a term <vp>Term</vp> like [[#toTerm|toTerm]]. The only difference between the predicates is that <vp>tryToTerm</vp> fails if it cannot convert the string or binary or any into a term of the specified domain whereas toTerm raises an exception.

See also [[#toTerm|toTerm]].

==== tryConvert ====

<vip>tryConvert : (<type> Type, Value) -> <type> Converted determ.</vip>

Checks whether the input term <vp>InputTerm</vp> can be strictly converted into the specified domain <vp>Type</vp> and returns the converted term <vp>Converted</vp>.

Call-template for this function is:

<vip>ReturnTerm = tryConvert(returnDomain, InputTerm)</vip>

Arguments:

* <vp>returnDomain</vp>: Specifies a domain to which <vp>tryConvert/2-></vp> predicate tries to convert the specified <vp>InputTerm</vp>. Here ''returnDomain'' can be any domain accessible in the current scope. The domain name ''returnDomain'' must be specified at compile-time, i.e. it cannot come from a variable.
* <vpbnf><InputTerm></vpbnf>: Specifies the term that must be converted. <vp>InputTerm</vp> may be any Prolog term or an expression. If <vp>InputTerm</vp> is an expression, then it will be evaluated before conversion.
* <vpbnf><ReturnTerm></vpbnf>: Returned term <vp>ReturnTerm</vp> will be of ''returnDomain'' domain.

The conversion rules are the same as of the embedded predicate [[#convert|convert/2->]], but <vp>tryConvert/2-></vp> fails when [[#convert|convert/2->]] generates conversion errors.

This predicate succeeds if the corresponding conversion succeeds. Otherwise it fails. The <vp>tryConvert/2-></vp> predicate tries to perform a clean and genuine conversion of the given <vp>InputTerm</vp> into a value of the specified domain ''returnDomain''. The <vp>tryConvert/2-></vp> predicate will fail if the required conversion cannot be performed. When <vp>tryConvert/2-></vp> predicate succeeds, it returns the term <vp>ReturnTerm</vp> converted to the specified domain ''returnDomain''.

For allowed conversions and rules of checked explicit conversions see [[#convert|convert/2->]] predicate.

See also [[#uncheckedConvert|uncheckedConvert/2->]].

==== uncheckedConvert ====

<vip>uncheckedConvert : (<type> Type, Value) -> <type> Converted.</vip>

Unchecked conversion of a value to another type.

Call-template for this function is:

<vip>ReturnTerm = uncheckedConvert(returnDomain, InputTerm)</vip>

Arguments:

* <vp>returnDomain</vp>: Specifies a domain to which <vp>uncheckedConvert</vp> predicate unsafely converts the specified <vp>InputTerm</vp>. Here ''returnDomain'' can be any domain accessible in the current scope, the <vp>ReturnTerm</vp> should has the same bit-size as the <vp>InputTerm</vp>. The domain name ''returnDomain'' must be specified at compile-time, i.e. it cannot come from a variable.
* <vpbnf><InputTerm></vpbnf>: Specifies the value that must be converted. <vp>InputTerm</vp> may be any Prolog term or an expression. If ''InputTerm'' is an expression, then it will be evaluated before conversion.
* <vpbnf><ReturnTerm></vpbnf>: Returned parameter <vp>ReturnTerm</vp> will be of ''returnDomain'' type.

<vp>uncheckedConvert</vp> evaluates <vp>InputTerm</vp>, change the type to ''returnDomain'' without any modification of the memory pattern and unifies with <vp>ReturnTerm</vp>. The <vp>uncheckedConvert</vp> predicate performs no runtime checks. It makes only compile time checking of bit-size equality of the converted domains. So almost any term may be quite recklessly converted to any other term. So quite disastrous results may occur if you try to use variables incorrectly converted by <vp>uncheckedConvert</vp>. Be extremely careful implementing <vp>uncheckedConvert</vp>; we strongly recommend you always, when it is possible, using of [[#convert|convert/2->]] and [[#tryConvert|tryConvert/2->]]. But notice that, when an object is returned by COM system it is necessary to convert it by <vp>uncheckedConvert</vp>, as Prolog program does not have information about its actual type.

==== upperBound ====

<vip>upperBound : (<numeric-domain> NumericDomain) -> <number-domain> UpperBound.</vip>

Returns the upper bound value of the specified numeric domain.

Call-template for this function is:

<vip>UpperBound = upperBound(domainName)</vip>

The <vp>upperBound</vp> is a compiling-time predicate. The <vp>upperBound</vp> returns the upper bound value of the specified numeric domain ''domainName''. The return value <vp>UpperBound</vp> belongs to the same domain ''domainName''. The ''domainName'' parameter should be the name of any numerical domain; this domain name should be explicitly specified at compile-time (that is, ''domainName'' cannot come from a variable).

See also [[#lowerBound|lowerBound/1->]].

Will cause a compile time error if the specified domain ''domainName'' is not numeric domain.
<noinclude>{{LanguageReferenceSubarticle|Built-in entities/Predicates}}</noinclude>

Language Reference/Terms/in

2014-06-23T11:08:19Z

SergeMukhin: misspelling

==== in ====

{{Template:NonReleased}}

<vipbnf><InOperator>:
in</vipbnf>

The <vp>in</vp> operator is used to test for member ship of a collection (e.g. a list) and to nondeterministically generate the members of a collection.

{{Example|
<vip>predicates
p : (Type X, Type* L).
clauses
p(X, L) :-
if X in L then
write("X is in L\n")
end if.</vip>
<vp>p</vp> is a procedure that takes a value <vp>X</vp> and a list <vp>L</vp> as arguments. If <vp>X</vp> is in the list <vp>L</vp> then it will write <vp>"X is in L"</vp>. In this case in is used as an in-test (membership test).
}}

{{Example|
<vip>predicates
q : (Type* L).
clauses
q(L) :-
foreach X in L do
writef("% is in L\n", X)
end foreach.</vip>
<vp>q</vp> is a procedure that takes a list <vp>L</vp> as argument. The "in" operator is used to nondeterministically return the members of L, so that they can be written.}}

The <vp>in</vp> operator can be defined for any domain and interface using the <vp>in_test</vp> and <vp>in_iterate</vp> attributes.

The <vp>in_test(<predicate name>)</vp> attribute defines the predicate that is used as in-test for a certain domain or interface. Likewise the <vp>in_iterate</vp> attribute defines the predicate that is used as in-ieratorfor the domain/interface.

{{Example|
<vip>domains
tree{E} = empty; node(tree{E} Left, E Value, tree{E} Right) [in_test(isMemberTree), in_iterate(getAll_nd)].</vip>
When the program contains <vp>A in B</vp> where <vp>A</vp> is bound <vp>B</vp> is a <vp>tree{E}</vp> then <vp>isMemberTree</vp> is actually called.

In that case <vp>A in B</vp> corresponds to <vp>isMemberTree(A, B)</vp>.

If <vp>A</vp> is free the call corresponds to <vp>A = getAll_nd(B)</vp>.}}

For a domain <collection> the predicate must have the type:

<vip>predicates
<predicate> : (<some-type> Elem, <collection> Collection) determ.</vip>

{{Example|
<vip>interface collection [in_test(contains), in_test(getAll_nd)]
...
end interface collection</vip>
When the program contains <vp>A in B</vp> where <vp>A</vp> is bound <vp>B</vp> is a <vp>collection</vp> then <vp>contains</vp> is actually called.

In that case <vp>A in B</vp> corresponds to <vp>B:contains(A)</vp>.

If <vp>A</vp> is free the call corresponds to <vp>A = B:getAll_nd()</vp>.}}

For a domain <vp><collection></vp> the <vp>in_test</vp> and <vp>in_iterate</vp> predicate must fulfill these schematic declarations:

<vip>domains
<collection> = ... [in_test(<in_test>), in_iterate(<in_iterate>)].
class predicates
<in_test> : (<some-type> Elem, <collection> Collection) determ.
<in_iterate : (<collection> Collection) -> <some-type> Elem nondeterm.</vip>

For an interface <vp><collection></vp> the <vp>in_test</vp> and <vp>in_iterate</vp> predicate must fulfill these schematic declarations:

<vip>interface <collection> [in_test(<in_test>), in_iterate(<in_iterate>)].
predicates
<in_test> : (<some-type> Elem) determ.
<in_iterate : () -> <some-type> Elem nondeterm.
...
end interface <collection></vip>

The <vp>in</vp> operator is predefined on list domains, and in PFC the collections have suitable attributes.

{{Example|
<vip>clauses
p() :-
foreach X in [1, 2, 3, 4] do % in_iterate
if X in [2, 4] then % in_test
...
end if
end foreach.</vip>

The first <vp>in</vp> is the predefined <vp>in_iterate</vp> for the list domain, and the second one is the predefined <vp>in_iterate</vp>.

<vip>clauses
q() :-
M1 = setM_redBlack::new(),
M1:inset("a"),
M1:inset("b"),
M2 = setM_redBlack::new(),
M2:inset("b"),
foreach X in M1 do % in_iterate
if X in M2 then % in_test
...
end if
end foreach.</vip>

For collections the <vp>in</vp> operators resolve to <vp>contains</vp> and <vp>getAll_nd</vp>:

<vip>interface collection{@Type}
[in_test(contains), in_iterate(getAll_nd)]

predicates
contains : (@Type Value) determ.
% @short Succeeds if the collection contains the value @Type
% @end

predicates
getAll_nd : () -> @Type Value nondeterm.
% @short @Type is nondeterministic iteration of the elements in the collection.
% @end

...

end interface collection</vip>}}

Ide/Project Settings

2013-09-03T10:40:29Z

SergeMukhin: /* Run Options Tab */

{{ideNavbar|IDE Project Settings}}

The '''Project Settings''' utility is used to create new Visual Prolog Projects and to change some settings of existing projects.

To activate the '''Project Settings''' dialog, select the '''Project | Settings''' menu item. '''Project Settings''' is also activated when you create a new project (with the '''Project | New''' command).

== General Tab ==

When creating a new project the sheet looks like:

[[Image:Ide_ApplicationExpert_General_Create.png]]

You need to specify a mandatory project name and other options. After the needed information is specified, press the '''OK''' button. The '''Project Settings''' utility will create the default files, define the {{ide|Make Facility#Build Script|build script}}, etc.

=== Project Name ===

The project name must be specified in the '''Project Name''' option while a project creation. '''Project Settings''' uses this project name to generate name for the project file: <vpbnf><ProjectName>.prj6</vpbnf>. The specified project name is also used as the default name of '''Subdirectory''' in which the project is placed.

=== Project Kind ===

Sets which type the application will have.

[[Image:Ide_ApplicationExpert_UI_Strategy.png]]

The IDE automatically generates different default sets of files (and codes) for each application type.

'''Note.''' DLL option is available for the Visual Prolog Commercial Edition only.

=== MDI Mode/SDI Mode ===

Specifies whether the IDE creates a ''multi document interface-'' or ''single document interface-'' project template respectively.

'''Note.''' This option is available for the Visual Prolog Commercial Edition only. Otherwise the ''MDI Mode'' is assumed by the default.

=== Base Directory and Subdirectory ===

The name of the directory, in which the project is placed, is generated from the path specified in '''Base Directory''' that is concatenated with the folder name specified in '''Subdirectory'''.

*'''Base Directory'''
*:Specifies the base directory for the project being created.With the '''Browse''' button, you can open up a directory browser to find a proper '''Base Directory.'''
*'''Subdirectory'''
*:Specifies the subdirectory (relative to the '''Base Directory'''), which should be the root directory for the project being created.By default the '''Subdirectory''' name is equal to the specified '''Project Name''', but it can be changed while the project creation.

'''Note.''' That if you choose a directory that already contains some project as the directory in which to place the project being created, then the '''Project Settings''' utility displays the '''These files will be overwritten''' warning dialog. It displays names of already existing files which will be overwritten after you push the '''Create''' button. Therefore, it is a good idea to store each project in its own directory.

=== Platform ===

Specifies the project target platform as one of the following:

* 32bit
* 64bit
* 32bit+64bit

When the two 32bit 64bit platforms are specified as the project target, the active platform can be choosen through the '''Build''' menu.

'''Note.''' This option is available for the Visual Prolog Commercial Edition only. Otherwise the ''32bit'' is assumed by the default.

'''Manifest File'''

When it is checked '''ON''', then the '''Manifest''' file is generated for the project.

A Win32 side-by-side assembly contains a collection of resources—a group of DLLs, windows classes, COM servers, type libraries, or interfaces—that are always provided together with applications. These are described in the assembly '''Manifest''' files. For more details about '''Manifest''' files see descriptions in MSDN.

'''Require commctrl v.6'''

Specifies that the generated manifest file contains a statement to require the system '''commctrl.dll''' version 6 for the application.

'''Require Administrative Rights'''

Specifies that the generated manifest file contains a statement to require the administrative privileges for the application.

To open the '''Project Settings '''dialog for the existing project, use the '''Project | Settings''' menu item.

The General tab will look, in this case, as foolows:

[[Image:Ide_ApplicationExpert_General.png]]

== Directories Tab ==

Here you can specify directories that will be used by the project. In '''Directories''' tab you can set up the project subdirectories to be used by the compiler, linker, resource generators, etc.

Directory names refer to the {{ide|Make Facility#Build Symbols|build script symbols}}. For example, when giving the name '''$(ProDir)''', it is automatically expanded to the actual path where the Visual Prolog system is installed.

When all these project subdirectories are defined, then it is possible to move a project to another place and still be able to use it without need to redefine the {{ide|Make Facility#Build Script|project build scripts}} manually. This is possible because:

* Usually these project subdirectories are defined relatively to the project root directory. Therefore, they are automatically redefined when the project is moved.
* Each of these subdirectories generates correspondent {{ide|Make Facility#Build Symbols|build symbols}} and namely these built symbols are used to define file locations in the {{ide|Make Facility#Build Script|project build scripts}}.

=== Intermediate ===

'''$(ObjDir)''' - This directory is used to place all intermediate (temporary) files of the project generated by the IDE. It defines the '''$(ObjDir)''' {{ide|Make Facility#Build Symbols|build script symbols}}. The IDE automatically adds suffix '''64''' to the intermediate directory name.

=== Final ===

'''$(ExeDir)''' - This directory is the place for the generated target module (executable or DLL). It defines the '''$(ExeDir)''' {{ide|Make Facility#Build Symbols|build script symbols}}. The IDE automatically adds suffix '''64''' to the final directory name.

=== Import Library ===

'''$(LibDir)''' - This directory is used for DLL projects to place the generated import library. It defines the '''$(LibDir)''' {{ide|Make Facility#Build Symbols|build script symbols}}.

=== Prolog Root ===

'''$(ProDir)''' - It is the root directory of the used Visual Prolog version. This directory defines the '''$(ProDir)''' {{ide|Make Facility#Build Symbols|build script symbols}}.

=== Include Directories ===

'''$(IncDir)''' - This list box displays the list of the project include directories.

Each line contains one directory. In these directories the compiler will search for included files (specified in <vp>#include</vp> or <vp>#bininclude</vp> compiler directives), if the specified filename does not contain an absolute path. A single dot indicates the current directory, which is always the project directory. Two dots indicate the parent directory of the current directory.

You can add a new directory to the list of the project include directories using the '''Browse''' button. The '''Browse''' button activates the '''Set New Directory''' dialog. Also you can use the '''Edit''' button, which activates the '''Edit Include Directory''' dialog. In this dialog you can directly type in a path. Using '''Up''' and '''Down''' buttons you can change the order in which the compiler will search in the specified include directories.

This directory defines the '''$(IncDir)''' {{ide|Make Facility#Build Symbols|build script symbols}}.

== Build Options Tab ==

Here you can edit the project {{ide|Make Facility#Make Rules|build script '''Rules'''}} and the project {{ide|Make Facility#Build Script|'''Build Script'''}}, specify the '''Type Library File''', etc.

=== Rules ===

Determine how to compile files with given extensions. An example is the following:

<vipbnf>pack->obj:$(Compiler) /L:R /L:I /L:STAT $(IncDir) /MAXE:200 /MAXW:1000
"$**.pack" /OBJECTFILE:"$(ObjDir)$*.obj" /DEBUGFILE:"$(ObjDir)$*.deb" /debug:full</vipbnf>

For more information about {{ide|Make Facility#Make Rules|Rules}} syntax see the {{ide|Make Facility|Make Facility}}.

=== Build Script ===

Describes how to build the final target. An example is the following,

<vipbnf>"$(ProDir)Bin\VIP6Link.exe" -F<< -E_VIPStartUp@0 -d -TPE -SGUI -o"$(ExeDir)$*.exe"
-M"$(ObjDir)$*.map" $(PROJECT_OBJ) "$(ObjDir)$*.res" $(PROJECT_LIB)<<</vipbnf>

For more information about {{ide|Make Facility#Build Script|Build Scripts}} see the '''Make Facility''', the {{ide|Command Line Tools#Command Line Compiler|Command Line Compiler}}, and the {{ide|Command Line Tools#Command Line Linker|Command Line Linker}}.

=== Definition (.def) File ===

'''[$(DEF_FILE)]''': A {{ide|Command Line Tools#Definition Files|module-definition}} ('''.DEF''') file provides additional input for the linker. The module-definition files describe the essential characteristics of a target application or library.

Ordinary module-definition files should be used when the project target is a DLL or when the target file should use DLLs.

When the project target is a DLL, then names of all predicates exported from the DLL have to be added to the {{ide|Command Line Tools#Definition Files|EXPORT}} section of the module-definition file, which is used to build the DLL.

When an import library is included into the project modules, then the correspondent DLL is linked statically to the application (load-time linking). Such projects must have module-definition files, whose {{ide|Command Line Tools#Definition Files|IMPORTS}} sections should specify names of all predicates imported from the DLL.

See {{ide|Command Line Tools#Definition Files|Definition Files}} in the {{ide|Command Line Tools#Command Line Linker|Command Line Linker}} for more information.

=== Type Library File ===

Here you can use the '''Browse''' button to specify a Type Library, which should be used in your project. Usually, you need this when creating COM objects.

== Version Information Tab ==

Here you specify some information about the project: '''Company''', '''Author''', '''Copyright''', '''File Version''', '''Trademarks''', etc.

Some of version information attributes can be shown by the operation system '''File Properties''' dialog and can be used to validate version of DLL or EXE, before loading them.

Version information contains the following fields:

*'''Company'''
*:Usually is the name of the company that is the Copyright owner to the project.
*'''Author'''
*:Represents information about the author of the project.
*'''Copyright'''
*:Represents the Copyright information, which is visible in the '''File Properties''' dialog.
*'''Description'''
*:Contains a short description.
*'''File Version'''
*:Is written in the A.B.C.D format, where A, B, C, D are integers. A means major version.
*'''Product Version'''
*:Is written in format A.B.C.D, where A, B, C, D are integers. A means major version.
*'''Trademarks:'''
*:Represents the project Trademarks information.
*'''File Flags:'''
*:These are flags that describe the target file of the project:
*#'''Debug'''
*#:This flag means that the project is built with debugging information.
*#'''Prerelease'''
*#:This flag means that the target file is an intermediate version.
*#'''Patched'''
*#:This flag means that the target file has been modified comparing with the original file, which has the same version number.
*#'''Special Build'''
*#:This flag means that the target file was built using standard release procedures but for special purpose.
*#'''Private Build'''
*#:This flag means that the target file was built for private purpose.

== Run Options Tab ==

*'''Run Arguments'''
:Here it is possible to specify command line parameters that will be passed to the target application when it starts from the IDE.
*'''Executable for Run/Debugger'''
:Here you can specify an executable filename that will be loaded by the IDE for debugging.
*'''External Project for Debugger'''
:Here you can specify a project with the debug information that should be used by the IDE while debugging.
*'''Working Directory for Run/Debug'''
:If this option is set, a user application will use this directory as a working directory for Run/Debug comands, otherwise the final directory will be used. If the relative path is defined then the path is calculated from the project directory.

Ide/Debugger/Debugger Views

2013-07-08T12:57:04Z

SergeMukhin: /* Disassembly Window Commands */

<noinclude>[[Category:Ide/Debugger]]</noinclude>
== Debugger Views ==

=== Run Stack Window ===

The '''Run Stack''' consists of three kinds of items:
*'''Continue''' item – marked with [[Image:Ide_db_RunStack_up.png]]. It describes ordinary executable clauses, which do not produce backtrack points and are not trapped.
*'''BackTrack''' item – marked with [[Image:Ide_db_RunStack_dn.png]].It describes a clause of a nondeterministic predicate. The next clause of this predicate can be executed when a program failure of this clause occurs. Such items occur when a clause of a predicate, which creates a '''backtrack''' point (can produce more than one solution) is called.
*'''TrapTrack''' item – marked with [[Image:Ide_db_RunStack_rh.png]] or [[Image:Ide_db_RunStack_dn_rh.png]]. They describe a continue item (clause), which will be resumed in any case independently whether an error condition occurs or no. For example, such item is created when a predicate call is trapped with the <vp>trap/3</vp> predicate. The [[Image:Ide_db_RunStack_rh.png]] icon is used to mark trapped clauses of deterministic predicates. The [[Image:Ide_db_RunStack_dn_rh.png]] icon is used to mark trapped clauses of nondeterministic predicates.

The '''BackTrack''' (marked with [[Image:Ide_db_RunStack_dn.png]]) and '''TrapTrack''' items (marked with [[Image:Ide_db_RunStack_dn_rh.png]]) are backtracking points. The clause, marked by one of these items, will be resumed and the program execution will be continued after the corresponding failure or an error occurs.

The typical example of the '''Run Stack''' window is presented in the following picture:

[[Image:Ide_db_RunStack.png]]

'''Pop-up Menu'''

The '''Run Stack''' window has the pop-up context menu:

[[Image:Ide_db_RunStack_menu.png]]

For each selected item in the tree, this menu contains items:

*'''Refresh'''
*:It refreshes all the '''Run Stack''' window contents, rebuilds the tree.
*: It also refreshes the {{ide|Debugger#Variables Window|'''Variables'''}} window (if it is displayed).

*'''Go To Code'''
*:Activates the Prolog source editor and places the cursor at the Prolog clause corresponding to the item selected in the '''Run Stack''' window. If the item does not correspond to a Prolog module with debug information, then the '''Disassembly''' window will be opened and the cursor will be placed onto the corresponding assembler instruction. The same action is caused by double-click a predicate call in the '''Run Stack''' window.

*'''Copy Line'''
*:It copies the selected line contents to the clipboard.

*'''Show Domains'''
*:This option turns ON/OFF displaying domains of variables.

*'''Show Values'''
*:This option turns ON/OFF displaying values of variables.

The '''Run Stack''' window can be activated by the IDE menu '''View | Run Stack'''.

=== Variables Window ===

The '''Variables''' window can be activated either by '''Ctrl+Alt+V''' or from the IDE menu '''View | Variables for Current Clause'''.

'''Variables Window Contents'''

The '''Variables''' window displays the tree of all program variables and facts from the traced clause, which are already created by the program at the current tracing step. These are: all variables and all object facts (fact variables), which are created in the clause before the executing instruction, and all class facts (fact variables), which can be used in this clause (declared in this class implementation).

The top line of the window displays the declaration of the predicate, whose clause is executed.

[[Image:Ide_db_Vars_Top.png]]

The '''Variables''' window content is updated after every trace step.

'''Pop-up Context Menu'''

The '''Variables in the Current Clause''' window has the following pop-up context menu:

[[Image:Ide_db_Vars_Menu.png]]

This menu contains items:

*''Insert into Watch Window''
*:Opens the '''Watch Window''' and moves there selected variable.

*''Copy''
*:This command copies the contents of the line selected in the '''Variables''' window to the clipboard.

*''Show as Hexadecimal''
*:Shows integral values in the hexadecimal format.

*''Show as Decimal''
*:Shows integral values in the decimal format.

*''Show as Octal''
*:Shows integral values in the octal format.

*''Show Domains''
*:This option turns '''ON/OFF''' displaying the domains after variable names.

*''Show Variable Addresses''
*:This option turns '''ON/OFF''' displaying the addresses after variable names.

*''Find''
*:This command allows search variable by name.

*''Copy Tree''
*:This command copies the contents of the window to the clipboard.

=== Facts Window ===

'''Class Facts'''

The '''Facts''' window always shows the current contents of all '''class''' fact databases defined in the program being debugged.

Simple example:

[[Image:Ide_db_Facts_View.png]]

Pressing '''CTRL+ALT+F''' opens '''Facts''' window:

[[Image:Ide_db_Facts_View3.png]]

Clicking icons opens sub-trees:

[[Image:Ide_db_Facts_View4.png]]

'''Facts''' window automatically goes to the fact that is selected in the text editor (if any):

[[Image:Ide_db_Facts_View11.png]]

[[Image:Ide_db_Facts_View41.png]]

'''Objects Facts''' you cat look like a components of object variables in the {{ide|Debugger#Variables Window|'''Variables''' window}}

'''Pop-up Context Menu'''

The '''Facts Window''' has the following pop-up context menu:

[[Image:Ide_db_Vars_Menu.png]]

This menu contains items:

*''Insert into Watch Window''
*:Opens the '''Watch Window''' and moves there selected fact.

*''Copy''
*:This command copies the contents of the line selected in the '''Facts''' window to the clipboard.

*''Show as Hexadecimal''
*:Shows integral values in the hexadecimal format.

*''Show as Decimal''
*:Shows integral values in the decimal format.

*''Show as Octal''
*:Shows integral values in the octal format.

*''Show Domains''
*:This option turns '''ON/OFF''' displaying the domains after facts names.

*''Show Addresses''
*:This option turns '''ON/OFF''' displaying the addresses after facts names.

*''Find''
*:This command allows search fact by name.

*''Copy Tree''
*:This command copies the contents of the window to the clipboard.

=== Breakpoints Window ===

The '''Breakpoints''' window shows all breakpoints, which have been set in the program being debugged.

You can set a breakpoint onto any executable line in program source files (or in the '''Disassembly''' window, where a breakpoint can be set on any instruction of the program being debugged).

There are two kinds of breakpoints: hard and soft. Hard breakpoints are active in any debugging mode. Soft breakpoints are active in normal debugging mode but disabled in a special mode of quick debugging, called ''Fast Forward Mode''.

==== Breakpoints Window Contents ====

The '''Breakpoints''' window for each breakpoint includes '''Status''', '''Source''', '''Line''', '''Count''', '''Comment''' and '''Action''', where:

*'''''Status'''''
*:Shows whether the breakpoint is ''hard'' or ''soft''.
**''Hard''
**:If a breakpoint is ''hard'' then it will be activated in any debugging mode. A hard breakpoint is marked with the filled circle [[Image:Ide_db_BreakPoints_en.png]] or [[Image:Ide_db_BreakPoints_assembler.png]] (for assembler) or [[Image:Ide_db_BreakPoints_shifted.png]] (for relocated breakpoint).
**''Soft''
**:If a breakpoint is ''soft'' then it will be activated only in normal (not Fast Forward) debugging mode. A soft breakpoint is marked with the hollow circle [[Image:Ide_db_BreakPoints_dis.png]] or [[Image:Ide_db_BreakPoints_assembler_disabled.png]] (for assembler).
**''Invalid''
**:A breakpoint is invalid when it is set on a line, which does not contain executable code. An invalid breakpoint is marked with the crossed hollow circle [[Image:Ide_db_BreakPoints_invalid.png]].

*'''''Source'''''
*:This column shows the source string:
*:<vipbnf><SourceName></vipbnf>
*:where:
*:''SourceName''
*:The description of a predicate in the address space of whose clauses the breakpoint is set:
*:*If the breakpoint is set in Prolog sources, then ''SourceName'' is the filename in which the breakpoint is set. It is displayed with the format:
*::<vipbnf><FileName> '(' <Path> ')'</vipbnf>
*::The ''Path'' can use {{ide|Make Facility#Build Symbols|Build script symbols}}.
*:* If the breakpoint is set in the '''Disassembly''' window, then ''SourceName'' has the format:
*::<vipbnf>--- assembler: <AddressValue></vipbnf>
*::''AddressValue'' is the hexadecimal address of the breakpoint in the assembler code of the predicate in which the breakpoint is set.

*'''''Line'''''
*:When the breakpoint is set in a Prolog source file, then this column displays the number of the line the breakpoint is set on. When the breakpoint is set in the Disassembly window, then the number of the line is equal to 0.

*'''''Count'''''
*:This column displays {{ide|Debugger#Breakpoint Properties|counts}} of breakpoints.

*'''''Comment'''''
*:This column displays {{ide|Debugger#Breakpoint Properties|comment strings}} of breakpoints.

*'''''Action'''''
*:This column displays the script text of a breakpoint. The script is performed each time the program reaches the breakpoint.

==== Breakpoints in Prolog and Disassembly Windows ====

Breakpoints can be set in Prolog source files and in the '''Disassembly''' window:

* In Prolog sources valid breakpoints can be set only on lines containing executable instructions. That is, breakpoints can be set only in predicate clauses on lines containing predicate calls, otherwise the breakpoints that are set on non-clause lines would be marked as invalid. The breakpoints that are set on clause lines that do not contain predicate calls would be shifted to the lines containing such calls (if any), but the initial line would be marked with [[Image:Ide_db_BreakPoints_shifted.png]]. Valid breakpoints are marked with red circles [[Image:Ide_db_BreakPoints_en.png]] or [[Image:Ide_db_BreakPoints_dis.png]] in Prolog sources and are shown in the '''Disassembly''' window as blue circles [[Image:Ide_db_BreakPoints_assembler.png]] or [[Image:Ide_db_BreakPoints_assembler_disabled.png]]. If a Prolog clause has several assembler implementations (when the clause has several flow patterns), then each breakpoint in Prolog sources can generate several breakpoints in the '''Disassembly''' window.
* Breakpoints that are set in the '''Disassembly''' window are marked with red circles [[Image:Ide_db_BreakPoints_en.png]] or [[Image:Ide_db_BreakPoints_dis.png]]. Such breakpoint can be later overwritten by a breakpoint (marked with blue circles [[Image:Ide_db_BreakPoints_assembler.png]] or [[Image:Ide_db_BreakPoints_assembler_disabled.png]]) that is set in Prolog sources on the same address as the breakpoint set in the '''Disassembly''' window. Notice that after modification and recompilation of the project some breakpoints that are set in the '''Disassembly''' window can be cleared (if other instructions are placed at breakpoint addresses.)

All breakpoints which are set in a program are seen in the '''Breakpoints''' window.

==== Breakpoint Properties ====

Each breakpoint has properties, which can be modified in the '''Breakpoint Properties''' dialog:

[[Image:Ide_db_BreakPoint_Properties.png]]

In this dialog:

The top line contains:

* If the breakpoint is set in Prolog sources, then the top line has format:
*:'''<vipbnf>File: <FileName> Line: <LineNumber></vipbnf>'''
*:''FileName'' is the name of the Prolog source file in which the breakpoint is set.
*:''LineNumber'' is the number of the line on which the breakpoint is set.

* If the breakpoint is set in the '''Disassembly''' window, then the top line has format:
*:'''<vipbnf>Breakpoint Address:<Address></vipbnf>
*:''Address'' is the breakpoint address in the program memory as it is seen in the '''Disassembly''' window.

'''Hard'''
:This check box controls the ''Hard/Soft'' state of the breakpoint. When you turn a breakpoint to Hard, then it will be activated in any debugging mode. When you turn a breakpoint to Soft, then it will be activated only in normal (not Fast Forward) debugging mode.

'''Counter''' ''Value''
:Shows the current number of activations of the breakpoint since its creation. The user cannot modify this value. This value increases by 1 each time when the program reaches the breakpoint. And resets to 0 at the beginning of the debug session.

'''Comment''' ''Comment string''
:In this edit box you can type in a ''Comment string''. By default it has the value of the corresponding line in the source file.

'''Action''' ''Script text''
:In this box you can type in a ''Script text''.

==== Pop-up Menu ====

The '''Breakpoints''' window has the pop-up context menu:

[[Image:Ide_db_BreakPoints_pop_up.png]]

To activate this menu, select a breakpoint and press the right mouse button. This menu contains items:

*'''Go to Source'''
*:If the breakpoint is set in the Prolog sources, then the '''Go to Code''' activates the Prolog source code editor, and moves the cursor to the Prolog code corresponding to the specified breakpoint. If the breakpoint is set in the '''Disassembly''' window, then the '''Go to Code''' moves the view to this breakpoint in the '''Disassembly''' window. The same action is performed by double-click the breakpoint or by pressing the '''Enter''' on the breakpoint.

*'''Properties'''
*:Invokes the {{ide|Debugger#Breakpoint Properties|'''Breakpoint Properties'''}} dialog for the selected breakpoint.

*'''Toggle (Turn to Hard/Soft)'''
*:Switches the ''Hard/Soft'' state of the selected breakpoints.

*'''Delete'''
*:Deletes the selected breakpoints.

*'''Turn to Hard All'''
*:Sets the state of all breakpoints that are set in the program to ''Hard''.

*'''Turn to Soft All'''
*:Sets the state of all breakpoints that are set in the program to ''Soft''.

*'''Remove All'''
*:Removes all breakpoints that are set in the program.

The '''Breakpoints''' window is auto-updated for any breakpoint updating.

The '''Breakpoints''' window can be activated either by '''Ctrl+Alt+B''' or from the IDE menu '''View | Breakpoints'''.

=== Threads Window ===
----
The '''Threads''' window shows information about the process being debugged and its threads.

The '''Threads''' window looks like following:

[[Image:Ide_db_Threads.png]]

Names displayed in the header of the window columns are the following:

*'''TID'''
*:This column displays thread identifiers of all threads created by the process being debugged.
*'''Current'''
*:This column identifies the current thread by the <vp>*</vp> sign. In the {{ide|Debugger#Variables Window|Variables}} window you can see only variables of predicates executed in the current thread.
*'''State'''
*:Displays states of threads. States can be '''''Running''''', '''''Stopped''''', and '''''Suspend'''''.
*: '''''Running''''' The thread has been started, it is not suspended (see <vp>thread::suspend/0-></vp>, <vp> syncObject::wait/0-></vp>, <vp>syncObject::wait/1-></vp>) or terminated (see <vp>thread::terminate/1</vp>).
*: '''''Suspend''''' The thread is in suspended state (see <vp>thread::createSuspended/3</vp>, <vp>thread::suspend/0-></vp>, <vp>syncObject::wait/0-></vp>, <vp>syncObject::wait/1-></vp>).
*: '''''Stopped''''' The thread was created and then stopped on a breakpoint, but it is not suspended (see <vp>thread::suspend/0-></vp>, <vp>syncObject::wait/0-></vp>, <vp>syncObject::wait/1-></vp>). If you set suspended state to a '''''Stopped''''' thread, then it turns into the '''''Suspend''''' state.
*'''Time'''
*:Thread creation time.
*'''User time'''
*:Processor time in the user-mode used by the thread.
*'''Kernel Time'''
*:Processor time in the kernel-mode used by the thread.
*'''Priority'''
*:The priority level of the thread. Here can be displayed the following numbers <vp>2, 1, 0, -1, -2</vp>.
*'''Predicate'''
*:This field contains the name of the currently executed thread's predicate (if it is possible to determine it).

{|{{prettytable}}
|-
! Displayed Number
! Priority Name
! Description
|-
| 2
| '''Highest'''
| The thread can be scheduled before threads with any other priority.
|-
| 1
| '''AboveNormal'''
| The thread can be scheduled after threads with '''Highest''' priority and before those with '''Normal''' priority.
|-
| 0
| '''Normal'''
| The thread can be scheduled after threads with '''AboveNormal''' priority and before those with '''BelowNormal''' priority. Threads have Normal priority by default.
|-
| -1
| '''BelowNormal'''
| The thread can be scheduled after threads with '''Normal''' priority and before those with '''Lowest''' priority.
|-
| -2
| '''Lowest'''
| The thread can be scheduled after threads with any other priority.
|}

'''Pop-up Menu'''

The '''Threads''' window has the pop-up context menu. The same commands can be activated from the '''Thread''' sub-menu of the IDE task menu.

[[Image:Ide_db_Threads_popup.png]]

*'''Goto Source'''
*:Opens the text editor and places the cursor onto the predicate, which created the selected thread.
*'''Set Current'''
*:Sets the selected thread as current.
*'''Resume'''
*:Resumes the run of the selected thread.
*'''Suspend'''
*:Suspends the selected thread.
*'''Copy'''
*:Copies the contents of the line selected in the '''Threads''' window to the clipboard.
*'''Copy All'''
*:Copies the contents of the '''Threads''' window to the clipboard.

The '''Threads''' window is updated after changing any displayed parameter.

The '''Threads''' window can be activated either by '''CTRL+Alt+H''' or from the IDE menu '''View | Threads'''.

=== Disassembly Window ===

The '''Disassembly''' window shows the assembly language interpretation of the inspected code.

The disassembly starts from the specified top address toward the upper memory and prints each instruction on a new line.

Each line is printed by the pattern:

<vipbnf><LineMarkers> <Address> [ <HexCode> ] <AssemblerCommand></vipbnf>

where:

''LineMarkers''
:Are the {{ide|Debugger#Debug Menu Commands|''instruction pointer''}} [[Image:Ide_db_InstructionPointer.png]] and the breakpoint[[Image:Ide_db_BreakPoints_en.png]] (or [[Image:Ide_db_BreakPoints_dis.png]]) markers, which can mark this line.
''Address''
:The start address of the instruction code.
''HexCode''
:This is the hexadecimal instruction code. This field can be shown/hidden from the pop-up menu of the '''Disassembly''' window by checking the '''Show OpCodes''' item.
''AssemblerCommand''
:This is the assembler command corresponding to the instruction code. Assembler commands have the Intel standard assembler abbreviation. If a certain address is resolved to an external name, then this name will be printed in the command column.
: The instruction, which will be executed at the next trace step, is marked with the [[Image:Ide_db_InstructionPointer.png]] ''Instruction pointer'' in the ''LineMarkers'' field.

Example:

[[Image:Ide_db_DisAsm_View.png]]

==== Pop-up Menu ====

The '''Disassembly''' window has the pop-up context menu with the followin commands:

*'''Go To Address'''
*:Invokes the '''Go to Address''' dialog
*:[[Image:Ide_db_DisAsm_Go2Address.png]]
*:to type in the address of the instruction, which should be displayed in the top line of the '''Disassembly''' window. The ''Address'' should be specified in the hexadecimal format. This dialog allows typing symbolic external link names and symbolic CPU register names.
*'''Go To EIP'''
*:Updates the '''Disassembly''' window and places the cursor at the address of the instruction on which the program execution is suspended.
*'''Breakpoint…'''
*:Allows handling the breakpoint [[Image:Ide_db_BreakPoints_en.png]] (or [[Image:Ide_db_BreakPoints_dis.png]]) for the assembler instruction pointed by the cursor. It has the following sub-commands:
*:[[Image:Ide_db_DisAsm_PopUp.png]]
*:*'''Toggle Breakpoint'''
*:*:Sets or removes a breakpoint at the instruction with the address pointed by the cursor.
*:*'''Enable / Disable'''
*:*:''Enables / Disables'' the breakpoint pointed by the cursor. This item is disabled if there is no breakpoint at the address pointed by the cursor.
*:*'''Properties'''
*:*:Invokes the '''Breakpoint Properties''' dialog for the breakpoint pointed by the cursor. This item is disabled if there is no breakpoint at the address pointed by the cursor.
*'''Go To Source'''
*:Activates the IDE source code editor and sets the cursor at the predicate whose assembler instruction is pointed by the cursor in the '''Disassembly''' window. (When it is possible.)
*'''Copy'''
*:Copies lines selected in the '''Disassembly''' window to the clipboard. A selection can be performed with the '''Shift+Up Arrow''' and '''Shift+Down Arrow''' key combinations.
*'''Show OpCodes'''
*:Checking and unchecking this item hides/shows hex images of operation (instruction) codes ('''OpCodes'''). These hex instruction codes are shown in the ''HexCode'' field.
*'''Source Annotation'''
*:Checking OFF/ON this item hides/shows object names, corresponding to predicate entry points. Each object name is printed on a new line before the corresponding instruction line.
*'''Show Hints'''
*:Shows additional information about the instruction being executed.

The '''Disassembly''' window is updated after each trace step of the debugger.

==== Disassembly Window Commands ====

*'''Trace Into''' command
*:Tracing in the '''Disassembly''' window with the '''Step Into''' command performs execution of one assembler instruction (including entering into procedures if any). That is, if the '''Step Over''' command will execute a <vp>call</vp> instruction as one trace step, then the '''Step Into''' command will go into the called procedure. It usually executes disassembler instructions line after line.
*'''Step Over''' command
*:Tracing in the '''Disassembly''' window with the '''Step Over''' command performs execution of one assembler instruction (including execution of <vp>call</vp> instructions). So the '''Step Over''' command works almost the same way as the '''Trace Into''' command except for execution of <vp>call</vp> instructions. In difference to the '''Trace Into''' command, it tries to perform <vp >call</vp> instructions as one step and reaches the next line only if the called code returns to that line.
*'''Run to Cursor''' command
*:Tracing in the '''Disassembly''' window with the '''Run to Cursor''' command works in the following way. The debugger places an invisible breakpoint at the address corresponding to the instruction specified by the cursor and performs the '''Debug Run''' command. It depends only upon the program code whether the program will reach this instruction or will never reach it.

If the tracing code has no debug information, then the '''Disassembly''' window is opened initially (when the debugger starts) and the instruction pointer [[Image:Ide_db_InstructionPointer.png]] points to the executing assembler instruction.

=== Registers Window ===

The '''Registers''' window shows current values of the CPU (Central Processor Unit) registers:

* General registers
* Segment registers
* Flags
* Floating-point registers

A register value is printed:

* '''red''', if it is changed from the last program trace step
* '''blue''', otherwise.

For example:

[[Image:Ide_db_Registers_fpu.png]]

The '''Floating Point''' command from context pop-up menu can be used to turn ON/OFF the displaying of Floating-point registers.

The '''Registers''' window can be activated either by '''Ctr+ Alt+G''' or from the IDE menu '''View | Registers'''.

=== Modules Window ===
----
The Modules Window shows all the modules currently loaded in this debug session. It shows the filename, path, the base address range, the code address range and the type of debug information.

[[Image:Ide_db_Modules.png]]

=== Memory Dump Window ===

The '''Memory Dump''' window shows the virtual memory dump of the program being debugged. Memory dump lines have the length, which is determined by the window width. The number of printed lines window height.

'''Information Displayed in the Memory Dump Window'''

Each line in the '''Memory Dump''' window is printed by the pattern:

<vipbnf><Address> | [ <HexValues> ] [ <ASCIIcharacters> ] [ <UnicodeCharacters>]</vipbnf>

where:

''Address''
:This is the hexadecimal address of the first byte of the memory displayed in this line.
''HexValues''
:<vipbnf><HexValues> : <HexValue> [ <HexValues> ]</vipbnf>
:This is the hexadecimal format of the memory dump. Each hex value can be an image of one, two, four or eight continued memory bytes (this is contolled by the '''Memory Dump''' window content pop-up menu).
''ASCIIcharacters''
:<vipbnf><ASCIIcharacters> : <ASCIIcharacter> [ <ASCIIcharacters> ]</vipbnf>
:This is the same memory dump but in the format of ASCII characters (a character represenrs one byte). Unprintable characters are printed as dots.
''UnicodeCharacters''
:<vipbnf><UnicodeCharacters> : <UnicodeCharacter> [ <UnicodeCharacters> ]</vipbnf>
:This is the same memory dump in the format of Unicode characters (a character represents two bytes). Unprintable characters are printed as dots.

Example:

[[Image:Ide_db_Memory_view1.png]]

The '''Memory Dump''' window title shows the module name, which memory is displayed in the window. If the module name cannot be determined, then the title displays ''Unknown module''.

'''Content Pop-up Menu'''

The '''Memory Dump''' window has the pop-up context menu which contains commands:
*'''Go To Address'''
*:'''Ctrl+G'''. Invokes the '''Go to Address''' dialog
*:[[Image:Ide_db_DisAsm_Go2Address.png]]
*: to type a new top address in hex format. This dialog allows typing symbolic external link names and symbolic CPU register names. Double-click in the '''Memory Dump''' window area also activates the '''Go to Address''' dialog.
*'''Go To ''Ptr'''''
*:'''Ctrl+Shift+G'''. Updates the '''Memory Dump''' window starting the first line from the address shown as ''Ptr'' (address defined by the memory contents of four or eight continued bytes at which the cursor is pointing if one of '''4-byte Integer''' or '''8-byte Integer''' is selected).
*'''Undo Go to'''
*:'''Alt+Left Arrow'''. Updates the '''Memory Dump''' window view to start from the previously used top (the first line) address.
*'''Redo Go to'''
*:'''Alt+Right Arrow'''. This operation is the counterpart to the '''Undo Go to'''. It updates the '''Memory Dump''' window view to start from the "next" top address, which was used before the '''Undo Go to''' command was implemented.
*'''Set Memory Breakpoint'''
*:This operation sets a memory breakpoint at address from the left pane.
*'''Remove Memory Breakpoint'''
*:This operation removes a previously set a memory breakpoint.
*'''Copy'''
*:Copies the selected lines to the clipboard. To select a line, click on it while holding the '''shift''' key. You can select multiple lines at one time.
*'''Copy ''Ptr'''''
*:'''Ctrl+C'''. Copies hexadecimal representation of the specified address (four or eight bytes) to the clipboard.
*'''Refresh'''
*:Refresh the '''Memory Dump''' window contents.
*'''Write Block'''
*:This command opens the '''Write Memory Block''' dialog:
*:[[Image:Ide_db_Memory_BlockWrite.png]]
*:*'''Filename'''
*:*:Here you should type in the name of a file in which the specified memory block should be saved.
*:*'''Start Address'''
*:*:Here you should specify a hexadecimal start address of the memory block.
*:*'''Length'''
*:*:Here you should specify a hexadecimal length in bytes of the memory block.
*'''Show Hex'''
*:Shows the column, which displays the memory dump in the hexadecimal format. This is the {{ide|Debugger#Debugger Views|''HexValues''}} column in the right pane.
*'''Show ASCII'''
*:Shows the column, which displays the '''''ASCII''''' format of the memory dump. This is the {{ide|Debugger#Debugger Views|''ASCIIcharacters''}} column in the right pane.
*'''Show Unicode'''
*:Shows the column, which displays the '''''Unicode''''' format of the memory dump. This is the {{ide|Debugger#Debugger Views|''UnicodeCharacters''}} column in the right pane.
*'''Update Speed...'''
*:Defines the rate of the Memory Dump window updating:
*:[[Image:iDE_db_Memory_menu1.png]]
*:*'''High'''
*:*:Performs automatic updating with the high rate.
*:*'''Normal'''
*:*:Performs automatic updating with normal rate.
*:*'''Low'''
*:*:Performs automatic updating with low rate.
*:*'''Manual'''
*:*:No automatic updating.
The '''Memory Dump''' window can be activated either by '''CTRL+Alt+M''' or from the IDE menu '''View | Memory Dump'''.

Ide/Debugger/Debugger Views

2013-07-08T11:08:31Z

SergeMukhin: /* Breakpoint Properties */

<noinclude>[[Category:Ide/Debugger]]</noinclude>
== Debugger Views ==

=== Run Stack Window ===

The '''Run Stack''' consists of three kinds of items:
*'''Continue''' item – marked with [[Image:Ide_db_RunStack_up.png]]. It describes ordinary executable clauses, which do not produce backtrack points and are not trapped.
*'''BackTrack''' item – marked with [[Image:Ide_db_RunStack_dn.png]].It describes a clause of a nondeterministic predicate. The next clause of this predicate can be executed when a program failure of this clause occurs. Such items occur when a clause of a predicate, which creates a '''backtrack''' point (can produce more than one solution) is called.
*'''TrapTrack''' item – marked with [[Image:Ide_db_RunStack_rh.png]] or [[Image:Ide_db_RunStack_dn_rh.png]]. They describe a continue item (clause), which will be resumed in any case independently whether an error condition occurs or no. For example, such item is created when a predicate call is trapped with the <vp>trap/3</vp> predicate. The [[Image:Ide_db_RunStack_rh.png]] icon is used to mark trapped clauses of deterministic predicates. The [[Image:Ide_db_RunStack_dn_rh.png]] icon is used to mark trapped clauses of nondeterministic predicates.

The '''BackTrack''' (marked with [[Image:Ide_db_RunStack_dn.png]]) and '''TrapTrack''' items (marked with [[Image:Ide_db_RunStack_dn_rh.png]]) are backtracking points. The clause, marked by one of these items, will be resumed and the program execution will be continued after the corresponding failure or an error occurs.

The typical example of the '''Run Stack''' window is presented in the following picture:

[[Image:Ide_db_RunStack.png]]

'''Pop-up Menu'''

The '''Run Stack''' window has the pop-up context menu:

[[Image:Ide_db_RunStack_menu.png]]

For each selected item in the tree, this menu contains items:

*'''Refresh'''
*:It refreshes all the '''Run Stack''' window contents, rebuilds the tree.
*: It also refreshes the {{ide|Debugger#Variables Window|'''Variables'''}} window (if it is displayed).

*'''Go To Code'''
*:Activates the Prolog source editor and places the cursor at the Prolog clause corresponding to the item selected in the '''Run Stack''' window. If the item does not correspond to a Prolog module with debug information, then the '''Disassembly''' window will be opened and the cursor will be placed onto the corresponding assembler instruction. The same action is caused by double-click a predicate call in the '''Run Stack''' window.

*'''Copy Line'''
*:It copies the selected line contents to the clipboard.

*'''Show Domains'''
*:This option turns ON/OFF displaying domains of variables.

*'''Show Values'''
*:This option turns ON/OFF displaying values of variables.

The '''Run Stack''' window can be activated by the IDE menu '''View | Run Stack'''.

=== Variables Window ===

The '''Variables''' window can be activated either by '''Ctrl+Alt+V''' or from the IDE menu '''View | Variables for Current Clause'''.

'''Variables Window Contents'''

The '''Variables''' window displays the tree of all program variables and facts from the traced clause, which are already created by the program at the current tracing step. These are: all variables and all object facts (fact variables), which are created in the clause before the executing instruction, and all class facts (fact variables), which can be used in this clause (declared in this class implementation).

The top line of the window displays the declaration of the predicate, whose clause is executed.

[[Image:Ide_db_Vars_Top.png]]

The '''Variables''' window content is updated after every trace step.

'''Pop-up Context Menu'''

The '''Variables in the Current Clause''' window has the following pop-up context menu:

[[Image:Ide_db_Vars_Menu.png]]

This menu contains items:

*''Insert into Watch Window''
*:Opens the '''Watch Window''' and moves there selected variable.

*''Copy''
*:This command copies the contents of the line selected in the '''Variables''' window to the clipboard.

*''Show as Hexadecimal''
*:Shows integral values in the hexadecimal format.

*''Show as Decimal''
*:Shows integral values in the decimal format.

*''Show as Octal''
*:Shows integral values in the octal format.

*''Show Domains''
*:This option turns '''ON/OFF''' displaying the domains after variable names.

*''Show Variable Addresses''
*:This option turns '''ON/OFF''' displaying the addresses after variable names.

*''Find''
*:This command allows search variable by name.

*''Copy Tree''
*:This command copies the contents of the window to the clipboard.

=== Facts Window ===

'''Class Facts'''

The '''Facts''' window always shows the current contents of all '''class''' fact databases defined in the program being debugged.

Simple example:

[[Image:Ide_db_Facts_View.png]]

Pressing '''CTRL+ALT+F''' opens '''Facts''' window:

[[Image:Ide_db_Facts_View3.png]]

Clicking icons opens sub-trees:

[[Image:Ide_db_Facts_View4.png]]

'''Facts''' window automatically goes to the fact that is selected in the text editor (if any):

[[Image:Ide_db_Facts_View11.png]]

[[Image:Ide_db_Facts_View41.png]]

'''Objects Facts''' you cat look like a components of object variables in the {{ide|Debugger#Variables Window|'''Variables''' window}}

'''Pop-up Context Menu'''

The '''Facts Window''' has the following pop-up context menu:

[[Image:Ide_db_Vars_Menu.png]]

This menu contains items:

*''Insert into Watch Window''
*:Opens the '''Watch Window''' and moves there selected fact.

*''Copy''
*:This command copies the contents of the line selected in the '''Facts''' window to the clipboard.

*''Show as Hexadecimal''
*:Shows integral values in the hexadecimal format.

*''Show as Decimal''
*:Shows integral values in the decimal format.

*''Show as Octal''
*:Shows integral values in the octal format.

*''Show Domains''
*:This option turns '''ON/OFF''' displaying the domains after facts names.

*''Show Addresses''
*:This option turns '''ON/OFF''' displaying the addresses after facts names.

*''Find''
*:This command allows search fact by name.

*''Copy Tree''
*:This command copies the contents of the window to the clipboard.

=== Breakpoints Window ===

The '''Breakpoints''' window shows all breakpoints, which have been set in the program being debugged.

You can set a breakpoint onto any executable line in program source files (or in the '''Disassembly''' window, where a breakpoint can be set on any instruction of the program being debugged).

There are two kinds of breakpoints: hard and soft. Hard breakpoints are active in any debugging mode. Soft breakpoints are active in normal debugging mode but disabled in a special mode of quick debugging, called ''Fast Forward Mode''.

==== Breakpoints Window Contents ====

The '''Breakpoints''' window for each breakpoint includes '''Status''', '''Source''', '''Line''', '''Count''', '''Comment''' and '''Action''', where:

*'''''Status'''''
*:Shows whether the breakpoint is ''hard'' or ''soft''.
**''Hard''
**:If a breakpoint is ''hard'' then it will be activated in any debugging mode. A hard breakpoint is marked with the filled circle [[Image:Ide_db_BreakPoints_en.png]] or [[Image:Ide_db_BreakPoints_assembler.png]] (for assembler) or [[Image:Ide_db_BreakPoints_shifted.png]] (for relocated breakpoint).
**''Soft''
**:If a breakpoint is ''soft'' then it will be activated only in normal (not Fast Forward) debugging mode. A soft breakpoint is marked with the hollow circle [[Image:Ide_db_BreakPoints_dis.png]] or [[Image:Ide_db_BreakPoints_assembler_disabled.png]] (for assembler).
**''Invalid''
**:A breakpoint is invalid when it is set on a line, which does not contain executable code. An invalid breakpoint is marked with the crossed hollow circle [[Image:Ide_db_BreakPoints_invalid.png]].

*'''''Source'''''
*:This column shows the source string:
*:<vipbnf><SourceName></vipbnf>
*:where:
*:''SourceName''
*:The description of a predicate in the address space of whose clauses the breakpoint is set:
*:*If the breakpoint is set in Prolog sources, then ''SourceName'' is the filename in which the breakpoint is set. It is displayed with the format:
*::<vipbnf><FileName> '(' <Path> ')'</vipbnf>
*::The ''Path'' can use {{ide|Make Facility#Build Symbols|Build script symbols}}.
*:* If the breakpoint is set in the '''Disassembly''' window, then ''SourceName'' has the format:
*::<vipbnf>--- assembler: <AddressValue></vipbnf>
*::''AddressValue'' is the hexadecimal address of the breakpoint in the assembler code of the predicate in which the breakpoint is set.

*'''''Line'''''
*:When the breakpoint is set in a Prolog source file, then this column displays the number of the line the breakpoint is set on. When the breakpoint is set in the Disassembly window, then the number of the line is equal to 0.

*'''''Count'''''
*:This column displays {{ide|Debugger#Breakpoint Properties|counts}} of breakpoints.

*'''''Comment'''''
*:This column displays {{ide|Debugger#Breakpoint Properties|comment strings}} of breakpoints.

*'''''Action'''''
*:This column displays the script text of a breakpoint. The script is performed each time the program reaches the breakpoint.

==== Breakpoints in Prolog and Disassembly Windows ====

Breakpoints can be set in Prolog source files and in the '''Disassembly''' window:

* In Prolog sources valid breakpoints can be set only on lines containing executable instructions. That is, breakpoints can be set only in predicate clauses on lines containing predicate calls, otherwise the breakpoints that are set on non-clause lines would be marked as invalid. The breakpoints that are set on clause lines that do not contain predicate calls would be shifted to the lines containing such calls (if any), but the initial line would be marked with [[Image:Ide_db_BreakPoints_shifted.png]]. Valid breakpoints are marked with red circles [[Image:Ide_db_BreakPoints_en.png]] or [[Image:Ide_db_BreakPoints_dis.png]] in Prolog sources and are shown in the '''Disassembly''' window as blue circles [[Image:Ide_db_BreakPoints_assembler.png]] or [[Image:Ide_db_BreakPoints_assembler_disabled.png]]. If a Prolog clause has several assembler implementations (when the clause has several flow patterns), then each breakpoint in Prolog sources can generate several breakpoints in the '''Disassembly''' window.
* Breakpoints that are set in the '''Disassembly''' window are marked with red circles [[Image:Ide_db_BreakPoints_en.png]] or [[Image:Ide_db_BreakPoints_dis.png]]. Such breakpoint can be later overwritten by a breakpoint (marked with blue circles [[Image:Ide_db_BreakPoints_assembler.png]] or [[Image:Ide_db_BreakPoints_assembler_disabled.png]]) that is set in Prolog sources on the same address as the breakpoint set in the '''Disassembly''' window. Notice that after modification and recompilation of the project some breakpoints that are set in the '''Disassembly''' window can be cleared (if other instructions are placed at breakpoint addresses.)

All breakpoints which are set in a program are seen in the '''Breakpoints''' window.

==== Breakpoint Properties ====

Each breakpoint has properties, which can be modified in the '''Breakpoint Properties''' dialog:

[[Image:Ide_db_BreakPoint_Properties.png]]

In this dialog:

The top line contains:

* If the breakpoint is set in Prolog sources, then the top line has format:
*:'''<vipbnf>File: <FileName> Line: <LineNumber></vipbnf>'''
*:''FileName'' is the name of the Prolog source file in which the breakpoint is set.
*:''LineNumber'' is the number of the line on which the breakpoint is set.

* If the breakpoint is set in the '''Disassembly''' window, then the top line has format:
*:'''<vipbnf>Breakpoint Address:<Address></vipbnf>
*:''Address'' is the breakpoint address in the program memory as it is seen in the '''Disassembly''' window.

'''Hard'''
:This check box controls the ''Hard/Soft'' state of the breakpoint. When you turn a breakpoint to Hard, then it will be activated in any debugging mode. When you turn a breakpoint to Soft, then it will be activated only in normal (not Fast Forward) debugging mode.

'''Counter''' ''Value''
:Shows the current number of activations of the breakpoint since its creation. The user cannot modify this value. This value increases by 1 each time when the program reaches the breakpoint. And resets to 0 at the beginning of the debug session.

'''Comment''' ''Comment string''
:In this edit box you can type in a ''Comment string''. By default it has the value of the corresponding line in the source file.

'''Action''' ''Script text''
:In this box you can type in a ''Script text''.

==== Pop-up Menu ====

The '''Breakpoints''' window has the pop-up context menu:

[[Image:Ide_db_BreakPoints_pop_up.png]]

To activate this menu, select a breakpoint and press the right mouse button. This menu contains items:

*'''Go to Source'''
*:If the breakpoint is set in the Prolog sources, then the '''Go to Code''' activates the Prolog source code editor, and moves the cursor to the Prolog code corresponding to the specified breakpoint. If the breakpoint is set in the '''Disassembly''' window, then the '''Go to Code''' moves the view to this breakpoint in the '''Disassembly''' window. The same action is performed by double-click the breakpoint or by pressing the '''Enter''' on the breakpoint.

*'''Properties'''
*:Invokes the {{ide|Debugger#Breakpoint Properties|'''Breakpoint Properties'''}} dialog for the selected breakpoint.

*'''Toggle (Turn to Hard/Soft)'''
*:Switches the ''Hard/Soft'' state of the selected breakpoints.

*'''Delete'''
*:Deletes the selected breakpoints.

*'''Turn to Hard All'''
*:Sets the state of all breakpoints that are set in the program to ''Hard''.

*'''Turn to Soft All'''
*:Sets the state of all breakpoints that are set in the program to ''Soft''.

*'''Remove All'''
*:Removes all breakpoints that are set in the program.

The '''Breakpoints''' window is auto-updated for any breakpoint updating.

The '''Breakpoints''' window can be activated either by '''Ctrl+Alt+B''' or from the IDE menu '''View | Breakpoints'''.

=== Threads Window ===
----
The '''Threads''' window shows information about the process being debugged and its threads.

The '''Threads''' window looks like following:

[[Image:Ide_db_Threads.png]]

Names displayed in the header of the window columns are the following:

*'''TID'''
*:This column displays thread identifiers of all threads created by the process being debugged.
*'''Current'''
*:This column identifies the current thread by the <vp>*</vp> sign. In the {{ide|Debugger#Variables Window|Variables}} window you can see only variables of predicates executed in the current thread.
*'''State'''
*:Displays states of threads. States can be '''''Running''''', '''''Stopped''''', and '''''Suspend'''''.
*: '''''Running''''' The thread has been started, it is not suspended (see <vp>thread::suspend/0-></vp>, <vp> syncObject::wait/0-></vp>, <vp>syncObject::wait/1-></vp>) or terminated (see <vp>thread::terminate/1</vp>).
*: '''''Suspend''''' The thread is in suspended state (see <vp>thread::createSuspended/3</vp>, <vp>thread::suspend/0-></vp>, <vp>syncObject::wait/0-></vp>, <vp>syncObject::wait/1-></vp>).
*: '''''Stopped''''' The thread was created and then stopped on a breakpoint, but it is not suspended (see <vp>thread::suspend/0-></vp>, <vp>syncObject::wait/0-></vp>, <vp>syncObject::wait/1-></vp>). If you set suspended state to a '''''Stopped''''' thread, then it turns into the '''''Suspend''''' state.
*'''Time'''
*:Thread creation time.
*'''User time'''
*:Processor time in the user-mode used by the thread.
*'''Kernel Time'''
*:Processor time in the kernel-mode used by the thread.
*'''Priority'''
*:The priority level of the thread. Here can be displayed the following numbers <vp>2, 1, 0, -1, -2</vp>.
*'''Predicate'''
*:This field contains the name of the currently executed thread's predicate (if it is possible to determine it).

{|{{prettytable}}
|-
! Displayed Number
! Priority Name
! Description
|-
| 2
| '''Highest'''
| The thread can be scheduled before threads with any other priority.
|-
| 1
| '''AboveNormal'''
| The thread can be scheduled after threads with '''Highest''' priority and before those with '''Normal''' priority.
|-
| 0
| '''Normal'''
| The thread can be scheduled after threads with '''AboveNormal''' priority and before those with '''BelowNormal''' priority. Threads have Normal priority by default.
|-
| -1
| '''BelowNormal'''
| The thread can be scheduled after threads with '''Normal''' priority and before those with '''Lowest''' priority.
|-
| -2
| '''Lowest'''
| The thread can be scheduled after threads with any other priority.
|}

'''Pop-up Menu'''

The '''Threads''' window has the pop-up context menu. The same commands can be activated from the '''Thread''' sub-menu of the IDE task menu.

[[Image:Ide_db_Threads_popup.png]]

*'''Goto Source'''
*:Opens the text editor and places the cursor onto the predicate, which created the selected thread.
*'''Set Current'''
*:Sets the selected thread as current.
*'''Resume'''
*:Resumes the run of the selected thread.
*'''Suspend'''
*:Suspends the selected thread.
*'''Copy'''
*:Copies the contents of the line selected in the '''Threads''' window to the clipboard.
*'''Copy All'''
*:Copies the contents of the '''Threads''' window to the clipboard.

The '''Threads''' window is updated after changing any displayed parameter.

The '''Threads''' window can be activated either by '''CTRL+Alt+H''' or from the IDE menu '''View | Threads'''.

=== Disassembly Window ===

The '''Disassembly''' window shows the assembly language interpretation of the inspected code.

The disassembly starts from the specified top address toward the upper memory and prints each instruction on a new line.

Each line is printed by the pattern:

<vipbnf><LineMarkers> <Address> [ <HexCode> ] <AssemblerCommand></vipbnf>

where:

''LineMarkers''
:Are the {{ide|Debugger#Debug Menu Commands|''instruction pointer''}} [[Image:Ide_db_InstructionPointer.png]] and the breakpoint[[Image:Ide_db_BreakPoints_en.png]] (or [[Image:Ide_db_BreakPoints_dis.png]]) markers, which can mark this line.
''Address''
:The start address of the instruction code.
''HexCode''
:This is the hexadecimal instruction code. This field can be shown/hidden from the pop-up menu of the '''Disassembly''' window by checking the '''Show OpCodes''' item.
''AssemblerCommand''
:This is the assembler command corresponding to the instruction code. Assembler commands have the Intel standard assembler abbreviation. If a certain address is resolved to an external name, then this name will be printed in the command column.
: The instruction, which will be executed at the next trace step, is marked with the [[Image:Ide_db_InstructionPointer.png]] ''Instruction pointer'' in the ''LineMarkers'' field.

Example:

[[Image:Ide_db_DisAsm_View.png]]

==== Pop-up Menu ====

The '''Disassembly''' window has the pop-up context menu with the followin commands:

*'''Go To Address'''
*:Invokes the '''Go to Address''' dialog
*:[[Image:Ide_db_DisAsm_Go2Address.png]]
*:to type in the address of the instruction, which should be displayed in the top line of the '''Disassembly''' window. The ''Address'' should be specified in the hexadecimal format. This dialog allows typing symbolic external link names and symbolic CPU register names.
*'''Go To EIP'''
*:Updates the '''Disassembly''' window and places the cursor at the address of the instruction on which the program execution is suspended.
*'''Breakpoint…'''
*:Allows handling the breakpoint [[Image:Ide_db_BreakPoints_en.png]] (or [[Image:Ide_db_BreakPoints_dis.png]]) for the assembler instruction pointed by the cursor. It has the following sub-commands:
*:[[Image:Ide_db_DisAsm_PopUp.png]]
*:*'''Toggle Breakpoint'''
*:*:Sets or removes a breakpoint at the instruction with the address pointed by the cursor.
*:*'''Enable / Disable'''
*:*:''Enables / Disables'' the breakpoint pointed by the cursor. This item is disabled if there is no breakpoint at the address pointed by the cursor.
*:*'''Properties'''
*:*:Invokes the '''Breakpoint Properties''' dialog for the breakpoint pointed by the cursor. This item is disabled if there is no breakpoint at the address pointed by the cursor.
*'''Go To Source'''
*:Activates the IDE source code editor and sets the cursor at the predicate whose assembler instruction is pointed by the cursor in the '''Disassembly''' window. (When it is possible.)
*'''Copy'''
*:Copies lines selected in the '''Disassembly''' window to the clipboard. A selection can be performed with the '''Shift+Up Arrow''' and '''Shift+Down Arrow''' key combinations.
*'''Show OpCodes'''
*:Checking and unchecking this item hides/shows hex images of operation (instruction) codes ('''OpCodes'''). These hex instruction codes are shown in the ''HexCode'' field.
*'''Source Annotation'''
*:Checking OFF/ON this item hides/shows object names, corresponding to predicate entry points. Each object name is printed on a new line before the corresponding instruction line.
*'''Show Hints'''
*:Shows additional information about the instruction being executed.

The '''Disassembly''' window is updated after each trace step of the debugger.

==== Disassembly Window Commands ====

*'''Trace Into''' ('''F11''') command
*:Tracing in the '''Disassembly''' window with the '''Step Into''' ('''F7''') command performs execution of one assembler instruction (including entering into procedures if any). That is, if the '''Step Over''' command will execute a <vp>call</vp> instruction as one trace step, then the '''Step Into''' command will go into the called procedure. It usually executes disassembler instructions line after line.
*'''Step Over''' ('''F10''') command
*:Tracing in the '''Disassembly''' window with the '''Step Over''' ('''F10)''' command performs execution of one assembler instruction (including execution of <vp>call</vp> instructions). So the '''Step Over''' ('''F10''') command works almost the same way as the '''Trace Into''' ('''F11''') command except for execution of <vp>call</vp> instructions. In difference to the '''Trace Into''' ('''F11''') command, it tries to perform <vp >call</vp> instructions as one step and reaches the next line only if the called code returns to that line.
*'''Run to Cursor''' ('''CTRL+F10''') command
*:Tracing in the '''Disassembly''' window with the '''Run to Cursor''' ('''CTRL+F10''') command works in the following way. The debugger places an invisible breakpoint at the address corresponding to the instruction specified by the cursor and performs the '''Debug Run''' ('''F5''') command. It depends only upon the program code whether the program will reach this instruction or will never reach it.

The '''Disassembly''' window can be activated:

* by '''Shift+Alt+1'''
* by '''Ctrl+D''' from the traceable source code. The topmost line of the '''Disassembly''' window displays the address of the disassembler instruction corresponding to the predicate pointed by the cursor in the source code.
* from the IDE menu '''View | Disassembly'''

If the tracing code has no debug information, then the '''Disassembly''' window is opened initially (when the debugger starts) and the instruction pointer [[Image:Ide_db_InstructionPointer.png]] points to the executing assembler instruction.

=== Registers Window ===

The '''Registers''' window shows current values of the CPU (Central Processor Unit) registers:

* General registers
* Segment registers
* Flags
* Floating-point registers

A register value is printed:

* '''red''', if it is changed from the last program trace step
* '''blue''', otherwise.

For example:

[[Image:Ide_db_Registers_fpu.png]]

The '''Floating Point''' command from context pop-up menu can be used to turn ON/OFF the displaying of Floating-point registers.

The '''Registers''' window can be activated either by '''Ctr+ Alt+G''' or from the IDE menu '''View | Registers'''.

=== Modules Window ===
----
The Modules Window shows all the modules currently loaded in this debug session. It shows the filename, path, the base address range, the code address range and the type of debug information.

[[Image:Ide_db_Modules.png]]

=== Memory Dump Window ===

The '''Memory Dump''' window shows the virtual memory dump of the program being debugged. Memory dump lines have the length, which is determined by the window width. The number of printed lines window height.

'''Information Displayed in the Memory Dump Window'''

Each line in the '''Memory Dump''' window is printed by the pattern:

<vipbnf><Address> | [ <HexValues> ] [ <ASCIIcharacters> ] [ <UnicodeCharacters>]</vipbnf>

where:

''Address''
:This is the hexadecimal address of the first byte of the memory displayed in this line.
''HexValues''
:<vipbnf><HexValues> : <HexValue> [ <HexValues> ]</vipbnf>
:This is the hexadecimal format of the memory dump. Each hex value can be an image of one, two, four or eight continued memory bytes (this is contolled by the '''Memory Dump''' window content pop-up menu).
''ASCIIcharacters''
:<vipbnf><ASCIIcharacters> : <ASCIIcharacter> [ <ASCIIcharacters> ]</vipbnf>
:This is the same memory dump but in the format of ASCII characters (a character represenrs one byte). Unprintable characters are printed as dots.
''UnicodeCharacters''
:<vipbnf><UnicodeCharacters> : <UnicodeCharacter> [ <UnicodeCharacters> ]</vipbnf>
:This is the same memory dump in the format of Unicode characters (a character represents two bytes). Unprintable characters are printed as dots.

Example:

[[Image:Ide_db_Memory_view1.png]]

The '''Memory Dump''' window title shows the module name, which memory is displayed in the window. If the module name cannot be determined, then the title displays ''Unknown module''.

'''Content Pop-up Menu'''

The '''Memory Dump''' window has the pop-up context menu which contains commands:
*'''Go To Address'''
*:'''Ctrl+G'''. Invokes the '''Go to Address''' dialog
*:[[Image:Ide_db_DisAsm_Go2Address.png]]
*: to type a new top address in hex format. This dialog allows typing symbolic external link names and symbolic CPU register names. Double-click in the '''Memory Dump''' window area also activates the '''Go to Address''' dialog.
*'''Go To ''Ptr'''''
*:'''Ctrl+Shift+G'''. Updates the '''Memory Dump''' window starting the first line from the address shown as ''Ptr'' (address defined by the memory contents of four or eight continued bytes at which the cursor is pointing if one of '''4-byte Integer''' or '''8-byte Integer''' is selected).
*'''Undo Go to'''
*:'''Alt+Left Arrow'''. Updates the '''Memory Dump''' window view to start from the previously used top (the first line) address.
*'''Redo Go to'''
*:'''Alt+Right Arrow'''. This operation is the counterpart to the '''Undo Go to'''. It updates the '''Memory Dump''' window view to start from the "next" top address, which was used before the '''Undo Go to''' command was implemented.
*'''Set Memory Breakpoint'''
*:This operation sets a memory breakpoint at address from the left pane.
*'''Remove Memory Breakpoint'''
*:This operation removes a previously set a memory breakpoint.
*'''Copy'''
*:Copies the selected lines to the clipboard. To select a line, click on it while holding the '''shift''' key. You can select multiple lines at one time.
*'''Copy ''Ptr'''''
*:'''Ctrl+C'''. Copies hexadecimal representation of the specified address (four or eight bytes) to the clipboard.
*'''Refresh'''
*:Refresh the '''Memory Dump''' window contents.
*'''Write Block'''
*:This command opens the '''Write Memory Block''' dialog:
*:[[Image:Ide_db_Memory_BlockWrite.png]]
*:*'''Filename'''
*:*:Here you should type in the name of a file in which the specified memory block should be saved.
*:*'''Start Address'''
*:*:Here you should specify a hexadecimal start address of the memory block.
*:*'''Length'''
*:*:Here you should specify a hexadecimal length in bytes of the memory block.
*'''Show Hex'''
*:Shows the column, which displays the memory dump in the hexadecimal format. This is the {{ide|Debugger#Debugger Views|''HexValues''}} column in the right pane.
*'''Show ASCII'''
*:Shows the column, which displays the '''''ASCII''''' format of the memory dump. This is the {{ide|Debugger#Debugger Views|''ASCIIcharacters''}} column in the right pane.
*'''Show Unicode'''
*:Shows the column, which displays the '''''Unicode''''' format of the memory dump. This is the {{ide|Debugger#Debugger Views|''UnicodeCharacters''}} column in the right pane.
*'''Update Speed...'''
*:Defines the rate of the Memory Dump window updating:
*:[[Image:iDE_db_Memory_menu1.png]]
*:*'''High'''
*:*:Performs automatic updating with the high rate.
*:*'''Normal'''
*:*:Performs automatic updating with normal rate.
*:*'''Low'''
*:*:Performs automatic updating with low rate.
*:*'''Manual'''
*:*:No automatic updating.
The '''Memory Dump''' window can be activated either by '''CTRL+Alt+M''' or from the IDE menu '''View | Memory Dump'''.

Ide/Resource Editor/Editing a Dialog

2013-05-23T09:24:46Z

SergeMukhin: /* Using Anchors for Positioning GUI Controls while Dialog Resizing */

<noinclude>[[Category:Ide]]</noinclude>

To edit a dialog, in the project tree (in the Project window) double click (or press '''Enter''') the name of a file with a dialog description (the '''.dlg''' filename extension). The
{{ide|Resource Editor#IDE Designer|'''IDE Designer'''}} appears and you can edit whatever form of a dialog you wish.

[[Image:Ide_MyDialog_Editor.png|center]]

The IDE Designer After Creation of a New Dialog

When a new dialog is created, it will by default have three push button controls: '''OK''', '''Cancel''' and '''Help'''. These can freely be rearranged or deleted.

==== Controls ====

Each control in a dialog must have an identifying name (constant in VPI style dialogs), which is unique within that dialog. While two controls within one dialog may not have the same name (or constant value), it is actually a good idea if controls in different dialogs, which perform the same action have the same names (or constants).

===== Types of Controls =====

{|{{prettytable}}
|-
| [[Image:Ide_PushButton.png]]
| A '''Push Button''' control serves to initiate a specialized action in an application.
|-
| [[Image:Ide_CheckBox.png]]
| A '''Check Box''' control lets you indicate a choice among two alternatives. For example some facility may be switched ON or switched OFF.
|-
| [[Image:Ide_RadioButton.png]]
| A group of '''Radio Button''' controls serves to indicate one choice from among a list of alternatives.
|-
| [[Image:Ide_StaticText.png]]
| A '''Static Text''' control reserves an area for the text in the dialog. Although called static, in fact the application can change the text during execution. This is often used for prompts or field names relating to other controls.
|-
| [[Image:Ide_EditControl.png]]
| An '''Edit Control''' reserves an area for text editing (e.g. names, numbers, text constants etc.). Editing text strings with multiple lines is possible.
|-
| [[Image:Ide_ListBox.png]]
| A '''List Box''' allows you to view a list of elements and to select one - or several - elements from this list.
|-
| [[Image:Ide_ListButton.png]]
| A '''List Button''' control serves for choosing one from the pop-out set of the alternatives revealed by pressing the button. Pressing the button again pops the list back in again.
|-
| [[Image:Ide_ListEdit.png]]
| A '''List Edit''' control allows single line text editing like an '''Edit''' control, or selection from a list of elements.
|-
| [[Image:Ide_VerticalScrollBar.png]] [[Image:Ide_HorizontalScrollBar.png]]
| The '''Vertical Scroll Bar''' and the '''Horizontal Scroll Bar''' controls serve to select a value within a scale of values.
|-
| [[Image:Ide_GroupBox.png]]
| A '''Group Box''' control serves for assembling together a number of controls in a functional group with a Group Name. Its only function is a visual one.
|-
| [[Image:Ide_Icon.png]]
| An '''Icon''' control reserves an area for an icon image.
|-
| [[Image:Ide_CustomControl.png]]
| A '''Custom Control''' can be either IDE Controls created in the project, it can be VPI user-defined control with a window class defined by <vp>vpi::classCreate</vp>, or it can be controls imported as {{ide|Creating new Project Items#Creating a COM Package|COM packages}} from DLLs, VBXs or OCXs.
|}

===== Inserting Controls =====

To insert a new control in a dialog, click the icon of the desired control type in the '''Controls toolbar'''. (You can also select the desired control type in the '''Controls''' sub-menu of the main IDE menu or in the pop-up menu in the {{ide|Resource Editor#IDE Designer|'''IDE Designer'''}}.)

===== Controls Toolbar =====

Originally the '''Controls toolbar''' is displayed below the {{ide|Resource Editor#IDE Designer|'''IDE Designer'''}} window. You see it in the following picture:

[[Image:Ide_Controls.png|center|frame|'''The Controls Toolbar''']]

Clicking icons in the '''Controls toolbar''' you select a type of a control to be placed into the edited dialog/window/form/IDE control (sometimes we will use the term ''container'' instead of dialog/window/form/IDE control). When you click a control type icon, then the current cursor is replaced with the cursor correspondent to the control type to be inserted. Move the cursor to some position in the container client area and click the mouse button. The control with the default size will be inserted at the specified position.

Instead of dropping a control into a container with a click, it is possible to drag out the rectangle (in the container client area) where a control should be placed; so you can specify not only the control position but also the control size.

After a VPI control is placed with the mouse into a {{ide|Resource_Editor#GUI and VPI Style Resources|VPI style container}}, the correspondent VPI control Attributes dialog appears. In this dialog you can change some control attributes, when you close the dialog, the control appears at the specified location in the container.

After a GUI control is placed with the mouse into a {{ide|Resource_Editor#GUI and VPI Style Resources|GUI style container}}, it immediately appears at the specified location in the container. To change properties of the GUI control, one should select it then the list of GUI control properties appears in the {{ide|Resource Editor#GUI Control Properties Table|GUI control Properties table}}.

There are the following icons in the '''Controls toolbar:'''

{|{{prettytable}}
|-
! Icon
! Insert a new:
! Description
|-
| [[Image:Ide_Ctrl_PushBtn.png]]
| Push Button
| After selection of this control the cursor becomes [[Image:Ide_Cursor_PushBtn.png]]
|-
| [[Image:Ide_Ctrl_CheckBx.png]]
| Check Box
| After selection of this control the cursor becomes [[Image:Ide_Cursor_Check.png]].
|-
| [[Image:Ide_Ctrl_RadioBtn.png]]
| Radio Button
| After selection of this control the cursor becomes [[Image:Ide_Cursor_RB.png]].
|-
| [[Image:Ide_Ctrl_StaText.png]]
| Static Text Control
| After selection of this control the cursor becomes [[Image:Ide_Cursor_Text.png]].
|-
| [[Image:Ide_Ctrl_EditCtrl.png]]
| Edit Control
| After selection of this control the cursor becomes [[Image:Ide_Cursor_Edit.png]].
|-
| [[Image:Ide_Ctrl_ListBox.png]]
| List Box
| After selection of this control the cursor becomes [[Image:Ide_Cursor_ListBox.png]].
|-
| [[Image:Ide_Ctrl_ListBtn.png]]
| List Button
| After selection of this control the cursor becomes [[Image:Ide_Cursor_ListBtn.png]].
|-
| [[Image:Ide_Ctrl_ListEdit.png]]
| List Edit
| After selection of this control the cursor becomes [[Image:Ide_Cursor_ListEdit.png]].
|-
| [[Image:Ide_Ctrl_HScroll.png]]
| Horizontal Scroll Bar
| After selection of this control the cursor becomes [[Image:Ide_Cursor_HScroll.png]].
|-
| [[Image:Ide_Ctrl_VScroll.png]]
| Vertical Scroll Bar
| After selection of this control the cursor becomes [[Image:Ide_Cursor_VScroll.png]].
|-
| [[Image:Ide_Ctrl_GroupBox.png]]
| Group Box
| After selection of this control the cursor becomes [[Image:Ide_Cursor_Group.png]].
|-
| [[Image:Ide_Ctrl_Icon.png]]
| Icon Control
| After selection of this control the cursor becomes [[Image:Ide_Cursor_Icon.png]].
|-
| [[Image:Ide_Ctrl_Custom.png]]
| Custom Control
| After selection of this control the cursor becomes [[Image:Ide_Cursor_Custom.png]].
|}

===== Selecting and Deselecting Controls =====

Click inside a control to select one control. A frame appears around the selected control.

To select a group of controls move the mouse pointer to the point in the dialog you want to be one corner of the selected area and press and hold the left mouse button. While holding the left mouse button move the mouse until all the desired controls in the dialog are inside the selected area. Then release the mouse button. All controls inside the specified rectangle will be selected.

Also after one or more controls are already selected, you can include one extra control in the selection by holding down the '''Ctrl''' key and click the control.

To deselect the control or group of controls click outside the selecting frame. Deselected controls lose their frame.

===== Resizing Controls =====

Once a control has been inserted in the dialog, it has a default size. To re-size a control, first click inside the control area to select it. Then move the cursor to the sizing handles on the selection frame. A new shape of cursor indicates the direction in which you can re-size the control. Press and hold the mouse button, drag until the selected control has the size you want, then release the mouse button.

You can also change the size of a control by double-clicking it to activate the dialog for control attributes setting. Select the position you want to change and after specifying a new position or size, press enter to return to the dialog.

'''Remark:''' You cannot change the size of icons. You can only change their location.

===== Moving Controls =====

To move a control or a group of controls first select them. Then move the cursor inside the selection frame, press and hold the mouse button, drag the mouse pointer to a new location and release the mouse. Also, when one or more controls are selected, it is possible to use the cursor keys to move the selection in small steps (corresponding to the '''Grid''' settings).

===== Arranging Controls =====

To arrange a group of controls first select the group. Then click an appropriate button in the '''Layout''' toolbar or a menu item in the '''Layout''' menu of the IDE menu (or in the pop-up menu).

[[Image:Ide_Layout.png|center|frame|'''The Layout Toolbar''']]

The '''Layout''' commands for justifying and resizing controls:

{|{{prettytable}}
|-
| [[Image:Ide_Layout_AllignLeft.png]]
| '''Align Left'''
| Align the selected controls along their left sides.
|-
| [[Image:Ide_Layout_CenterVertically.png]]
| '''Align Center'''
| Center the selected controls vertically.
|-
| [[Image:Ide_Layout_AllignRight.png]]
| '''Align Right'''
| Align the selected controls along their right sides.
|-
| [[Image:Ide_Layout_AllignTops.png]]
| '''Align Top'''
| Align the selected controls along their tops.
|-
| [[Image:Ide_Layout_CenterHorizontally.png]]
| '''Align Middle'''
| Center the selected controls horizontally.
|-
| [[Image:Ide_Layout_AllignBottom.png]]
| '''Align Bottom'''
| Align the selected controls along their bottoms.
|-
| [[Image:Ide_Layout_SpacingHorizontally.png]]
| '''Even Horizontal Spacing'''
| Spacing the selected controls evenly between the leftmost and the rightmost controls.
|-
| [[Image:Ide_GridButton.png]]
| '''Grid'''
| Toggle the Grid (see below).
|-
| [[Image:Ide_Layout_SpacingVertically.png]]
| '''Even Vertical Spacing'''
| Spacing the selected controls evenly between the topmost and the bottom-most controls.
|-
| [[Image:Ide_Layout_SameSize.png]]
| '''Make Same Size'''
| Make the selected controls the same size as a model control.
|-
| [[Image:Ide_Layout_SameHorizontal.png]]
| '''Make Same Horizontal Size'''
| Make the selected controls the same width as a model control.
|-
| [[Image:Ide_Layout_SameVertical.png]]
| '''Make Same Vertical Size'''
| Make the selected controls the same height as a model control.
|-
|
| '''Size To Contents'''
| Resize the selected controls to optimally display its titles (caption texts).
|}

==== Editing Properties of GUI Controls ====

When you open a GUI dialog or a Form (GUI window) in the '''IDE Designer''', then near from the opened dialog (form) the {{ide|Resource Editor#GUI Control Properties Table|'''Control Properties table'''}} appears.

To change ''properties'' of a GUI package control first select this control (by clicking in it) in the dialog (form). The current set of the control properties appears in the '''Control Properties''' table. Now you can edit the displayed GUI control properties.

'''Click here to view {{ide|Resource Editor#GUI Control Properties Table|GUI Control Properties table}}'''

The displayed set of properties depends on the control type. The {{ide|Resource Editor#GUI Control Properties Table|'''Control Properties table'''}} contains two types of properties. General properties are common to all types of controls and some properties, which are individual to different kinds of controls.

Initially this '''Control Properties''' table is empty. However, as soon as one of controls in the edited dialog (form) is selected this table starts to display properties of the selected control.

If the '''Control Properties''' table is closed, then double-click a control - the '''Control Properties''' table appears. Also the '''Control Attributes''' command, from the '''IDE Designer''' {{ide|Resource Editor#Speed Menu|speed menu}}, can be used to open the '''Control Properties''' table.
{{:ide/Resource Editor/GUI Control Properties Table}}

==== Editing Attributes of VPI Controls ====

To change attributes of a VPI package control double-click it or select the control and activates the '''Control Attributes''' command from the '''IDE Designer''' {{ide|Resource Editor#Speed Menu|speed menu}}. Then the '''''<ControlType>'' Attributes''' dialog appears.

These dialogs contains two levels of attributes. The general group contains attributes, which are common to all types of controls: the '''Text''' determines the control title, the '''Constant''' (name) is used as the control identifier, and the '''Control Size''' group determines position and size of the control.

Notice that the '''Text''' property/attribute is not used for some controls, for instance, it is not used for scroll bars.

Notice that in the '''Text''' fields the ampersand symbol <vp>&</vp> is reserved for indicating that the next to it character is to be underlined. For example, if you use the text string '''E&xit''' as a control name, then this control will be displayed with the title '''Exit''' at runtime. I.e. the char '''x''' will be displayed underlined (thus visually indicating that the '''x''' is an accelerator key). If you need to display the ampersand <vp>&</vp> symbol in the '''Text''' of a control, then use two of them <vp>&&</vp>.

Other attributes are individual to different kinds of controls.

==== Using Anchors for Positioning GUI Controls while Dialog Resizing ====

VPI controls remember in their attributes only their absolute positions and sizes. Therefore, when a VPI dialog or a VPI window containing such VPI controls are resized, these VPI controls do not change their positions and sizes!

In difference to them GUI controls have additional ''Anchor'' properties, which help to reposition (and may be resize) GUI controls when containing them GUI dialog (or form) is resized.

Each GUI control has four anchor properties: '''Left Anchor''', '''Top Anchor''', '''Right Anchor''', and '''Bottom Anchor''' (see {{ide|Resource Editor#GUI Control Properties Table|'''Anchor Properties of GUI Controls'''}}).

Each anchor determines that the specified ('''Left''', '''Top''', '''Right''' or '''Bottom''') control boundary should be '''always''' positioned on the stated distance from the nearest (correspondent) border of the dialog (frame).

Each of anchors can have the '''True''' or '''False''' values. When the anchor value is '''True''', then this anchor is active (used to position the correspondent control).

For example, when the '''Left Anchor''' is active (has the '''True''' value), then the ''left'' control boundary should be positioned on the stated distance from the nearest (''left'') border of the dialog (frame).

The simplest way to see which anchors are active for a control, is to select this control. Then some red arrows between control boundaries and correspondent boundaries of the dialog can bee seen. Each arrow specifies, that the correspondent anchor is active. For example, the arrow from the control top to the dialog top identifies, that the '''Top Anchor''' is active. In the picture below, you see three arrows, which specify that the '''Left''', '''Top''', and '''Right''' anchors are active to the '''Push Button''' control.

[[Image:Ide_de_Anchors.png|center]]

Numbers near such arrows show distances (in Dialog Base Units) between the correspondent boundaries of the control and the dialog.

Normally each control has one active horizontal and one active vertical anchors. When the dialog is resized, then such control is always positioned on the specified distances from the specified boundaries of the dialog. The size of the control is not changed!

When a control has both horizontal (or/and both vertical) anchors active, then both horizontal (or/and both vertical) boundaries of the control should be placed on some specified distances from the correspondent horizontal (vertical) boundaries of the dialog. Therefore, when the dialog is resized, then such control is also resized accordingly to keep the specified distances.

When no one of horizontal (or vertical) anchors of a control are active, then no one of horizontal (or vertical) boundaries of the control are bounded to the correspondent horizontal (vertical) boundaries of the dialog. Coordinates of such controls are handles on the "proportional basis". For example, when the dialog width is increased onto <vp>Delta</vp> dialog base units, then the <vp>X</vp> coordinate of the control is also increased, but it is increased two times smaller. That is the <vp>X</vp> coordinate of the control is increased only onto <vp>Delta/2</vp> dialog base units.

==== Cut, Copy and Paste, Undo and Redo ====

You can '''Cut''' or '''Copy''' a group of selected controls onto the Windows clipboard, and '''Paste''' controls from the clipboard back into a dialog. The '''Undo''' and '''Redo''' commands serve to delete or restore the last editing operations of your dialog.

==== Grid ====

When the menu (or the pop-up menu) entry '''Resource | Grid''' is activated, or when the [[Image:Ide_GridButton.png]] button from the '''Layout''' toolbar is pressed, the following dialog appears:

[[Image:Ide_GridSpecification.png|center|frame|'''The Dialog to Specify the Grid Properties''']]

With a grid in place, arranging the controls inside a dialog is easier. Also it is possible to tell the {{ide|Resource Editor#IDE Designer|'''IDE Designer'''}} by the '''Snap to Grid''' that it should place controls at the grid intersections to give a satisfactory result.

[[Image:Ide_MyDialog_withGrid.png|center|frame|'''Using a grid in the Dialog/Window/Form Editor''']]

==== Test Mode ====

The {{ide|Resource Editor#IDE Designer|'''IDE Designer'''}} has the '''Test Mode''', so it is possible to see how the dialog with the created controls behaves. To illustrate the '''Test Mode''' we will assign some default values to the controls. The test mode is activated and deactivated from the '''Resource''' menu (or from the pop-up menu).

[[Image:Ide_MyDialog_TestMode.png|center|frame|'''Test Mode for a Dialog''']]

==== Tab Stops ====

When activating the menu (or the pop-up menu) entry '''Resource | Tabstops''', it is possible to specify to which controls you can Tab to in the dialog. When this command is activated a small button with the <vp>+</vp> or <vp>-</vp> appears on controls depending upon whether the control has a tab stop or not. By clicking the small buttons, it is possible to toggle the setting.

[[Image:Ide_MyDialog_TabStops.png|center|frame|'''Specifying Tab Stops for a Dialog''']]

To exit the tab stop mode, just click in the dialog but outside of any controls.

==== Visit Order ====

When the tab stops have been specified for a dialog, then it is possible to specify the order in which controls will receive focus when tabbing.

[[Image:Ide_MyDialog_VisitOrder.png|center|frame|'''Displaying the Visit Order''']]

To change the visit order, click a small rectangle displaying the visit order number for a control that has an incorrect sequence number and this will bring up another dialog to change this sequence:

[[Image:Ide_MyDialog_ChangeVisitOrder.png|center|frame|'''Changing the Visit Order''']]

To stop the visit order mode, just click in the dialog outside any controls.

==== Speed Menu ====

When you are in the {{ide|Resource Editor#IDE Designer|'''IDE Designer'''}} you can click the right mouse button to activate the Speed Menu. From this menu you can easily call any {{ide|Resource Editor#IDE Designer|'''IDE Designer'''}} command:

[[Image:Ide_We_SpeedMenu.png|center|frame|'''The IDE Designer Speed Menu''']]

Ide/Resource Editor/Editing a Dialog

2013-05-23T09:23:41Z

SergeMukhin: /* Attributes of VPI Controls */

<noinclude>[[Category:Ide]]</noinclude>

To edit a dialog, in the project tree (in the Project window) double click (or press '''Enter''') the name of a file with a dialog description (the '''.dlg''' filename extension). The
{{ide|Resource Editor#IDE Designer|'''IDE Designer'''}} appears and you can edit whatever form of a dialog you wish.

[[Image:Ide_MyDialog_Editor.png|center]]

The IDE Designer After Creation of a New Dialog

When a new dialog is created, it will by default have three push button controls: '''OK''', '''Cancel''' and '''Help'''. These can freely be rearranged or deleted.

==== Controls ====

Each control in a dialog must have an identifying name (constant in VPI style dialogs), which is unique within that dialog. While two controls within one dialog may not have the same name (or constant value), it is actually a good idea if controls in different dialogs, which perform the same action have the same names (or constants).

===== Types of Controls =====

{|{{prettytable}}
|-
| [[Image:Ide_PushButton.png]]
| A '''Push Button''' control serves to initiate a specialized action in an application.
|-
| [[Image:Ide_CheckBox.png]]
| A '''Check Box''' control lets you indicate a choice among two alternatives. For example some facility may be switched ON or switched OFF.
|-
| [[Image:Ide_RadioButton.png]]
| A group of '''Radio Button''' controls serves to indicate one choice from among a list of alternatives.
|-
| [[Image:Ide_StaticText.png]]
| A '''Static Text''' control reserves an area for the text in the dialog. Although called static, in fact the application can change the text during execution. This is often used for prompts or field names relating to other controls.
|-
| [[Image:Ide_EditControl.png]]
| An '''Edit Control''' reserves an area for text editing (e.g. names, numbers, text constants etc.). Editing text strings with multiple lines is possible.
|-
| [[Image:Ide_ListBox.png]]
| A '''List Box''' allows you to view a list of elements and to select one - or several - elements from this list.
|-
| [[Image:Ide_ListButton.png]]
| A '''List Button''' control serves for choosing one from the pop-out set of the alternatives revealed by pressing the button. Pressing the button again pops the list back in again.
|-
| [[Image:Ide_ListEdit.png]]
| A '''List Edit''' control allows single line text editing like an '''Edit''' control, or selection from a list of elements.
|-
| [[Image:Ide_VerticalScrollBar.png]] [[Image:Ide_HorizontalScrollBar.png]]
| The '''Vertical Scroll Bar''' and the '''Horizontal Scroll Bar''' controls serve to select a value within a scale of values.
|-
| [[Image:Ide_GroupBox.png]]
| A '''Group Box''' control serves for assembling together a number of controls in a functional group with a Group Name. Its only function is a visual one.
|-
| [[Image:Ide_Icon.png]]
| An '''Icon''' control reserves an area for an icon image.
|-
| [[Image:Ide_CustomControl.png]]
| A '''Custom Control''' can be either IDE Controls created in the project, it can be VPI user-defined control with a window class defined by <vp>vpi::classCreate</vp>, or it can be controls imported as {{ide|Creating new Project Items#Creating a COM Package|COM packages}} from DLLs, VBXs or OCXs.
|}

===== Inserting Controls =====

To insert a new control in a dialog, click the icon of the desired control type in the '''Controls toolbar'''. (You can also select the desired control type in the '''Controls''' sub-menu of the main IDE menu or in the pop-up menu in the {{ide|Resource Editor#IDE Designer|'''IDE Designer'''}}.)

===== Controls Toolbar =====

Originally the '''Controls toolbar''' is displayed below the {{ide|Resource Editor#IDE Designer|'''IDE Designer'''}} window. You see it in the following picture:

[[Image:Ide_Controls.png|center|frame|'''The Controls Toolbar''']]

Clicking icons in the '''Controls toolbar''' you select a type of a control to be placed into the edited dialog/window/form/IDE control (sometimes we will use the term ''container'' instead of dialog/window/form/IDE control). When you click a control type icon, then the current cursor is replaced with the cursor correspondent to the control type to be inserted. Move the cursor to some position in the container client area and click the mouse button. The control with the default size will be inserted at the specified position.

Instead of dropping a control into a container with a click, it is possible to drag out the rectangle (in the container client area) where a control should be placed; so you can specify not only the control position but also the control size.

After a VPI control is placed with the mouse into a {{ide|Resource_Editor#GUI and VPI Style Resources|VPI style container}}, the correspondent VPI control Attributes dialog appears. In this dialog you can change some control attributes, when you close the dialog, the control appears at the specified location in the container.

After a GUI control is placed with the mouse into a {{ide|Resource_Editor#GUI and VPI Style Resources|GUI style container}}, it immediately appears at the specified location in the container. To change properties of the GUI control, one should select it then the list of GUI control properties appears in the {{ide|Resource Editor#GUI Control Properties Table|GUI control Properties table}}.

There are the following icons in the '''Controls toolbar:'''

{|{{prettytable}}
|-
! Icon
! Insert a new:
! Description
|-
| [[Image:Ide_Ctrl_PushBtn.png]]
| Push Button
| After selection of this control the cursor becomes [[Image:Ide_Cursor_PushBtn.png]]
|-
| [[Image:Ide_Ctrl_CheckBx.png]]
| Check Box
| After selection of this control the cursor becomes [[Image:Ide_Cursor_Check.png]].
|-
| [[Image:Ide_Ctrl_RadioBtn.png]]
| Radio Button
| After selection of this control the cursor becomes [[Image:Ide_Cursor_RB.png]].
|-
| [[Image:Ide_Ctrl_StaText.png]]
| Static Text Control
| After selection of this control the cursor becomes [[Image:Ide_Cursor_Text.png]].
|-
| [[Image:Ide_Ctrl_EditCtrl.png]]
| Edit Control
| After selection of this control the cursor becomes [[Image:Ide_Cursor_Edit.png]].
|-
| [[Image:Ide_Ctrl_ListBox.png]]
| List Box
| After selection of this control the cursor becomes [[Image:Ide_Cursor_ListBox.png]].
|-
| [[Image:Ide_Ctrl_ListBtn.png]]
| List Button
| After selection of this control the cursor becomes [[Image:Ide_Cursor_ListBtn.png]].
|-
| [[Image:Ide_Ctrl_ListEdit.png]]
| List Edit
| After selection of this control the cursor becomes [[Image:Ide_Cursor_ListEdit.png]].
|-
| [[Image:Ide_Ctrl_HScroll.png]]
| Horizontal Scroll Bar
| After selection of this control the cursor becomes [[Image:Ide_Cursor_HScroll.png]].
|-
| [[Image:Ide_Ctrl_VScroll.png]]
| Vertical Scroll Bar
| After selection of this control the cursor becomes [[Image:Ide_Cursor_VScroll.png]].
|-
| [[Image:Ide_Ctrl_GroupBox.png]]
| Group Box
| After selection of this control the cursor becomes [[Image:Ide_Cursor_Group.png]].
|-
| [[Image:Ide_Ctrl_Icon.png]]
| Icon Control
| After selection of this control the cursor becomes [[Image:Ide_Cursor_Icon.png]].
|-
| [[Image:Ide_Ctrl_Custom.png]]
| Custom Control
| After selection of this control the cursor becomes [[Image:Ide_Cursor_Custom.png]].
|}

===== Selecting and Deselecting Controls =====

Click inside a control to select one control. A frame appears around the selected control.

To select a group of controls move the mouse pointer to the point in the dialog you want to be one corner of the selected area and press and hold the left mouse button. While holding the left mouse button move the mouse until all the desired controls in the dialog are inside the selected area. Then release the mouse button. All controls inside the specified rectangle will be selected.

Also after one or more controls are already selected, you can include one extra control in the selection by holding down the '''Ctrl''' key and click the control.

To deselect the control or group of controls click outside the selecting frame. Deselected controls lose their frame.

===== Resizing Controls =====

Once a control has been inserted in the dialog, it has a default size. To re-size a control, first click inside the control area to select it. Then move the cursor to the sizing handles on the selection frame. A new shape of cursor indicates the direction in which you can re-size the control. Press and hold the mouse button, drag until the selected control has the size you want, then release the mouse button.

You can also change the size of a control by double-clicking it to activate the dialog for control attributes setting. Select the position you want to change and after specifying a new position or size, press enter to return to the dialog.

'''Remark:''' You cannot change the size of icons. You can only change their location.

===== Moving Controls =====

To move a control or a group of controls first select them. Then move the cursor inside the selection frame, press and hold the mouse button, drag the mouse pointer to a new location and release the mouse. Also, when one or more controls are selected, it is possible to use the cursor keys to move the selection in small steps (corresponding to the '''Grid''' settings).

===== Arranging Controls =====

To arrange a group of controls first select the group. Then click an appropriate button in the '''Layout''' toolbar or a menu item in the '''Layout''' menu of the IDE menu (or in the pop-up menu).

[[Image:Ide_Layout.png|center|frame|'''The Layout Toolbar''']]

The '''Layout''' commands for justifying and resizing controls:

{|{{prettytable}}
|-
| [[Image:Ide_Layout_AllignLeft.png]]
| '''Align Left'''
| Align the selected controls along their left sides.
|-
| [[Image:Ide_Layout_CenterVertically.png]]
| '''Align Center'''
| Center the selected controls vertically.
|-
| [[Image:Ide_Layout_AllignRight.png]]
| '''Align Right'''
| Align the selected controls along their right sides.
|-
| [[Image:Ide_Layout_AllignTops.png]]
| '''Align Top'''
| Align the selected controls along their tops.
|-
| [[Image:Ide_Layout_CenterHorizontally.png]]
| '''Align Middle'''
| Center the selected controls horizontally.
|-
| [[Image:Ide_Layout_AllignBottom.png]]
| '''Align Bottom'''
| Align the selected controls along their bottoms.
|-
| [[Image:Ide_Layout_SpacingHorizontally.png]]
| '''Even Horizontal Spacing'''
| Spacing the selected controls evenly between the leftmost and the rightmost controls.
|-
| [[Image:Ide_GridButton.png]]
| '''Grid'''
| Toggle the Grid (see below).
|-
| [[Image:Ide_Layout_SpacingVertically.png]]
| '''Even Vertical Spacing'''
| Spacing the selected controls evenly between the topmost and the bottom-most controls.
|-
| [[Image:Ide_Layout_SameSize.png]]
| '''Make Same Size'''
| Make the selected controls the same size as a model control.
|-
| [[Image:Ide_Layout_SameHorizontal.png]]
| '''Make Same Horizontal Size'''
| Make the selected controls the same width as a model control.
|-
| [[Image:Ide_Layout_SameVertical.png]]
| '''Make Same Vertical Size'''
| Make the selected controls the same height as a model control.
|-
|
| '''Size To Contents'''
| Resize the selected controls to optimally display its titles (caption texts).
|}

==== Editing Properties of GUI Controls ====

When you open a GUI dialog or a Form (GUI window) in the '''IDE Designer''', then near from the opened dialog (form) the {{ide|Resource Editor#GUI Control Properties Table|'''Control Properties table'''}} appears.

To change ''properties'' of a GUI package control first select this control (by clicking in it) in the dialog (form). The current set of the control properties appears in the '''Control Properties''' table. Now you can edit the displayed GUI control properties.

'''Click here to view {{ide|Resource Editor#GUI Control Properties Table|GUI Control Properties table}}'''

The displayed set of properties depends on the control type. The {{ide|Resource Editor#GUI Control Properties Table|'''Control Properties table'''}} contains two types of properties. General properties are common to all types of controls and some properties, which are individual to different kinds of controls.

Initially this '''Control Properties''' table is empty. However, as soon as one of controls in the edited dialog (form) is selected this table starts to display properties of the selected control.

If the '''Control Properties''' table is closed, then double-click a control - the '''Control Properties''' table appears. Also the '''Control Attributes''' command, from the '''IDE Designer''' {{ide|Resource Editor#Speed Menu|speed menu}}, can be used to open the '''Control Properties''' table.
{{:ide/Resource Editor/GUI Control Properties Table}}

==== Editing Attributes of VPI Controls ====

To change attributes of a VPI package control double-click it or select the control and activates the '''Control Attributes''' command from the '''IDE Designer''' {{ide|Resource Editor#Speed Menu|speed menu}}. Then the '''''<ControlType>'' Attributes''' dialog appears.

These dialogs contains two levels of attributes. The general group contains attributes, which are common to all types of controls: the '''Text''' determines the control title, the '''Constant''' (name) is used as the control identifier, and the '''Control Size''' group determines position and size of the control.

Notice that the '''Text''' property/attribute is not used for some controls, for instance, it is not used for scroll bars.

Notice that in the '''Text''' fields the ampersand symbol <vp>&</vp> is reserved for indicating that the next to it character is to be underlined. For example, if you use the text string '''E&xit''' as a control name, then this control will be displayed with the title '''Exit''' at runtime. I.e. the char '''x''' will be displayed underlined (thus visually indicating that the '''x''' is an accelerator key). If you need to display the ampersand <vp>&</vp> symbol in the '''Text''' of a control, then use two of them <vp>&&</vp>.

Other attributes are individual to different kinds of controls.

==== Using Anchors for Positioning GUI Controls while Dialog Resizing ====

VPI controls remember in their attributes ({{ide|Resource Editor#Attributes of VPI Controls|'''Attributes of VPI Controls'''}}) only their absolute positions and sizes. Therefore, when a VPI dialog or a VPI window containing such VPI controls are resized, these VPI controls do not change their positions and sizes!

In difference to them GUI controls have additional ''Anchor'' properties, which help to reposition (and may be resize) GUI controls when containing them GUI dialog (or form) is resized.

Each GUI control has four anchor properties: '''Left Anchor''', '''Top Anchor''', '''Right Anchor''', and '''Bottom Anchor''' (see {{ide|Resource Editor#GUI Control Properties Table|'''Anchor Properties of GUI Controls'''}}).

Each anchor determines that the specified ('''Left''', '''Top''', '''Right''' or '''Bottom''') control boundary should be '''always''' positioned on the stated distance from the nearest (correspondent) border of the dialog (frame).

Each of anchors can have the '''True''' or '''False''' values. When the anchor value is '''True''', then this anchor is active (used to position the correspondent control).

For example, when the '''Left Anchor''' is active (has the '''True''' value), then the ''left'' control boundary should be positioned on the stated distance from the nearest (''left'') border of the dialog (frame).

The simplest way to see which anchors are active for a control, is to select this control. Then some red arrows between control boundaries and correspondent boundaries of the dialog can bee seen. Each arrow specifies, that the correspondent anchor is active. For example, the arrow from the control top to the dialog top identifies, that the '''Top Anchor''' is active. In the picture below, you see three arrows, which specify that the '''Left''', '''Top''', and '''Right''' anchors are active to the '''Push Button''' control.

[[Image:Ide_de_Anchors.png|center]]

Numbers near such arrows show distances (in Dialog Base Units) between the correspondent boundaries of the control and the dialog.

Normally each control has one active horizontal and one active vertical anchors. When the dialog is resized, then such control is always positioned on the specified distances from the specified boundaries of the dialog. The size of the control is not changed!

When a control has both horizontal (or/and both vertical) anchors active, then both horizontal (or/and both vertical) boundaries of the control should be placed on some specified distances from the correspondent horizontal (vertical) boundaries of the dialog. Therefore, when the dialog is resized, then such control is also resized accordingly to keep the specified distances.

When no one of horizontal (or vertical) anchors of a control are active, then no one of horizontal (or vertical) boundaries of the control are bounded to the correspondent horizontal (vertical) boundaries of the dialog. Coordinates of such controls are handles on the "proportional basis". For example, when the dialog width is increased onto <vp>Delta</vp> dialog base units, then the <vp>X</vp> coordinate of the control is also increased, but it is increased two times smaller. That is the <vp>X</vp> coordinate of the control is increased only onto <vp>Delta/2</vp> dialog base units.

==== Cut, Copy and Paste, Undo and Redo ====

You can '''Cut''' or '''Copy''' a group of selected controls onto the Windows clipboard, and '''Paste''' controls from the clipboard back into a dialog. The '''Undo''' and '''Redo''' commands serve to delete or restore the last editing operations of your dialog.

==== Grid ====

When the menu (or the pop-up menu) entry '''Resource | Grid''' is activated, or when the [[Image:Ide_GridButton.png]] button from the '''Layout''' toolbar is pressed, the following dialog appears:

[[Image:Ide_GridSpecification.png|center|frame|'''The Dialog to Specify the Grid Properties''']]

With a grid in place, arranging the controls inside a dialog is easier. Also it is possible to tell the {{ide|Resource Editor#IDE Designer|'''IDE Designer'''}} by the '''Snap to Grid''' that it should place controls at the grid intersections to give a satisfactory result.

[[Image:Ide_MyDialog_withGrid.png|center|frame|'''Using a grid in the Dialog/Window/Form Editor''']]

==== Test Mode ====

The {{ide|Resource Editor#IDE Designer|'''IDE Designer'''}} has the '''Test Mode''', so it is possible to see how the dialog with the created controls behaves. To illustrate the '''Test Mode''' we will assign some default values to the controls. The test mode is activated and deactivated from the '''Resource''' menu (or from the pop-up menu).

[[Image:Ide_MyDialog_TestMode.png|center|frame|'''Test Mode for a Dialog''']]

==== Tab Stops ====

When activating the menu (or the pop-up menu) entry '''Resource | Tabstops''', it is possible to specify to which controls you can Tab to in the dialog. When this command is activated a small button with the <vp>+</vp> or <vp>-</vp> appears on controls depending upon whether the control has a tab stop or not. By clicking the small buttons, it is possible to toggle the setting.

[[Image:Ide_MyDialog_TabStops.png|center|frame|'''Specifying Tab Stops for a Dialog''']]

To exit the tab stop mode, just click in the dialog but outside of any controls.

==== Visit Order ====

When the tab stops have been specified for a dialog, then it is possible to specify the order in which controls will receive focus when tabbing.

[[Image:Ide_MyDialog_VisitOrder.png|center|frame|'''Displaying the Visit Order''']]

To change the visit order, click a small rectangle displaying the visit order number for a control that has an incorrect sequence number and this will bring up another dialog to change this sequence:

[[Image:Ide_MyDialog_ChangeVisitOrder.png|center|frame|'''Changing the Visit Order''']]

To stop the visit order mode, just click in the dialog outside any controls.

==== Speed Menu ====

When you are in the {{ide|Resource Editor#IDE Designer|'''IDE Designer'''}} you can click the right mouse button to activate the Speed Menu. From this menu you can easily call any {{ide|Resource Editor#IDE Designer|'''IDE Designer'''}} command:

[[Image:Ide_We_SpeedMenu.png|center|frame|'''The IDE Designer Speed Menu''']]

Ide/Creating new Project Items/Creating a COM Package

2013-05-23T09:22:51Z

SergeMukhin: /* Options */

<noinclude>[[Category:Ide]]</noinclude>
'''How to Import an Existing COM Component'''
=== Terminology Used in COM ===

The Component Object Model (COM) is a way for software components to communicate with each other. It is a binary standard that allows any two components to communicate regardless of what machine they are running on (as long as the machines are connected), what operating systems the machines are running (as long as they support COM), and what language the components are written in. COM provides location transparency: it does not matter whether components are in DLLs or in EXEs. COM components are binary units of code that include packaging and registration code and that create COM objects. Each COM component, in the COM programming model, is a programming structure encapsulating both data and functionality. It is defined and allocated as a single unit and the only public access to the COM data and functionality is through the programming interfaces.

Each COM is simply a program module: a DLL or an EXE file. It can contain one or more COM ''components''. (In Microsoft MSDN terminology ''components'' are ''coclasses''.) Each component knows about several interfaces. (In MSDN terminology - each component can support several interfaces.) Each component supports the default interface '''iUnknown'''. Using the '''iUnknown::queryInterface/2->''' predicate from the '''iUnknown''' interface, one can retrieve references to all interfaces known to a component. Each interface can provide several predicates (methods).

The main aim of importing a COM component into your project is using predicates defined in this COM component. Therefore, the COM package generated for an imported COM component has to provide some wrapper (glue code) to methods implemented in the COM component. That is, the generated COM package must provide declarations of correspondent interfaces, predicates, and domains.

=== How to Create a New COM Package ===

To create a COM package providing the interface (wrapper) to some COM component, you should activate the '''File | New''' IDE command. Then in the left pane of the opened '''Create Project Item''' dialog you should select '''COM Package'''. Then the dialog accepts the following shape:

[[Image:Ide_How_COMPackage.png|center|frame|Creating '''New COM Package''' Dialog]]

After you fill in all required COM package settings, you can press the '''Create''' button. Then the IDE creates the package subdirectory, the package header file (<vp>XML.ph</vp> for the above picture), and the package implementation file (<vp>XML.pack</vp> for the above picture). They appear in the project tree in the Project Window after the created package is compiled.

=== Options ===

'''Name:'''
:In the '''Name''' edit control you should type in the name (<vp>XML</vp> on the picture) of the COM package (wrapping package) being created.

'''Parent Directory'''
:In the '''Parent Directory''' you should type in or select (using the '''Browse''' button) the ''parent directory'' for the package. The package will be placed into the subdirectory of this ''parent directory''. If you specify a non-existing name, then this directory will be created. By default, '''Parent Directory''' displays the directory selected in the project tree when you activate this dialog. If this directory is one of the project subdirectories, then its path is displayed relatively to the project root directory. If '''Parent Directory''' is empty, than it is equal to the project root directory.
:In the '''Parent Directory''' the IDE creates the new subdirectory with the name correspondent to the specified package name. (It is <vp>XML</vp> for the above picture.). The package will be placed into this subdirectory.

'''Source''' Group Box

Controls in this group box are used to specify a COM module ('''DLL''' or '''EXE''') from which a component should be imported. It contains the following controls:

*'''Type Library'''
*:When this option is checked ON, then in the edit control you should specify a file that contains the ''type library'' describing the COM component.
*:Press the '''Load''' button to activate the '''Load Type Library File''' dialog using which you can find and insert the name of the type library file into the edit control.
*: '''Attention!''' Notice that you '''HAVE to''' press the '''Load''' button to enforce the IDE to load the COM information from the specified type library even if you directly type in the type library filename into the edit control.
*: If a COM client (our program importing COM server components) needs using COM server predicates, then the client application must have information about predicates in COM server components. Predicates often return values and accept parameters. The COM client requires declarations of all these predicates (and domains) in order to use them. This information can be made known in several ways. The Microsoft recommended way is to create a type library. (Remember that type libraries do not provide Prolog declarations.) Type library information can be stored in files with the following filename extensions: '''.tlb''' (type library itself), '''.olb''' (multiple type libraries or foreign object libraries), '''.dll''' (COM DLLs can embed type library resources), '''.exe''' (COM EXEs can embed type library resources), '''.ocx''' (ActiveX controls).

*'''TypeLib ID'''
*:When this option is checked ON, then in the edit control you should specify the '''TypeLib ID''' of the ''type library'' for the COM component that you wish to import. The '''TypeLib ID''' is a universally unique identifier (UUID) under which the type library is registered in the Windows system registry. (See '''CLSID''' for more information.) The '''TypeLib ID''' should be specified as a string of hexadecimal numbers with the following format:
*: <vipbnf>{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}</vipbnf>
*:Then you '''MUST''' press the '''Load''' button to enforce the IDE to load COM information from the type library registered with this '''TypeLib ID'''.
*:In the system registry database you can find all registered '''TypeLib ID'''s under:
*:'''<vipbnf>HKEY_CLASSES_ROOT\TypeLib = {TypeLib ID}</vipbnf>'''

*'''CLSID'''
*:When this option is checked ON, then in the edit control you should specify the '''CLSID''' of the COM component that you wish to import. The '''CLSID''' should be specified as a string of hexadecimal numbers with the following format:
*:<vipbnf>{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}</vipbnf>
*:Then you '''MUST''' press the '''Load''' button to enforce the IDE to load COM information from the COM module that embeds the COM component with the specified '''CLSID'''.
*: '''Note.''' Really a COM module can embed several COM components. If you wish to import one of these COM components, then you can specify a CLSID registered to any COM component in this COM module. (Later you will be able to specify the required COM component (or interface) in the list box.
*: In MSDN terminology, '''CLSID''' is a class identifier. In the Visual Prolog PFC terminology (see the COM package description in the PFC) '''CLSID''' is a COM component identifier.
*:'''CLSID''' is a universally unique identifier (UUID) that identifies the type of a COM component. Each COM component has its '''CLSID''' in the Windows system registry database so that it can be loaded and used by other applications. For example, a spreadsheet can create worksheet components, chart components, and macrosheet components. Each of these components has its own '''CLSID''' that uniquely identifies this component to the system. That is, if your COM module (COM server or COM container) allows linking to its embedded components, then you need to register the special '''CLSID''' for each COM component embedded into the COM module.
*:The '''CLSID''' is stored in the Windows registry database under the following registry key:
*:'''<vipbnf>HKEY_LOCAL_MACHINE\SOFTWARE\Classes\CLSID = {CLSID}</vipbnf>'''
*:The '''CLSID''' is a 128-bit number (in the hexadecimal format) within a pair of curly braces. Typically, '''CLSID'''s (and other UUID values) are represented as strings of hexadecimal numbers with the following format:
*:<vipbnf>{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}</vipbnf>
*:For example,
*:<vipbnf>{4208fb66-e22a-11d1-a7d7-00a0c982c00d}</vipbnf>
*:You can use the '''UUIDGEN.exe''' tool to create a new UUID.
*:When you find a '''CLSID''' you can find the associated '''PROGID''' under the following registry sub-key:
*:'''<vipbnf>HKEY_LOCAL_MACHINE\SOFTWARE\Classes\CLSID\{CLSID}\ProgID = <programatic identifier></vipbnf>'''
*:See the '''PROGID''' options description below.
*: '''Universally unique identifier (UUID)'''
*: The universally unique identifier (UUID) is also known as the globally unique identifier (GUID). The UUID, or GUID, is a unique, 128-bit value used to identify objects. Objects can be OLE servers, interfaces, client objects, etc. Beginning from this moment objects will be identified with UUIDs.

*'''PROGID'''
*:When this option is checked ON. In the edit control you should specify the '''PROGID''' of the COM module from which you wish to import the COM component. The '''PROGID''' should be specified as a string of the following format:
*:'''<Program>.<Component>.<Version>'''
*: Words are separated by dots as in <vp>Word.Document.6</vp>. (Blank spaces cannot be used.)
*:Then you '''MUST''' press the '''Load''' button to enforce the IDE to load COM information from the COM module registered with this '''PROGID'''.
*:'''PROGID'''s are versioned programmatic identifiers. '''PROGID'''s present human-readable versions of class identifiers ('''CLSID''') used to identify COM components. '''PROGID''' is a registry entry that can be associated with '''CLSID'''. Like '''CLSID''', '''PROGID''' identifies a COM component but with less precision because it is not guaranteed to be globally unique. The ''<vp>Version</vp>'' portion is optional but strongly recommended. Using ''<vp>Version</vp>'', even if there is only one version of the '''PROGID''', helps to avoid conflicts. It enables different versions of a component coexist without overwriting '''PROGID'''s. If you do not specify a version for a '''PROGID''', the default ''<vp>Version</vp>'' <vp>= 1</vp>.
*:How to find '''PROGID''' entries in the registry is described in the '''CLSID'''.

*'''IID'''
*:When this option is checked ON, then in the edit control you should specify the '''IID''' of the COM component interface that you wish to import.
*:'''IID''' is a universally unique identifier (UUID) that uniquely identifies a particular COM interface. '''IID''' should be specified as a string of hexadecimal numbers with the following format:
*:<vipbnf>{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}</vipbnf>
*:Then you '''MUST''' press the '''Load''' button to enforce the IDE to load COM information from the COM module that embeds the interface with the specified '''IID'''.
*:Really you can specify an '''IID''' registered to any interface embedded into the same COM module that embeds the interface you wish to import. (Later you will be able to specify the required COM component (or interface) in the list box.
*:In the system registry database you can find all registered '''IID'''s under:
*:'''<vipbnf>HKEY_LOCAL_MACHINE\SOFTWARE\Classes\Interface</vipbnf>'''

Ide/Creating new Project Items/Creating a COM Package

2013-05-23T09:18:59Z

SergeMukhin: /* Options */

<noinclude>[[Category:Ide]]</noinclude>
'''How to Import an Existing COM Component'''
=== Terminology Used in COM ===

The Component Object Model (COM) is a way for software components to communicate with each other. It is a binary standard that allows any two components to communicate regardless of what machine they are running on (as long as the machines are connected), what operating systems the machines are running (as long as they support COM), and what language the components are written in. COM provides location transparency: it does not matter whether components are in DLLs or in EXEs. COM components are binary units of code that include packaging and registration code and that create COM objects. Each COM component, in the COM programming model, is a programming structure encapsulating both data and functionality. It is defined and allocated as a single unit and the only public access to the COM data and functionality is through the programming interfaces.

Each COM is simply a program module: a DLL or an EXE file. It can contain one or more COM ''components''. (In Microsoft MSDN terminology ''components'' are ''coclasses''.) Each component knows about several interfaces. (In MSDN terminology - each component can support several interfaces.) Each component supports the default interface '''iUnknown'''. Using the '''iUnknown::queryInterface/2->''' predicate from the '''iUnknown''' interface, one can retrieve references to all interfaces known to a component. Each interface can provide several predicates (methods).

The main aim of importing a COM component into your project is using predicates defined in this COM component. Therefore, the COM package generated for an imported COM component has to provide some wrapper (glue code) to methods implemented in the COM component. That is, the generated COM package must provide declarations of correspondent interfaces, predicates, and domains.

=== How to Create a New COM Package ===

To create a COM package providing the interface (wrapper) to some COM component, you should activate the '''File | New''' IDE command. Then in the left pane of the opened '''Create Project Item''' dialog you should select '''COM Package'''. Then the dialog accepts the following shape:

[[Image:Ide_How_COMPackage.png|center|frame|Creating '''New COM Package''' Dialog]]

After you fill in all required COM package settings, you can press the '''Create''' button. Then the IDE creates the package subdirectory, the package header file (<vp>XML.ph</vp> for the above picture), and the package implementation file (<vp>XML.pack</vp> for the above picture). They appear in the project tree in the Project Window after the created package is compiled.

=== Options ===

'''Name:'''
:In the '''Name''' edit control you should type in the name (<vp>XML</vp> on the picture) of the COM package (wrapping package) being created.

'''Parent Directory'''
:In the '''Parent Directory''' you should type in or select (using the '''Browse''' button) the ''parent directory'' for the package. The package will be placed into the subdirectory of this ''parent directory''. If you specify a non-existing name, then this directory will be created. By default, '''Parent Directory''' displays the directory selected in the project tree when you activate this dialog. If this directory is one of the project subdirectories, then its path is displayed relatively to the project root directory. If '''Parent Directory''' is empty, than it is equal to the project root directory.
:In the '''Parent Directory''' the IDE creates the new subdirectory with the name correspondent to the specified package name. (It is <vp>XML</vp> for the above picture.). The package will be placed into this subdirectory.

'''Source''' Group Box

Controls in this group box are used to specify a COM module ('''DLL''' or '''EXE''') from which a component should be imported. It contains the following controls:

*'''Type Library'''
*:When this option is checked ON, then in the edit control you should specify a file that contains the ''type library'' describing the COM component.
*:Press the '''Load''' button to activate the '''Load Type Library File''' dialog using which you can find and insert the name of the type library file into the edit control.
*: '''Attention!''' Notice that you '''HAVE to''' press the '''Load''' button to enforce the IDE to load the COM information from the specified type library even if you directly type in the type library filename into the edit control.
*: If a COM client (our program importing COM server components) needs using COM server predicates, then the client application must have information about predicates in COM server components. Predicates often return values and accept parameters. The COM client requires declarations of all these predicates (and domains) in order to use them. This information can be made known in several ways. The Microsoft recommended way is to create a type library. (Remember that type libraries do not provide Prolog declarations.) Type library information can be stored in files with the following filename extensions: '''.tlb''' (type library itself), '''.olb''' (multiple type libraries or foreign object libraries), '''.dll''' (COM DLLs can embed type library resources), '''.exe''' (COM EXEs can embed type library resources), '''.ocx''' (ActiveX controls).

*'''TypeLib ID'''
*:When this option is checked ON, then in the edit control you should specify the '''TypeLib ID''' of the ''type library'' for the COM component that you wish to import. The '''TypeLib ID''' is a universally unique identifier (UUID) under which the type library is registered in the Windows system registry. (See '''CLSID''' for more information.) The '''TypeLib ID''' should be specified as a string of hexadecimal numbers with the following format:
*: <vipbnf>{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}</vipbnf>
*:Then you '''MUST''' press the '''Load''' button to enforce the IDE to load COM information from the type library registered with this '''TypeLib ID'''.
*:In the system registry database you can find all registered '''TypeLib ID'''s under:
*:'''<vipbnf>HKEY_CLASSES_ROOT\TypeLib = {TypeLib ID}</vipbnf>'''

*'''CLSID'''
*:When this option is checked ON, then in the edit control you should specify the '''CLSID''' of the COM component that you wish to import. The '''CLSID''' should be specified as a string of hexadecimal numbers with the following format:
*:<vipbnf>{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}</vipbnf>
*:Then you '''MUST''' press the '''Load''' button to enforce the IDE to load COM information from the COM module that embeds the COM component with the specified '''CLSID'''.
*: '''Note.''' Really a COM module can embed several COM components. If you wish to import one of these COM components, then you can specify a CLSID registered to any COM component in this COM module. (Later you will be able to specify the required COM component (or interface) in the list box in the '''Import''' group box.)
*: In MSDN terminology, '''CLSID''' is a class identifier. In the Visual Prolog PFC terminology (see the COM package description in the PFC) '''CLSID''' is a COM component identifier.
*:'''CLSID''' is a universally unique identifier (UUID) that identifies the type of a COM component. Each COM component has its '''CLSID''' in the Windows system registry database so that it can be loaded and used by other applications. For example, a spreadsheet can create worksheet components, chart components, and macrosheet components. Each of these components has its own '''CLSID''' that uniquely identifies this component to the system. That is, if your COM module (COM server or COM container) allows linking to its embedded components, then you need to register the special '''CLSID''' for each COM component embedded into the COM module.
*:The '''CLSID''' is stored in the Windows registry database under the following registry key:
*:'''<vipbnf>HKEY_LOCAL_MACHINE\SOFTWARE\Classes\CLSID = {CLSID}</vipbnf>'''
*:The '''CLSID''' is a 128-bit number (in the hexadecimal format) within a pair of curly braces. Typically, '''CLSID'''s (and other UUID values) are represented as strings of hexadecimal numbers with the following format:
*:<vipbnf>{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}</vipbnf>
*:For example,
*:<vipbnf>{4208fb66-e22a-11d1-a7d7-00a0c982c00d}</vipbnf>
*:You can use the '''UUIDGEN.exe''' tool to create a new UUID.
*:When you find a '''CLSID''' you can find the associated '''PROGID''' under the following registry sub-key:
*:'''<vipbnf>HKEY_LOCAL_MACHINE\SOFTWARE\Classes\CLSID\{CLSID}\ProgID = <programatic identifier></vipbnf>'''
*:See the '''PROGID''' options description below.
*: '''Universally unique identifier (UUID)'''
*: The universally unique identifier (UUID) is also known as the globally unique identifier (GUID). The UUID, or GUID, is a unique, 128-bit value used to identify objects. Objects can be OLE servers, interfaces, client objects, etc. Beginning from this moment objects will be identified with UUIDs.

*'''PROGID'''
*:When this option is checked ON. In the edit control you should specify the '''PROGID''' of the COM module from which you wish to import the COM component. The '''PROGID''' should be specified as a string of the following format:
*:'''<Program>.<Component>.<Version>'''
*: Words are separated by dots as in <vp>Word.Document.6</vp>. (Blank spaces cannot be used.)
*:Then you '''MUST''' press the '''Load''' button to enforce the IDE to load COM information from the COM module registered with this '''PROGID'''.
*:'''PROGID'''s are versioned programmatic identifiers. '''PROGID'''s present human-readable versions of class identifiers ('''CLSID''') used to identify COM components. '''PROGID''' is a registry entry that can be associated with '''CLSID'''. Like '''CLSID''', '''PROGID''' identifies a COM component but with less precision because it is not guaranteed to be globally unique. The ''<vp>Version</vp>'' portion is optional but strongly recommended. Using ''<vp>Version</vp>'', even if there is only one version of the '''PROGID''', helps to avoid conflicts. It enables different versions of a component coexist without overwriting '''PROGID'''s. If you do not specify a version for a '''PROGID''', the default ''<vp>Version</vp>'' <vp>= 1</vp>.
*:How to find '''PROGID''' entries in the registry is described in the '''CLSID'''.

*'''IID'''
*:When this option is checked ON, then in the edit control you should specify the '''IID''' of the COM component interface that you wish to import.
*:'''IID''' is a universally unique identifier (UUID) that uniquely identifies a particular COM interface. '''IID''' should be specified as a string of hexadecimal numbers with the following format:
*:<vipbnf>{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}</vipbnf>
*:Then you '''MUST''' press the '''Load''' button to enforce the IDE to load COM information from the COM module that embeds the interface with the specified '''IID'''.
*:Really you can specify an '''IID''' registered to any interface embedded into the same COM module that embeds the interface you wish to import. (Later you will be able to specify the required COM component (or interface) in the list box.
*:In the system registry database you can find all registered '''IID'''s under:
*:'''<vipbnf>HKEY_LOCAL_MACHINE\SOFTWARE\Classes\Interface</vipbnf>'''

Ide/Key Bindings

2013-05-07T07:51:34Z

SergeMukhin: fix Ctrl+K, need F6...

{{ideNavbar|Key Bindings}}

A number of Visual Prolog menu entries have accelerator keys (hot keys) associated with them.

Beginning with Visual Prolog 7.0 some key binding have been changed to comply with Microsoft de facto standards.
The table below shows Visual Prolog 7.2 accelerator keys by functions.

:{| {{prettytable}}
|- class="header2"
|align="center" style="background:#cee0f2; text-align:center; font-weight:bold; color: #006B9C;" |
Function
|align="center" style="background:#cee0f2; text-align:center; font-weight:bold; color: #006B9C;" |
Key
|-
|colspan="2" align="center" style="background:#cee0f2; text-align:center; font-weight:bold; color: #006B9C;" |
Edit
|-
| Copy
| Ctrl-C
|-
| Cut
| Ctrl-X
|-
| Paste
| Ctrl-V
|-
| Paste
| Ctrl-Ins
|-
| Undo
| Ctrl-Z
|-
| Redo
| Ctrl-Y
|-
| Redo
| Ctrl-Shift-Z
|-
| Select All
| Ctrl-A
|-
| Select Current Word
| Ctrl-W
|-
| Box Editor: Size To Content
| Shift-F6
|-
| Code Expert
| Ctrl+Shift+W
|-
| Delete Line
| Ctrl-Shift-L
|-
| Delete to End of Line
| Ctrl-Shift-E
|-
| Word Delete To End
Delete Object from Facts Tree
Retract Fact(s)
| Ctrl-Del
|-
| Insert Predicate
| Ctrl-Shift-I
|-
| Replace
| Ctrl-H
|-
| Lower Case
| Ctrl-U
|-
| Upper Case
| Ctrl-Shift-U
|-
| Toggle Case
| Ctrl-Alt-U
|-
| Zoom In
| Ctrl-[+] or Ctrl-Scroll mouse wheel up
|-
| Zoom Out
| Ctrl-[-] or Ctrl-Scroll mouse wheel down
|-
| Zoom to Normal
| Ctrl-0
|-
| Comment Line(s)
| Ctrl-Alt-5
|-
| Uncomment Line(s)
| Ctrl-Alt-Shift-5
|-
| Insert Date Stamp
| Ctrl-Shift-Y
|-
|colspan="2" align="center" style="background:#cee0f2; text-align:center; font-weight:bold; color: #006B9C;" |
Navigation
|-
| Find
| Ctrl-F
|-
| Find in Files
| Ctrl-Shift-F
|-
| Find Next
| F3
|-
| Locate in Project Tree
| Ctrl-T
|-
| View Current Position
| Shift-F4
|-
| Go Back
| Ctrl+Shift+F8
|-
| Go to Address
| Ctrl-G
|-
| Go to Definition
| F12
Ctrl-Shift-C
|-
| Go To Declaration
| Ctrl-F12
Ctrl-Shift-D
|-
| Go To Definition
|
|-
| Go to Executing Predicate Source
| Ctrl-E
|-
| Go To Facts Database
| Ctrl+Alt+F
|-
| Go To Line
| Ctrl-F2
|-
| Go To Next Error
| F8
|-
| Go To Position on Clipboard
| Shift-F2
|-
| Go To Previous Error
| Shift-F8
|-
| Window Navigation Dialog
| Ctrl-Tab or Ctrl-F6
|-
| Set/Remove bookmark
| Ctrl-K
|-
|colspan="2" align="center" style="background:#cee0f2; text-align:center; font-weight:bold; color: #006B9C;" |
Compile
|-
| Build
| Ctrl-Shift-B
|-
| Stop Build
| Ctrl-Break
|-
| Build Resource Only
| Alt-F8
|-
| Compile
| Ctrl-F7
|-
| Rebuild Project
| Ctrl-Shift-Alt-B
|-
| Run
| Ctrl-F5
|-
| Run in Window
| Alt-F5
|-
| Locate in Project Tree
| Ctrl-T
|-
|colspan="2" align="center" style="background:#cee0f2; text-align:center; font-weight:bold; color: #006B9C;" |
Debug
|-
| Start Debugging
| F5
|-
| Stop Debugging
| Shift-F5
|-
| Breakpoint Properties
| Alt-F9
|-
| Refresh Debug Window
| Ctrl-R
|-
| Registers window
| Ctrl-Alt-G
|-
| Breakpoints Window
| Ctrl-Alt-B
|-
| CallStack Window
| Ctrl-Alt-C
|-
| Disassembly Window
| Ctrl-Alt-D
|-
| Variable window
| Ctrl-Alt-V
|-
| Memory Dump 1 Window
| Ctrl-Alt-M
|-
| Threads Window
| Ctrl-Alt-H
|-
| Enable Breakpoint
| Ctrl-F9
|-
| Toggle Breakpoint
| F9
|-
| Step Into
| F11
|-
| Step out of
| Shift-F11
|-
| Step Over
| F10
|-
| Run To Cursor
| Ctrl-F10
|-
|colspan="2" align="center" style="background:#cee0f2; text-align:center; font-weight:bold; color: #006B9C;" |
Project
|-
| New Project
| Ctrl-Shift-N
|-
| Open Project
| Ctrl-Shift-O
|-
| Add Module to Project
| Ctrl-Shift-A
|-
| Create Project Item
| Ctrl-N
|-
|colspan="2" align="center" style="background:#cee0f2; text-align:center; font-weight:bold; color: #006B9C;" |
IDE
|-
| "Qualification…" Dialog
| Ctrl-Shift-S
|-
| Close all Editors
| Ctrl+Q
|-
| Close all Inactive Editors
| Ctrl+Shift+Q
|-
| Close the active window
| Ctrl-F4
|-
| Project window
| Ctrl-Alt-P
|-
| Project Settings
| Alt-F7
|-
| Save File
| F2
|-
| Save Project
| Ctrl-S
|-
| Source Browser
| Ctrl-B
|-
|colspan="2" align="center" style="background:#cee0f2; text-align:center; font-weight:bold; color: #006B9C;" |
Other
|-
| Help
| F1
|-
| Output
| Ctrl-Alt-O
|-
| Print
| Ctrl-P
|}

[[ru:IDE:Горячие Клавиши]]

Language Reference/Built-in entities/Predicates

2013-04-29T07:31:22Z

SergeMukhin: add link to Language_Reference/Terms#List_Comprehension

<noinclude>__NOTOC__</noinclude>

{|{{prettytable}}
|-
|[[#assert|assert/1]]
|Insert the specified fact at the end of the matched internal facts database.
|-
|[[#asserta|asserta/1]]
|Insert a fact at the beginning of the matched internal facts database.
|-
|[[#assertz|assertz/1]]
|Insert a fact at the end of the matched internal facts database.
|-
|[[#bound|bound/1]] <vp>determ</vp>
|Test whether the specified variable is bound to a value.
|-
|[[#class_name|class_name/0->]]
|This compile time predicate returns the string ''ClassName'' that represents the name of the current interface or class.
|-
|[[#compare|compare/2->]]
|Returns the result of the variables' comparison.
|-
|[[#convert|convert/2->]]
|Checked term conversion.
|-
|[[#digitsOf|digitsOf/1->]]
|Returns precision of the specified floating-point domain.
|-
|[[#errorExit|errorExit/1]] <vp>erroneous</vp>
|Performs a run-time error with the specified return code ''ErrorNumber'' and sets the internal error information.
|-
|[[#fail|fail/0]] <vp>failure</vp>
|Invoke backtracking.
|-
|[[#free|free/1]] <vp>determ</vp>
|Check whether a variable is free.
|-
|[[#fromEllipsis|fromEllipsis/1->]]
|Creates the list of terms of the universal type <vp>any</vp> from the ''EllipsisBlock''.
|-
|[[#hasDomain|hasDomain/2]]
|Checks whether the variable ''VariableName'' has the domain ''domainName''.
|-
|[[#isErroneous|isErroneous/1]] <vp>determ</vp>
|Returns the lower bound value of the specified numeric domain.
|-
|[[#lowerBound|lowerBound/1->]]
|Returns the lower bound value of the specified numeric domain.
|-
|[[#maxDigits|maxDigits/1->]]
|Retrieves the value of digits (precision) of the basic domain corresponding to the specified floating-point domain ''domainName''.
|-
|[[#not|not/1]] <vp>determ</vp>
|Negate the result (success/fail) of subgoal.
|-
|[[#predicate_fullname|predicate_fullname/1->]]
|This compile time predicate returns the string ''PredicateFullName'' that represent the name of the predicate in which clause body <vp>predicate_name</vp> is called. The returned predicate name is qualified with a scope name.
|-
|[[#predicate_name|predicate_name/1->]]
|This compile time predicate returns the string ''PredicateName'' that represent the name of the predicate in which clause body <vp>predicate_name</vp> is called. The returned predicate name is not qualified with a scope name.
|-
|[[#programPoint|programPoint/0->]]
|This compile time predicate returns the <vp>programPoint</vp> corresponding to the place where it is called.
|-
|[[#retract|retract/1]] <vp>nondeterm</vp>
|Remove a matched fact from the matched internal facts database.
|-
|[[#retractall|retractall/1]]
|Remove all matching facts from the matched internal facts database.
|-
|[[#retractFactDb|retractFactDb/1]]
|Remove all facts from the specified named internal facts database.
|-
|[[#sizeBitsOf|sizeBitsOf/1->]]
|Retrieves the number of bits occupied in memory by an entity of the specified domain ''DomainName''.
|-
|[[#sizeOf|sizeOf/1->]]
|Retrieves the number of bytes occupied in memory by the specified term.
|-
|[[#sizeOfDomain|sizeOfDomain/1->]]
|Retrieves the number of bytes occupied in memory by the entity of the specified domain ''DomainName''.
|-
|[[#sourcefile_lineno|sourcefile_lineno/0->]]
|Returns the current line number in the source file processed by the compiler .
|-
|[[#sourcefile_name|sourcefile_name/0->]]
|Returns the name of the source file processed by the compiler.
|-
|[[#sourcefile_timestamp|sourcefile_timestamp/0->]]
|Returns the string representing the date and time of the source file processed by the compiler.
|-
|[[#succeed|succeed/0]]
|The predicate <vp>succeed/0</vp> will always succeed.
|-
|[[#toAny|toAny/1->]]
|Converts the specified ''Term'' to the value of the universal term type <vp>any</vp>.
|-
|[[#toBinary|toBinary/1->]]
|Converts the specified Term to the binary representation.
|-
|[[#toBoolean|toBoolean/1->]]
|The purpose of this meta-predicate is to convert the deterministic call (to a predicate or fact) to the procedure that returns the value of <vp>boolean</vp> domain.
|-
|[[#toEllipsis|toEllipsis/1->]]
|Creates the ''EllipsisBlock'' from the list of <vp>any</vp> type values.
|-
|[[#toString|toString/1->]]
|Converts the specified ''Term'' to the string representation.
|-
|[[#toTerm|toTerm/1->]] [[#toTerm|toTerm/2->]]
|Converts the string/binary representation of the specified term ''SrcTerm'' into representation corresponding to the domain of ''PrologTerm'' variable of the return value.
|-
|[[#tryToTerm|tryToTerm/1->]] <vp>determ</vp> [[#tryToTerm|tryToTerm/2->]] <vp>determ</vp>
|Converts the string/binary representation of the specified term ''SrcTerm'' into representation corresponding to the domain of ''PrologTerm'' variable of the return value.
|-
|[[#tryConvert|tryConvert/2->]] <vp>determ</vp>
|Checks whether the input term ''InputTerm'' can be strictly converted into the specified domain ''returnDomain'' and returns the converted term ''ReturnTerm''.
|-
|[[#uncheckedConvert|uncheckedConvert/2->]]
|Unchecked conversion of domains.
|-
|[[#upperBound|upperBound/1->]]
|Returns the upper bound value of the specified numeric domain.
|}

The following predicates are deprecated:
{|{{prettytable}}
|-
| finally/2
| Use <vp>try ... finally ... end try</vp> instead.
|-
| findall/3
| Use list comprehension [[Language_Reference/Terms#List_Comprehension| <vp>[ ... || ... ]</vp>]] instead
|-
| trap/3 <vp>determ</vp>
| Use <vp>try ... catch V do ... end try</vp> instead
|}

==== assert ====

<vip>assert : (<fact-term> FactTerm).</vip>

Insert the specified fact at the end of the matched internal facts database

<vp>assert(Fact)</vp> inserts <vp>Fact</vp> in the matched internal facts database after any other stored facts for the corresponding database predicate. <vp>Fact</vp> must be a term belonging to the domain of an internal facts database. <vp>assert/1</vp> applied to a single fact changes the existing instance of a fact to the specified one. <vp>assert/1</vp> has the same effect as [[#assertz|assertz/1]]. See also [[#asserta|asserta/1]]

Notice that the combination of [[#retract|retract/1]] and <vp>assert/1</vp> like the following can lead to endless loop:

<vip>loop() :-
retract(fct(X)),
... % creating Y from X
assert(fct(Y)),
fail.</vip>

The problem is that the retract in first line will eventually retract the fact asserted in the last line, because that fact is inserted ''last'' in the fact chain.

Exceptions:

* Attempt to a fact declared as determ, but the fact instance already exists.

==== asserta ====

<vip>asserta : (<fact-term> FactTerm).</vip>

Insert a fact at the beginning of the matched internal facts database.

The <vp>asserta(Fact)</vp> predicate inserts a <vp>Fact</vp> in the matched internal facts database before any other stored facts for the corresponding predicate. The <vp>Fact</vp> must be a term belonging to the domain of an internal facts database. The <vp>asserta/1</vp> applied to a single fact changes the existing instance of a fact to the specified one. See also [[#assert|assert/1]] and [[#assertz|assertz/1]].

Exceptions:

* Attempt to a fact declared as determ, but the fact instance already exists.

==== assertz ====

<vip>assertz : (<fact-term> FactTerm).</vip>

<vp>assertz</vp> does exactly the same as the [[#assert|assert/1]] predicate.

==== bound ====

<vip>bound : (<variable> Variable) determ.</vip>

Test whether the specified variable is bound to a value.

The <vp>bound(Variable)</vp> succeeds if <vp>Variable</vp> is bound and fails if it is free. The <vp>bound</vp> predicate is used to control flow patterns and to check the binding of reference variables. The <vp>bound</vp> predicate treats the specified <vp>Variable</vp> as bound if any of it's part is instantiated.

See also [[#free|free/1]].

==== class_name ====

<vip>class_Name : () -> string ClassName.</vip>

This compile time predicate returns the string <vp>ClassName</vp> that represents the name of the current interface or class.

==== compare ====

<vip>compare : (A Left, A Right) -> compareResult CompareResult.</vip>

Comparison of two terms of the same domain, resturns the value of [[#compareResult|compareResult]] domain.

<vp>CompareResult</vp> = compare("<vp>bar</vp>", "<vp>foo</vp>")

==== convert ====

<vip>convert : (<type> Type, Term) -> <type> Converted.</vip>

Checked term conversion.

Call-template for this function is:

<vp>ReturnTerm</vp> = convert(returnDomain, <vp>InputTerm</vp>)

* <vpbnf>returnDomain</vpbnf>: Specifies a domain to which function <vp>convert/2-></vp> converts <vp>InputTerm</vp>. Here ''returnDomain'' must be a name of built-in Visual Prolog domain, an interface domain, a name of such user defined domain that is synonym to one of built-in Visual Prolog domains, a numeric domain, binary and pointer domains. The domain name ''returnDomain'' must be specified at compile-time, i.e. it cannot come from a variable.

* <vpbnf><InputTerm></vpbnf>: Specifies the value that must be converted. <vp>InputTerm</vp> may be any Prolog term or an expression. If <vp>InputTerm</vp> is an expression, then it will be evaluated before the conversion.

* <vpbnf><ReturnTerm></vpbnf>: Returned parameter <vp>ReturnTerm</vp> will be of ''returnDomain'' type.

The <vp>convert</vp> predicate performs a clean and genuine conversion of the given <vp>InputTerm</vp>, returning a new term <vp>ReturnTerm</vp> of the specified new domain ''returnDomain''. If <vp>convert</vp> cannot perform the required conversion, it rises errors. The similar functionality is provided by the [[#tryConvert|tryConvert/2->]] predicate, but <vp>tryConvert-></vp> fails and does not produce any runtime errors if it cannot perform the conversion.

===== Allowed conversions =====

* Between numerical domains.
* Between interface types.
* Between [[#string|string]] and [[#symbol|symbol]] domains.
* From [[#binary|binary]] to [[#pointer|pointer]].
* For synonyms of mentioned domains.
* Between [http://wiki.visual-prolog.com/index.php?title=How_To_Remove_Reference_Domains_from_a_Project reference] domains and corresponding non-reference domains.

The contrast to these is [[#uncheckedConvert|uncheckedConvert/2->]] predicate, which performs an unchecked conversion between terms from any domains, which have the same bit-size.

The <vp>convert/2-></vp> (or [[#tryConvert|tryConvert/2->]]) predicate accomplishes a checked explicit conversion, when the source and target domains are statically known during the compilation. The result of an explicit conversion can be one of the following:

* '''ok''' the successful conversion to the target domain;
* '''run-time-check''' the conversion to the target domain with generation of run-time checking for compatibility;
* '''error''' the conversion is impossible, error output.

===== Rules of Checked Explicit Conversions =====

* Synonyms of domains are converted using the same rules that are applied to the domains themselves.
* Numerical domains can be converted to the numerical domains only.
* Integral constants are the representatives of the anonymous integral domain: <vp>[const .. const]</vp>.
* Real constants are the representatives of the anonymous real domain: <vp>digits</vp> <vp>dig [const .. const]</vp>, where <vp>dig</vp> is the number of the digits in mantissa without insignificant zeroes.
* A value of the symbol domain can be converted to the string domain and vice versa.
* A value of binary domain can be converted to the pointer domain.
* The domains that are implicitly introduced for interfaces can be converted only to the interface domains according to the rules specified below.
* All other domains cannot be converted.

===== Conversions of Numerical Domains =====

* The range is considered first during such conversion. If the ranges of source and target do not intersect, then an error is produced. If the ranges of source and target only partially intersect, then run-time checking is generated. Also, if one of domains is real and another is an integral one, then the integer range is converted to the real range before the comparison.
* When input term in real and output is integer, then <vp>convert/2-></vp> and [[#tryConvert|tryConvert/2->]] predicates truncate the input value to the nearest integer value, which is nearer to zero.

===== Conversions of Interface Types =====

Predicate <vp>convert/2-></vp> allow to convert any object to any interface type. The actual correctness of such conversion is checked at runtime. When object is created, its type is internally stored, therefore when the object is passed as argument it still remember about its original type. This original type is used for checking allowed conversions. The example:

<vip>interface x
supports a, b
end interface x</vip>

If object is created by class, which implements <vp>x</vp> interface, and then object is passed as parameter of type <vp>a</vp> to some predicate, then it is allowed to convert the object to <vp>b</vp> type.

Exceptions:

* Check range error.
* Unsupported interface type.

==== digitsOf ====

<vip>digitsOf : (<real-domain> Domain) -> unsigned.</vip>

Returns precision of the specified floating-point domain.

Call-template for this function is:

<vip>Precision = digitsof(domainName)</vip>

The input parameter ''domainName'' of this compiling-time predicate is a floating-point domain, it should be explicitly specified at compile-time (that is, ''domainName'' cannot come from a variable). The predicate returns the number <vpbnf><Precision></vpbnf> that was determined by the <vp>digits</vp> attribute in the domain declaration.

The compiler guarantees that values of the domain ''domainName'' will have at least <vpbnf><Precision></vpbnf> number of significant decimal digits.

==== errorExit ====

<vip>errorExit : (unsigned ErrorNumber) erroneous.</vip>

Performs a run-time error with the specified return code <vp>ErrorNumber</vp>, which can be used in the [[#try-catch-finally|try-catch-finally]].

==== fail ====

<vip>fail : () failure.</vip>

The <vp>fail</vp> predicate forces failure and, hence, always causes backtracking. A clause that fails (with <vp>fail</vp> or for some other reason) cannot bind output arguments.

==== free ====

<vip>free : (<variableName> Variable) determ.</vip>

Check whether a variable is free.

Call-template for this predicate is:

<vip>free(Variable)</vip>

The <vp>free</vp> predicate succeeds if the specified <vp>Variable</vp> is free and fails if <vp>Variable</vp> is bound. The <vp>free</vp> predicate treats the specified <vp>Variable</vp> as bound if any of it's part are instantiated.

See also [[#bound|bound/1]].

==== fromEllipsis ====

<vip>fromEllipsis : (...) -> any* AnyTermList.</vip>

This predicate creates the list of terms of the universal type <vp>any</vp> from the ''EllipsisBlock'' '''...''' (i.e. from the special varying parameters block).

Call-template for this function is:

<vip>AnyTermList = fromEllipsis(EllipsisBlock )</vip>

See also [[#toEllipsis|toEllipsis/1->]].

==== hasDomain ====

<vip>hasDomain : (<type> Type, <variable> Variable) procedure.</vip>

<vp>hasDomain</vp> is not really a predicate, but more a declaration: It states that the variable <vp>Variable</vp> must have the type <vp>Type</vp>.

The variable can be free, bound or of some mixed flow. The binding of the variable is not changes in any way.

==== lowerBound ====

<vip>lowerBound : (<numeric-domain> NumericDomain) -> <numeric-domain> LowerBound.</vip>

Returns the lower bound of the specified <vp>NumericDomain</vp>.

Call-template for this function is:

<vip>LowerBoundValue = lowerBound(domainName)</vip>

The <vp>lowerBound</vp> is a compiling-time predicate. The <vp>lowerBound</vp> returns the lower bound value <vp>LowerBoundValue</vp> of the specified numeric domain ''domainName''. The return value <vp>LowerBoundValue</vp> belongs to the same domain ''domainName''. The ''domainName'' parameter should be the name of any numerical domain; this domain name should be explicitly specified at compile-time (that is, ''domainName'' cannot come from a variable). See also [[#upperBound|upperBound/1->]].

It will give a compile time error if the specified domain ''domainName'' is not numeric domain.

==== isErroneous ====

<vip>isErroneous : (<fact-variable> FactVariable) determ.</vip>

The predicate succeeds if the specified fact variable is <vp>erroneous</vp>.

Call-template for this predicate is:

<vip>isErroneous(factVariableName)</vip>

The predicate succeeds if the specified fact variable <vp>factVariableName</vp> has the <vp>erroneous</vp> value, otherwise it fails.

==== maxDigits ====

<vip>maxDigits : (<real-domain> RealDomain) -> unsigned MaxDigits</vip>

Retrieves the value of digits (precision) of the basic domain corresponding to the specified floating-point domain ''domainName''.

Call-template for this function is:

<vip>MaxDigitsNumber = maxdigits(domainName)</vip>

The return maximal number of digits <vp>MaxDigitsNumber</vp> for the ''domainName'' parameter, which should be the name of a <vp>real</vp> domain.

==== not ====

See [[Language_Reference/Terms#Not|term not]]

==== predicate_fullname ====

<vip>predicate_fullname : () -> string PredicateFullName.</vip>

This predicate returns the name <vp>PredicateFullName</vp> of the predicate in which it is invoked. The returned predicate name is qualified with a scope name.

<vp>predicate_fullname</vp> can only be used inside a clause. Use of <vp>predicate_fullname</vp> in other places causes a compile time error. See also [[#predicate_name|predicate_name]].

==== predicate_name ====

<vip>predicate_name : () -> string PredicateName.</vip>

This predicate returns the name <vp>PredicateName</vp> of the predicate in which it is invoked.

<vp>predicate_name</vp> can only be used inside a clause. Use of <vp>predicate_name</vp> in other places causes a compile time error. See also [[#predicate_fullname|predicate_fullname]]

==== programPoint ====

<vip>programPoint : () -> core::programPoint ProgramPoint.</vip>

This predicate returns the name <vp>programPoint</vp> corresponding to the place where it is invoked.

==== retract ====

<vip>retract : (<fact-term> FactTerm) nondeterm anyflow.</vip>

Successively removes the first matching fact from the facts database. Fails when no more facts match.

Call-template for this predicate is:

<vip>retract(FactTemplate)</vip>

Here <vp>FactTemplate</vp> should be a fact term. The <vp>retract/1</vp> predicate deletes the first fact that matches the <vp>FactTemplate</vp> in the appropriated facts database. During backtracking, the rest of the matching facts will be deleted.

Notice that <vp>FactTemplate</vp> can have any level of instantiation. The <vp>FactTemplate</vp> is matched with the facts in the facts database, which means that any free variables will be bound in the call to <vp>retract/1</vp>.

The <vp>FactTemplate</vp> can contain any anonymous variables. That is, variables with names consisting from the single underscore <vp>_</vp> or a variable with a name starting with an underscore <vp>_AnyValue</vp> if the variable occurs only once in the clause. For example.

<vip>retract(person("Hans", _Age)),</vip>

will retract the first matched person fact that has "<vp>Hans</vp>" as the first argument and anything as the second argument.

When retracting a fact, which is declared to be determ, the call to <vp>retract/1</vp> will be deterministic.

See also [[#retractall|retractall/1]] and [[#retractFactDb|retractFactDb]].

The <vp>retract/1</vp> predicate cannot be applied to single facts or fact variables.

Be careful calling <vp>retract/1</vp> with free <vp>FactTemplate</vp> variable if any single fact is declared in the project current scope. If you retract a single fact, then the run-time error is generated. The <vp>retract/1</vp> predicate fails when there are no more matches.

==== retractall ====

<vip>retractall : (<fact-term> FactTerm) .</vip>

Remove all matching facts from the facts database.

Call-template for this predicate is:

<vip>retractall(FactTemplate)</vip>

Here <vp>FactTemplate</vp> should be a fact term.

The <vp>retractall/1</vp> retracts all facts which match the given ''FactTemplate''. It always succeeds, even if no facts were retracted.

Attempting to retract a <vp>single</vp> fact will cause a compile time error.

It is not possible to obtain any output values from <vp>retractall/1</vp>. For this reason, the variables in the call must be bound or be a single underscores (anonymous). Notice that <vp>FactTemplate</vp> can have any level of instantiation, but free variables must be single underscores ("unconditionally anonymous"). In difference to [[#retract|retract/1]] "conditionally" anonymous variables with names starting from the underscore (like <vp>_AnyValue</vp>) cannot be used in <vp>retractall/1</vp>.

See also [[#retract|retract/1]] and [[#retractFactDb|retractFactDb/1]].

==== retractFactDb ====

<vip>retractFactDb : (factDB FactDB).</vip>

Remove all facts from the named internal facts database <vp>FactDB</vp>.

Call-template for this predicate is:

<vip>retractFactDb(FactDB)</vip>

The <vp>retractFactDb/1</vp> removes all facts from the named facts database <vp>FactDB</vp>.

Notice, it is impossible to retract <vp>single</vp> facts and fact variables, so the predicate leaves such ones as they are.

See also [[#retractall|retractall/1]] and [[#retract|retract/1]].

==== retractAll/2 ====

Obsolete predicate! Use [[#retractFactDb|retractFactDb/1]] instead.

==== sizeBitsOf ====

<vip>sizeBitsOf : (<domain> DomainName) -> unsigned BitSize.</vip>

Retrieves the number of bits occupied in memory by an entity of the specified domain <vp>DomainName</vp>.

Call-template for this function is:

<vip>BitSize = sizeBitsOf(DomainName)</vip>

This compiling-time predicate receives the domain <vp>DomainName</vp> as input parameter and return the size of memory that is occupied by the entity of the given domain. The result is measured in bits. For the integer domains <vp>sizeBitsOf/1-></vp> predicate returns the value that was defined for the size-field in a domain's declaration.

The following is always true for the integral domains:

<vip>sizeOfDomain(domain)*8 - 7 <= sizeBitsOf(domain) <= sizeOfDomain(domain)*8</vip>

See also [[#sizeOfDomain|sizeOfDomain]]/1->.

==== sizeOf ====

<vip>sizeOf : (<term> Term) -> integer ByteSize.</vip>

Retrieves the number of bytes occupied in memory by the specified term <vp>Term</vp>.

Call-template for this function is:

<vip>ByteSize = sizeOf(Term)</vip>

The <vp>sizeOf/1-></vp> function receives a term as input parameter and returns value <vp>ByteSize</vp> that specifies the number of bytes occupied in memory by this term <vp>Term</vp>.

==== sizeOfDomain ====

<vip>sizeOfDomain : (<domain> Domain) -> integer ByteSize.</vip>

Retrieves the number of bytes occupied in memory by the entity of the specified domain <vp>DomainName</vp>.

Call-template for this function is:

<vip>ByteSize = sizeOfDomain(DomainName)</vip>

This compiling-time predicate receives the domain <vp>DomainName</vp> as input parameter and return the size of memory that is occupied by the entity of the given domain. The result is measured in bytes. The returned value <vp>ByteSize</vp> belongs to the integer domain. Compare with [[#sizeBitsOf|sizeBitsOf/1->]], which returns size of a domain measured in bits.

==== sourcefile_lineno ====

<vip>sourcefile_lineno : () -> unsigned LineNumber.</vip>

Returns the current line number in the source file processed by the compiler.

==== sourcefile_name ====

<vip>sourcefile_name : () -> string FileName.</vip>

Returns the name of the source file processed by the compiler.

==== sourcefile_timestamp ====

<vip>sourcefile_timestamp : () -> string TimeStamp..</vip>

Returns a string that represents the date and time of the currently compiled source file in format <vp>YYYY-MM-DD</vp> <vp>HH:MM:SS</vp>. Where:

* <vp>YYYY</vp> - Year.
* <vp>MM</vp> - Month.
* <vp>DD</vp> - Day.
* <vp>HH</vp> - Hour.
* <vp>MM</vp> - Minute.
* <vp>SS</vp> - Second.

==== succeed ====

<vip>succeed : ().</vip>

The predicate <vp>succeed/0</vp> will always succeed.

==== toAny ====

<vip>toAny : (Term) -> any UniversalTypeValue.</vip>

Converts the specified <vp>Term</vp> to the value of universal term type <vp>any</vp>.

Call-template for this function is:

<vip>UniversalTypeValue = toAny(Term)</vip>

==== toBinary ====

<vip>toBinary : (Term) -> binary Serialized.</vip>

Converts the specified <vp>Term</vp> to [[#binary|binary]] representation.

Call-template for this function is:

<vip>Serialized = toBinary(Term)</vip>

When a <vp>Term</vp> (of some domain ''domainName'') is converted into a binary, it can safely be stored in a file or sent over a network to another program. Later the obtained binary value <vp>Serialized</vp> can be converted back to a Visual Prolog term, using [[#toTerm|toTerm/1->]] function (the domain for the reversed term should be adequate to ''domainName'') for the reverse conversion.

==== toBoolean ====

<vip>toBoolean : (<term> SubGoal) -> boolean Succeed.</vip>

The purpose of this meta-predicate is to convert the deterministic call (to a predicate or fact) to the procedure that returns the value of [[#boolean|boolean]] domain.

Call-template for this meta-predicate is:

<vip>True_or_False = toBoolean(deterministic_call)</vip>

The <vp>toBoolean/1-></vp> meta-predicate returns [[#boolean|boolean]] value. The result is <vp>true</vp> if ''deterministic_call'' succeeds. The result is <vp>false</vp> if ''deterministic_call'' fails.

==== toEllipsis ====

<vip>toEllipsis : (any* AnyTermList) -> ....</vip>

This predicate creates ''EllipsisBlock'' '''...''' (i.e. the special varying parameters block) from the list of terms of the universal type <vp>any</vp>. Such ''EllipsisBlock'' can be later passed to a predicate which expects the varying number of arguments (i.e. is declared with the ellipsis (''...'')), like <vp>write/...</vp>, at the position of the ellipsis (''...'').

Call-template for this function is:

<vip>EllipsisBlock = toEllipsis(<any_term_list>), write(EllipsisBlock )</vip>

See also [[#fromEllipsis|fromEllipsis/1->]].

==== toString ====

<vip>toString : (Term) -> string Serialized.</vip>

Converts the specified <vp>Term</vp> to string representation.

Call-template for this function is:

<vip>Serialized = toString(Term)</vip>

When a <vp>Term</vp> (of some domain ''domainName'') is converted into a string, it can safely be stored in a file or sent over a network to another program. Later the obtained string value can be converted back to a Visual Prolog term, using [[#toTerm|toTerm/1->]] function (the domain of the return value should be adequate to ''domainName'') for the reverse conversion.

==== toTerm ====

<vip>toTerm : (string Serialized) -> Term.
toTerm : (binary Serialized) -> Term.
toTerm : (any Serialized) -> Term.
toTerm : (<domain> Type, string Serialized) -> Term.
toTerm : (<domain> Type, binary Serialized) -> Term.
toTerm : (<domain> Type, any Serialized) -> Term.</vip>

Converts the string/binary/any representation of the specified term <vp>Serialized</vp> into representation corresponding to the domain of <vp>Term</vp> variable of the return value. The domain can be stated explicitly or it can be left to the compiler to determine a suitable domain.

Call-template for this function is:

<vip>Term = toTerm(Serialized) % with implicit domain
Term = toTerm(domainName, Serialized) % with explicit domain, domainName</vip>

If the domain is not specified the compiler must be able to determine the domain for the returned value <vp>Term</vp> at compile-time. Notice that binary version of <vp>toTerm</vp> predicate performs almost byte to byte conversion and only checking general compatibility of <vp>Serialized</vp> data with the domain required to the return value <vp>Term</vp>. The programmer is wholly responsible for providing binary data of <vp>Serialized</vp> that can be correctly converted to the term of the desired domain. The <vp>toTerm</vp> predicates are counterparts to predicates [[#toBinary|toBinary/1->]] and [[#toString|toString/1->]]. When a ''Term'' (of some domain ''domainName'') is converted into a binary or string representation <vp>Serialized</vp> (by [[#toBinary|toBinary/1->]] or [[#toString|toString/1->]] or [[#toAny|toAny/1->]] correspondingly), it can safely be stored in a file or sent over a network to another program. Later the corresponding <vp>toTerm/1</vp>-> function can convert the obtained string/binary value <vp>Serialized</vp> back to a Visual Prolog term <vp>Term</vp>. For correctness of the reverse conversion the domain of the clause variable <vp>Term</vp> should be adequate to the initial domain ''domainName''.

See also [[#tryToTerm|tryToTerm]].

It gives a compile time error if the compiler cannot determine the return domain.

Exceptions

* Run time errors are generated when the <vp>toTerm</vp> predicate cannot convert the string or binary into a term of the specified domain.

==== tryToTerm ====

<vip>tryToTerm : (string Serialized) -> Term.
tryToTerm : (binary Serialized) -> Term.
tryToTerm : (any Serialized) -> Term.
tryToTerm : (<domain> Type, string Serialized) -> Term.
tryToTerm : (<domain> Type, binary Serialized) -> Term.
tryToTerm : (<domain> Type, any Serialized) -> Term.</vip>

Converts the string/binary/any representation <vp>Serialized</vp> into a term <vp>Term</vp> like [[#toTerm|toTerm]]. The only difference between the predicates is that <vp>tryToTerm</vp> fails if it cannot convert the string or binary or any into a term of the specified domain whereas toTerm raises an exception.

See also [[#toTerm|toTerm]].

==== tryConvert ====

<vip>tryConvert : (<type> Type, Value) -> <type> Converted determ.</vip>

Checks whether the input term <vp>InputTerm</vp> can be strictly converted into the specified domain <vp>Type</vp> and returns the converted term <vp>Converted</vp>.

Call-template for this function is:

<vip>ReturnTerm = tryConvert(returnDomain, InputTerm)</vip>

Arguments:

* <vp>returnDomain</vp>: Specifies a domain to which <vp>tryConvert/2-></vp> predicate tries to convert the specified <vp>InputTerm</vp>. Here ''returnDomain'' can be any domain accessible in the current scope. The domain name ''returnDomain'' must be specified at compile-time, i.e. it cannot come from a variable.
* <vpbnf><InputTerm></vpbnf>: Specifies the term that must be converted. <vp>InputTerm</vp> may be any Prolog term or an expression. If <vp>InputTerm</vp> is an expression, then it will be evaluated before conversion.
* <vpbnf><ReturnTerm></vpbnf>: Returned term <vp>ReturnTerm</vp> will be of ''returnDomain'' domain.

The conversion rules are the same as of the embedded predicate [[#convert|convert/2->]], but <vp>tryConvert/2-></vp> fails when [[#convert|convert/2->]] generates conversion errors.

This predicate succeeds if the corresponding conversion succeeds. Otherwise it fails. The <vp>tryConvert/2-></vp> predicate tries to perform a clean and genuine conversion of the given <vp>InputTerm</vp> into a value of the specified domain ''returnDomain''. The <vp>tryConvert/2-></vp> predicate will fail if the required conversion cannot be performed. When <vp>tryConvert/2-></vp> predicate succeeds, it returns the term <vp>ReturnTerm</vp> converted to the specified domain ''returnDomain''.

For allowed conversions and rules of checked explicit conversions see [[#convert|convert/2->]] predicate.

See also [[#uncheckedConvert|uncheckedConvert/2->]].

==== uncheckedConvert ====

<vip>uncheckedConvert : (<type> Type, Value) -> <type> Converted.</vip>

Unchecked conversion of a value to another type.

Call-template for this function is:

<vip>ReturnTerm = uncheckedConvert(returnDomain, InputTerm)</vip>

Arguments:

* <vp>returnDomain</vp>: Specifies a domain to which <vp>uncheckedConvert</vp> predicate unsafely converts the specified <vp>InputTerm</vp>. Here ''returnDomain'' can be any domain accessible in the current scope, the <vp>ReturnTerm</vp> should has the same bit-size as the <vp>InputTerm</vp>. The domain name ''returnDomain'' must be specified at compile-time, i.e. it cannot come from a variable.
* <vpbnf><InputTerm></vpbnf>: Specifies the value that must be converted. <vp>InputTerm</vp> may be any Prolog term or an expression. If ''InputTerm'' is an expression, then it will be evaluated before conversion.
* <vpbnf><ReturnTerm></vpbnf>: Returned parameter <vp>ReturnTerm</vp> will be of ''returnDomain'' type.

<vp>uncheckedConvert</vp> evaluates <vp>InputTerm</vp>, change the type to ''returnDomain'' without any modification of the memory pattern and unifies with <vp>ReturnTerm</vp>. The <vp>uncheckedConvert</vp> predicate performs no runtime checks. It makes only compile time checking of bit-size equality of the converted domains. So almost any term may be quite recklessly converted to any other term. So quite disastrous results may occur if you try to use variables incorrectly converted by <vp>uncheckedConvert</vp>. Be extremely careful implementing <vp>uncheckedConvert</vp>; we strongly recommend you always, when it is possible, using of [[#convert|convert/2->]] and [[#tryConvert|tryConvert/2->]]. But notice that, when an object is returned by COM system it is necessary to convert it by <vp>uncheckedConvert</vp>, as Prolog program does not have information about its actual type.

==== upperBound ====

<vip>upperBound : (<numeric-domain> NumericDomain) -> <number-domain> UpperBound.</vip>

Returns the upper bound value of the specified numeric domain.

Call-template for this function is:

<vip>UpperBound = upperBound(domainName)</vip>

The <vp>upperBound</vp> is a compiling-time predicate. The <vp>upperBound</vp> returns the upper bound value of the specified numeric domain ''domainName''. The return value <vp>UpperBound</vp> belongs to the same domain ''domainName''. The ''domainName'' parameter should be the name of any numerical domain; this domain name should be explicitly specified at compile-time (that is, ''domainName'' cannot come from a variable).

See also [[#lowerBound|lowerBound/1->]].

Will cause a compile time error if the specified domain ''domainName'' is not numeric domain.
<noinclude>{{LanguageReferenceSubarticle|Built-in entities/Predicates}}</noinclude>

Ide/IDE Dialogs

2013-04-26T08:26:27Z

SergeMukhin: /* Window Navigation Dialog */

{{ideNavbar|IDE Dialogs}}

=== Warning: These files will be overwritten ===

When you create a new project with the IDE {{ide|Project Settings#General Tab|Project Settings}} facility, you can specify the '''Subdirectory''' in which the project will be placed (notice that usually this name is generated automatically from the specified project name). Notice that each project contains several standard files (always automatically generated by the IDE) with standard names. Therefore, if the specified subdirectory name coincides with one in which a previously created project already exists, then these 2 projects should have several standard files with the same names. Because the old versions of these files can be incompatible with the new project, the {{ide|Project Settings#General Tab|Project Settings}} generates the warning dialog with the title:

'''These files will be overwritten:'''

In the central pane of this dialog you see a list of files which should be overwritten.

You can select the following actions:

'''Continue'''

If you select this button, then the old versions of files specified in the list will be overwritten with the new versions.

'''Cancel'''

If you select this button, then no files will be overwritten, the IDE returns into the {{ide|Project Settings#General Tab|Project Settings}} dialog where you can the specify other name in the '''Subdirectory''' control.

=== Resolve Ambiguity ===

This dialog appears when you execute the:

* '''Go to Declaration''' ('''Ctrl+Shift+D'''),
* '''Go to Definition''' ('''Ctrl+Shift+C'''), or
* '''Show Visual Prolog Help''' ('''F1''')

commands and the cursor points onto a "'''''name'''''", which has several versions of the "'''''name'''''" references in the generated {{ide|Code Experts#Source Browser|browse information}} and cannot resolve this ambiguity using all additional information about the "'''''name'''''", which The IDE can gather in the edited file.

Correspondently it have titles:

* '''Resolve Ambiguity of "''name''" Declaration'''
* '''Resolve Ambiguity of "''name''" Definition'''
* '''Choose "''name''" to Show Help Topic'''

These dialogs display lists of references to the "'''''name'''''" with additional information (gathered in the generated by the compiler {{ide|Code Experts#Source Browser|browse information}}, which helps you to resolve ambiguity of the "'''''name'''''".

Names are prefixed with the same {{ide|Project Tree#Icons Used in the Project Window|icons}}, which are used in the Project window.

To continue an initiated command execution you need to select (click) one of displayed lines containing unique references to the "'''''name'''''".

=== Send Bug Report to Support ===

Normally you should use '''Help | Send Bug Report...''' IDE command to send a bug report or feedback. You can also send a mail directly to the '''Visual Prolog Support Service'''.

'''About Visual Prolog Support Service'''

'''Visual Prolog Support''' is responsible for answering questions only about bugs and problems with using of Visual Prolog language, the IDE, and other tools and packages supplied in '''Commercial''' editions of Visual Prolog.

'''Guidelines for preparing Bug Reports to Visual Prolog Support'''
----

'''1. Please check the following information sources before submitting your E-mail:'''

* [http://www.visual-prolog.com/vip6/support/faq.htm Frequently Asked Questions]
* [http://kb.visual-prolog.com Visual Prolog Knowledge Base]

'''2. Please do not ask Visual Prolog Support about general problems like: "Visual Prolog and Fuzzy Logic?"'''

For things please use [http://discuss.visual-prolog.com/ Visual Prolog Discussion Forum], where you are free to discuss any question deals with Visual Prolog. Anybody can read the debate, but you need to register if you want to make postings.

Prolog Development Center will follow and participate as much as possible in the debates. But we cannot make any "answer guarantee"; this is mainly your forum.

This forum will receive all major announcements from Prolog Development Center.

'''3. Your message MUST contain information generated by "Help | Send Bug Report | Show Details" IDE command.'''

This information contains some parameters about your computer and your project that are useful for correct understanding of the problem. It should be copied to the mail.

'''4. How to write a message:'''

*'''To:'''
*:The address of Visual Prolog International Support Group is: '''support@visual-prolog.com'''
*'''Subject:'''
*:Use a short, precise, and relevant Subject (title line). Please, do not use subjects like: '''My 1st problem with Prolog'''
*'''Message Text:'''
*:One problem per message, please.
*:Here you should describe your problem as detailed and precise, as it is possible.
*:Please supply examples of code illustrating your problem.
*:The information supplied in your message should be sufficient to reproduce your problem on our computers.

Please follow the above guidelines when you E-mail Bug Reports to Visual Prolog Support.

Regards

The Visual Prolog International Support Group

support@visual-prolog.com

=== Replace Text ===

Using this dialog you can find and replace each or every occurrence of a text pattern (a string or a regular expression) in the edited file.

'''Text to Find'''
:In the '''Text to Find''' box, type in the search string, or ''regular expression'', or choose a previous string from the drop-down list.
'''New Text'''
:Type the replacement string, or ''regular replacement expression'' in the '''New Text''' box, or choose a previous string from the drop-down list. Notice that ''regular replacement expressions'' have limited syntax regarding to ''regular expressions'' used in the '''Text to Find''' patterns.
'''Origin'''
:Options in the '''Origin''' group box defines the file scope in which the string should be searched.
:*'''Entire Scope'''
:*:Defines that the string should be searched in all file.
:*'''From Cursor'''
:*:Defines that the string should be searched beginning from the current cursor position.
:*'''Selected Text'''
:*:Defines that the string should be searched only in the selected piece of the edited text.
'''Direction'''
:Options in the '''Direction''' group box defines the direction in which the string should be searched.
:*'''Forward'''
:*:Search the document below the insertion point.
:*'''Backward'''
:*:Search the document above the insertion point.
'''Options'''
:In this group box you defines the search options.
:*'''Case Sensitive'''
:*:Find strings having the given pattern of uppercase and lowercase letters.
:*'''Whole Words Only'''
:*:Find occurrences of the string as whole words. It only displays instances of the Find what string that are matched in complete words. For example, a search for "my::List" will return "my::List" but not "cmy::List" or "my::Listtt".
:*'''Use Regular Expressions'''
:*:See [Find_Text_in_Files.htm #Regular_Expressions2 Regular Expressions] for details.
'''Replace'''
:Press the '''Replace''' button to replace the current selection or to invoke searching of the specified string (regular expression) with the specified options if there are no selection.
'''Find Next'''
:Press the '''Find''' button to invoke searching of the next occurrence of the specified string (regular expression) with the specified options.
'''Change All'''
:Press the '''Change All''' button to replace all occurrences of the search text, in the specified scope.
'''Close'''
:Close this dialog.
'''Help'''
:Displays this help topic.

=== Find Text in Files ===

Using this dialog you can find each occurrence of a combination of any characters, including uppercase and lowercase characters, whole words, or parts of words, or regular expressions in the specified group of files.

[[Image:Ide_FindInFiles.png]]

'''Text to Find'''
:In the '''Text to Find''' box, type in the search string, or ''regular expression'', or choose a previous string from the drop-down list.
'''Find in All Opened Editors'''
:Check this option if you wish that the IDE search the specified string only in that text files, which are currently opened in the IDE text editors.
'''Find in Project Files Only'''
:Check this option if you wish that the IDE search the specified string only in text files, which are parts of the project currently loaded into the IDE.
:This button is disabled when the project is not loaded.
'''Show Search Results in New Window'''
:If this option is checked ON, then the IDE will open new '''Search results''' window each time the search is completed, otherwise it will display search results in the same window.
'''In Files:'''
:In this list editor you can specify (or select from the list of previously used) the file mask which will be used to restrict files in which the IDE will search for the string. For example, you can use <vp>*</vp> operator to specify that any sub-string can be used instead of this operator.
:This option is disabled when the '''Find in All Opened Editors''' option is checked ON.
'''In Folder:'''
:In this list editor you can specify (or select from the list of previously used) the folder, which will be used to restrict files in which the IDE will search for the string.
:This option is disabled when the '''Find in All Opened Editors''' option is checked ON.
'''Browse'''
:Press this button to open the '''Set New Directory''' dialog in which you can select the folder, which name will be inserted into the '''In Folder''' field.
: Notice that when '''Find in Project Files Only''' is checked ON, then this dialog will gives you access only to the folders known to the project.
:This button is disabled when the '''Find in All Opened Editors''' option is checked ON.
'''Search Subfolders'''
:When this option is checked ON (the default), then the IDE will search in all subfolders of the folder specified in the '''In Folder''' field.
:Otherwise, search will be only in the files directly in the folder specified in the '''In Folder''' field.
'''Whole Words Only'''
:Find occurrences of the string as whole words. It only displays instances of the Find what string that are matched in complete words. For example, a search for "my::List" will return "my::List" but not "cmy::List" or "my::Listtt".
'''Case Sensitive'''
:The selected item specifies whether the search should match case of the whole search string ('''Case Sensitive'''), ignore the case ('''Case Insensitive''') or match the case of the first character of the search string ('''Prolog Sensitive'''). The last option is unavailable, when '''Regular Expressions''' option is checked ON.

==== Regular Expressions ====

Provides possibility to perform advanced string searching operations (searching, matching and replacing) using regular expressions.

'''Regular Expressions '''
:A ''regular expression'' (or pattern) is a text string that describes some (mathematical) group of strings. A string <vp>S</vp> "matches" a regular expression <vp>R</vp> if <vp>S</vp> belongs to the set of strings described by <vp>R</vp>. Using regular expression, you can:
:* check whether the specified string matches the specified pattern;
:* search within a string for a substring matching the specified pattern;
:* perform replacing within matched substrings.
:Some regular expressions can match only one substring. That is, a set of strings such regular expression describes has only one member. For example, the regular expression '''foo''' matches only the substring '''foo''' and no others. Other regular expressions can match more than one substring. That is, a set of strings such regular expression describes has more than one member. For example, the regular expression <vp>f*</vp> matches the set of strings made up of any number (including zero) of '''f''' characters. Some characters in regular expressions match themselves (such as '''f''') and some do not match to any concrete character (such as <vp>*</vp>). Characters that do not match themselves are used to specify patterns, which describe sets of different strings.
'''Regular Expression Syntax'''
See the [pfc\regEx\packRegEx.htm regEx] package for more details of regular expression syntax.

'''Find'''
:Press the '''Find''' button to invoke searching of the specified string (regular expression) with the specified options.
'''Stop'''
:Press the '''Stop''' button to stop searching.
'''Help'''
:Displays this help topic.

==== Search results ====

[[Image:Ide_FindInFilesResults.png]]

This window displays the table which contains the names of files in which the specified string is found, the line number and the position, where the specified text is located and the content of the whole line.

If you double-click any filename, then this file will be opened in the text editor.

=== Find Text ===

Using this dialog you can find each occurrence of a combination of any characters, including uppercase and lowercase characters, whole words, or parts of words, or regular expressions.

'''Text to Find'''
:In the '''Text to Find''' box, type in the search string, or regular expression, or choose a previous string from the drop-down list.
'''Origin'''
:Options in the '''Origin''' group box defines the file scope in which the string should be searched.
:'''Entire Scope'''
::Defines that the string should be searched in all file.
:'''From Cursor'''
::Defines that the string should be searched beginning from the current cursor position.
:'''Selected Text'''
::Defines that the string should be searched only in the selected piece of the edited text.
'''Direction'''
:Options in the '''Direction''' group box defines the direction in which the string should be searched.
:'''Forward'''
::Search the document below the insertion point.
:'''Backward'''
::Search the document above the insertion point.
'''Options'''
:In this group box you defines the search options.
:'''Case Sensitive'''
::Find strings having the given pattern of uppercase and lowercase letters.
:'''Whole Words Only'''
::Find occurrences of the string as whole words.
:'''Use Regular Expressions'''
::See [Find_Text_in_Files.htm #Regular_Expressions2 Regular Expressions] for details.
'''Find'''
:Press the '''Find''' button to invoke searching of the specified string (regular expression) with the specified options.
'''Close'''
:Close this dialog.
'''Help'''
:Displays this help topic.

=== Window Navigation Dialog ===

The order, in which '''Ctrl-TAB''' shifts between IDE windows, has been changed to visit most-recently-visited windows first.

Furthermore, '''Ctrl-TAB''' also brings up a navigation dialog listing all the open windows. The dialog stays up as long as Ctrl-key is pressed. In this dialog you can see the windows in the order they will be shifted to, but you can also choose a window directly using the mouse or the arrow keys. If you press letters the list will be filtered to windows starting with the letters you have pressed.

'''Ctrl-F1''' Help,

'''Ctrl-Del''' will close the selected window,

'''Ctrl-BackSpace''' removes the last letter,

'''Ctrl-Alt''' switches on/off showing only read-write files.

'''Ctrl-*''' switches on/off alternate filter by letter.