## 6.2 Dealing with Prolog data

By nature, XPCE data is not Prolog data. This implies that anything passed to a XPCE method must be converted from Prolog to something suitable for XPCE . A natural mapping with fast and automatic translation is defined for atoms, and numbers (both integers and floating point). As we have seen in section 2, compound terms are translated into instances using the functor-name as class-name.

In XPCE 5.0 we added the possibility to embed arbitrary Prolog data in an object. There are three cases where Prolog data is passed natively embedded in a instance of the class prolog_term.

- Explicit usage of `prolog(Data)`
  By tagging a Prolog term using the functor prolog/1 , Data is embedded in an instance of prolog_term. This term is passed unaltered unless it is passed to a method that does not accept the type `Any`, in which case translation to an object is enforced.
- When passed to a method typed `Prolog`
  Prolog defined methods and instance-variables (see section 7) can define their type as `Prolog`. In this case the data is packed in a prolog_term object.
- When passed to a method typed `unchecked`
  A few methods in the system don't do type-checking themselves.

We will explain the complications using examples. First we create a code object:

    1 ?- new(@m, and(message(@prolog, write, @arg1),
                     message(@prolog, nl))).

This code object will print the provided argument in the Prolog window followed by a newline:

    2 ?- send(@m, forward, hello).
    hello

From this example one might expect that XPCE is transparent to Prolog data. This is true for integers, floats and atoms as these have a natural representation in both languages. However:

    3 ?- send(@m, forward, chain(hello)).
    @774516
    4 ?- send(@m, forward, 3 + 4).
    7
    5 ?- send(@m, forward, [hello, world]).
    @608322

In all these examples the argument is a Prolog compound term which ---according to the definition of send/3--- is translated into a XPCE instance of the class of the principal functor. In 3) this is an instance of class chain. In 4) this is an instance of class +. Class + however is a subclass of the XPCE class function and function objects are evaluated when given to a method that does not accept a function-type argument. Example 5) illustrates that a list is converted to a XPCE chain.

We can fix these problems using the prolog/1 functor. Example 7) illustrates that also non-ground terms may be passed.

    6 ?- send(@m, forward, prolog(chain(hello))).
    chain(hello)
    7 ?- send(@m, forward, prolog(X)).
    _G335

    X = _G335

Below is a another realistic example of this misconception.

    ?- new(D, dialog('Bug')),
       send(D, append, button(verbose,
                              message(@prolog, assert,
                                      verbose(on)))),
       send(D, open).
    [PCE warning: new: Unknown class: verbose
            in: new(verbose(on)) ]

One correct solution for this task is below. An alternative is to call a predicate set_verbose/0 that realises the assertion.

    make_verbose_dialog :-
            new(D, dialog('Correct')),
            send(D, append,
                 button(verbose,
                        message(@prolog, assert,
                                prolog(verbose(on))))),
            send(D, open).

### 6.2.1 Life-time of Prolog terms in XPCE

.

XPCE is connected to Prolog through the foreign language interface. Its interface predicates are passed Prolog terms by reference. Such a reference however is only valid during the execution of the foreign procedure. So, why does the example above work? As soon as the send/3 in make_verbose_dialog/0 returns the term-reference holding the term `verbose(on)` is no longer valid!

To solve this problem, prolog_term has two alternative representations. It is created from a term-reference. After the interface call (send/3 in this case) returns, it checks whether it has created Prolog term objects. If it finds such an object that is not referenced, it destroys the object. If it finds an object that is referenced it records Prolog terms into the database and stores a reference to the recorded database record.

Summarising, Prolog terms are copied as soon as the method to which they are passed returns. Normally this is the case if a Prolog terms is used to fill an instance-variable in XPCE .