\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename manual.info
@include version.texinfo
@settitle GNU Prolog for Java @value{VERSION} Manual
@c %**end of header

@dircategory GNU Libraries
@direntry
* Prolog for Java: (gnuprologjava). GNU Prolog for Java manual.
@end direntry


@copying
This manual is for GNU Prolog for Java @value{VERSION},
which is a Java library for utilising Prolog.

Copyright @copyright{} 2010 Free Software Foundation, Inc.

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,''
and with the Back-Cover Texts as in (a) below.  A copy of the
license is included in the section entitled ``GNU Free Documentation
License.''

(a) The FSF's Back-Cover Text is: ``You have the freedom to
copy and modify this GNU manual.''
@end quotation

@end copying


@titlepage
@title GNU Prolog for Java
@subtitle for version @value{VERSION}, @value{UPDATED}
@author Daniel Thomas (@email{info-gnuprolog@gnu.org})
@insertcopying
@end titlepage

@contents

@ifnottex
@node Top
@top GNU Prolog for Java

This manual is for GNU Prolog for Java (version @value{VERSION}, @value{UPDATED}).
@end ifnottex

@menu
* Overview:: Getting started with GNU Prolog for Java
* Using the API:: Loading prolog code, constructing questions and getting answers.
* Installation:: Instructions on how to install GNU Prolog for Java
* Extending:: Instructions on how to extend GNU Prolog for Java
* GNU Free Documentation License::
* Index::
@end menu


@node Overview
@chapter Overview

GNU Prolog for Java (GPJ) is a Java library (gnu.prolog) which allows the use of Prolog from within Java programs.  It supports part 1 of the ISO standard for Prolog with some extensions. It is licenced under the LGPLv3 which can be found in the COPYING and COPYING.LIBRARY files distributed with GNU Prolog for Java (GPJ) and published by the Free Software Foundation.

For normal usage there are only a few classes which you will need to interact with.
gnu.prolog.vm.Environment which provides the core of the prolog environment.
gnu.prolog.vm.Interpreter which is what you use to run your prolog queries.
gnu.prolog.term which contains the various types of Prolog terms which exist and which you use to construct your prolog questions if you want answers (beyond SUCCESS, SUCCESS_LAST and FAIL).

The use of the API is explained in the next chapter: @ref{Using the API}.

If you wish to install GPJ then instructions are provided in the @ref{Installation} chapter.

If you wish to extend GPJ by writing your own predicates (for example to allow prolog code to make calls into your Java code) then see the chapter on @ref{Extending} GPJ.

Further documentation is provided in the README file and changes brought about by new versions will be detailed in the NEWS file. The @uref{http://www.gnu.org/software/gnuprologjava/api/ java API has javadoc based documentation}.

The gnu.prolog.demo package contains various example programs which use the API.

@node Using the API
@chapter Using the API
@menu
* Setup:: Setting up the VM to run
* Constructing Terms:: Constructing questions to ask
@end menu
You may also find the demo programs in gnu.prolog.demo which are distributed with the docs useful in showing the use of the API.

The basic usage is quite simple if you are already familiar with both Prolog and Java.

@node Setup, Constructing Terms, Using the API, Using the API
@section Setup
First construct a gnu.prolog.vm.Environment which is the core of the VM using @code{new Environment()}.

Then load any prolog files you want to which define additional predicates etc using @code{environment.ensureLoaded(AtomTerm.get(``URL of file''))} for each file. Though if you already have an gnu.prolog.vm.AtomTerm representation of the file then you can use that.

Instances of Terms should be got using their relevant @code{get(Type)} methods as we ensure only one gnu.prolog.term.Term instance for each distinct object they represent.

Then you will need to create at least one gnu.prolog.vm.Interpreter which is used to execute goals. You do this using @code{environment.createInterpreter()}. You might want multiple Interpreters if you want to run goals in multiple threads. 

Having created it you need to use it to run the initialization of any files you have loaded by using @code{env.runInitialization(interpreter);}. This ensures the goals contained in any ``:- initialization(goal).'' or ``:- goal.''s in the files you have loaded are run.

At this point the setup is completed and you can start running goals. This is done using @code{interpreter.runOnce(Term);} where Term is the goal you want to execute. This does one execution of the goal and then stops.
The construction of Terms is explained in the next section. If you need something more complex than that then you will need to use @code{goal = interpreter.prepareGoal(goalTerm); int rc = interpreter.execute(goal)} and then depending on the value of rc possibly run @code{execute(goal)} again. If you stop running @code{execute(goal)} while rc is still SUCCESS then you need to run @code{interpreter.stop(goal)}.

@node Constructing Terms
@section Constructing Terms
Terms are contained in the gnu.prolog.term package. They all extend Term and there are four basic types: @code{VariableTerm}s, @code{CompoundTerm}s and @code{AtomicTerm}s (including @code{AtomTerm}, @code{FloatTerm}, @code{IntegerTerm}).

@code{VariableTerm}s are used to represent prolog variables which are written as `A' or `X' in Prolog. During exectuion a VariableTerm may become unified with some other Term. To extract the value from a VariableTerm after execution use the #dereference() method (which is implemented by Term) which finds the value which may lie at the end of an arbitary long chain of VariableTerms.
There is a subclass of @code{VariableTerm}: @code{ChangeableTerm} which is used for Terms the value of which varies depending on the value of Prolog flags. This is currently used only for the double_quotes flag. The value of a @code{ChangeableTerm} is updated when the #dereference() method is called.
A VariableTerm can be constructed using either the @code{VariableTerm()} or the @code{VariableTerm(``VariableName'')} constructors, the second is preferable as it helps when debugging to know more easily which VariableTerm is which.

@code{CompoundTerm}s are the mechanism by which terms can be combined together and are the basic component of everything from lists to relations. They consist of a @code{CompoundTermTag} which contains the functor such as the `foo' in `foo(a,b)' or the `.' in `[a,b,c]' (by the representation of lists in Prolog) and the arity (number of arguments) such as 2 in the foo case above. This leads to the notation of foo/2 for a term with a functor of foo and an arity of 2. A @code{CompoundTerm} also has an array of arguments (Term[]). There are a variety of different constructors but @code{CompoundTerm(AtomTerm functor, Term[] args)} @code{CompoundTerm(String functor, Term[] args)} which provide the functor and the arguments are probably the most useful.

@code{AtomicTerm}s extend the abstract @code{AtomicTerm} class and are used for representing constants such as Strings and chars (@code{AtomTerm}); Numbers (@code{NumericTerm}) including doubles (@code{FloatTerm}) and integers (@code{IntegerTerm}) and finally Java Objects which can be embedded using @code{JavaObjectTerm}s. @code{AtomTerm} and @code{IntegerTerm} have static get(Type) methods rather than constructors while FloatTerm and JavaObjectTerm have normal constructors.

For example (using @code{gnu.prolog.demo.mentalarithmetic.MentalArithmetic#generateQuestion(int limit, int length)}: 
@example
// // Construct the question.
// Create variable terms so that we can pull the answers out later
VariableTerm listTerm = new VariableTerm("List");
VariableTerm answerTerm = new VariableTerm("Answer");
// Create the arguments to the compound term which is the question
Term[] args = @{ new IntegerTerm(limit), new IntegerTerm(length), listTerm, answerTerm @};
// Construct the question
CompoundTerm goalTerm = new CompoundTerm(AtomTerm.get("arithmetic"), args);
@end example

@node Installation
@chapter Installation
If you download the jar file according to the instructions on the @uref{http://www.gnu.org/software/gnuprologjava/ GNU Prolog for Java website} and put it in your path then installation should be complete.

It is our intention that GNU Prolog for Java be shipped with various distributions notably Debian and also the distributions approved of by GNU. At time of writing this had not been done. Assistance in doing this is appricated.
@c MAY-NEED-UPDATE

@node Extending
@chapter Extending

@menu
* Creating new predicates:: instructions on how to create new predicates to allow prolog code to make calls into java code.
* Adding more Prolog functionality:: instructions on how further functionality can be added to the Prolog environment by loading additional Prolog files.
@end menu

@node Creating new predicates
@section Creating new predicates
GPJ is easily extendible by creating new java predicates such as those in gnu.prolog.vm.builtins. They need to implement @code{gnu.prolog.vm.PrologCode}. @code{gnu.prolog.vm.ExecuteOnlyCode} is provided for convenience as most will not need to implement the @code{install} or @code{uninstall} methods.
@c TODO

@node Adding more Prolog functionality
@section Adding more Prolog functionality
If you wish to add further Prolog functionality, for example to support golog or to add support for DCGs then this can be done by loading the relevant Prolog files.
@menu
* Golog:: Using Prolog for situation calculus.
* Definite clause grammar (DCG):: Support for part 3 of the ISO Prolog standard (ISO/IEC DTR 13211-3:2006) ``provide convenient and simple functionality for parsing and processing text in a variety of languages.''
@end menu

@node Golog
@subsection Golog
The Cognitive Robotics Group at the University of Toronto provides a prolog file providing support for the Golog language for situation calculus (an extension of Prolog). @uref{http://www.cs.toronto.edu/cogrobo/main/systems/index.html}.
This has not yet been tested to determine whether it works with GPJ. @c TODO test whether it works
Should you have difficulty finding this file then Daniel Thomas may be able to help.

@node Definite clause grammar (DCG)
@subsection Definite clause grammar (DCG)
The ISO working group on the Prolog standard publishes a reference implementation of the part 3 draft which it should be possible to load as with any other Prolog file. @uref{http://www.sju.edu/~jhodgson/wg17/Drafts/DCGs/reference_implementation}. Should you have difficulty finding it it is also in the git repository for GPJ.
This should then provide support for part 3 of the standard. This currently does not work as it depends on some of the 2006 ISO extensions which we should have implemented for 0.3.0.

@node GNU Free Documentation License
@appendix GNU Free Documentation License

@include fdl.texinfo


@node Index
@unnumbered Index

@printindex cp

@bye
