Language Reference/Built-in entities/Predicates

assert/1	Insert the specified fact at the end of the matched internal facts database.
asserta/1	Insert a fact at the beginning of the matched internal facts database.
assertz/1	Insert a fact at the end of the matched internal facts database.
bound/1 determ	Test whether the specified variable is bound to a value.
class_name/0->	This compile time predicate returns the string ClassName that represents the name of the current interface or class.
compare/2->	Returns the result of the variables' comparison.
convert/2->	Checked term conversion.
digitsOf/1->	Returns precision of the specified floating-point domain.
errorExit/1 erroneous	Performs a run-time error with the specified return code ErrorNumber and sets the internal error information.
fail/0 failure	Invoke backtracking.
free/1 determ	Check whether a variable is free.
fromEllipsis/1->	Creates the list of terms of the universal type any from the EllipsisBlock.
hasDomain/2	Checks whether the variable VariableName has the domain domainName.
isErroneous/1 determ	Returns the lower bound value of the specified numeric domain.
lowerBound/1->	Returns the lower bound value of the specified numeric domain.
maxDigits/1->	Retrieves the value of digits (precision) of the basic domain corresponding to the specified floating-point domain domainName.
not/1 determ	Negate the result (success/fail) of subgoal.
predicate_fullname/1->	This compile time predicate returns the string PredicateFullName that represent the name of the predicate in which clause body predicate_name is called. The returned predicate name is qualified with a scope's name.
programPoint/0->	This compile time predicate returns the programPoint corresponding to the place where it is called.
retract/1 nondeterm	Remove a matched fact from the matched internal facts database.
retractall/1	Remove all matching facts from the matched internal facts database.
retractFactDb/1	Remove all facts from the specified named internal facts database.
sizeBitsOf/1->	Retrieves the number of bits occupied in memory by an entity of the specified domain DomainName.
sizeOf/1->	Retrieves the number of bytes occupied in memory by the specified term.
sizeOfDomain/1->	Retrieves the number of bytes occupied in memory by the entity of the specified domain DomainName.
sourcefile_lineno/0->	Returns the current line number in the source file processed by the compiler .
sourcefile_name/0->	Returns the name of the source file processed by the compiler.
sourcefile_timestamp/0->	Returns the string representing the date and time of the source file processed by the compiler.
succeed/0	The predicate succeed/0 will always succeed.
toAny/1->	Converts the specified Term to the value of the universal term type any.
toBinary/1->	Converts the specified Term to the binary representation.
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 boolean domain.
toEllipsis/1->	Creates the EllipsisBlock from the list of any type values.
toString/1->	Converts the specified Term to the string representation.
toTerm/1-> 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/1-> determ tryToTerm/2-> determ	Converts the string/binary representation of the specified term SrcTerm into representation corresponding to the domain of PrologTerm variable of the return value.
tryConvert/2-> determ	Checks whether the input term InputTerm can be strictly converted into the specified domain returnDomain and returns the converted term ReturnTerm.
uncheckedConvert/2->	Unchecked conversion of domains.
upperBound/1->	Returns the upper bound value of the specified numeric domain.

The following predicates are deprecated:

finally/2	Use try ... finally ... end try instead.
findall/3	Use list comprehension [ ... || ...  ] instead
trap/3 determ	Use try ... catch V do ... end try instead

assert

assert : (<fact-term> FactTerm).

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

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

Notice that the combination of retract/1 and assert/1 like the following can lead to endless loop:

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

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

asserta : (<fact-term> FactTerm).

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

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

Exceptions:

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

assertz

assertz : (<fact-term> FactTerm).

assertz does exactly the same as the assert/1 predicate.

bound

bound : (<variable> Variable) determ.

Test whether the specified variable is bound to a value.

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

See also free/1.

class_name

class_Name : () -> string ClassName.

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

compare

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

Comparison of two terms of the same domain, resturns the value of compareResult domain.

CompareResult = compare("bar", "foo")

convert

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

Checked term conversion.

Call-template for this function is:

ReturnTerm = convert(returnDomain, InputTerm)

• returnDomain: Specifies a domain to which function convert/2-> converts InputTerm. 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.

• InputTerm: Specifies the value that must be converted. InputTerm may be any Prolog term or an expression. If InputTerm is an expression, then it will be evaluated before the conversion.

• ReturnTerm: Returned parameter ReturnTerm will be of returnDomain type.

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

Allowed conversions

• Between numerical domains.
• Between interface types.
• Between string and symbol domains.
• From binary to pointer.
• For synonyms of mentioned domains.
• Between reference domains and corresponding non-reference domains.

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

The convert/2-> (or 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: [const .. const].
• Real constants are the representatives of the anonymous real domain: digits dig [const .. const], where dig 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 convert/2-> and tryConvert/2-> predicates truncate the input value to the nearest integer value, which is nearer to zero.

Conversions of Interface Types

Predicate convert/2-> 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:

interface x
      supports a, b
end interface x

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

Exceptions:

• Check range error.
• Unsupported interface type.

digitsOf

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

Returns precision of the specified floating-point domain.

Call-template for this function is:

Precision = digitsof(domainName)

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 Precision that was determined by the digits attribute in the domain declaration.

The compiler guarantees that values of the domain domainName will have at least Precision number of significant decimal digits.

errorExit

errorExit : (unsigned ErrorNumber) erroneous.

Performs a run-time error with the specified return code ErrorNumber, which can be used in the try-catch-finally.

fail

fail : () failure.

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

free

free : (<variableName> Variable) determ.

Check whether a variable is free.

Call-template for this predicate is:

free(Variable)

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

See also bound/1.

fromEllipsis

fromEllipsis : (...) -> any* AnyTermList.

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

Call-template for this function is:

AnyTermList = fromEllipsis(EllipsisBlock )

See also toEllipsis/1->.

hasDomain

hasDomain : (<type> Type, <variable> Variable) procedure.

hasDomain is not really a predicate, but more a declaration: It states that the variable Variable must have the type Type.

The variable can be free, bound or of some mixed flow. The binding of the variable is not changes in any way.

lowerBound

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

Returns the lower bound of the specified NumericDomain.

Call-template for this function is:

LowerBoundValue = lowerBound(domainName)

The lowerBound is a compiling-time predicate. The lowerBound returns the lower bound value LowerBoundValue of the specified numeric domain domainName. The return value LowerBoundValue 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/1->.

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

isErroneous

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

The predicate succeeds if the specified fact variable is erroneous.

Call-template for this predicate is:

isErroneous(factVariableName)

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

maxDigits

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

Retrieves the value of digits (precision) of the basic domain corresponding to the specified floating-point domain domainName.

Call-template for this function is:

MaxDigitsNumber = maxdigits(domainName)

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

not

not : (<term> SubGoal) determ.

Succeds if the SubGoal fails, and vice versa.

Call-template for this predicate is:

not(SubGoal)

The not succeeds if SubGoal fails when evaluated. Notice that SubGoal cannot bind any variables, because not(SubGoal) only succeeds if SubGoal fails (and a failing goal does not bind anything).

predicate_fullname

predicate_fullname : () -> string PredicateFullName.

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

predicate_fullname can only be used inside a clause. Use of predicate_fullname in other places causes a compile time error. See also predicate_name.

predicate_name

predicate_name : () -> string PredicateName.

This predicate returns the name PredicateName of the predicate in which it is invoked.

predicate_name can only be used inside a clause. Use of predicate_name in other places causes a compile time error. See also predicate_fullname

programPoint

programPoint : () -> programPoint ProgramPoint.

This predicate returns the name programPoint corresponding to the place where it is invoked.

retract

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

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

Call-template for this predicate is:

retract(FactTemplate)

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

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

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

retract(person("Hans", _Age)),

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

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

See also retractall/1 and retractFactDb.

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

Be careful calling retract/1 with free FactTemplate 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 retract/1 predicate fails when there are no more matches.

retractall

retractall : (<fact-term> FactTerm) .

Remove all matching facts from the facts database.

Call-template for this predicate is:

retractall(FactTemplate)

Here FactTemplate should be a fact term.

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

Attempting to retract a single fact will cause a compile time error.

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

See also retract/1 and retractFactDb/1.

retractFactDb

retractFactDb : (factDB FactDB).

Remove all facts from the named internal facts database FactDB.

Call-template for this predicate is:

retractFactDb(FactDB)

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

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

See also retractall/1 and retract/1.

retractAll/2

Obsolete predicate! Use retractFactDb/1 instead.

sizeBitsOf

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

Retrieves the number of bits occupied in memory by an entity of the specified domain DomainName.

Call-template for this function is:

BitSize = sizeBitsOf(DomainName)

This compiling-time predicate receives the domain DomainName 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 sizeBitsOf/1-> 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:

sizeOfDomain(domain)*8 - 7 <= sizeBitsOf(domain) <= sizeOfDomain(domain)*8

See also sizeOfDomain/1->.

sizeOf

sizeOf : (<term> Term) -> integer ByteSize.

Retrieves the number of bytes occupied in memory by the specified term Term.

Call-template for this function is:

ByteSize = sizeOf(Term)

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

sizeOfDomain

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

Retrieves the number of bytes occupied in memory by the entity of the specified domain DomainName.

Call-template for this function is:

ByteSize = sizeOfDomain(DomainName)

This compiling-time predicate receives the domain DomainName 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 ByteSize belongs to the integer domain. Compare with sizeBitsOf/1->, which returns size of a domain measured in bits.

sourcefile_lineno

sourcefile_lineno : () -> unsigned LineNumber.

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

sourcefile_name

sourcefile_name : () -> string FileName.

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

sourcefile_timestamp

sourcefile_timestamp : () -> string TimeStamp..

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

succeed : ().

The predicate succeed/0 will always succeed.

toAny

toAny : (Term) -> any UniversalTypeValue.

Converts the specified Term to the value of universal term type any.

Call-template for this function is:

UniversalTypeValue = toAny(Term)

toBinary

toBinary : (Term) -> binary Serialized.

Converts the specified Term to binary representation.

Call-template for this function is:

Serialized = toBinary(Term)

When a Term (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 Serialized can be converted back to a Visual Prolog term, using toTerm/1-> function (the domain for the reversed term should be adequate to domainName) for the reverse conversion.

toBoolean

toBoolean : (<term> SubGoal) -> boolean Succeed.

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

Call-template for this meta-predicate is:

True_or_False = toBoolean(deterministic_call)

The toBoolean/1-> meta-predicate returns boolean value. The result is true if deterministic_call succeeds. The result is false if deterministic_call fails.

toEllipsis

toEllipsis : (any* AnyTermList) -> ....

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

Call-template for this function is:

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

See also fromEllipsis/1->.

toString

toString : (Term) -> string Serialized.

Converts the specified Term to string representation.

Call-template for this function is:

Serialized = toString(Term)

When a Term (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/1-> function (the domain of the return value should be adequate to domainName) for the reverse conversion.

toTerm

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.

Converts the string/binary/any representation of the specified term Serialized into representation corresponding to the domain of Term 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:

Term = toTerm(Serialized) % with implicit domain
Term = toTerm(domainName, Serialized) % with explicit domain, domainName

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

See also tryToTerm.

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

Exceptions

• Run time errors are generated when the toTerm predicate cannot convert the string or binary into a term of the specified domain.

tryToTerm

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.

Converts the string/binary/any representation Serialized into a term Term like toTerm. The only difference between the predicates is that tryToTerm 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.

tryConvert

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

Checks whether the input term InputTerm can be strictly converted into the specified domain Type and returns the converted term Converted.

Call-template for this function is:

ReturnTerm = tryConvert(returnDomain, InputTerm)

Arguments:

• returnDomain: Specifies a domain to which tryConvert/2-> predicate tries to convert the specified InputTerm. 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.
• InputTerm: Specifies the term that must be converted. InputTerm may be any Prolog term or an expression. If InputTerm is an expression, then it will be evaluated before conversion.
• ReturnTerm: Returned term ReturnTerm will be of returnDomain domain.

The conversion rules are the same as of the embedded predicate convert/2->, but tryConvert/2-> fails when convert/2-> generates conversion errors.

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

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

See also uncheckedConvert/2->.

uncheckedConvert

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

Unchecked conversion of a value to another type.

Call-template for this function is:

ReturnTerm = uncheckedConvert(returnDomain, InputTerm)

Arguments:

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

uncheckedConvert evaluates InputTerm, change the type to returnDomain without any modification of the memory pattern and unifies with ReturnTerm. The uncheckedConvert 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 uncheckedConvert. Be extremely careful implementing uncheckedConvert; we strongly recommend you always, when it is possible, using of convert/2-> and tryConvert/2->. But notice that, when an object is returned by COM system it is necessary to convert it by uncheckedConvert, as Prolog program does not have information about its actual type.

upperBound

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

Returns the upper bound value of the specified numeric domain.

Call-template for this function is:

UpperBound = upperBound(domainName)

The upperBound is a compiling-time predicate. The upperBound returns the upper bound value of the specified numeric domain domainName. The return value UpperBound 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/1->.

Will cause a compile time error if the specified domain domainName is not numeric domain.