Merge pull request #1 from DennisMerritt/master

Design Notes.rtf

@@ -0,0 +1,193 @@
+{\rtf1\ansi\ansicpg1252\cocoartf1348\cocoasubrtf170
+{\fonttbl\f0\fswiss\fcharset0 Helvetica;\f1\fnil\fcharset0 Monaco;}
+{\colortbl;\red255\green255\blue255;}
+\margl1440\margr1440\vieww14980\viewh16700\viewkind0
+\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\pardirnatural
+
+\f0\fs24 \cf0 Design Notes & Status\
+\
+2016-04-29\
+\
+The log/2 bug was nastier than thought.  It had to do with using different forms of the file name when loading modules, so the log module wasn\'92t noted.  Working OK now.\
+\
+Diagnostic tool \'97 make direct calls to the various dynamic predicates, such as mod_import and the like.  These revealed that the higher level modules weren\'92t seeing the log module after it had been read once.\
+\
+2016-04-27\
+\
+Working with current sources.  Here\'92s the development cycle.  Run it, if it fails, fix it.  So I imagine we\'92ll keep running into various problems, and each one will make the tool better.  Here\'92s the ones I encountered with these tests.\
+\
+It was failing to handle :- use_module(project(X)) statements.  I added a poor fix, which was in process to recognize those statements and do nothing.  A better fix is to figure out the path to X and \'91xinput\'92 that file so it can be included in the cross reference.\
+\
+It was getting read errors, that were due to an operator, <->, not being understood.  The fix was to put a catch around the \'91read\'92 in the xinput loop and log the errors and display them at the top of the cross reference.  These could be made easier to understand.\
+\
+I random check of the results.  Lots of undefined and unused.  Looked at semantics atomize which was said to be unused.  Checked and it was used, but in a maplist so it was two arguments shy.  Added the code to \'91uses\'92 predicate that looks at such things, and added the extra arguments, so now it\'92s happy with atomize.\
+\
+There are lots more.  The more the reasons are understood and dealt with, the smarter the xref will become.\
+\
+Check the change log to see the ones made in this round.  The main predicates that do the work are \'91process\'92, taking the first pass, and \'91uses\'92 which is looking at the individual goals and recording what needs to be recorded.\
+\
+Starting at the top of the warnings, the discontiguous warning for logicTranslator/processNode is there because it is discontiguous.  Probably an error in the code.\
+\
+2016-04-27\
+\
+Improved formatting, fixed a number of disconnects, especially with dynamic predicates.\
+\
+Added a file relation report as well, which files load which other files.  It\'92s complex for this run!\
+\
+Check it out, see if the report seems right or wrong.\
+\
+2016-04-26\
+\
+It now runs, whether or not correctly to be determined, on large numbers of Solstice files.  It can be started with a single file, and then it automatically tracks all the use_module and include directives to take into account everyone.\
+\
+See dw_main.pro to see how it was started.\
+\
+See xrf_SessionManager.txt to see a large amount of output.  It has the complete cross reference, and then the cones down from everything that is an orphan at the top, and the cones up from all the dynamic predicates.  Plus tons of warnings, not sure if they\'92re right or not.\
+\
+Because it is tracking the file structure, it would be nice to add a report on which files call which as well, and maybe I\'92ll add that tomorrow.\
+\
+NOTE: the reports are all generated in xrfSicstusMain.pro.  The data are all facts created by xrfSicstus.  The written reports are really just a guide to how to use the underlying data.  That data could be used by a graphical front end, or some kind of query interface to see just segments of the data.\
+\
+The reports could be simplified by eliminating all the reporting on builtin predicates.  It could be an option.  Might not want to know all the calls to nl.\
+\
+2016-04-25\
+\
+The cross reference is now running under SICStus, with knowledge of SICStus modules and dynamic predicates.\
+\
+The system will be set up to produce three kinds of reports.  Also, the raw data needed for the reports can be accessed directly for different purposes.\
+\
+The current examples/tests have been done with the Amzi! Duck World tutorial, modified to run on SICStus.  (SICStus does not use ISO standard module declarations.)  The Duck World tutorial is a very simple interactive fiction game, where the dynamic predicate loc/2 is key, as it\'92s constantly updated to record the current state of the game.  It has three modules, user, rules, and data.\
+\
+
+\b Cross Reference
+\b0 \
+\
+An alphabetical listing of all predicates with the direct sub-goals and callers listed.  Note that asserts/retracts are handled a bit different, and show up as, for example: assert-data:loc/2.\
+\
+Here\'92s an entry for a predicate in the game:\
+\
+\pard\pardeftab720
+
+\f1\fs22 \cf0 rules:connect/2\
+   subgoals:\
+      data:nextto/2\
+   called from:  \
+      rules:goto/1\
+      rules:look_connect/1\
+\
+\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\pardirnatural
+
+\f0\fs24 \cf0 Note that dynamic predicates have a third category cross reference, where they\'92re modified by asserts or retracts.  Here\'92s the entry for the dynamic loc/2 predicate:\
+\
+\pard\pardeftab720
+
+\f1\fs22 \cf0 data:loc/2   dynamic\
+   modified in:\
+      rules:move/2\
+   no subgoals\
+   called from:  \
+      rules:chase/1\
+      rules:done/0\
+      rules:ducks/0\
+      rules:fox/0\
+      rules:goto/1\
+      rules:look/0\
+      rules:look_have/1\
+      rules:look_here/1\
+      rules:take/1
+\f0\fs24 \
+\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\pardirnatural
+\cf0 \
+
+\b Top Down Cone
+\b0 \
+\
+Predicates that aren\'92t called by any others are consider the tops of cones of influence.  They will be analyzed with a tree structure that shows all the sub-goals and sub-goals lower.  Here\'92s part of the main/0 cone looking down.  Notice that the move/2 predicate lists the assert/retract subgoals for loc/2.\
+\
+\pard\pardeftab720
+
+\f1\fs22 \cf0 user:main/0    uses:\
+.  user:go/0\
+.  .  builtin: \\= /2\
+.  .  rules:demons/0\
+.  .  .  rules:ducks/0\
+.  .  .  .  data:loc/2\
+.  .  .  .  rules:move/2\
+.  .  .  .  .  assert-data:loc/2\
+.  .  .  .  .  retract-data:loc/2\
+.  .  .  .  builtin:nl/0\
+.  .  .  .  builtin:write/1\
+.  .  .  rules:fox/0\
+.  .  .  .  data:loc/2\
+.  .  .  .  builtin:nl/0\
+.  .  .  .  builtin:write/1\
+.  .  rules:do/1\
+.  .  .  rules:chase/1\
+.  .  .  .  data:loc/2\
+.  .  .  .  rules:move/2\
+.  .  .  .  .  assert-data:loc/2\
+.  .  .  .  .  retract-data:loc/2\
+.  .  .  .  builtin:nl/0\
+.  .  .  .  builtin:write/1\
+.  .  .  rules:goto/1\
+.  .  .  .  rules:connect/2
+\f0\fs24 \
+\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\pardirnatural
+\cf0 \
+\
+
+\b Dynamic Predicates, Bottom Up
+\b0 \
+\
+Dynamic predicates have places where they\'92re modified, and places where they\'92re used.  These reports trace both of those cones up.  Here\'92s part of the report for loc/2 in the data module.  Note from above, that move/2 is where the asserts/retracts are for loc/2.\
+\
+\pard\pardeftab720
+
+\f1\fs22 \cf0 data:loc/2   modified in:\
+.  rules:move/2\
+.  .  rules:chase/1\
+.  .  .  rules:do/1\
+.  .  .  .  user:go/0\
+.  .  .  .  .  user:go/0  ***** looping *****\
+.  .  .  .  .  user:main/0\
+.  .  rules:ducks/0\
+.  .  .  rules:demons/0\
+.  .  .  .  user:go/0\
+.  .  .  .  .  user:go/0  ***** looping *****\
+.  .  .  .  .  user:main/0\
+\
+\pard\pardeftab720
+
+\f0\fs24 \cf0 \
+\pard\pardeftab720
+
+\f1\fs22 \cf0 data:loc/2   used by:\
+.  rules:chase/1\
+.  .  rules:do/1\
+.  .  .  user:go/0\
+.  .  .  .  user:go/0  ***** looping *****\
+.  .  .  .  user:main/0\
+.  rules:done/0\
+.  .  user:go/0\
+.  .  .  user:go/0  ***** looping *****\
+.  .  .  user:main/0\
+.  rules:ducks/0\
+.  .  rules:demons/0\
+.  .  .  user:go/0\
+.  .  .  .  user:go/0  ***** looping *****\
+.  .  .  .  user:main/0\
+.  rules:fox/0\
+.  .  rules:demons/0\
+.  .  .  user:go/0\
+.  .  .  .  user:go/0  ***** looping *****\
+.  .  .  .  user:main/0\
+\
+\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\pardirnatural
+
+\f0\b\fs24 \cf0 More Work\
+
+\b0 \
+From here it needs to be tested with PhaseChange modules.\
+\
+Support for maplist and others needs to be added so those meta-predicates can be tracked by their content.\
+}

dw_data.pro

@@ -4,8 +4,8 @@
 % asserted/retracted from the other modules, so it is
 % declared as dynamic.
 
-:- module(data).
-:- export([nextto/2, loc/2]).
+:- module(data,
+      [nextto/2, loc/2]).
 :- dynamic(loc/2).
 
 nextto(pen, yard).
@@ -15,4 +15,3 @@ loc(egg,pen).
 loc(ducks,pen).
 loc(you,house).
 
-:- end_module(data).

dw_main.pro

@@ -32,16 +32,16 @@
 % code in the 'user' module to refer, without module
 % qualification, to the predicates exported from 'rules'.
 
-:- import(rules).
+:- use_module('dw_rules.pro').
 
 % The code in this file is in module 'user'.  Because that
 % is the default module, it does not need to be specified.
 % The following predicates are all in 'user'.
 
-dw_main :-
-	write(` Welcome to Duck World `),nl,
+main :-
+	write(' Welcome to Duck World '),nl,
 	instructions,
-	write(` Go get an egg `),nl,
+	write(' Go get an egg '),nl,
 	go.
 
 % Because 'rules' are imported by 'user', this
@@ -50,26 +50,26 @@ dw_main :-
 
 go :- done.
 go :-
-	write($>> $),
+	write('>> '),
 	read(X),
 	X \= quit,
 	do(X),
 	demons,
 	!, go.
-go :- write($ Quitter $), nl.
+go :- write(' Quitter '), nl.
 
 instructions :-
 	nl,
-	write($You start in the house, the ducks and an egg$), nl,
-	write($are in the pen.  You have to get the egg$), nl,
-	write($without losing any ducks.$), nl,
+	write('You start in the house, the ducks and an egg'), nl,
+	write('are in the pen.  You have to get the egg'), nl,
+	write('without losing any ducks.'), nl,
 	nl,
-	write($Enter commands at the prompt as Prolog terms$), nl,
-	write($ending in period:$), nl,
-	write($  goto(X). - where X is a place to go to.$), nl,
-	write($  take(X). - where X is a thing to take.$), nl,
-	write($  chase(X). - chasing ducks sends them to the pen.$), nl,
-	write($  look. - the state of the game.$), nl,
-	write($  help. - this information.$), nl,
-	write($  quit. - exit the game.$), nl,
+	write('Enter commands at the prompt as Prolog terms'), nl,
+	write('ending in period:'), nl,
+	write('  goto(X). - where X is a place to go to.'), nl,
+	write('  take(X). - where X is a thing to take.'), nl,
+	write('  chase(X). - chasing ducks sends them to the pen.'), nl,
+	write('  look. - the state of the game.'), nl,
+	write('  help. - this information.'), nl,
+	write('  quit. - exit the game.'), nl,
 	nl.