[Added documentation
Adrian Prantl <adrian@complang.tuwien.ac.at>**20090128141717] {
hunk ./compiler.fs 1
+\ compiler.fs -- a simplified Prolog -> Warren Abstract Machine (WAM) compiler
+\
+\ Copyright (C) December 2008 and January 2009
+\ Adrian Prantl and Gergö Barany
+\
+\   This program is free software: you can redistribute it and/or modify
+\   it under the terms of the GNU General Public License as published by
+\   the Free Software Foundation, either version 3 of the License, or
+\   (at your option) any later version.
+\
+\   This program is distributed in the hope that it will be useful,
+\   but WITHOUT ANY WARRANTY; without even the implied warranty of
+\   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+\   GNU General Public License for more details.
+\
+\   You should have received a copy of the GNU General Public License
+\   along with this program.  If not, see <http://www.gnu.org/licenses/>
+\
+\ Features:
+\ 
+\ This file contains a recursive-descent parser for a subset of Prolog
+\ that generates WAM instructions on-the-fly, using a lookahead of 1 goal.
+\ It copes with facts, clauses and queries. Supported primitives are
+\ atoms, lists, named and anonymous variables, the :- operator and structures.
+\ Definitely NOT supported are integers, DCGs and infix operators apart from
+\ the ":-".
+\ The generated code tries to follow the one described in [Warren 1983] as
+\ closely as possible. The most significant difference is that the machine
+\ code ist output in postfix notation. This makes it possible to directly
+\ evaluate the generated code as forth words. The virtual machine
+\ implementation can be found in the file 'wam.fs'.
+\ This file also contains a toplevel shell that allows for readline-like
+\ command editing.
+\
+\ Things to try out:
+\
+\ Start the prolog shell with 
+\   $ gforth wam.fs compiler.fs -e queries
+\   ...
+\   Enter queries, one per line; empty line when you're done.
+\   ?- concatenate(A,B,[a,b]).    
+\   B = [a, b]
+\   A = []
+\   ;
+\   B = [b]
+\   A = [a]
+\   ;
+\   B = []
+\   A = [a, b]
+\   ;
+\   No (further) solutions
+\   ?-
+\   
+\   Type ';' to ask the system for more solutions.
+\
+\
+\ Literature:
+\
+\   [Warren 1983] David H. D. Warren. "An abstract Prolog instruction set".
+\      Technical Note 309, SRI International, Menlo Park, CA, October 1983.
+
+
+
hunk ./compiler.fs 804
-
-\ concatenate([], L, L).
-\ concatenate([X|L1], L2, [X|L3]) :- concatenate(L1, L2, L3).
-\
-\ concatenate/3: switch_on_term C1a, C1, C2, fail
-\
-\ C1a: try_me_else C2a
-\ C1:  get_nil A1
-\      get_value A2, A3
-\      proceed
-\
-\ C2a: trust_me_else fail
-\ C2:  get_list A1
-\      unify_variable X4
-\      unify_variable A1
-\      get_list A3
-\      unify_variable X4
-\      unify_variable A3
-\      execute concatenate/3
-
-
-\ ----------------------------------------------------------------------
-\ TESTS
-\ ----------------------------------------------------------------------
-
hunk ./compiler.fs 817
+\ ----------------------------------------------------------------------
+\ SHELL
+\ ----------------------------------------------------------------------
+
hunk ./compiler.fs 856
+\ concatenate([], L, L).
+\ concatenate([X|L1], L2, [X|L3]) :- concatenate(L1, L2, L3).
+\
+\ concatenate/3: switch_on_term C1a, C1, C2, fail
+\
+\ C1a: try_me_else C2a
+\ C1:  get_nil A1
+\      get_value A2, A3
+\      proceed
+\
+\ C2a: trust_me_else fail
+\ C2:  get_list A1
+\      unify_variable X4
+\      unify_variable A1
+\      get_list A3
+\      unify_variable X4
+\      unify_variable A3
+\      execute concatenate/3
+
+
+\ ----------------------------------------------------------------------
+\ TESTS
+\ ----------------------------------------------------------------------
+
hunk ./wam.fs 1679
+    ." compare_terms("
+    	a1 @ unparse ." , "
+    	a2 @ unparse ." , "
+    	a3 @ unparse ." )"
hunk ./wam.fs 1689
+    ." -> success: " prolog-success @ . cr
}