Package com.svincent.moksa

An implementation of a Warren's Abstract Machine and associated builtin predicates, to conform to ISO Prolog.

See:
Description

Interface Summary

Trailable

Interface which must be implemented by objects that want to live in the Trail.

Class Summary

Builtin	Defines a number of useful primitive predicates.
Builtin.Arg_3	Allows arguments of a functor to be retrieved and set.
Builtin.ArithmeticComparisonRule	Base class for arithmetic comparison builtins.
Builtin.Asserta_1
Builtin.Assertz_1
Builtin.Atom_1	Tests whether its argument is an atom (8.3.2).
Builtin.Atomic_1	Tests whether its argument is atomic (8.3.5).
Builtin.BuiltinRule	All of the builtin primitive rules subclass BuiltinRule.
Builtin.Call_1	Calls a goal (7.8.3)
Builtin.Catch_3	Calls a goal with an exception handler.
Builtin.Compound_1	Tests whether its argument is a compound term (8.3.6).
Builtin.Copy_term_2	copy_term(?Term1, ?Term2) is true iff Term2 unifies with a renamed copy of Term1.
Builtin.Cut_1
Builtin.Equals_2	Equals
Builtin.Fail_0	Always fails
Builtin.Functor_3	Allows a term to be split into its components (8.5.1)
Builtin.GreaterThan_2	Greater than
Builtin.GreaterThanEquals_2	Greater than/equals
Builtin.Halt_0	Halts the machine
Builtin.Identical_2	Tests whether its arguments are identical terms (8.4.1).
Builtin.Integer_1	Tests whether its argument is an integer (8.3.3).
Builtin.Is_2	Evaluate expression (8.6.1)
Builtin.LessThan_2	Less than
Builtin.LessThanEquals_2	Less than/equals
Builtin.Nonvar_1	Tests whether its argument is not a variable (8.3.7).
Builtin.NotEquals_2	Not equals
Builtin.Number_1	Tests whether its argument is a number (8.3.8).
Builtin.Real_1	Tests whether its argument is a floating-point value (8.3.4).
Builtin.Set_prolog_flag_2
Builtin.Set_var_nameXXX_2
Builtin.Throw_1	Throws an exception to the nearest matching exception handler, or halts the machine, if neccessary.
Builtin.Unify_2	Implements the =/2 predicate (8.2.1).
Builtin.Univ_2	Allows a compound term to be constructed from a list
Builtin.Var_1	Tests whether its argument is a variable (8.3.1).
CompiledRule	Provides a superclass for compiled rules.
CompoundTerm	A compoundTerm is a Prolog tree constant (normally of the form f(x1, x2, ..., xn), where f is known as the compoundTerm's functor, and x1 through xn are known as the term's subterms.
CompoundTerm.ListWrapper	A wrapper for a CompoundTerm as a list.
CompoundTerm.PrologIterator
Continuation	This is the Continuation concept, made explicit, for clarity.
InterpretedRule	A rule, but interpreted, rather than compiled.
Io	Provides the Prolog environment with an ISO I/O subsystem.
Io.Close_2	Closes the specified file.
Io.Current_input_1	Unifies the given variable with the current input
Io.Current_output_1	Unifies the given variable with the current output
Io.Flush_output_1	Flushes the specified stream.
Io.Get_char_2	Gets a character from the given output stream.
Io.Get_prolog_token_2	Gets a Prolog token from the given output stream.
Io.Get_stream_properties_2	get_stream_properties (S, Props)
Io.Nl_1	Prints a newline to the given output stream.
Io.Open_4	Opens the specified file.
Io.PrologInput	An identifier for an input stream.
Io.PrologOutput	An identifier for an output stream.
Io.PrologOutputStream
Io.PrologWriter
Io.Put_char_2	Puts the given character to the given output stream.
Io.StreamIdentifier	An identifier for a currently open input or output stream.
Io.Write_2	Writes its argument to the given output stream.
IsoPrologParser	Parses ISO Prolog source files.
JavaInterface	Provides an interface to Java code.
JavaInterface.Java_constructor_2	Constructs a new Java object of a given class.
JavaInterface.Java_method_3	Calls a method on a class or instance..
JavaInterface.JavaRule
JavaTerm	A subclass of PrologTerm which contains a reference to a Java object.
MiniPrologParser	Parses a subset of the Prolog language, that I call 'Mini-Prolog'.
MoksaProlog	The main entry point for the current version of MoksaProlog.
MoksaUtil	Contains static utility methods to do a bunch of random stuff that doesn't belong elsewhere.
Prologc	Compiles Prolog source files into Java class files.
Prologc.PrologRuleCompiler	A compiler for Prolog rules.
Prologc.PrologTermCompiler	Make one of these for the entire method construction process: it keeps state about what it's created so far.
PrologEngine	Global context for everything, plus a public interface for users.
PrologEngine.ArithmeticHandler
PrologFactory	Responsible for creating instances of various Prolog entities.
PrologLoader	Superclass of the Loader generated for each prolog file compiled by MoksaProlog.
PrologPackageManager	Manages Prolog source.
PrologPackageManager.PrologClassLoader
PrologParser	A parser for the Prolog language.
PrologTerm	Represents a WAM first-order term (i.e.
PrologTermVisitor	A Visitor pattern implementation for PrologTerms.
PrologTokenizer	This class encapsulates the tokenization of Prolog.
PrologUtil	Contains a bunch of static methods for doing useful tasks for compiling Prolog.
Rule	The abstract base class for all Rules.
Variable	Represents a Variable: a WAM term that contains (possibly) a reference to another WAM term.
VariableCollector	Collects all the variables out of an PrologTerm compoundTerm.
Wam	An implementation of a Warren's Abstract Machine, as documented in Warren's Abstract Machine: a Tutorial Reconstruction, by Hassan Ait-Kaci.
Wam.ChoicePoint	Represents a choice point.
Wam.ExceptionHandler	A registered exception handler for the current thread of execution.
WamFloat	A WamFloat is a Prolog constant for a floating-point number
WamInteger	A WamInteger is a Prolog constant for an integral number.
WamObject	Base class for stuff in the Wam package.

Exception Summary

NoSuchRuleException	Thrown when a rule (name/arity) is invoked that doesn't exist..
PrologException	Superclass of all exceptions thrown from the WAM.
PrologException.UnhandledPrologException
PrologParseException	Thrown when an exception occurs whilst parsing Prolog source.
PrologRuntimeException	Superclass of all runtime exceptions thrown from the WAM.
PrologStringFormatException	Thrown when a string is not in proper Prolog-quoted form.
PrologTermVisitor.WamVisitorException

Package com.svincent.moksa Description

An implementation of a Warren's Abstract Machine and associated builtin predicates, to conform to ISO Prolog.

How do I use it?

The API is still very much in flux: more will be written about it in this documentation as it solidifies.

How does it work?

MoksaProlog is built on top of a Warren's Abstract Machine (WAM), an implementation of Prolog designed by David Warren in 1983. I don't have the time, inclination, or skill to describe how the WAM functions. Luckily, there's a book you can read that does that. I can only describe what I did.

That said, I hope that my source is self evident: I try to document any tricky bits, in the hope that MoksaProlog can be used as a means by which people can figure out how to write a Prolog environment for themselves, particularly in an object-oriented language like Java.

The biggest single difference, and the trickiest thing in MoksaProlog's implementation, is continuation passing.

So what's continuation passing?

A continuation is an additional parameter to every function in the system that tells the function what to do when it's done. This is implemented in MoksaProlog by an additional register in the machine called continuation, of type Continuation.

If you look at the Continuation class, you'll see what's stored in it: it owns the next Rule to invoke (which is our only pointer to instructions that we have in MoksaProlog), the values of the argument registers to pass this Rule when invoking it, and the Continuation to pass the Rule, so that it knows what to do next.

Every Rule in the system is responsible, then, for returning a Continuation instance of the thing to do next. Often, this new Continuation is a function of the Continuation that was passed into the Rule.

Let's look at some example cases, to try and make things clearer:

• If the Rule wants to call another Rule, it makes a new Continuation consisting of the function to be called, its arguments, and a Continuation telling the function where to go when its done.
  • If the called Rule is the last thing we do, then we pass it the Continuation that was passed to us.
  • If we want to do something after we call the Rule, we pass the Rule a Continuation containing the thing we want to do (which will, in turn, probably contain the Continuation that was passed to us)
• If the Rule just wants to return, it returns the Continuation passed into it.
• If the Rule wants to fail, it returns a Continuation with a call to the 'fail' Rule: typically done by returning the global instance wam.Fail. This is one of the only Continuations that can be reused globally this way, since Fail ignores the Continuation passed to it.
• If the Rule wants to throw an exception, it returns a Continuation with a call to the 'throw' Rule. This is typically done by calling the method Wam.callThrow, which constructs such a Continuation..

Note that it is possible to pass 'null' in as the Continuation. If you do this, and that ever executes, then the machine will halt (this is the termination case for the machine, currently)

Hopefully, that helps a bit. There are other discussions of continuation passing programming in most good programming language design/implementation books.

Who are you?

My name is Shawn Vincent: I'm a professional systems programmer, specializing in Java. Moksa is something I do in my spare time: it has no particular connection or distance from my work life, at Meteko (which has a very cool product, by the way).

Credits

Vital to any software's success is the help of nice people the world over. Many people have had a part in allowing MoksaProlog to be released, and I'll never be able to thank them all.

The single biggest contributer to MoksaProlog has got to be Hassan Aït-Kaci, the author of the book: Warren's Abstract Machine: A Tutorial Reconstruction, originally published by MIT press. If it weren't for this book, I'd never have been able to figure out how the WAM works, and how to write one. The book itself is out of print, but Hassan has made it available for noncommercial use: you can download it in various formats from his web site.

Speaking about books, the book that caused me to walk the path of Prolog in my journeys with Moksa was Programming with Constraints: an Introduction, by Kim Marriott and Peter J. Stuckey. It is an excellent book, well worth reading if you're interested in this stuff. This book will also come in handy later on when I'm adding constraint processing support for Moksa.

Also, all my teachers at the University of Waterloo, all my colleagues that I've worked with in the programming industry over the years, my friends: everybody who has influenced my programming style, increasing my skill, and teaching me techniques: MoksaProlog would not have been possible without your help.