prologj
Class PrologJ

java.lang.Object
  prologj.PrologJ

public class PrologJ

extends java.lang.Object

Top-level of the PrologJ java API This class supports static methods for performing various operations on prolog entities from within Java programs.

Constructor Summary

PrologJ()

Method Summary

static void	asserta(PrologBoundTerm term) Assert a term encapsulated in a bound term object at the front of the database
static void	asserta(java.lang.String term) Assert a term represented by a string at the front of the database
static void	assertz(PrologBoundTerm term) Assert a term encapsulated in a bound term object at the back of the database
static void	assertz(java.lang.String term) Assert a term represented by a string at the back of the database
static boolean	call(PrologBoundTerm goal) Attempt to satisfy a goal encapsulated in a bound term object once, and report only success or failure
static boolean	call(PrologBoundTerm goal, PrologContinuation continuation) Attempt to satisfy a goal encapsulated in a bound term object, with access to the bindings of the variables and the possibility of redoing it if it succeeds.
static boolean	call(java.lang.String term) Attempt to satisfy a goal represented by a string once, and report only success or failure
static boolean	call(java.lang.String term, PrologContinuation continuation) Attempt to satisfy a goal represented by a string, with access to the bindings of the variables and the possibility of redoing it if it succeeds.
static void	consult(java.io.BufferedReader bufferedReader, boolean throwImmediately) Treat a stream represented by a BufferedReader as a sequence of clauses to be asserted into the database
static void	ensure_loaded() This method is called from compiled code to ensure that this class is loaded (and therefore the system is initialized).
static boolean	interpret(java.io.BufferedReader bufferedReader, boolean failImmediately, boolean throwImmediately) Treat a stream represented by a BufferedReader as a sequence of goals to be called.
static void	listing(java.io.PrintWriter printWriter) List out the clauses of predicates of any arity for all Prolog predicates (with source code available) currently in the database, quietly skipping over private ones.
static void	listing(java.io.PrintWriter printWriter, boolean ignorePrivate) List out the clauses of predicates of any arity for all Prolog predicates (with source code available) currently in the database.
static void	listing(java.io.PrintWriter printWriter, java.lang.String name, boolean ignorePrivate) List out the clauses of Prolog predicates of any arity for a given atom (with source code available), in a form suitable for reading by consult()
static void	listing(java.io.PrintWriter printWriter, java.lang.String name, int arity, boolean ignorePrivate) List out the clauses for a given Prolog predicate or predicates (with source code available) in a form suitable for reading by consult().
static void	main(java.lang.String[] args) Main method when run as an application.
static PrologBoundTerm	makeBoundTerm(java.lang.String text) Create a bound term object that encapsulates a term, given its textual representation
static void	reconsult(java.io.BufferedReader bufferedReader, boolean throwImmediately) Treat a stream represented by a BufferedReader as a sequence of clauses to be asserted into the database, replacing any definitions for the referenced predicates that are already there
static boolean	retract(PrologBoundTerm term) Attempt to retract one instance of a term encapsulated in a bound term object from the database, and report only success or failure.
static boolean	retract(PrologBoundTerm term, PrologContinuation continuation) Attempt to retract a term encapsulated in a bound term object from the database, with access to the variable bindings for the term retracted, and the possibility of redoing to retract another matching term.
static boolean	retract(java.lang.String term) Attempt to retract one instance of a term represented by a string from the database, and report only success or failure.
static boolean	retract(java.lang.String term, PrologContinuation continuation) Attempt to retract a term represented by a string from the database, with access to the variable bindings for the term retracted, and the possibility of redoing to retract another matching term.
static void	retractall(PrologBoundTerm term) Retract all instances of a term encapsulated in a bound term object from the database
static void	retractall(java.lang.String term) Retract all instances of a term represented by a string from the database
static void	set_input(java.io.BufferedReader bufferedReader) Cause a BufferedReader to be used as default input for subsequent operations
static void	set_output(java.io.PrintWriter printWriter) Cause a PrintWriter to be used as default output for subsequent operations
static void	setBuiltinPredicateCategories(java.lang.String categories) Set the category(s) of built-in predicates that are available

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

PrologJ

public PrologJ()

Method Detail

asserta

public static void asserta(PrologBoundTerm term)
                    throws PrologException

Assert a term encapsulated in a bound term object at the front of the database

Parameters:

term - a bound term object that is a callable term

Throws:

PrologException - if this term does not have the proper form to be asserted into the database, or represents a non-modifiable predicate

asserta

public static void asserta(java.lang.String term)
                    throws PrologException

Assert a term represented by a string at the front of the database

Parameters:

term - the textual representation of the term to be asserted

Throws:

PrologException - if this term does not have the proper form to be asserted into the database, or represents a non-modifiable predicate

assertz

public static void assertz(PrologBoundTerm term)
                    throws PrologException

Assert a term encapsulated in a bound term object at the back of the database

Parameters:

term - a bound term object that is a callable term

Throws:

PrologException - if this term does not have the proper form to be asserted into the database, or represents a non-modifiable predicate

assertz

public static void assertz(java.lang.String term)
                    throws PrologException

Assert a term represented by a string at the back of the database

Parameters:

term - the textual representation of the term to be asserted

Throws:

PrologException - if this term does not have the proper form to be asserted into the database, or represents a non-modifiable predicate

call

public static boolean call(PrologBoundTerm goal,
                           PrologContinuation continuation)
                    throws PrologException

Attempt to satisfy a goal encapsulated in a bound term object, with access to the bindings of the variables and the possibility of redoing it if it succeeds.

Parameters:

goal - a bound term object that is a callable term

continuation - an object whose succeed() method is called if the goal succeeds.

Returns:

false if this method failed, or the continuation failed (returned false) and this method could not be successfully redone; true if this method succeeded and its continuation returned true.

Throws:

PrologException - if this term does not have the proper form to be called as a goal, or if execution of the goal or the continuation results in an error.

call

public static boolean call(java.lang.String term,
                           PrologContinuation continuation)
                    throws PrologException

Attempt to satisfy a goal represented by a string, with access to the bindings of the variables and the possibility of redoing it if it succeeds.

Parameters:

term - the textual representation of the goal to be called

continuation - an object whose succeed() method is called if the goal succeeds

Returns:

false if this method failed, or the continuation failed (returned false) and this method could not be successfully redone; true if this method succeeded and its continuation returned true.

Throws:

PrologException - if this term does not have the proper form to be called as a goal, or if execution of the goal or the continuation results in an error.

call

public static boolean call(PrologBoundTerm goal)
                    throws PrologException

Attempt to satisfy a goal encapsulated in a bound term object once, and report only success or failure

Parameters:

goal - an object that is a callable term

Returns:

true if the goal succeeds, false if it fails.

Throws:

PrologException - if this term does not have the proper form to be called as a goal, or if execution of the goal results in an error.

call

public static boolean call(java.lang.String term)
                    throws PrologException

Attempt to satisfy a goal represented by a string once, and report only success or failure

Parameters:

term - the textual representation of the goal to be called

Returns:

true if this method succeeded, false if it failed

Throws:

PrologException - if this term does not have the proper form to be called as a goal, or if execution of the goal results in an error.

retract

public static boolean retract(PrologBoundTerm term,
                              PrologContinuation continuation)
                       throws PrologException

Attempt to retract a term encapsulated in a bound term object from the database, with access to the variable bindings for the term retracted, and the possibility of redoing to retract another matching term.

Parameters:

term - a bound term object that is a callable term

continuation - an object whose succeed() method is called if the goal succeeds.

Returns:

false if this method failed, or the continuation failed (returned false) and this method could not be successfully redone; true if this method succeeded and its continuation returned true.

Throws:

PrologException - if this term does not have the proper form for a clause in the database, or belongs to a non-modifiable predicate, or execution of the continuation resulted in an error.

retract

public static boolean retract(java.lang.String term,
                              PrologContinuation continuation)
                       throws PrologException

Attempt to retract a term represented by a string from the database, with access to the variable bindings for the term retracted, and the possibility of redoing to retract another matching term.

Parameters:

term - the textual representation of the term to be retracted

continuation - an object whose succeed() method is called if the goal succeeds.

Returns:

false if this method failed, or the continuation failed (returned false) and this method could not be successfully redone; true if this method succeeded and its continuation returned true.

Throws:

PrologException - if this term does not have the proper form for a clause in the database, or belongs to a non-modifiable predicate, or execution of the continuation resulted in an error.

retract

public static boolean retract(PrologBoundTerm term)
                       throws PrologException

Attempt to retract one instance of a term encapsulated in a bound term object from the database, and report only success or failure.

Parameters:

term - a bound term object that is a callable term

Returns:

true if one term matching term was successfully retracted, false if no matching term was found.

Throws:

PrologException - if this term does not have the proper form for a clause in the database, or belongs to a non-modifiable predicate

retract

public static boolean retract(java.lang.String term)
                       throws PrologException

Attempt to retract one instance of a term represented by a string from the database, and report only success or failure.

Parameters:

term - the textual representation of the term to be retracted

Returns:

true if one term matching term was successfully retracted, false if no matching term was found.

Throws:

PrologException - if this term does not have the proper form for a clause in the database, or belongs to a non-modifiable predicate

retractall

public static void retractall(PrologBoundTerm term)
                       throws PrologException

Retract all instances of a term encapsulated in a bound term object from the database

Parameters:

term - a bound term object that is a callable term

Throws:

PrologException - if this term does not have the proper form for a clause in the database, or belongs to a non-modifiable predicate

retractall

public static void retractall(java.lang.String term)
                       throws PrologException

Retract all instances of a term represented by a string from the database

Parameters:

term - the textual representation of the term to be retracted

Throws:

PrologException - if this term does not have the proper form for a clause in the database, or belongs to a non-modifiable predicate

makeBoundTerm

public static PrologBoundTerm makeBoundTerm(java.lang.String text)
                                     throws PrologException

Create a bound term object that encapsulates a term, given its textual representation

Parameters:

text - the textual representation of the term

Returns:

a bound term object that encapsulates this term

Throws:

PrologException - if term is not a syntactically- correct representation of a Prolog term

consult

public static void consult(java.io.BufferedReader bufferedReader,
                           boolean throwImmediately)
                    throws PrologException

Treat a stream represented by a BufferedReader as a sequence of clauses to be asserted into the database

Parameters:

bufferedReader - the source to read clauses from

throwImmediately - true if any exception arising from the processing of a clause should be thrown immediately. If this parameter is false, such errors are reported to user_error and processing continues.

Throws:

PrologException - if throwImmediately is true and there is any problem (including a syntax error) processing a clause or directive in the stream; or if there is a non-catchable error in any case.

reconsult

public static void reconsult(java.io.BufferedReader bufferedReader,
                             boolean throwImmediately)
                      throws PrologException

Treat a stream represented by a BufferedReader as a sequence of clauses to be asserted into the database, replacing any definitions for the referenced predicates that are already there

Parameters:

bufferedReader - the source to read clauses from

throwImmediately - true if any exception arising from the processing of a clause should be thrown immediately. If this parameter is false, such errors are reported to user_error and processing continues.

Throws:

PrologException - if throwImmediately is true and there is any problem (including a syntax error) processing a clause or directive in the stream; or if there is a non-catchable error in any case.

interpret

public static boolean interpret(java.io.BufferedReader bufferedReader,
                                boolean failImmediately,
                                boolean throwImmediately)
                         throws PrologException

Treat a stream represented by a BufferedReader as a sequence of goals to be called.

Parameters:

bufferedReader - the source to read goals from

failImmediately - if this parameter is true, then the failure of any goal read from the stream causes this method to fail immediately; if false, reading and executing of goals continues until the end of the stream is reached even if one or more fail.

throwImmediately - true if any exception arising from the processing of a clause should be thrown immediately. If this parameter is false, such errors are reported to user error and processing continues.

Returns:

true iff all goals execute without failure; false if any goal fails

Throws:

PrologException - if throwImmediately is true and there is any problem (including a syntax error) processing a goal or directive in the stream; or if there is a non-catchable error in any case.

listing

public static void listing(java.io.PrintWriter printWriter,
                           java.lang.String name,
                           int arity,
                           boolean ignorePrivate)
                    throws PrologException

List out the clauses for a given Prolog predicate or predicates (with source code available) in a form suitable for reading by consult().

Parameters:

printWriter - the sink to write the listing to

name - the name of the predicate. This parameter can be null, in which case all user-defined predicates are listed, and arity is ignored.

arity - the arity of the predicate. This parameter can be -1, which causes all predicates for this atom to be written

ignorePrivate - true if the predicate is to be ignored if it is private - nothing is written for it in this case.

Throws:

PrologException - if there is an IOException writing the sink

listing

public static void listing(java.io.PrintWriter printWriter,
                           java.lang.String name,
                           boolean ignorePrivate)
                    throws PrologException

List out the clauses of Prolog predicates of any arity for a given atom (with source code available), in a form suitable for reading by consult()

Parameters:

printWriter - the sink to write the listing to

name - the name of the predicate. This parameter can be null, in which case all user-defined predicates are listed

ignorePrivate - true if private predicates are to be ignored - nothing is written for them in this case.

Throws:

PrologException - if there is an IOException writing the sink

listing

public static void listing(java.io.PrintWriter printWriter,
                           boolean ignorePrivate)
                    throws PrologException

List out the clauses of predicates of any arity for all Prolog predicates (with source code available) currently in the database.

Parameters:

printWriter - the sink to write the listing to

ignorePrivate - true if private predicates are to be ignored - nothing is written for them in this case.

Throws:

PrologException - if there is an IOException writing the sink

listing

public static void listing(java.io.PrintWriter printWriter)
                    throws PrologException

List out the clauses of predicates of any arity for all Prolog predicates (with source code available) currently in the database, quietly skipping over private ones.

Parameters:

printWriter - the sink to write the listing to

Throws:

PrologException - if there is an IOException writing the sink

set_input

public static void set_input(java.io.BufferedReader bufferedReader)

Cause a BufferedReader to be used as default input for subsequent operations

Parameters:

bufferedReader - the BufferedReader to use as default input. This parameter can be null, in which case the system reverts to using the standard user_input stream. Because the PrologJ system does line buffering internally, the program should not access this stream - or any stream it is filtering - directly while it is in use as standard input for Prolog.

set_output

public static void set_output(java.io.PrintWriter printWriter)

Cause a PrintWriter to be used as default output for subsequent operations

Parameters:

printWriter - the PrintWriter to use as default output. This parameter can be null, in which case the system reverts to using the standard user_output stream.

setBuiltinPredicateCategories

public static void setBuiltinPredicateCategories(java.lang.String categories)
                                          throws java.lang.IllegalArgumentException

Set the category(s) of built-in predicates that are available

Parameters:

categories - a string consisting of the one letter codes for predicate categories to be made available

Throws:

java.lang.IllegalArgumentException - if categories contains an invalid code

main

public static void main(java.lang.String[] args)

Main method when run as an application. This method can be invoked in one of two ways: by double-clicking the PrologJ.jar file, or by running the jar file (possibly with options/files) from the command line.

- In the former case, the interpreter is run, with a GUI Console object used for input and output.

- In the latter case, either the interpreter or the compiler is run, with standard io used for input and output. (The compiler is run if one or more files is specified; the interpreter if no files are specified.)

ensure_loaded

public static void ensure_loaded()

This method is called from compiled code to ensure that this class is loaded (and therefore the system is initialized). It is not normally called by user code.