Predicates

Predicate directives and clauses can be encapsulated inside objects and categories. Protocols can only contain predicate directives. From the point of view of a traditional imperative object-oriented language, predicates allow both object state and object behavior to be represented. Mutable object state can be represented using dynamic object predicates but should only be used when strictly necessary, as it breaks declarative semantics.

Reserved predicate names

For practical and performance reasons, some predicate names have a fixed interpretation. These predicates are declared in the built-in protocols. They are: goal_expansion/2 and term_expansion/2, declared in the expanding protocol; before/3 and after/3, declared in the monitoring protocol; and forward/1, declared in the forwarding protocol. By default, the compiler prints a warning when a definition for one of these predicates is found but the reference to the corresponding built-in protocol is missing.

Declaring predicates

Logtalk provides a clear distinction between declaring a predicate and defining a predicate and thus clear closed-world assumption semantics. Messages or calls for declared but undefined predicates fail. Messages or calls for unknown (i.e., non-declared) predicates throw an error. Note that this is a fundamental requirement for supporting protocols: we must be able to declare a predicate without necessarily defining it.

All object (or category) predicates that we want to access from other objects (or categories) must be explicitly declared. A predicate declaration must contain, at least, a scope directive. Other directives may be used to document the predicate or to ensure proper compilation of the predicate clauses.

Scope directives

A predicate scope directive specifies from where the predicate can be called, i.e. its visibility. Predicates can be public, protected, private, or local. Public predicates can be called from any object. Protected predicates can only be called from the container object or from a container descendant. Private predicates can only be called from the container object. Predicates are local when they are not declared in a scope directive. Local predicates, like private predicates, can only be called from the container object (or category), but they are invisible to the reflection built-in methods (current_predicate/1 and predicate_property/2) and to the message error handling mechanisms (i.e., sending a message corresponding to a local predicate results in a predicate_declaration existence error instead of a scope error).

The scope declarations are made using the directives public/1, protected/1, and private/1. For example:

:- public(init/1).

:- protected(valid_init_option/1).

:- private(process_init_options/1).

If a predicate does not have a (local or inherited) scope declaration, it is assumed that the predicate is local. Note that we do not need to write scope declarations for all defined predicates. One exception is local dynamic predicates: declaring them as private predicates may allow the Logtalk compiler to generate optimized code for asserting and retracting clauses.

Note that a predicate scope directive doesn’t specify where a predicate is, or can be, defined. For example, a private predicate can only be called from an object holding its scope directive. But it can be defined in descendant objects. A typical example is an object playing the role of a class defining a private (possibly dynamic) predicate for its descendant instances. Only the class can call (and possibly assert/retract clauses for) the predicate, but its clauses can be found/defined in the instances themselves.

Scope directives may also be used to declare grammar rule non-terminals and operators. For example:

:- public(url//1).

:- public(op(800, fx, tag)).

Note that, in the case of operators, the operator definitions don’t become global when the entity containing the directives is compiled and loaded. This prevents an application from breaking when, for example, an updated third-party library adds new operators. It also allows loading entities that provide conflicting operator definitions. Here the usual programming idiom is to copy the operator definitions to a uses/2 directive. For example, the lgtunit tool makes available a (=~=)/2 predicate (for approximate float equality) that is intended to be used as an infix operator:

:- uses(lgtunit, [
    op(700, xfx, =~=), (=~=)/2
]).

Thus, in practice, the solution to use library entity operators in client entities is the same for using library entity predicates with implicit message-sending.

Mode directive

Often predicates can only be called using specific argument patterns. The valid arguments and instantiation modes of those arguments can be documented using the mode/2 directive. For example:

:- mode(member(?term, ?list), zero_or_more).

The first directive argument describes a valid calling mode. The minimum information will be the instantiation mode of each argument. The first four possible values are described in the ISO Prolog Core standard [ISO95]). The remaining two can also be found in use in some Prolog systems.

+

Argument must be instantiated (but not necessarily ground).

-

Argument should be a free (non-instantiated) variable. When bound, the call will unify the computed term with the given argument.

?

Argument can either be instantiated or free.

@

Argument will not be further instantiated (modified).

++

Argument must be ground.

--

Argument must be unbound. Used mainly when returning an opaque term (e.g., a stream handle).

Note that the + and @ instantiation modes have the same meaning for atomic arguments. E.g. you can write either +atom or @atom but the first alternative is preferred.

These six mode atoms are also declared as prefix operators by the Logtalk compiler. This makes it possible to include type information for each argument as in the example above. Some possible type values are: event, object, category, protocol, callable, term, nonvar, var, atomic, atom, number, integer, float, compound, and list. The first four are Logtalk specific. The remaining are common Prolog types. We can also use our own types that can be either atoms or ground compound terms. See the types library documentation for an extensive list of pre-defined types that cover most common use cases.

The second directive argument documents the number of proofs, but not necessarily distinct solutions, for the specified mode. As an example, the member(X, [1,1,1,1]) goal has only one distinct solution but four proofs for that solution. Note that different modes for the same predicate often have different determinism. The possible values are:

zero

Predicate always fails (e.g., the false/0 standard predicate).

one

Predicate always succeeds once (e.g., the flush_output/0 standard predicate).

zero_or_one

Predicate either fails or succeeds (e.g., the atom/1 standard predicate).

zero_or_more

Predicate has zero or more proofs (e.g., the current_predicate/1 standard predicate).

one_or_more

Predicate has one or more proofs (e.g., the repeat/0 standard predicate).

zero_or_error

Predicate either fails or throws an error.

one_or_error

Predicate either succeeds once or throws an error (e.g., the open/3 standard predicate).

zero_or_one_or_error

Predicate succeeds once or fails or throws an error (e.g., the get_char/1 standard predicate).

zero_or_more_or_error

Predicate may fail or succeed multiple times or throw an error (e.g., the retract/1 standard predicate).

one_or_more_or_error

Predicate may succeed one or more times or throw an error.

error

Predicate will throw an error (e.g., the type_error/2 built-in method).

The last six values support documenting that some call modes may throw an error or will throw an error despite the call arguments complying with the expected types and instantiation modes. As an example, consider the open/3 standard predicate:

:- mode(open(@source_sink, @io_mode, --stream), one_or_error).

In this case, the mode directive tells the user that a valid call can still throw an error (there may be e.g. a permission error opening the specified source or sink).

Notice that using the zero, one, zero_or_one, zero_or_more, or one_or_more modes is not only for predicates that never throw an exception; they can also be used for any predicate that doesn’t throw an exception when the arguments are valid. For example, the current_predicate/1 standard predicate throws an exception if the argument is neither a variable nor a predicate indicator, but it succeeds zero or more times when its argument is valid:

:- mode(current_predicate(?predicate_indicator), zero_or_more).

Some predicates have more than one valid mode, thus implying several mode directives. For example, to document the possible use modes of the standard atom_concat/3 predicate, we would write:

:- mode(atom_concat(?atom, ?atom, +atom), one_or_more).
:- mode(atom_concat(+atom, +atom, -atom), one).

The first mode/2 directive specifies that the atom_concat/3 predicate can be used to split an atom into a prefix and a suffix. The second mode/2 directive specifies that concatenating two atoms results in a new atom. There are often several alternative mode/2 directives that can be used to specify a predicate. For example, an alternative to the second mode/2 directive above would be:

:- mode(atom_concat(+atom, +atom, ?atom), zero_or_one).

In this case, the same information is provided by both alternatives. But the first alternative is simpler and thus preferred.

Some old Prolog compilers supported some sort of mode directives to improve performance. To the best of my knowledge, there is no modern Prolog compiler supporting this kind of directive for that purpose. The current Logtalk version simply parses this directive for collecting its information for use in the reflection API (assuming the source_data flag is turned on). In any case, the use of mode directives is a good starting point for documenting your predicates.

Meta-predicate directive

Some predicates may have arguments that will be called as goals, interpreted as closures that will be used for constructing goals, or passing meta-arguments to calls to other meta-predicates. To ensure that these goals will be executed in the correct context (i.e., in the calling context, not in the meta-predicate definition context), we need to use the meta_predicate/1 directive (in the case of meta non-terminals, there’s also a meta_non_terminal/1 directive). For example:

:- meta_predicate(findall(*, 0, *)).
:- meta_predicate(map(2, *, *)).

The meta-predicate mode arguments in this directive have the following meaning:

0

Meta-argument that will be called as a goal.

N

Meta-argument that will be a closure used to construct a call by extending it with N arguments. The value of N must be a positive integer.

::

Argument that is context-aware but that will not be called as a goal or a closure. It can contain, however, sub-terms that will be called as goals or closures.

^

Goal that may be existentially quantified (Vars^Goal).

*

Normal argument.

The following meta-predicate mode arguments are for use only when writing backend Prolog adapter files to deal with proprietary built-in meta-predicates and meta-directives:

/

Predicate indicator (Name/Arity), list of predicate indicators, or conjunction of predicate indicators.

//

Non-terminal indicator (Name//Arity), list of predicate indicators, or conjunction of predicate indicators.

[0]

List of goals.

[N]

List of closures.

[/]

List of predicate indicators.

[//]

List of non-terminal indicators.

To the best of my knowledge, the use of non-negative integers to specify closures was first introduced on Quintus Prolog for providing information for predicate cross-reference tools.

Note that Logtalk meta-predicate semantics are different from Prolog meta-predicate semantics (assuming a predicate-based module system as common):

• Meta-arguments are always called in the meta-predicate calling context, independent of using explicit or implicit message-sending (to the object defining the meta-predicate when not local). Most Prolog systems have different semantics for explicit versus implicit module qualification.

• Logtalk is not based on a predicate prefixing mechanism. Therefore, the meta-predicate directive is required for any predicate with meta-arguments (including when simply passing the meta-arguments to a call to another meta-predicate). This is usually not required in Prolog systems due to the module prefixing of meta-arguments.

• Sending a message from a meta-predicate definition to call a meta-predicate defined in another object resets the calling context for any passed meta-argument to the object sending the message (including for messages to self). Meta-arguments behave differently in Prolog systems due to their module prefixing.

• Logtalk protects from common scenarios where specially crafted meta-predicate definitions are used to break object (and category) encapsulation by changing the meta-arguments passed by client code or trying to subvert the implicit calling context to call client predicates other than the predicates passed as meta-arguments.

Warning

As each Logtalk entity is independently compiled, this directive must be included in every object or category that contains a definition for the described meta-predicate, even if the meta-predicate declaration is inherited from another entity, to ensure proper compilation of meta-arguments.

Discontiguous directive

The clause of an object (or category) predicate may not be contiguous. In that case, we must declare the predicate discontiguous by using the discontiguous/1 directive:

:- discontiguous(foo/1).

This is a directive that we should avoid using: it makes your code harder to read, and it is not supported by some Prolog backends.

Warning

As each Logtalk entity is compiled independently of other entities, this directive must be included in every object or category that contains a definition for the described predicate (even if the predicate declaration is inherited from another entity).

Dynamic directive

An object predicate can be static or dynamic. By default, all predicates (and non-terminals) of static objects defined in source files are static. To declare a dynamic predicate (or non-terminal), we use the dynamic/1 directive. For example:

:- dynamic(foo/1).

Predicates of objects dynamically created at runtime (using the create_object/4 built-in predicate) and predicates of dynamic objects defined in source files (using the dynamic/0 directive) are implicitly dynamic.

Dynamic predicates can be used to represent persistent mutable object state. Note that static objects may declare and define dynamic predicates. Categories can only declare dynamic predicates (with the importing objects holding the predicate definitions).

Warning

As each Logtalk entity is compiled independently from other entities, this directive must be included in every object that contains a definition for the described predicate (even if the predicate declaration is inherited from another object or imported from a category). If we omit the dynamic declaration then the predicate definition will be compiled static.

Operator directive

An object (or category) predicate can be declared as an operator using the familiar op/3 directive:

:- op(Priority, Specifier, Operator).

Operators are local to the object (or category) where they are declared. This means that, if you declare a public predicate as an operator, you cannot use operator notation when sending to an object (where the predicate is visible) the respective message (as this would imply visibility of the operator declaration in the context of the sender of the message). If you want to declare global operators and, at the same time, use them inside an entity, just write the corresponding directives at the top of your source file, before the entity opening directive.

Note that operators can also be declared using a scope directive. Only these operators are visible to the current_op/3 reflection method.

When the same operators are used on several entities within the same source file, the corresponding directives must either be repeated in each entity or appear before any entity that uses them. But in the later case, this results in a global scope for the operators. If you prefer the operators to be local to the source file, just undefine them at the end of the file. For example:

% before any entity that uses the operator
:- op(400, xfx, results).

...

% after all entities that used the operator
:- op(0, xfx, results).

Global operators can be declared in the application loader file.

Uses directive

When a predicate makes heavy use of predicates defined on other objects, its predicate clauses can be verbose due to all the necessary message-sending goals. Consider the following example:

foo :-
    ...,
    findall(X, list::member(X, L), A),
    list::append(A, B, C),
    list::select(Y, C, R),
    ...

Logtalk provides a directive, uses/2, which allows us to simplify the code above. One of the usage templates for this directive is:

:- uses(Object, [
    Name1/Arity1, Name2/Arity2, ...
]).

Rewriting the code above using this directive results in a simplified and more readable predicate definition:

:- uses(list, [
    append/3, member/2, select/3
]).

foo :-
    ...,
    findall(X, member(X, L), A),
    append(A, B, C),
    select(Y, C, R),
    ...

Logtalk also supports an extended version of this directive that allows the declaration of predicate aliases using the notation Predicate as Alias (or the alternative notation Predicate::Alias). For example:

:- uses(btrees, [new/1 as new_btree/1]).
:- uses(queues, [new/1 as new_queue/1]).

You may use this extended version for solving conflicts between predicates declared on several uses/2 directives or just for giving new names to the predicates that will be more meaningful on their using context.

Predicate aliases can also be used to define predicate shorthands, simplifying code maintenance. For example:

:- uses(pretty_printer, [
    indent(4, Term) as indent(Term)
]).

Assuming multiple calls to the shorthand, a change to the indent value will require a change to a single line instead of changing every call.

Another common use of predicate aliases is changing the order of the predicate arguments without using lambda expressions. For example:

:- uses(meta, [
    fold_left(Closure, Result0, List, Result) as foldl(Closure, List, Result0, Result)
]).

See the directive documentation for details and other examples.

The uses/2 directive allows simpler predicate definitions as long as there are no conflicts between the predicates declared in the directive and the predicates defined in the object (or category) containing the directive. A predicate (or its alias if defined) cannot be listed in more than one uses/2 directive. In addition, a uses/2 directive cannot list a predicate (or its alias if defined) that is defined in the object (or category) containing the directive. Any conflicts are reported by Logtalk as compilation errors.

The object identifier argument can also be a parameter variable when using the directive in a parametric object or a parametric category. In this case, dynamic binding will necessarily be used for all listed predicates (and non-terminals). The parameter variable must be instantiated at runtime when the messages are sent. This feature simplifies experimenting with multiple implementations of the same protocol (for example, to evaluate the performance of each implementation for a particular case). It also simplifies writing tests that check multiple implementations of the same protocol.

An object (or category) can make a predicate listed in a uses/2 (or use_module/2) directive part of its protocol by simply adding a scope directive for the predicate. For example, in the statistics library we have:

:- public(modes/2).
:- uses(numberlist, [modes/2]).

Therefore, a goal such as sample::modes(Sample, Modes) implicitly calls numberlist::modes(Sample, Modes) without requiring an explicit local definition for the modes/2 predicate (which would trigger a compilation error).

Alias directive

Logtalk allows the definition of an alternative name for an inherited or imported predicate (or for an inherited or imported grammar rule non-terminal) through the use of the alias/2 directive:

:- alias(Entity, [
    Predicate1 as Alias1,
    Predicate2 as Alias2,
    ...
]).

This directive can be used in objects, protocols, or categories. The first argument, Entity, must be an entity referenced in the opening directive of the entity containing the alias/2 directive. It can be an extended or implemented protocol, an imported category, an extended prototype, an instantiated class, or a specialized class. The second argument is a list of pairs of predicate indicators (or grammar rule non-terminal indicators) using the as infix operator.

A common use for the alias/2 directive is to give an alternative name to an inherited predicate in order to improve readability. For example:

:- object(square,
    extends(rectangle)).

    :- alias(rectangle, [width/1 as side/1]).

    ...

:- end_object.

The directive allows both width/1 and side/1 to be used as messages to the object square. Thus, using this directive, there is no need to explicitly declare and define a “new” side/1 predicate. Note that the alias/2 directive does not rename a predicate, it only provides an alternative, additional name; the original name continues to be available (although it may be masked due to the default inheritance conflict mechanism).

Another common use for this directive is to solve conflicts when two inherited predicates have the same name and arity. We may want to call the predicate that is masked out by the Logtalk lookup algorithm (see the Inheritance section) or we may need to call both predicates. This is simply accomplished by using the alias/2 directive to give alternative names to masked-out or conflicting predicates. Consider the following example:

:- object(my_data_structure,
    extends(list, set)).

    :- alias(list, [member/2 as list_member/2]).
    :- alias(set,  [member/2 as set_member/2]).

    ...

:- end_object.

Assuming that both list and set objects define a member/2 predicate, without the alias/2 directives, only the definition of member/2 predicate in the object list would be visible on the object my_data_structure, as a result of the application of the Logtalk predicate lookup algorithm. By using the alias/2 directives, all the following messages would be valid (assuming a public scope for the predicates):

% uses list member/2
| ?- my_data_structure::list_member(X, L).

 % uses set member/2
| ?- my_data_structure::set_member(X, L).

% uses list member/2
| ?- my_data_structure::member(X, L).

When used this way, the alias/2 directive provides functionality similar to programming constructs of other object-oriented languages that support multi-inheritance (the most notable example probably being the renaming of inherited features in Eiffel).

Note that the alias/2 directive never hides a predicate that is visible on the entity containing the directive as a result of the Logtalk lookup algorithm. However, it may be used to make visible a predicate that otherwise would be masked by another predicate, as illustrated in the above example.

The alias/2 directive may also be used to give access to an inherited predicate, which otherwise would be masked by another inherited predicate, while keeping the original name as follows:

:- object(my_data_structure,
    extends(list, set)).

    :- alias(list, [member/2 as list_member/2]).
    :- alias(set,  [member/2 as set_member/2]).

    member(X, L) :-
        ^^set_member(X, L).

    ...

:- end_object.

Thus, when sending the message member/2 to my_data_structure, the predicate definition in set will be used instead of the one contained in list.

Documenting directive

A predicate can be documented with arbitrary user-defined information by using the info/2 directive:

:- info(Name/Arity, List).

The second argument is a list of Key is Value terms. See the Documenting section for details.

Multifile directive

A predicate can be declared multifile by using the multifile/1 directive:

:- multifile(Name/Arity).

This allows clauses for a predicate to be defined in several objects and/or categories. This is a directive that should be used with care. It’s commonly used in the definition of hook predicates. Multifile predicates (and non-terminals) may also be declared dynamic using the same predicate (or non-terminal) notation (multifile predicates are static by default).

Logtalk precludes using a multifile predicate for breaking object encapsulation by checking that the object (or category) declaring the predicate (using a scope directive) defines it also as multifile. This entity is said to contain the primary declaration for the multifile predicate. Entities containing primary multifile predicate declarations must always be compiled before entities defining clauses for those multifile predicates. The Logtalk compiler will print a warning if the scope directive is missing. Note also that the multifile/1 directive is mandatory when defining multifile predicates.

Consider the following simple example:

:- object(main).

    :- public(a/1).
    :- multifile(a/1).
    a(1).

:- end_object.

After compiling and loading the main object, we can define other objects (or categories) that contribute with clauses for the multifile predicate. For example:

:- object(other).

    :- multifile(main::a/1).
    main::a(2).
    main::a(X) :-
        b(X).

    b(3).
    b(4).

:- end_object.

After compiling and loading the above objects, you can use queries such as:

| ?- main::a(X).

X = 1 ;
X = 2 ;
X = 3 ;
X = 4
yes

Note that the order of multifile predicate clauses depends on several factors, including loading order and compiler implementation details. Therefore, your code should never assume or rely on a specific order of the multifile predicate clauses.

When a clause of a multifile predicate is a rule, its body is compiled within the context of the object or category defining the clause. This allows clauses for multifile predicates to call local object or category predicates. But the values of the sender, this, and self in the implicit execution context are passed from the clause head to the clause body. This is necessary to ensure that these values are always valid and to allow multifile predicate clauses to be defined in categories. A call to the parameter/2 execution context methods, however, retrieves parameters of the entity defining the clause, not from the entity for which the clause is defined. The parameters of the entity for which the clause is defined can be accessed by simple unification at the clause head.

Multifile predicate rules should not contain cuts, as these may prevent other clauses for the predicate from being used by callers. The compiler prints by default a warning when a cut is found in a multifile predicate definition.

Local calls to the database methods from multifile predicate clauses defined in an object take place in the object’s own database instead of the database of the entity holding the multifile predicate primary declaration. Similarly, local calls to the expand_term/2 and expand_goal/2 methods from a multifile predicate clause look for clauses of the term_expansion/2 and goal_expansion/2 hook predicates starting from the entity defining the clause instead of the entity holding the multifile predicate primary declaration. Local calls to the current_predicate/1, predicate_property/2, and current_op/3 methods from multifile predicate clauses defined in an object also lookup predicates and their properties in the object’s own database instead of the database of the entity holding the multifile predicate primary declaration.

Coinductive directive

A predicate can be declared coinductive by using the coinductive/1 directive. For example:

:- coinductive(comember/2).

Logtalk support for coinductive predicates is experimental and requires a backend Prolog compiler with minimal support for cyclic terms. The value of the read-only coinduction flag is set to supported for the backend Prolog compilers providing that support.

Synchronized directive

A predicate can be declared synchronized by using the synchronized/1 directive. For example:

:- synchronized(write_log_entry/2).
:- synchronized([produce/1, consume/1]).

See the section on synchronized predicates for details.

Defining predicates

Object predicates

We define object predicates as we have always defined Prolog predicates, the only difference being that we have four more control structures (the three message-sending operators plus the external call operator) to play with. For example, if we wish to define an object containing common utility list predicates like append/2 or member/2 we could write something like:

:- object(list).

    :- public(append/3).
    append([], L, L).
    append([H| T], L, [H| T2]) :-
        append(T, L, T2).

    :- public(member/2).
    member(H, [H| _]).
    member(H, [_| T]) :-
        member(H, T).

:- end_object.

Note that, abstracting from the opening and closing object directives and the scope directives, what we have written is also valid Prolog code. Calls in a predicate definition body default to the local predicates unless we use the message-sending operators or the external call operator. This simplifies conversion from plain Prolog code to Logtalk objects: often we just need to add the necessary encapsulation and scope directives to the old code.

Category predicates

A category can only contain clauses for static predicates. But there are no restrictions in declaring and calling dynamic predicates from inside a category. Because a category can be imported by multiple objects, dynamic predicates must be called either in the context of self, using the message to self control structure, (::)/1, or in the context of this (i.e., in the context of the object importing the category). For example, if we want to define a category implementing attributes using the dynamic database of self we could write:

:- category(attributes).

    :- public(get/2).
    :- public(set/2).

    :- private(attribute_/2).
    :- dynamic(attribute_/2).

    get(Var, Value) :-
        ::attribute_(Var, Value).

    set(Var, Value) :-
        ::retractall(attribute_(Var, _)),
        ::asserta(attribute_(Var, Value).

:- end_category.

In this case, the get/2 and set/2 predicates will always access/update the correct definition, contained in the object receiving the messages.

In alternative, if we want a category implementing attributes using the dynamic database of this, we would write instead:

:- category(attributes).

    :- public(get/2).
    :- public(set/2).

    :- private(attribute_/2).
    :- dynamic(attribute_/2).

    get(Var, Value) :-
        attribute_(Var, Value).

    set(Var, Value) :-
        retractall(attribute_(Var, _)),
        asserta(attribute_(Var, Value).

:- end_category.

In this case, each object importing the category will have its own clauses for the attribute_/2 private dynamic predicate.

Meta-predicates

Meta-predicates may be defined inside objects and categories as any other predicate. A meta-predicate is declared using the meta_predicate/1 directive as described earlier in this section. When defining a meta-predicate, the arguments in the clause heads corresponding to the meta-arguments must be variables. All meta-arguments are called in the context of the object or category calling the meta-predicate. In particular, when sending a message that corresponds to a meta-predicate, the meta-arguments are called in the context of the object or category sending the message.

The most simple example is a meta-predicate with a meta-argument that is called as a goal. E.g. the ignore/1 built-in predicate could be defined as:

:- public(ignore/1).
:- meta_predicate(ignore(0)).

ignore(Goal) :-
   (Goal -> true; true).

The 0 in the meta-predicate template tells us that the meta-argument is a goal that will be called by the meta-predicate.

Some meta-predicates have meta-arguments that are not goals but closures. Logtalk supports the definition of meta-predicates that are called with closures instead of goals as long as the definition uses the call/1-N built-in predicate to call the closure with the additional arguments. A classical example is a list mapping predicate:

:- public(map/2).
:- meta_predicate(map(1, *)).

map(_, []).
map(Closure, [Arg| Args]) :-
    call(Closure, Arg),
    map(Closure, Args).

Note that in this case the meta-predicate directive specifies that the closure will be extended with exactly one additional argument. When calling a meta-predicate, a closure can correspond to a user-defined predicate, a built-in predicate, a lambda expression, or a control construct.

In some cases, it is not a meta-argument but one of its sub-terms that is called as a goal or used as a closure. For example:

:- public(call_all/1).
:- meta_predicate(call_all(::)).

call_all([]).
call_all([Goal| Goals]) :-
    call(Goal),
    call_all(Goals).

The :: mode indicator in the meta-predicate template allows the corresponding argument in the meta-predicate definition to be a non-variable term and instructs the compiler to look into the argument sub-terms for goal and closure meta-variables.

When a meta-predicate calls another meta-predicate, both predicates require meta_predicate/1 directives. For example, the map/2 meta-predicate defined above is usually implemented by exchanging the argument order to take advantage of first-argument indexing:

:- meta_predicate(map(1, *)).
map(Closure, List) :-
    map_(List, Closure).

:- meta_predicate(map_(*, 1)).
map_([], _).
map_([Head| Tail], Closure) :-
    call(Closure, Head),
    map_(Tail, Closure).

Note that Logtalk, unlike most Prolog module systems, is not based on a predicate prefixing mechanism. Thus, the meta-argument calling context is not part of the meta-argument itself.

Lambda expressions

The use of lambda expressions as meta-predicate goal and closure arguments often saves writing auxiliary predicates for the sole purpose of calling the meta-predicates. A simple example of a lambda expression is:

| ?- meta::map([X,Y]>>(Y is 2*X), [1,2,3], Ys).
Ys = [2,4,6]
yes

In this example, a lambda expression, [X,Y]>>(Y is 2*X), is used as an argument to the map/3 list mapping predicate, defined in the library object meta, in order to double the elements of a list of integers. Using a lambda expression avoids writing an auxiliary predicate for the sole purpose of doubling the list elements. The lambda parameters are represented by the list [X,Y], which is connected to the lambda goal, (Y is 2*X), by the (>>)/2 operator. The map/3 predicate calls the lambda goal with fresh/unique variables, represented by the X and Y parameters, for each pair of elements of the second and third list arguments.

Currying is supported. I.e. it is possible to write a lambda expression whose goal is another lambda expression. The above example can be rewritten as:

| ?- meta::map([X]>>([Y]>>(Y is 2*X)), [1,2,3], Ys).
Ys = [2,4,6]
yes

Lambda expressions may also contain lambda-free variables. I.e. variables that are global to the lambda expression and shared with the surrounding meta-call context. Consider the following variant of the previous example:

| ?- between(1, 3, N), meta::map({N}/[X,Y]>>(Y is N*X), [1,2,3], L).
N = 1, L = [1,2,3] ;
N = 2, L = [2,4,6] ;
N = 3, L = [3,6,9]
yes

In this case, the lambda-free variable, N, bound by the between/3 goal, is fixed across all implicit calls made by the map/3 goal.

A second example of free variables in a lambda expression using GNU Prolog as the backend compiler:

| ?- meta::map({Z}/[X,Y]>>(Z#=X+Y), [1,2,3], Zs).
Z = _#22(3..268435455)
Zs = [_#3(2..268435454),_#66(1..268435453),_#110(0..268435452)]
yes

The ISO Prolog construct {}/1 is used for representing the lambda-free variables as this representation is often associated with set representation. Note that the order of the free variables is of no consequence (on the other hand, a list is used for the lambda parameters as their order does matter).

Both lambda free variables and lambda parameters can be any Prolog term. Consider the following example by Markus Triska:

| ?- meta::map([A-B,B-A]>>true, [1-a,2-b,3-c], Zs).
Zs = [a-1,b-2,c-3]
yes

Lambda expressions can be used, as expected, in non-deterministic queries, as in the following example using SWI-Prolog as the backend compiler and Markus Triska’s CLP(FD) library:

| ?- meta::map({Z}/[X,Y]>>(clpfd:(Z#=X+Y)), Xs, Ys).
Xs = [],
Ys = [] ;
Xs = [_G1369],
Ys = [_G1378],
_G1369+_G1378#=Z ;
Xs = [_G1579, _G1582],
Ys = [_G1591, _G1594],
_G1582+_G1594#=Z,
_G1579+_G1591#=Z ;
Xs = [_G1789, _G1792, _G1795],
Ys = [_G1804, _G1807, _G1810],
_G1795+_G1810#=Z,
_G1792+_G1807#=Z,
_G1789+_G1804#=Z ;
...

As illustrated by the above examples, lambda expression syntax reuses the ISO Prolog construct {}/1 and the standard operators (/)/2 and (>>)/2, thus avoiding defining new operators, which is always tricky for a portable system such as Logtalk. The operator (>>)/2 was chosen as it suggests an arrow, similar to the syntax used in other languages such as OCaml and Haskell to connect lambda parameters with lambda functions. This syntax was also chosen in order to simplify parsing, error checking, and compilation of lambda expressions. The full specification of the lambda expression syntax can be found in the language grammar.

The compiler checks whenever possible that all variables in a lambda expression are either classified as free variables or as lambda parameters. Non-classified variables in a lambda goal (including any anonymous variables) should be regarded as a programming error. The compiler also checks whenever possible if a variable is classified as both a free variable and a lambda parameter. There are a few cases where a variable playing a dual role is intended, but, in general, this also results from a programming error. A third check verifies that no lambda parameter variable is used elsewhere in a clause. Such cases are either programming errors, when the variable appears before the lambda expression, or bad programming style, when the variable is used after the lambda expression. These linter warnings are controlled by the lambda_variables flag. Note that the dynamic features of the language and lack of sufficient information at compile-time may prevent the compiler from checking all uses of lambda expressions. To improve linter coverage, compile code using lambda expressions with the optimize flag turned on, as that will result in additional cases of meta-arguments being evaluated for possible optimizations.

Warning

Variables listed in lambda parameters must not be shared with other goals in a clause.

An optimizing meta-predicate and lambda expression compiler, based on the term-expansion mechanism, is provided as a standard library for practical performance.

A common use of lambda expressions as closure meta-arguments is to workaround closures always being extended by appending additional arguments to construct a goal. For example, assume that we want to filter a list of atoms by a given length. We can use the standard atom_length/2 predicate despite the argument order by writing:

filter(Length, Atoms, Filtered) :-
    meta::include({Length}/[Atom]>>atom_length(Atom,Length), Atoms, Filtered).

But Logtalk supports a faster alternative by using predicate aliases to change the argument order when calling library or built-in predicates:

:- uses(user, [
   atom_length(Atom, Length) as length_atom(Length, Atom)
]).

filter(Length, Atoms, Filtered) :-
    meta::include(length_atom(Length), Atoms, Filtered).

In this case, the performance is no longer dependent on compiling away lambda expressions. The resulting code is also easier to read (and thus debug and maintain). But the uses/2 directive is implicitly defining an auxiliary predicate, which is exactly what we wanted to avoid in the first place by using a lambda expression.

Redefining built-in predicates

Logtalk built-in predicates and Prolog built-in predicates can be redefined inside objects and categories. Although the redefinition of Logtalk built-in predicates should be avoided, the support for redefining Prolog built-in predicates is a practical requirement given the different sets of proprietary built-in predicates provided by backend Prolog systems.

The compiler supports a redefined_built_ins flag, whose default value is silent, that can be set to warning to alert the user of any redefined Logtalk or Prolog built-in predicate.

The redefinition of Prolog built-in predicates can be combined with the conditional compilation directives when writing portable applications where some of the supported backends don’t provide a built-in predicate found in the other backends. As an example, consider the de facto standard msort/2 predicate (which sorts a list while keeping duplicates). This predicate is provided as a built-in predicate in most but not all backends. The list library object includes the code:

:- if(predicate_property(msort(_, _), built_in)).

    msort(List, Sorted) :-
        {msort(List, Sorted)}.

:- else.

    length(List, Length) :-
        ...

:- endif.

I.e. the object will use the built-in predicate when available. Otherwise, it will use the predicate definition provided by the list object.

The redefinition of built-in predicates can also be accomplished using predicate shorthands. This can be useful when porting code while minimizing the changes. For example, assume that existing code uses the format/2 de facto standard predicate for writing messages. To convert the code to use the message printing mechanism, we could write:

:- uses(logtalk, [
    print_message(comment, core, Format+Arguments) as format(Format, Arguments)
]).

process(Crate, Contents) :-
    format('Processing crate ~w...', [Crate]),
    ...,
    format('Filing with ~w...', [Contents]),
    ....

The predicate shorthand instructs the compiler to rewrite all format/2 goals as logtalk::print_message/3 goals, thus allowing us to reuse the code without changes.

Definite clause grammar rules

Definite clause grammar rules (DCGs) provide a convenient notation to represent the parsing and rewrite rules common of most grammars in Prolog. In Logtalk, definite clause grammar rules can be encapsulated in objects and categories. Currently, the ISO/IEC WG17 group is working on a draft specification for a definite clause grammars Prolog standard. Therefore, in the meantime, Logtalk follows the common practice of Prolog compilers supporting definite clause grammars, extending it to support calling grammar rules contained in categories and objects. A common example of a definite clause grammar is the definition of a set of rules for parsing simple arithmetic expressions:

:- object(calculator).

    :- public(parse/2).

    parse(Expression, Value) :-
        phrase(expr(Value), Expression).

    expr(Z) --> term(X), "+", expr(Y), {Z is X + Y}.
    expr(Z) --> term(X), "-", expr(Y), {Z is X - Y}.
    expr(X) --> term(X).

    term(Z) --> number(X), "*", term(Y), {Z is X * Y}.
    term(Z) --> number(X), "/", term(Y), {Z is X / Y}.
    term(Z) --> number(Z).

    number(C) --> "+", number(C).
    number(C) --> "-", number(X), {C is -X}.
    number(X) --> [C], {0'0 =< C, C =< 0'9, X is C - 0'0}.

:- end_object.

After compiling and loading this object, we can test the grammar rules using the parse/2 message:

| ?- calculator::parse("1+2-3*4", Result).

Result = -9
yes

The non-terminals can be called from predicates using the private built-in methods phrase/2 and phrase/3 as shown in the example above. When we want to use the built-in methods phrase/2 and phrase/3, the non-terminal used as in the first argument must be within the scope of the sender. For the above example, assuming that we want the predicate corresponding to the expr//1 non-terminal to be public, the corresponding scope directive would be:

:- public(expr//1).

The // infix operator used above tells the Logtalk compiler that the scope directive refers to a grammar rule non-terminal, not to a predicate. The idea is that the predicate corresponding to the translation of the expr//1 non-terminal will have a number of arguments equal to one plus the number of additional arguments necessary for processing the implicit difference list of tokens.

In the body of a grammar rule, we can call rules that are inherited from ancestor objects, imported from categories, or contained in other objects. This is accomplished by using non-terminals as messages. Using a non-terminal as a message to self allows us to call grammar rules in categories and ancestor objects. To call grammar rules encapsulated in other objects, we use a non-terminal as a message to those objects. Consider the following example, containing grammar rules for parsing natural language sentences:

:- object(sentence,
    imports(determiners, nouns, verbs)).

    :- public(parse/2).

    parse(List, true) :-
        phrase(sentence, List).
    parse(_, false).

    sentence --> noun_phrase, verb_phrase.

    noun_phrase --> ::determiner, ::noun.
    noun_phrase --> ::noun.

    verb_phrase --> ::verb.
    verb_phrase --> ::verb, noun_phrase.

:- end_object.

The categories imported by the object would contain the necessary grammar rules for parsing determiners, nouns, and verbs. For example:

:- category(determiners).

    :- private(determiner//0).

    determiner --> [the].
    determiner --> [a].

:- end_category.

Along with the message-sending operators ((::)/1, (::)/2, and (^^)/1), we may also use other control constructs such as (<<)/2, (\+)/1, !/0, (;)/2, (->)/2, {}/1, call//1-N, and catch/3 in the body of a grammar rule. When using a backend Prolog compiler that supports modules, we may also use the (:)/2 control construct.

Warning

The semantics of (\+)/1 and (->)/2 control constructs in grammar rules with a terminal or a non-terminal in the first argument are problematic due to unrestricted lookahead that may or may not be valid depending on the grammar rule implicit arguments. By default, the linter will print warnings for such calls (controlled by the grammar_rules flag). Preferably restrict the use of the (\+)/1 control construct to {}/1 arguments and the use of the (->)/2 control construct to {}/1 test arguments.

In addition, grammar rules may contain meta-calls (a variable taking the place of a non-terminal), which are translated to calls of the built-in method phrase//1. The meta_non_terminal/1 directive allows the declaration of non-terminals that have arguments that are meta-called from grammar rules. For example:

:- meta_non_terminal(zero_or_more(1, *)).

zero_or_more(Closure, [Terminal| Terminals]) -->
    call(Closure, Terminal), !, zero_or_more(Closure, Terminals).
zero_or_more(_, []) -->
    [].

You may have noticed that Logtalk defines {}/1 as a control construct for bypassing the compiler when compiling a clause body goal. As exemplified above, this is the same control construct that is used in grammar rules for bypassing the expansion of rule body goals when a rule is converted into a clause. Both control constructs can be combined in order to call a goal from a grammar rule body, while bypassing at the same time the Logtalk compiler. Consider the following example:

bar :-
    write('bar predicate called'), nl.


:- object(bypass).

    :- public(foo//0).

    foo --> {{bar}}.

:- end_object.

After compiling and loading this code, we may try the following query:

| ?- logtalk << phrase(bypass::foo, _, _).

bar predicate called
yes

This is the expected result, as the expansion of the grammar rule into a clause leaves the {bar} goal untouched, which, in turn, is converted into the goal bar when the clause is compiled. Note that we tested the bypass::foo//0 non-terminal by calling the phrase/3 built-in method in the context of the logtalk built-in object. This workaround is necessary due to the Prolog backend implementation of the phrase/3 predicate not being aware of the Logtalk (::)/2 message-sending control construct semantics.

A grammar rule non-terminal may be declared as dynamic or discontiguous, as any object predicate, using the same Name//Arity notation illustrated above for the scope directives. In addition, grammar rule non-terminals can be documented using the info/2 directive, as in the following example:

:- public(sentence//0).

:- info(sentence//0, [
    comment is 'Rewrites sentence into noun and verb phrases.'
]).

Note

Future Logtalk versions may compile grammar rules differently from Prolog traditional compilation to prevent name clashes between non-terminals and predicates. Therefore, you should always call non-terminals from predicates using the phrase/2-3 built-in methods and always call predicates from grammar rules using the call//1 built-in method. This recommended practice, besides making your code forward compatible with future Logtalk versions, also makes the code more clear. The linter prints warnings when these guidelines are not followed (notably, when a predicate is called as a non-terminal or a non-terminal is called as a predicate).

Built-in methods

Built-in methods are built-in object and category predicates. These include methods to access message execution context, to find sets of solutions, to inspect objects, for database handling, for term and goal expansion, and for printing messages. Some of them are counterparts to standard Prolog built-in predicates that take into account Logtalk semantics. Similar to Prolog built-in predicates, built-in methods cannot be redefined.

Logic and control methods

The !/0, true/0, fail/0, false/0, and repeat/0 standard control constructs and logic predicates are interpreted as built-in public methods and thus can be used as messages to any object. In practice, they are only used as messages when sending multiple messages to the same object (see the section on message broadcasting).

Execution context methods

Logtalk defines five built-in private methods to access an object execution context. These methods are in the common usage scenarios translated to a single unification performed at compile-time with a clause head context argument. Therefore, they can be freely used without worrying about performance penalties. When called from inside a category, these methods refer to the execution context of the object importing the category. These methods are private and cannot be used as messages to objects.

To find the object that received the message under execution, we may use the self/1 method. We may also retrieve the object that has sent the message under execution using the sender/1 method.

The method this/1 enables us to retrieve the name of the object for which the predicate clause whose body is being executed is defined instead of using the name directly. This helps to avoid breaking the code if we decide to change the object name and forget to change the name references. This method may also be used from within a category. In this case, the method returns the object importing the category on whose behalf the predicate clause is being executed.

Here is a short example including calls to these three object execution context methods:

:- object(test).

    :- public(test/0).

    test :-
        this(This),
        write('Calling predicate definition in '),
        writeq(This), nl,
        self(Self),
        write('to answer a message received by '),
        writeq(Self), nl,
        sender(Sender),
        write('that was sent by '),
        writeq(Sender), nl, nl.

:- end_object.


:- object(descendant,
    extends(test)).

:- end_object.

After compiling and loading these two objects, we can try the following goal:

| ?- descendant::test.

Calling predicate definition in test
to answer a message received by descendant
that was sent by user
yes

Note that the goals self(Self), sender(Sender), and this(This), being translated to unifications with the clause head context arguments at compile-time, are effectively removed from the clause body. Therefore, a clause such as:

predicate(Arg) :-
    self(Self),
    atom(Arg),
    ... .

is compiled with the goal atom(Arg) as the first condition on the clause body. As such, the use of these context execution methods does not interfere with the optimizations that some Prolog compilers perform when the first clause body condition is a call to a built-in type-test predicate or a comparison operator.

For parametric objects and categories, the method parameter/2 enables us to retrieve current parameter values (see the section on parametric objects for a detailed description). For example:

:- object(block(_Color)).

    :- public(test/0).

    test :-
        parameter(1, Color),
        write('Color parameter value is '),
        writeq(Color), nl.

:- end_object.

An alternative to the parameter/2 predicate is to use parameter variables:

:- object(block(_Color_)).

    :- public(test/0).

    test :-
        write('Color parameter value is '),
        writeq(_Color_), nl.

:- end_object.

After compiling and loading either version of the object, we can try the following goal:

| ?- block(blue)::test.

Color parameter value is blue
yes

Calls to the parameter/2 method are translated to a compile-time unification when the second argument is a variable. When the second argument is bound, the calls are translated to a call to the built-in predicate arg/3.

When type-checking predicate arguments, it is often useful to include the predicate execution context when reporting an argument error. The context/1 method provides access to that context. For example, assume a predicate foo/2 that takes an atom and an integer as arguments. We could type-check the arguments by writing (using the library type object):

foo(A, N) :-
    % type-check arguments
    context(Context),
    type::check(atom, A, Context),
    type::check(integer, N, Context),
    % arguments are fine; go ahead
    ... .

Error handling and throwing methods

Besides the catch/3 and throw/1 methods inherited from Prolog, Logtalk also provides a set of convenience methods to throw standard error/2 exception terms: instantiation_error/0, uninstantiation_error/1, type_error/2, domain_error/2, existence_error/2, permission_error/3, representation_error/1, evaluation_error/1, resource_error/1, syntax_error/1, and system_error/0. When using these methods, the second argument of the error/2 exception term is bound to the execution context (as it would be provided by the context/1 method).

Database methods

Logtalk provides a set of built-in methods for object database handling similar to the usual database Prolog predicates: abolish/1, asserta/1, assertz/1, clause/2, retract/1, and retractall/1. These methods always operate on the database of the object receiving the corresponding message. When called locally, these predicates take into account any uses/2 or use_module/2 directives that refer to the dynamic predicate being handled. For example, in the following object, the clauses for the data/1 predicate are retracted and asserted in user due to the uses/2 directive:

:- object(an_object).

    :- uses(user, [data/1]).

    :- public(some_predicate/1).
    some_predicate(Arg) :-
        retractall(data(_)),
        assertz(data(Arg)).

:- end_object.

When working with dynamic grammar rule non-terminals, you may use the built-in method expand_term/2 convert a grammar rule into a clause that can then be used with the database methods.

Logtalk also supports asserta/2, assertz/2, clause/3, and erase/1 built-in methods when run with a backend that supports the corresponding legacy built-in predicates that work with clause references.

Meta-call methods

Logtalk supports the generalized call/1-N meta-predicate. This built-in private meta-predicate must be used in the implementation of meta-predicates that work with closures instead of goals. In addition, Logtalk supports the built-in private meta-predicates ignore/1, once/1, and (\+)/1. These methods cannot be used as messages to objects.

All solutions methods

The usual all solutions meta-predicates are built-in private methods in Logtalk: bagof/3, findall/3, findall/4, and setof/3. There is also a forall/2 method that implements generate-and-test loops. These methods cannot be used as messages to objects.

Reflection methods

Logtalk provides a comprehensive set of built-in predicates and built-in methods for querying about entities and predicates. Some of the information, however, requires that the source files are compiled with the source_data flag turned on.

The reflection API supports two different views on entities and their contents, which we may call the transparent box view and the black box view. In the transparent box view, we look into an entity disregarding how it will be used and returning all information available on it, including predicate declarations and predicate definitions. This view is supported by the entity property built-in predicates. In the black box view, we look into an entity from a usage point of view using built-in methods for inspecting object operators and predicates that are within scope from where we are making the call: current_op/3, which returns operator specifications; predicate_property/2, which returns predicate properties; and current_predicate/1, which enables us to query about user-defined predicate definitions. See below for a more detailed description of these methods.

Definite clause grammar parsing methods and non-terminals

Logtalk supports two definite clause grammar parsing built-in private methods, phrase/2 and phrase/3, with definitions similar to the predicates with the same name found on most Prolog compilers that support definite clause grammars. These methods cannot be used as messages to objects.

Logtalk also supports phrase//1, call//1-N, and eos//0 built-in non-terminals. The call//1-N non-terminals take a closure (which can be a lambda expression) plus zero or more additional arguments and are processed by appending the input list of tokens and the list of remaining tokens to the arguments.

Predicate properties

We can find the properties of visible predicates by calling the predicate_property/2 built-in method. For example:

| ?- bar::predicate_property(foo(_), Property).

Note that this method takes into account the predicate’s scope declarations. In the above example, the call will only return properties for public predicates.

An object’s set of visible predicates is the union of all the predicates declared for the object with all the built-in methods and all the Logtalk and Prolog built-in predicates.

The following predicate properties are supported:

scope(Scope)

The predicate scope (useful for finding the predicate scope with a single call to predicate_property/2)

public, protected, private

The predicate scope (useful for testing if a predicate has a specific scope)

static, dynamic

All predicates are either static or dynamic (note, however, that a dynamic predicate can only be abolished if it was dynamically declared)

logtalk, prolog, foreign

A predicate can be defined in Logtalk source code, Prolog code, or in foreign code (e.g., in C)

built_in

The predicate is a built-in predicate

multifile

The predicate is declared multifile (i.e., it can have clauses defined in multiple files or entities)

meta_predicate(Template)

The predicate is declared as a meta-predicate with the specified template

coinductive(Template)

The predicate is declared as a coinductive predicate with the specified template

declared_in(Entity)

The predicate is declared (using a scope directive) in the specified entity

defined_in(Entity)

The predicate definition is looked up in the specified entity (note that this property does not necessarily imply that clauses for the predicate exist in Entity; the predicate can simply be false as per the closed-world assumption)

redefined_from(Entity)

The predicate is a redefinition of a predicate definition inherited from the specified entity

non_terminal(NonTerminal//Arity)

The predicate resulted from the compilation of the specified grammar rule non-terminal

alias_of(Predicate)

The predicate (name) is an alias for the specified predicate

alias_declared_in(Entity)

The predicate alias is declared in the specified entity

synchronized

The predicate is declared as synchronized (i.e., it’s a deterministic predicate synchronized using a mutex when using a backend Prolog compiler supporting a compatible multi-threading implementation)

Some properties are only available when the entities are defined in source files and when those source files are compiled with the source_data flag turned on:

recursive

The predicate definition includes at least one recursive rule

inline

The predicate definition is inlined

auxiliary

The predicate is not user-defined but rather automatically generated by the compiler or the term-expansion mechanism

mode(Mode, Solutions)

Instantiation, type, and determinism mode for the predicate (which can have multiple modes)

info(ListOfPairs)

Documentation key-value pairs as specified in the user-defined info/2 directive

number_of_clauses(N)

The number of clauses for the predicate existing at compilation time (note that this property is not updated at runtime when asserting and retracting clauses for dynamic predicates)

number_of_rules(N)

The number of rules for the predicate existing at compilation time (note that this property is not updated at runtime when asserting and retracting clauses for dynamic predicates)

declared_in(Entity, Line)

The predicate is declared (using a scope directive) in the specified entity in a source file at the specified line (if applicable)

defined_in(Entity, Line)

The predicate is defined in the specified entity in a source file at the specified line (if applicable)

redefined_from(Entity, Line)

The predicate is a redefinition of a predicate definition inherited from the specified entity, which is defined in a source file at the specified line (if applicable)

alias_declared_in(Entity, Line)

The predicate alias is declared in the specified entity in a source file at the specified line (if applicable)

The properties declared_in/1-2, defined_in/1-2, and redefined_from/1-2 do not apply to built-in methods and Logtalk or Prolog built-in predicates. Note that if a predicate is declared in a category imported by the object, it will be the category name — not the object name — that will be returned by the property declared_in/1. The same is true for protocol declared predicates.

Some properties, such as line numbers, are only available when the entity holding the predicates is defined in a source file compiled with the source_data flag turned on. Moreover, line numbers are only supported in backend Prolog compilers that provide access to the start line of a read term. When such support is not available, the value -1 is returned for the start and end lines.

Finding declared predicates

We can find, by backtracking, all visible user predicates by calling the current_predicate/1 built-in method. This method takes into account predicate scope declarations. For example, the following call will only return user predicates that are declared public:

| ?- some_object::current_predicate(Name/Arity).

The predicate property non_terminal/1 may be used to retrieve all grammar rule non-terminals declared for an object. For example:

current_non_terminal(Object, Name//Args) :-
    Object::current_predicate(Name/Arity),
    functor(Predicate, Functor, Arity),
    Object::predicate_property(Predicate, non_terminal(Name//Args)).

Usually, the non-terminal and the corresponding predicate share the same functor, but users should not rely on this always being true.

Calling Prolog predicates

Logtalk is designed for both robustness and portability. In the context of calling Prolog predicates, robustness requires that the compilation of Logtalk source code must not have accidental dependencies on Prolog code that happens to be loaded at the time of the compilation. One immediate consequence is that only Prolog built-in predicates are visible from within objects and categories. But Prolog systems provide a widely diverse set of built-in predicates, easily raising portability issues. Relying on non-standard predicates is often unavoidable, however, due to the narrow scope of Prolog standards. Logtalk applications may also require calling user-defined Prolog predicates, either in user or in Prolog modules.

Calling Prolog built-in predicates

In predicate clauses and object initialization/1 directives, predicate calls that are not prefixed with a message-sending, super call, or module qualification operator (::, ^^, or :), are compiled to either calls to local predicates or as calls to Logtalk/Prolog built-in predicates. A predicate call is compiled as a call to a local predicate if the object (or category) contains a scope directive, a multifile directive, a dynamic directive, or a definition for the called predicate. When that is not the case, the compiler checks if the call corresponds to a Logtalk or Prolog built-in predicate. Consider the following example:

foo :-
    ...,
    write(bar),
    ...

The call to the write/1 predicate will be compiled as a call to the corresponding Prolog standard built-in predicate unless the object (or category) containing the above definition also contains a predicate named write/1 or a directive for the predicate.

When calling non-standard Prolog built-in predicates or using non-standard Prolog arithmetic functions, we may run into portability problems while trying your applications with different backend Prolog compilers. We can use the compiler portability flag to generate warnings for calls to non-standard predicates and arithmetic functions. We can also help document those calls using the uses/2 directive. For example, a few Prolog systems provide an atom_string/2 non-standard predicate. We can write (in the object or category calling the predicate):

:- uses(user, [atom_string/2])

This directive is based on the fact that built-in predicates are visible in plain Prolog (i.e., in user). Besides helping to document the dependency on a non-standard built-in predicate, this directive will also silence the compiler portability warning.

Calling Prolog non-standard built-in meta-predicates

Prolog built-in meta-predicates may only be called locally within objects or categories, i.e. they cannot be used as messages. Compiling calls to non-standard, Prolog built-in meta-predicates can be tricky, however, as there is no standard way of checking if a built-in predicate is also a meta-predicate and finding out which are its meta-arguments. But Logtalk supports overriding the original meta-predicate template when not programmatically available or usable. For example, assume a det_call/1 Prolog built-in meta-predicate that takes a goal as argument. We can add to the object (or category) calling it the directive:

:- meta_predicate(user::det_call(0)).

Another solution is to explicitly declare non-standard built-in Prolog meta-predicates in the corresponding adapter file using the internal predicate '$lgt_prolog_meta_predicate'/3. For example:

'$lgt_prolog_meta_predicate'(det_call(_), det_call(0), predicate).

The third argument can be either the atom predicate or the atom control_construct, a distinction that is useful when compiling in debug mode.

Calling Prolog foreign predicates

Prolog systems often support defining foreign predicates, i.e. predicates defined using languages other than Prolog using a foreign language interface. There isn’t, however, any standard for defining, making available, and recognizing foreign predicates. From a Logtalk perspective, the two most common scenarios are calling a foreign predicate (from within an object or a category) and making a set of foreign predicates available as part of an object (or category) protocol. Assuming, as this is the most common case, that foreign predicates are globally visible once made available (using a Prolog system-specific loading or linking procedure), we can simply call them as user-defined plain predicates, as explained in the next section. When defining an object (or category) that makes available foreign predicates, the advisable solution is to name the predicates after the object (or category) and then define object (or category) predicates that call the foreign predicates. Most backend adapter files include support for recognizing foreign predicates that allows the Logtalk compiler to inline calls to the predicates (thus avoiding call indirection overheads).

Calling Prolog user-defined plain predicates

User-defined Prolog plain predicates (i.e., predicates that are not defined in a Prolog module) can be called from within objects or categories by sending the corresponding message to user. For example:

foo :-
    ...,
    user::bar,
    ...

In alternative, we can use the uses/2 directive and write:

:- uses(user, [bar/0]).

foo :-
    ...,
    bar,
    ...

Note that user is a pseudo-object in Logtalk containing all predicate definitions that are not encapsulated (either in a Logtalk entity or a Prolog module).

When the Prolog predicate is not a meta-predicate, we can also use the {}/1 compiler bypass control construct. For example:

foo :-
    ...,
    {bar},
    ...

But note that in this case the reflection API will not record the dependency of the foo/0 predicate on the Prolog bar/0 predicate as we are effectively bypassing the compiler.

Calling Prolog module predicates

Prolog module predicates can be called from within objects or categories by using explicit qualification. For example:

foo :-
    ...,
    module:bar,
    ...

You can also use the use_module/2 directive to call the module predicates using implicit qualification:

:- use_module(module, [bar/0]).

foo :-
    ...,
    bar,
    ...

Note that the first argument of the use_module/2 directive, when used within an object or a category, is a module name, not a file specification (also be aware that Prolog modules are sometimes defined in files with names that differ from the module names).

As loading a Prolog module varies between Prolog systems, the actual loading directive or goal is preferably done from the application loader file. An advantage of this approach is that it contributes to a clean separation between loading and using a resource, with the loader file being the central point that loads all application resources (complex applications often use a hierarchy of loader files, but the main idea remains the same).

As an example, assume that we need to call predicates defined in a CLP(FD) Prolog library, which can be loaded using library(clpfd) as the file specification. In the loader file, we would add:

:- use_module(library(clpfd), []).

Specifying an empty import list is often used to avoid adding the module-exported predicates to plain Prolog. In the objects and categories we can then call the library predicates, using implicit or explicit qualification, as explained. For example:

:- object(puzzle).

    :- public(puzzle/1).

    :- use_module(clpfd, [
        all_different/1, ins/2, label/1,
        (#=)/2, (#\=)/2,
        op(700, xfx, #=), op(700, xfx, #\=)
    ]).

    puzzle([S,E,N,D] + [M,O,R,E] = [M,O,N,E,Y]) :-
        Vars = [S,E,N,D,M,O,R,Y],
        Vars ins 0..9,
        all_different(Vars),
                  S*1000 + E*100 + N*10 + D +
                  M*1000 + O*100 + R*10 + E #=
        M*10000 + O*1000 + N*100 + E*10 + Y,
        M #\= 0, S #\= 0,
        label([M,O,N,E,Y]).

:- end_object.

Warning

The actual module code must be loaded prior to the compilation of Logtalk source code that uses it. In particular, programmers should not expect that the module be auto-loaded (including when using a backend Prolog compiler that supports an auto-loading mechanism).

The module identifier argument can also be a parameter variable when using the directive in a parametric object or a parametric category. In this case, dynamic binding will necessarily be used for all listed predicates (and non-terminals). The parameter variable must be instantiated at runtime when the calls are made.

Logtalk supports the declaration of predicate aliases and predicate shorthands in use_module/2 directives used within objects and categories. For example, the ECLiPSe IC Constraint Solvers define a (::)/2 variable domain operator that clashes with the Logtalk (::)/2 message-sending operator. We can solve the conflict by writing:

:- use_module(ic, [(::)/2 as ins/2]).

With this directive, calls to the ins/2 predicate alias will be automatically compiled by Logtalk to calls to the (::)/2 predicate in the ic module.

Calling Prolog module meta-predicates

The Logtalk library provides implementations of common meta-predicates, which can be used in place of module meta-predicates (e.g., list mapping meta-predicates). If that is not the case, the Logtalk compiler may need help to understand the module meta-predicate templates. Despite some recent progress in standardization of the syntax of meta_predicate/1 directives and of the meta_predicate/1 property returned by the predicate_property/2 reflection predicate, portability is still a major problem. Thus, Logtalk allows the original meta_predicate/1 directive to be overridden with a local directive that Logtalk can make sense of. It also allows providing a meta_predicate/1 directive when it’s missing from the module defining the meta-predicate. Note that Logtalk is not based on a predicate prefixing mechanism as found in module systems. This fundamental difference precludes an automated solution at the Logtalk compiler level.

As an example, assume that you want to call from an object (or a category) a module meta-predicate with the following meta-predicate directive:

:- module(foo, [bar/2]).

:- meta_predicate(bar(*, :)).

The : meta-argument specifier is ambiguous. It tell us that the second argument of the meta-predicate is module sensitive, but it does not tell us how. Some legacy module libraries and some Prolog systems use : to mean 0 (i.e., a meta-argument that will be meta-called). Some others use : for meta-arguments that are not meta-called but that still need to be augmented with module information. Whichever the case, the Logtalk compiler doesn’t have enough information to unambiguously parse the directive and correctly compile the meta-arguments in the meta-predicate call. Therefore, the Logtalk compiler will generate an error stating that : is not a valid meta-argument specifier when trying to compile a foo:bar/2 goal. There are two alternative solutions for this problem. The advised solution is to override the meta-predicate directive by writing, inside the object (or category) where the meta-predicate is called:

:- meta_predicate(foo:bar(*, *)).

or:

:- meta_predicate(foo:bar(*, 0)).

depending on the true meaning of the second meta-argument. The second alternative, only usable when the meta-argument can be handled as a normal argument, is to simply use the {}/1 compiler bypass control construct to call the meta-predicate as-is:

... :- {foo:bar(..., ...)}, ...

The downside of this alternative is that it hides the dependency on the module library from the reflection API and thus from the developer tools.

Defining Prolog multifile predicates

Some Prolog module libraries, e.g. constraint packages, expect clauses for some library predicates to be defined in other modules. This is accomplished by declaring the library predicate multifile and by explicitly prefixing predicate clause heads with the library module identifier. For example:

:- multifile(clpfd:run_propagator/2).
clpfd:run_propagator(..., ...) :-
    ...

Logtalk supports the definition of Prolog module multifile predicates in objects and categories. While the clause head is compiled as-is, the clause body is compiled in the same way as a regular object or category predicate, thus allowing calls to local object or category predicates. For example:

:- object(...).

    :- multifile(clpfd:run_propagator/2).
    clpfd:run_propagator(..., ...) :-
        % calls to local object predicates
        ...

:- end_object.

The Logtalk compiler will print a warning if the multifile/1 directive is missing. These multifile predicates may also be declared dynamic using the same Module:Name/Arity notation.

Asserting and retracting Prolog predicates

To assert and retract clauses for Prolog dynamic predicates, we can use an explicitly qualified module argument. For example:

:- object(...).

    :- dynamic(m:bar/1).

    foo(X) :-
        retractall(m:bar(_)),
        assertz(m:bar(X)),
        ...

:- end_object.

In alternative, we can use use_module/2 directives to declare the module predicates. For example:

:- object(...).

    :- use_module(m, [bar/1]).
    :- dynamic(m:bar/1).

    foo(X) :-
        % retract and assert bar/1 clauses in module m
        retractall(bar(_)),
        assertz(bar(X)),
        ...

:- end_object.

When the Prolog dynamic predicates are defined in user, the recommended and most portable practice (as not all backends support a module system) is to use a uses/2 directive:

:- object(...).

    :- uses(user, [bar/1]).
    :- dynamic(user::bar/1).

    foo(X) :-
        % retract and assert bar/1 clauses in user
        retractall(bar(_)),
        assertz(bar(X)),
        ...

:- end_object.

Note that in the alternatives using uses/2 or use_module/2 directives, the argument of the database handling predicates must be known at compile-time. If that is not the case, you must use either an explicitly-qualified argument or the {}/1 control construct instead. For example:

:- object(...).

    add(X) :-
        % assert clause X in module m
        assertz(m:X),
        ...

    remove(Y) :-
        % retract all clauses in user whose head unifies with Y
        {retractall(Y)},
        ...

:- end_object.