Skip to content

lindseyspratt/proscriptls

 
 

Repository files navigation

ProscriptLS

A Javascript implementation of Prolog

ProscriptLS (Proscript Logic for Systems) is a fork of the original Proscript project by Matt Lilley. There are two major enhancements in this fork: builtins to work with the DOM (Document Object Model) of HTML and a proper interactive Prolog tracing debugger that can be used in the client web page (using a JQuery Terminal). For the DOM enhancements there is a javascript function proscriptls_init("goal") that can be called in <body> onload to run a Prolog query to initialize the HTML environment. proscriptls("goal") can be used in handlers in the HTML page where the evaluation shares the same predicate assertions as that set up by the proscriptls_init ls function.

The primary documentation is index.html.

Organization

The engine implementation: WAM and builtins

src/engine/

The Warren Abstract Engine (WAM) is implemented primarily in wam.js.

Builtins and support functions are also present in:

  • fli.js: SWI-Prolog-like foreign langauge interface. Allows escaping to Javascript from Prolog, so you can call low(er) level functions. Huge chunks of this (like PL_cut_query!) are not implemented
  • foreign.js: This implements a lot of core WAM building blocks directly in javascript. For example, you will find implemntations for univ, writeln and halt here.
  • memory_files.js: stream IO with memory files.
  • gc.js: Implements a garbage collector
  • read.js: Handles input and output of terms, including parsing Prolog terms
  • record.js: Handles dynamic adjustment of the state: assert and friends
  • stream.js: Handles reading and writing to streams, and all the ISO predicates (the ones implemented anyway) like get_char/2 and put_code/2.
  • dom.js, object_method.js, object_property.js: Builtins for working with the DOM.
  • debugger.js: The interactive Prolog tracing debugger. (see also debugger.pl)
  • dump.js: a debugging tool to analyze for dangling predicates (referenced in a call but not defined) print out the predicates in a prosciptls_state.js file or to print out the WAM program for a particular predicate.

Engine functions that may be customized:

  • src/engine/standalone.js: Contains implementations of stdout and flush_stdout/1. You can either include this (in which case you will get output printed to a variable called stdout_buffer), or implement them yourself to do something /with/ the stuff written to stdout.

The compiler and the rest of the system

src/system/

The compiler is itself written in Prolog.

  • wam_compiler.pl: The guts of the compiler. Exports build_saved_state/2, build_saved_state/3, and bootstrap/2, all actually implemented in wam_boostrap.pl
  • bootstrap_js.pl: This is the part of the compiler compiled by the bootstrapping compiler to generate the saved state for the actual compiled system
  • debugger.pl: Implements (with debugger.js) interactive Prolog tracing debugger.
  • url.pl: handles file paths for consulting Prolog source from the client.
  • not.pl: defines free_variables/4 predicate needed by bag_of/3 in bootstrap_js.pl.
  • promise.pl: utilities for working with Javascript Promise objects in support of consulting Prolog source.

src/tools/

Some Prolog predicates are only used during the build. These are in:

  • wam_boostrap.pl: This is the part of the compiler only executed in the bootstrapping process to generate the boostrapped compiler.
  • testing.pl: Contains implementations of debugging predicates used for debugging the compiler
  • js_preprocess.pl: Minimizes several *.js files and combined them into the proscriptls_engine.js. The minimization is primarily removing debug_msg function calls if debug===false. Also implements a simple macro processor by allowing/removing Javascript code surrounded by 'if foo...endif' where 'foo=true/false' is present in list of third argument to preprocess/3 (called by Makefile for src/engine).
  • node_exports.js, node_standalone.js, node_test.js, type_references.pl: where node_exports.js, node_standalone.js, node_test.js are used by docs/Makefile to generate proscriptls_state_node.js, which in turn is used by docs/Makefile to evalutate generate_type_references/1 in type_references.pl to generate the docs/type_references.template. The type_references.template file is used in creating index_doc.html.

src/docs/

The HTML files in docs are generated from the *.template files in src/docs. The substitute_template/2 predicate in library/template.pl is called using ProscriptLS with NodeJS by src/docs/Makefile to process the *.template files to create various *.html files.

  • *.template: source files for substitute_template/2 to create *.html files.
  • proscriptls_state_doc.js: ProscriptLS Javascript state file generated by wam_compiler using library/template.pl. This library file is used with NodeJS to evaluate substitute_template/2.

Making ProscriptLS at the top-level

Running 'make' from the command-line with working-directory at the root of the proscriptls project creates the proscriptls Javascript libraries and HTML for documentation.

dist/

  • proscriptls_state.js (the saved state)

  • proscriptls_engine.js (the executable runtime)

  • proscriptls.js - combination of proscriptls_state.js and proscriptls_engine.js.

You must include both of proscriptls_state.js and proscriptls_engine.js or their combination in proscriptls.js if you want a working system. See test.html for an example.

docs/

Most of the files in this directory are generated by the 'make' process. The two exceptions are index.css and index.pl.

  • index.html: primary documentation HTML for ProscriptLS, generated from src/docs/*.template files.
  • index_about.html, index_doc.html, index_download.html: secondary documentation HTML linked from index.html. These files are also generated from src/docs/*.template files.
  • index.css: CSS used with index*.html.
  • index.pl: ProscriptLS programs used with index*.html files to implement hide/reveal tree behavior in sidebar navigation menu.
  • object.pl: Used by index.pl. It is a copy of library/object.pl placed in docs so that GitHub Pages service can find it.
  • proscriptls.js: Used to run index.pl predicates. This is a copy of dist/proscriptls.js placed in docs so that GitHub Pages service can find it.

Debugging terminal

A debugging terminal can be displayed in an HTML page using the terminal/proscriptls_interpreter_terminal.js. An example with just the terminal is terminal/terminal_test.html. Another example is examples/calculator.html. The debugging terminal is a command-line Prolog interpreter. It also supports the 'trace' predicate to enable the interactive trace/debug mode. E.g. 'trace,mem(X,[a,b])' is a query that activates tracing while evaluating the mem/2 predicate.

Trying it out

There are several examples in the examples directory: test.html, simple_test.html, console_button_test.html, and calculator.html.

test.html provides an execution environment for you to try out the final state

terminal_test.html (with proscriptls_interpreter_terminal.js) is an example using the JQuery Terminal to run the interactive Prolog debugger in a web page.

simple_test.html uses simple_test.pl to write "Hello World".

About

A WAM-based Javascript implementation of Prolog with DOM builtins and debugger.

Topics

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • JavaScript 48.2%
  • Prolog 45.4%
  • HTML 3.4%
  • CSS 1.9%
  • Makefile 1.1%