Declarativa

## InterProlog - Prolog side API

The following predicates are available from Prolog; they're grouped into 3 categories:

- Invoking Java methods from Prolog
- Object/term conversion
- Visualization of Prolog data

## Invoking Java methods from Prolog

### ipPrologEngine(E)

A reference to the PrologEngine object that launched this Prolog process.

### javaMessage( Target,Result,Exception,MessageName,ArgList,NewArgList )

Synchronously sends a message to Java object Target, waiting for its Result, catching any Exception that may occur. There are sugared versions below. In any case, arguments in ArgList must be of the proper Java-compatible types, in the form of object specifications. NewArgList contains the same objects in ArgList after the message is processed, possibly reflecting state changes.

The messages available are those documented as public constructors and methods on the Java classes being used.

### javaMessage(Target,Result,Message)

Same as javaMessage/6, but accepts the Message in methodName(arguments) format, neglects the new state of the arguments, and treats some Target cases, avoiding the need for common object specifications (accepting simpler forms): object reference (integer), class object (atom), and class variable (class-variable term)

### javaMessage(Target,Message)

Same as javaMessage(Target,_,Message)

## Object/term conversion

### buildTermModel( Term,TermModel ) / recoverTermModel( TermModel,Term )

Builds/recovers an object specification for a tree of TermModel instances, representing a Prolog Term; used by browseTerm or any code that needs to pass a full Prolog term to Java. Prolog variables are mapped into numbered instances of a dedicated Java class, VariableNode.

### ipObjectSpec(ClassName,VarsValues,Object)

If Object is a variable, bind it to an object specification similar to the prototype/example given for the class except for the differences in VarValues; otherwise VarsValue will be bound to the differences between Object and prototype.If the class is an array, VarValues will be a list simply with the array values. Otherwise VarValueList is a list [VarName1=Value1, ..., VarNameN=ValueN]. Each VarName must be an atom, the name of a Java instance variable of the classEach Value must be compatible with the corresponding object field; this is only partially checked, as not all information is available on the Prolog side.

This predicate depends on ipObjectTemplate below.

### ipObjectSpec( Name,G,Vars, examples-[SubstA,SubstB]/ANames)

One such fact is made available for each ObjectPairExample(Name,A,B) instance that the Java programmer sent to Prolog, either on startup or later through teachMoreObjects(); Name is the name of the class as given by the Java programmer; objects A and B are compared, producing a generalizing object (specification) G plus variable list Vars, that if bound to either SubstA or SubstB would become A or B resp. For the meaning of ANames see ipObjectTemplate

### ipObjectTemplate(Name,Template,ANames,TVars,TSubs)

One such fact is made available for each ObjectPairExample(Name,A,B) instance that the Java programmer sent to Prolog, either on startup or through teachMoreObjects(); object A is analysed, and all variables in its class description are replaced by logic variables, collected in TVars, with values collected in TSubs; the resulting object specification is Template; binding TVars to TSubs would make Template = A; the variable types(names) are collected in ANames.

### More about object specification

Strings and null objects have trivial specifications: string(Atom) and 'null', resp. Other cases require the use of either ipObjectSpec or ipObjectTemplate:

#### ipObjectSpec('InvisibleObject',X,[ID],_)

Object X should be the object already existing and registered as (int) ID on the Java side

#### ipObjectSpec('IPClassObject',X,[C],_)

X is the class object for class with name C

#### ipObjectSpec('IPClassVariable',X,[C,V],_)

X is the class variable V of class C

#### ipObjectSpec(boolean,X,[B],_)

X is a boolean basic type for B (which should be 1 or 0); similar ipObjectSpec facts are available for the remaining basic types: byte, small, int, long, float, double, char

#### ipObjectSpec(C,X,Variables,_)

(Generic case) New object X of class C; C must be the fully qualified class name.

## Visualization of Prolog data

### browseTerm(Term)

Creates a window with an outline (JTree) browser for Term.

### browseList(List)

Creates a window with a JList browser on List. Double-clicking on items creates a term browser window.

### browseTreeTerm(Tree)

Creates a window with a multi-pane hierarchical browser for Tree; this is assumed to be represented by some (dummy) functor with arity 2 or larger; the first argument is considered the node, the second a children list. The tree must have depth 2 or larger.

### browseLiteralInstances(GroundTerm,Instances)

Creates a window with a JTable showing a set of term instances; the GroundTerm is used to title the table columns.

Comments to: interprolog@declarativa.com
October 21, 2005