
A WAM Prolog for Teaching
=========================

From the website:

  Dr. Andrew Davison
  Dept. of Computer Engineering
  Prince of Songkla University
  Hat Yai, Songkhla 90112, Thailand
  E-mail: ad@fivedots.coe.psu.ac.th
  http://fivedots.coe.psu.ac.th/~ad/


If you use this code, please mention my name, and include a link
to the website.

Thanks,
  Andrew

============================

This directory contains:

* examps/			-- Prolog examples; compile and run your code **in here**

* src/				-- the source code for the BuProlog compiler 
                       and the BuWAM
* "A WAM Prolog for Teaching.pdf"
     -- a 60+ page guide to BuProlog and BuWAM


This work is derived from the Prolog system by 
   Stefan Buettcher, stefan@buettcher.org, Feb. 2002,
   available at http://stefan.buettcher.org/cs/wam/.


----------------------------
Before Compilation/Execution


You need to download and install:
  1) GraphViz: https://graphviz.gitlab.io/
      * follow its download instructions as normally

  2) JFlex: https://www.jflex.de/
      * download, unzip, and extract jflex-full-xxx.jar
      * install the JAR anywhere, but make a note of the path and update
        the path used in BuWAM's src/jflex.bat batch file

----------------------------
Compiling BuProlog/BuWAM


JAR files for BuProlog and the BuWAM are already in /examps, but
you can recompile them by openning a command window in /src and
typing:

> makeJARs.bat

- this will recreate the two JARS (BuProlog.jar and BuWAM.jar)
  and copy them into /examps


----------------------------
Compiling Prolog programs


Open a command window in /examps and type:

> java -jar BuProlog.jar <Prolog filename>
e.g.
> java -jar BuProlog.jar append.pro

This will generate a WAM file (e.g. append.wam).

Or you use the prolog.bat batch file:

> prolog append.pro

You can add the "-d" and/or "-p" options to switch on diagnostics 
and/or graph printing.
e.g.

> prolog -p append.pro
> prolog -d append.pro 2> debug.txt

The diagnostic output is usually very large, so redirect 
it to a text file.


----------------------------
Running WAM code


Open a command window in /examps and type:

> java -jar BuWAM.jar <WAM filename>
e.g.
> java -jar BuWAM.jar append.wam

This will load the append.wam file and start a REPL where you
can type in queries:
e.g.
?- append(X,Y,[1,2,3]).

At the "?-" prompt, type q (and <ENTER>) to quit BuWAM.


You can also start the BuWAM by calling the wam.bat batch file:

> wam append.wam

You can add the "-d" and/or "-p" options to switch on diagnostics 
and/or graph printing.
e.g.

> wam -p append.wam
> wam -d append.wam 2> debug.txt

The diagnostic output is usually very large, so redirect 
it to a text file.

----------------------------
Testing GraphViz

If the "-p" option fails to generate any graphs then you can test
GraphViz separately from BuProlog by running CallGraph.java's main()
function.

Open a command window in /src and type:

> java CallGraph

A small "hello World" graph should be written to test.png


----------------------------
Testing JFlex

You can test JFlex independently of BuProlog by calling LexerTest.java
in /src.

Open a command window in /src and type:

> java LexerTest append.pro


----------------------------
Changing BuProlog and/or BuWAM


If you modify the Java code for BuProlog and/or BuWAM, and **new**
class files are generated at compile time, then you must edit
makeJars.bat in /src to include those new files when it packages
up the JAR files.

-----------------------------
Last updated: 24th July 2020
