From: Thomas Walker Lynch <xtujpz@reasoningtechnology.com>
Date: Tue, 5 Nov 2024 02:28:10 +0000 (+0000)
Subject: updating project structure
X-Git-Url: https://git.reasoningtechnology.com/style/static/gitweb.js?a=commitdiff_plain;h=aac7cff2208b71798aea2ff31118e2f69b5e7a54;p=Ariadne

updating project structure
---

diff --git a/developer/document/variable_suffix_conventions.txt b/developer/document/variable_suffix_conventions.txt
index e5ef76e..e3ad587 100644
--- a/developer/document/variable_suffix_conventions.txt
+++ b/developer/document/variable_suffix_conventions.txt
@@ -15,9 +15,13 @@ Instead of making a variable name plural, add the interface qualifier.
 ## Always a good idea to use these when working with files
 
 - `_fp`: Refers to a file path. The part after the last slash is a file name.
+
+- `_afp`: Refers to an absolute file path.
   
 - `_dp`: Refers to a directory path. By convention, the value ends in a slash.
 
+- `_adp`: Refers to an absolute directory path. 
+
 - `_fn`: Refers to a file name. Value has no slashes.
 
 - `_dn`: Refers to a directory name. Value has no slashes.
diff --git a/developer/temp b/developer/temp
deleted file mode 100644
index b626df8..0000000
--- a/developer/temp
+++ /dev/null
@@ -1,42 +0,0 @@
---------------------------------------------------------------------------------
-javac/LabelList.java:
-package com.ReasoningTechnology.Ariadne;
-import java.util.ArrayList;
-
-  public class LabelList extends ArrayList<Label> {}
-
---------------------------------------------------------------------------------
-javac/Node.java:
-package com.ReasoningTechnology.Ariadne;
-import java.util.Map;
-
-  public interface Node extends Map<Label ,Object>{}
-
---------------------------------------------------------------------------------
-javac/NodeList.java:
-package com.ReasoningTechnology.Ariadne;
-import java.util.ArrayList;
-
-  public interface NodeList extends ArrayList<Node> {}
-
---------------------------------------------------------------------------------
-javac/Production.java:
-package com.ReasoningTechnology.Ariadne;
-import java.util.function.Function;
-
-  public interface Production extends Function<Label ,Node>{}
-
---------------------------------------------------------------------------------
-javac/ProductionList.java:
-package com.ReasoningTechnology.Ariadne;
-import java.util.ArrayList; 
-
-public class ProductionList extends ArrayList<Production> {}
-
---------------------------------------------------------------------------------
-javac/TokenSet.java:
-package com.ReasoningTechnology.Ariadne;
-import java.util.HashSet;  
-
-public class TokenSet extends HashSet<Token>{}
-
diff --git a/developer/tool/clean_build_directories b/developer/tool/clean_build_directories
index ed9e807..7091d81 100755
--- a/developer/tool/clean_build_directories
+++ b/developer/tool/clean_build_directories
@@ -1,9 +1,10 @@
-#!/bin/bash
+#!/usr/bin/env bash
+script_afp=$(realpath "${BASH_SOURCE[0]}")
 
 # Removes all files found in the build directories. It asks no questions as to
-# how or why the files got there. Be especially careful with the 'shell' directory
-# if you added scripts to it for release with the project they will be deleted.
-# consider adding a `shell-leaf` directory instead of adding scripts to `shell`.
+# how or why the files got there. Be especially careful with the 'shell'
+# directory if you have authored scripts for release, add a `shell-leaf`
+# directory instead of putting them in `shell`.
 
 # input guards
   env_must_be="developer/tool/env"
@@ -15,7 +16,7 @@
 # remove files
   set -x
   cd "$REPO_HOME"/developer
-  rm -r scratch_pad/*
+  rm -r scratchpad/*
   rm jvm/*
   rm shell/*
   set +x
diff --git a/developer/tool/clean_javac_output b/developer/tool/clean_javac_output
index 57e64c1..5ebeb51 100755
--- a/developer/tool/clean_javac_output
+++ b/developer/tool/clean_javac_output
@@ -1,4 +1,5 @@
-#!/bin/bash
+#!/usr/bin/env bash
+script_afp=$(realpath "${BASH_SOURCE[0]}")
 # remove  all files created by make's call to `javac`
 
 # input guards
@@ -11,7 +12,7 @@
 # remove files
   set -x
   cd "$REPO_HOME"/developer
-  rm -r scratch_pad/com/ReasoningTechnology/Ariadne
+  rm -r scratchpad/com/ReasoningTechnology/"$PROJECT"
   set +x
 
 echo "$(script_fn) done."
diff --git a/developer/tool/clean_make_output b/developer/tool/clean_make_output
new file mode 100755
index 0000000..a7c6ebf
--- /dev/null
+++ b/developer/tool/clean_make_output
@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+script_afp=$(realpath "${BASH_SOURCE[0]}")
+# remove all files made by `make`
+
+# input guards
+
+  env_must_be="developer/tool/env"
+  if [ "$ENV" != "$env_must_be" ]; then
+    echo "$(script_fp):: error: must be run in the $env_must_be environment"
+    exit 1
+  fi
+
+# wrappers to clean (this list space separated list will grow)
+
+  wrapper=$(shell_wrapper_list)
+
+# remove files
+
+  set -x
+  cd "$REPO_HOME"/developer
+  rm -r scratchpad/com/ReasoningTechnology/"$PROJECT"
+  rm jvm/"$PROJECT".jar
+  rm shell/{$wrapper}
+  set +x
+
+echo "$(script_fn) done."
diff --git a/developer/tool/clean_release b/developer/tool/clean_release
index f5b59c7..a33f19a 100755
--- a/developer/tool/clean_release
+++ b/developer/tool/clean_release
@@ -1,4 +1,5 @@
-#!/bin/bash
+#!/usr/bin/env bash
+script_afp=$(realpath "${BASH_SOURCE[0]}")
 # remove files made by `make` and by `release`
 
 # input guards
@@ -12,15 +13,15 @@
 # things to clean
 
   release_dir="$REPO_HOME"/release
-  wrapper=build
+  wrapper=$(shell_wrapper_list)
 
 # remove files
   set -x
   cd "$REPO_HOME"/developer
-  rm -r scratch_pad/com/ReasoningTechnology/Ariadne
-  rm jvm/Ariadne.jar
+  rm -r scratchpad/com/ReasoningTechnology/"$PROJECT"
+  rm jvm/"$PROJECT".jar
   rm shell/{$wrapper}
-  rm -f "$release_dir"/Ariadne.jar
+  rm -f "$release_dir"/"$PROJECT".jar
   rm -f "$release_dir"/{$wrapper}
   set +x
 
diff --git a/developer/tool/distribute_source b/developer/tool/distribute_source
new file mode 100755
index 0000000..faf844d
--- /dev/null
+++ b/developer/tool/distribute_source
@@ -0,0 +1,32 @@
+#!/bin/env bash
+script_afp=$(realpath "${BASH_SOURCE[0]}")
+
+# This script links the sources into the directory tree in parallel to the package.
+
+# Input guards
+
+  env_must_be="developer/tool/env"
+  if [ "$ENV" != "$env_must_be" ]; then
+    echo "$(script_fp):: error: must be run in the $env_must_be environment"
+    exit 1
+  fi
+
+  cd "$REPO_HOME"/developer
+
+# Link sources into the package tree
+
+  package_tree="scratchpad/com/ReasoningTechnology/$PROJECT"
+  mkdir -p "$package_tree"
+  echo "Package: $package_tree"
+
+  echo -n "Linking:"
+  for source_file in javac/*.java; do
+    echo -n " $(basename "$source_file")"
+    link_target="$package_tree/$(basename "$source_file")"
+    if [ ! -L "$link_target" ]; then
+      ln -s "$(realpath --relative-to="$package_tree" "$source_file")" "$link_target"
+    fi
+  done
+  echo "."
+
+echo "$(script_fp) done."
diff --git a/developer/tool/env b/developer/tool/env
index 3321c60..66446d4 100644
--- a/developer/tool/env
+++ b/developer/tool/env
@@ -1,17 +1,19 @@
 #!/usr/bin/env bash
+script_afp=$(realpath "${BASH_SOURCE[0]}")
 
 # input guards
 
   env_must_be="tool_shared/bespoke/env"
+  error=false
   if [ "$ENV" != "$env_must_be" ]; then
     echo "$(script_fp):: error: must be run in the $env_must_be environment"
-    exit 1
+    error=true
   fi
-
   if [[ "${BASH_SOURCE[0]}" == "$0" ]]; then
-    echo "$script_name:: This script must be sourced, not executed."
-    exit 1
+    echo "$script_afp:: This script must be sourced, not executed."
+    error=true
   fi
+  if $error; then exit 1; fi
 
 # so we can do the build
 
@@ -25,7 +27,7 @@ export PATH=\
 
 export CLASSPATH=\
 "$REPO_HOME"/developer/jvm\
-:"$REPO_HOME"/developer/jvm/Ariadne.jar\
+:"$REPO_HOME"/developer/jvm/"$PROJECT".jar\
 :"$JAVA_HOME"/lib\
 :"$CLASSPATH"
 
@@ -40,7 +42,7 @@ export PATH=\
 
 # some feedback to show all went well
 
-  export PROJECT="$PROJECT"_developer
+  export PROMPT_DECOR="$PROJECT"_developer
   export ENV=$(script_fp)
   echo ENV "$ENV"
   cd "$REPO_HOME"/developer/
diff --git a/developer/tool/make b/developer/tool/make
index ab9c643..be84a0e 100755
--- a/developer/tool/make
+++ b/developer/tool/make
@@ -1,4 +1,5 @@
 #!/bin/env bash
+script_afp=$(realpath "${BASH_SOURCE[0]}")
 
 # input guards
 
@@ -12,7 +13,7 @@
 
 echo "Compiling files..."
   set -x
-  javac -d scratch_pad javac/*.java
+  javac -g -d scratchpad javac/*.java
   set +x
   if [ $? -ne 0 ]; then
     echo "Compilation failed."
@@ -21,9 +22,9 @@ echo "Compiling files..."
 
 echo "Creating JAR file..."
   set -x
-  jar_file=jvm/Ariadne.jar
+  jar_file=jvm/"$PROJECT".jar
   mkdir -p jvm
-  jar cf $jar_file -C scratch_pad .
+  jar cf $jar_file -C scratchpad .
   set +x
   if [ $? -eq 0 ]; then
     echo "JAR file created successfully: $jar_file"
@@ -35,11 +36,11 @@ echo "Creating JAR file..."
 echo "Creating shell wrappers..."
   mkdir -p shell
   # wrapper is a space separated list
-  wrapper=build
+  wrapper=$(shell_wrapper_list)
   for file in $wrapper;do
     cat > shell/$file << EOL
 #!/bin/bash
-java com/ReasoningTechnology/Ariadne/$file
+java com.ReasoningTechnology."$PROJECT".$file
 EOL
     chmod +x shell/$file
   done
diff --git a/developer/tool/release b/developer/tool/release
index b6b9dbd..bcf4686 100755
--- a/developer/tool/release
+++ b/developer/tool/release
@@ -1,4 +1,5 @@
-#!/bin/bash
+#!/usr/bin/env bash
+script_afp=$(realpath "${BASH_SOURCE[0]}")
 
 # input guards
 
@@ -17,8 +18,8 @@
 
   release_dir="$REPO_HOME/release"
   shell_dir="$REPO_HOME/developer/shell"
-  Ariadne_jar_fp="$REPO_HOME/developer/jvm/Ariadne.jar"
-  wrapper=build
+  project_jar_fp="$REPO_HOME/developer/jvm/"$PROJECT".jar"
+  wrapper=$(shell_wrapper_list)
 
 
   if [ ! -d "$release_dir" ]; then
@@ -51,7 +52,7 @@
   echo "Starting release process..."
 
   # Install the JAR file
-  install_file "$Ariadne_jar_fp" "$release_dir" "ug+r"
+  install_file "$project_jar_fp" "$release_dir" "ug+r"
 
   # Install shell wrappers
   for wrapper in $wrapper; do
diff --git a/developer/tool/shell_wrapper_list b/developer/tool/shell_wrapper_list
new file mode 100755
index 0000000..c95affe
--- /dev/null
+++ b/developer/tool/shell_wrapper_list
@@ -0,0 +1,15 @@
+#!/bin/env bash
+script_afp=$(realpath "${BASH_SOURCE[0]}")
+
+# input guards
+
+  env_must_be="developer/tool/env"
+  if [ "$ENV" != "$env_must_be" ]; then
+    echo "$(script_fp):: error: must be run in the $env_must_be environment"
+    exit 1
+  fi
+
+  cd "$REPO_HOME"/developer
+
+# list of classes that have main calls and get shell wrappers
+echo Mosaic
diff --git a/document/bash_name_of_script.txt b/document/bash_name_of_script.txt
new file mode 100644
index 0000000..3637574
--- /dev/null
+++ b/document/bash_name_of_script.txt
@@ -0,0 +1,40 @@
+
+Bash is inconsistent about returning the name of the running script in
+all scenarios (sourced, executed directly, from with in a function called
+by another function).
+
+1.
+
+BASH_SOURCE[0] was used because $0 did not work with sourced scripts (a
+fact that is leveraged for detecting when in a sourced script).
+
+2.
+
+However, this did not work in all scenarios:
+
+  read -r -d '' script_afp_string <<'EOF'
+  realpath "${BASH_SOURCE[0]}" 2>/dev/null
+  EOF
+
+    script_afp(){
+      eval "$script_afp_string"
+    }
+
+  export script_afp_string
+  export -f script_afp
+
+When `script_afp` was exported, used in another file, and used within a function
+in that other file, it reported `environment` for the script name at
+BASH_SOURCE[0].  In various call scenarios the actual script name appears at
+BASH_SOURCE[1] or even at BASH_SOURCE[2].  
+
+3.
+
+As a stable alternative to having a script_afp function, place this line
+at the top of scripts that use the `script_XX` functions, or at the top
+of all scripts:
+
+  script_afp=realpath "${BASH_SOURCE[0]}"
+
+Then use $script_afp as a string within other functions. It will have stable
+value no matter the call structure.
diff --git a/document/directory_naming.html b/document/directory_naming.html
index 92e1703..d409362 100644
--- a/document/directory_naming.html
+++ b/document/directory_naming.html
@@ -13,7 +13,7 @@
 
   body {
     font-family: 'Noto Sans JP', Arial, sans-serif;
-    background-color: hsl(0, 0%, 10%);
+    background-color: hsl(0, 0%, 0%);
     color: hsl(42, 100%, 80%);
     padding: 2rem;
     margin: 0;
@@ -84,7 +84,7 @@
     <h2>Reference</h2>
 
     <ul>
-      <li>Ariadne/<span class="description">aka REPO_HOME, top level owned by the project administrator.</span></li>
+      <li>Mosaic/<span class="description">aka REPO_HOME, top level owned by the project administrator.</span></li>
       <ul>
         <li>developer/ <span class="description">Workspace for the developer. Has the source code, build scripts, and development-specific tools.</span></li>
         <ul>
@@ -92,19 +92,17 @@
           <li>document/ <span class="description">Documentation on developing and building the project.</span></li>
           <li>javac/ <span class="description">Java source files for compilation.</span></li>
           <li>jvm/ <span class="description">Compiled Java bytecode files for the project, typically a jar for a Java project.</span></li>
-          <li>scratch_pad/ <span class="description">Temporary storage typically for intermediate files created during build.</span></li>
+          <li>scratchpad/ <span class="description">Temporary storage typically for intermediate files created during build.</span></li>
           <li>shell/ <span class="description">Shell scripts intended to be part of the project release. (These are not tools.)</span></li>
           <li>tool/ <span class="description">Tools created by the developer, used for development tasks.</span></li>
         </ul>
         <li>document/ <span class="description">General documentation about the project.</span></li>
         <li>release/ <span class="description">Release candidate for testing. Becomes the release on the release branch.</span></li>
-        <li>scratch_pad/ <span class="description">Temporary storage for project administration tasks.</span></li>
+        <li>scratchpad/ <span class="description">Temporary storage for project administration tasks.</span></li>
         <li>tester/ <span class="description">Workspace for the tester. Has the test bench, tests, and test scripts.</span></li>
         <ul>
           <li>document/ <span class="description">Test-specific documentation.</span></li>
-          <li>test0/ <span class="description">Test case 0 environment and associated scripts.</span></li>
-          <li>test1/ <span class="description">Test case 1 environment and associated scripts.</span></li>
-          <li>test2/ <span class="description">Test case 2 environment and associated scripts.</span></li>
+          <li>javac/ <span class="description">The tests of the test bench sources.</span></li>
           <li>tool/ <span class="description">Tools needed for testing and managing the test environment.</span></li>
         </ul>
         <li>tool/ <span class="description">Project administration specific tools.</span></li>
@@ -150,14 +148,14 @@
       
     <p>When attempting to apply the <code>is-for</code> property in practice it
       became apparent that using this sole property was insufficient.  Consider
-      the directories <code>deprecated/</code> and <code>scratch_pad/</code>. There is no
-      <em>Mr. Deprecated</em> or <em>Mr. Scratch_Pad</em> who the contained
+      the directories <code>deprecated/</code> and <code>scratchpad/</code>. There is no
+      <em>Mr. Deprecated</em> or <em>Mr. Scratchpad</em> who the contained
       files are for. (And this conclusion is not for the lack of trying. Even
       mythological beings did not suffice as agents.) Rather than being for an
       agent, the files collected in such a directory have in common a state of
       being that was imposed upon them by decree.  Perhaps the developer, has
       decreed that a file is now deprecated, or a build script has decreed that
-      it is a scratch_pad file. Such decrees are typically more dynamic than the
+      it is a scratchpad file. Such decrees are typically more dynamic than the
       relationship properties. Also, these properties are disconnected from the
       contents of the file.  When, for example, a file has the property of being
       for the java compiler, we gain some information about its contents. In the
diff --git a/document/work_flow.txt b/document/work_flow.txt
index b72f01a..6c3ea4c 100644
--- a/document/work_flow.txt
+++ b/document/work_flow.txt
@@ -9,7 +9,7 @@
 
 #### 2. Developer
 
-2.1. From the Ariadne directory, run `> source env_developer` to set up the
+2.1. From the Mosaic directory, run `> source env_developer` to set up the
      developer environment.
 2.2. Use `> make` to build the project, and `> release` to copy relevant files
      to `$REPO_HOME/release` for testing.
@@ -17,7 +17,7 @@
 
 #### 3. Tester
 
-3.1. From the Ariadne directory, run `> source env_tester` to set up the tester
+3.1. From the Mosaic directory, run `> source env_tester` to set up the tester
      environment.
 3.2. Use `> make` to build the tests, and `> shell/test_<name>` to run a test.
      Alternatively, you can cd into one of the test directories, source the
@@ -29,7 +29,7 @@
 
 4.1. The release candidate is located in the `$REPO_HOME/release` directory and
      has passed testing.
-4.2. Check that the program `$REPO_HOME/tool_shared/bespoke/release` outputs the
+4.2. Check that the program `$REPO_HOME/tool_shared/bespoke/version` outputs the
      correct information. If necessary, modify it.
 4.3. A new branch is created in the project for the release, named
      `release_v<n>.0`, where `v<n>.0` is the version number from the `version`
diff --git a/env_administrator b/env_administrator
index 4b691ce..0fc10de 100644
--- a/env_administrator
+++ b/env_administrator
@@ -1,9 +1,10 @@
 #!/usr/bin/env bash
+script_afp=$(realpath "${BASH_SOURCE[0]}")
+if [[ "${BASH_SOURCE[0]}" == "$0" ]]; then
+  echo "$script_afp:: This script must be sourced, not executed."
+  exit 1
+fi
 
-script_path="$(dirname "$(realpath "${BASH_SOURCE[0]}")")"
-export REPO_HOME="${script_path%}/"
-echo REPO_HOME "$REPO_HOME"
+source tool_shared/bespoke/env
 
-cd "$REPO_HOME"
-source tool/env
 
diff --git a/env_developer b/env_developer
index 8659f86..6240b20 100644
--- a/env_developer
+++ b/env_developer
@@ -1,10 +1,10 @@
 #!/usr/bin/env bash
+script_afp=$(realpath "${BASH_SOURCE[0]}")
+if [[ "${BASH_SOURCE[0]}" == "$0" ]]; then
+  echo "$script_afp:: This script must be sourced, not executed."
+  exit 1
+fi
 
-script_path="$(dirname "$(realpath "${BASH_SOURCE[0]}")")"
-export REPO_HOME="${script_path%}/"
-echo REPO_HOME "$REPO_HOME"
-
-cd "$REPO_HOME"
 source tool_shared/bespoke/env
 source developer/tool/env
 
diff --git a/env_tester b/env_tester
index d1bd2d5..44aace3 100644
--- a/env_tester
+++ b/env_tester
@@ -1,9 +1,9 @@
 #!/usr/bin/env bash
+script_afp=$(realpath "${BASH_SOURCE[0]}")
+if [[ "${BASH_SOURCE[0]}" == "$0" ]]; then
+  echo "$script_afp:: This script must be sourced, not executed."
+  exit 1
+fi
 
-script_path="$(dirname "$(realpath "${BASH_SOURCE[0]}")")"
-export REPO_HOME="${script_path%}/"
-echo REPO_HOME "$REPO_HOME"
-
-cd "$REPO_HOME"
 source tool_shared/bespoke/env
 source tester/tool/env
diff --git a/tester/document/about_TestBench.txt b/tester/document/about_TestBench.txt
deleted file mode 100644
index 7bca2ea..0000000
--- a/tester/document/about_TestBench.txt
+++ /dev/null
@@ -1,7 +0,0 @@
-
-javac/TestBench is the non-project specific part of the test bench. (It does not
-belong here, rather it should be its own project.)
-
-javac/TestBenchAriadne Has the project specific tests.
-
-
diff --git a/tester/document/jdb.txt b/tester/document/jdb.txt
new file mode 100644
index 0000000..1ed956a
--- /dev/null
+++ b/tester/document/jdb.txt
@@ -0,0 +1,54 @@
+About `jdb`
+
+1. setting the environment
+
+  The environment should be set before running the IDE. For example,
+
+  > cd Mosaic
+  > source env_tester
+  > emacs & 
+
+  (I use emacs as my IDE. You might be using a different tool.)
+
+2. location of the executable
+
+  Provided that the project administrator installed it, jdb is located in the
+  third_party tools directory. In the tester environment the variable
+  `JAVA_HOME` should hold the jdb directory path, and this should already
+  be in the `PATH`.  For example:
+
+  > echo $ENV
+  tester/tool/env
+
+  > echo $JAVA_HOME
+  /var/user_data/Thomas-developer/Mosaic/tool_shared/third_party/jdk-11
+
+  > which jdb
+  /var/user_data/Thomas-developer/Mosaic/tool_shared/third_party/jdk-11/bin/jdb
+
+3. invocation from a shell command:
+
+     jdb -sourcepath $SOURCEPATH <class_name>
+
+   The `SOURCEPATH` is assigned a value in `tester/tool/env`.  In some versions
+   of jdb there is no space between `-sourcepath` and the `$SOURCDEPATH`.  
+
+   jdb will read CLASSPATH from the environment. In contrast jdb will not read
+   `SOURCEPATH` from the environment. It must be passed as an argument.
+
+   There is a `run_jdb` script in the `tool` directory.
+
+4. invocation inside of Emacs
+
+   The file `tool_shared/bespoke/emacs.el` holds a definition for the `jdbx`
+   command.  This command will read the SOURCEPATH from the environment and run
+   jdb in Emacs.
+
+   That file also holds the definition for a listener to the jdb `sourcepath`
+   command.
+
+
+
+
+
+
diff --git a/tester/javac/TestBench.java b/tester/javac/TestBench.java
index d036ce2..642d09f 100644
--- a/tester/javac/TestBench.java
+++ b/tester/javac/TestBench.java
@@ -11,6 +11,22 @@ import java.util.Map;
 
 public class TestBench{
 
+  /* --------------------------------------------------------------------------------
+    Static Data
+  */
+
+  private static PrintStream original_out;
+  private static PrintStream original_err;
+  private static InputStream original_in;
+  
+  private static ByteArrayOutputStream out_content;
+  private static ByteArrayOutputStream err_content;
+  private static InputStream in_content;
+
+  /* --------------------------------------------------------------------------------
+    Test utility methods
+  */
+
   // typically used to gather results before a return
   public static boolean all(boolean[] conditions){
     for( boolean condition : conditions ){
@@ -21,26 +37,18 @@ public class TestBench{
     return true;
   }
 
-  public static void flush_stdin() throws IOException{
-    while(System.in.available() > 0){
-      System.in.read();
-    }
-  }
-
-  public static void set_test_input(String input_data){
-    ByteArrayInputStream test_in = new ByteArrayInputStream(input_data.getBytes());
-    System.setIn(test_in);
-  }
-
-  public static void log_output(String test_name ,String stream ,String output_data) throws IOException{
-    // Only log if there is actual content to log
-    if(output_data != null && !output_data.isEmpty()){
-      try(FileWriter log_writer = new FileWriter("test_log.txt" ,true)){  // Append mode
-        log_writer.write("Test: " + test_name + "\n");
-        log_writer.write("Stream: " + stream + "\n");
-        log_writer.write("Output:\n" + output_data + "\n");
-        log_writer.write("----------------------------------------\n");
-      }
+  /* --------------------------------------------------------------------------------
+    Test run helpers
+  */
+  public static void log_output(String test_name ,String stream ,String output_data){
+    try(FileWriter log_writer = new FileWriter("test_log.txt" ,true)){  // Append mode
+      log_writer.write("Test: " + test_name + "\n");
+      log_writer.write("Stream: " + stream + "\n");
+      log_writer.write("Output:\n" + output_data + "\n");
+      log_writer.write("----------------------------------------\n");
+    } catch(IOException e) {
+      System.err.println("Error writing to log for test: " + test_name + ", stream: " + stream);
+      e.printStackTrace(System.err);
     }
   }
 
@@ -70,8 +78,20 @@ public class TestBench{
 
     return true;
   }
+  
+  public static void flush_stdin() throws IOException{
+    while(System.in.available() > 0){
+      System.in.read();
+    }
+  }
+
+  public static void set_test_input(String input_data){
+    ByteArrayInputStream test_in = new ByteArrayInputStream(input_data.getBytes());
+    System.setIn(test_in);
+  }
 
-  public static void run(Object test_suite ,String[] stdin_array){
+
+  public static void run(Object test_suite){
 
     int failed_test = 0;
     int passed_test = 0;
@@ -95,15 +115,23 @@ public class TestBench{
         continue;
       }
 
+      PrintStream original_out = null;
+      PrintStream original_err = null;
+      InputStream original_in  = null;
+
+      ByteArrayOutputStream out_content = null;
+      ByteArrayOutputStream err_content = null;
+      ByteArrayInputStream in_content = null;
+
       try{
         // Redirect the I/O channels so the tests can manipulate them as data.
-        PrintStream original_out = System.out;
-        PrintStream original_err = System.err;
-        InputStream original_in = System.in;
+        original_out = System.out;
+        original_err = System.err;
+        original_in = System.in;
   
-        ByteArrayOutputStream out_content = new ByteArrayOutputStream();
-        ByteArrayOutputStream err_content = new ByteArrayOutputStream();
-        ByteArrayInputStream in_content = new ByteArrayInputStream(String.join("\n" ,stdin_array).getBytes());
+        out_content = new ByteArrayOutputStream();
+        err_content = new ByteArrayOutputStream();
+        in_content = new ByteArrayInputStream();
 
         System.setOut(new PrintStream(out_content));
         System.setErr(new PrintStream(err_content));
@@ -116,13 +144,13 @@ public class TestBench{
         System.setIn(original_in);
 
         // Report the error
-        System.out.println("TestBench:: when redirecting i/o in preparation for running test \'" + test.getName() + "\' ,test bench itself throws error: " + e.toString());
+        System.out.println("TestBench:: when redirecting i/o in preparation for running test \'" + method.getName() + "\' ,test bench itself throws error: " + e.toString());
         failed_test++;
         continue;
       }
 
       // Capture detritus 
-      Exception exception_string = "";
+      String exception_string = "";
       String stdout_string = "";
       String stderr_string = "";
 
@@ -146,7 +174,7 @@ public class TestBench{
         fail_exception = true;
 
         // We keep it to report it
-        exception = e;
+        exception_string = e.toString();
 
       } finally{
         
@@ -156,6 +184,7 @@ public class TestBench{
         System.setIn(original_in);
       }
 
+      // Report the test result.
       if(
          fail_reported 
          || fail_exception 
@@ -182,7 +211,7 @@ public class TestBench{
 
     }
 
-    // Report summary of results
+    // Summarize all the test results
     System.out.println("Total tests run: " + (passed_test + failed_test));
     System.out.println("Total tests passed: " + passed_test);
     System.out.println("Total tests failed: " + failed_test);
diff --git a/tester/jvm/TestBench.jar b/tester/jvm/TestBench.jar
index 378f60c..fa385ca 100644
Binary files a/tester/jvm/TestBench.jar and b/tester/jvm/TestBench.jar differ
diff --git a/tester/tool/clean_build_directories b/tester/tool/clean_build_directories
index 2aff503..5b84fd0 100755
--- a/tester/tool/clean_build_directories
+++ b/tester/tool/clean_build_directories
@@ -1,8 +1,10 @@
-#!/bin/bash
+#!/usr/bin/env bash
+script_afp=$(realpath "${BASH_SOURCE[0]}")
 
-# Caveat: the 'shell' directory is for built wrapper functions. `clean_build_directories` will
-# remove all the files in this directory. For bespoke scripts used by the tester, put
-# them in the `tool` directory.
+# Caveat: the 'shell' directory is for built wrapper
+# functions. `clean_build_directories` will remove all the files in this
+# directory. For bespoke scripts used by the tester, put them in the `tool`
+# directory.
 
 # input guards
   env_must_be="tester/tool/env"
@@ -14,7 +16,7 @@
 # remove files
   set -x
   cd "$REPO_HOME"/tester
-  rm -r scratch_pad/*
+  rm -r scratchpad/*
   rm jvm/*
   rm shell/*
   set +x
diff --git a/tester/tool/env b/tester/tool/env
index e406896..e73741c 100644
--- a/tester/tool/env
+++ b/tester/tool/env
@@ -1,17 +1,19 @@
 #!/usr/bin/env bash
+script_afp=$(realpath "${BASH_SOURCE[0]}")
 
 # input guards
 
   env_must_be="tool_shared/bespoke/env"
+  error=false
   if [ "$ENV" != "$env_must_be" ]; then
     echo "$(script_fp):: error: must be run in the $env_must_be environment"
-    exit 1
+    error=true
   fi
-
   if [[ "${BASH_SOURCE[0]}" == "$0" ]]; then
-    echo "$script_name:: This script must be sourced, not executed."
-    exit 1
+    echo "$script_afp:: This script must be sourced, not executed."
+    error=true
   fi
+  if $error; then exit 1; fi
 
 # so we can do testing
 
@@ -23,11 +25,15 @@ export PATH=\
 
 export CLASSPATH=\
 "$JAVA_HOME"/lib\
-:"$REPO_HOME"/release/Ariadne.jar\
-:"$REPO_HOME"/tester/jvm/TestBench.jar\
-:"$REPO_HOME"/tester/jvm/TestBenchAriadne.jar\
+:"$REPO_HOME"/release/"$PROJECT".jar\
+:"$REPO_HOME"/tester/jvm/Test_"$PROJECT".jar\
 :"$CLASSPATH"
 
+export SOURCEPATH=\
+"$REPO_HOME"/tester/javac/\
+:"$REPO_HOME"/developer/scratchpad/\
+
+
 # misc
 
   # make .githolder and .gitignore visible
@@ -35,7 +41,7 @@ export CLASSPATH=\
 
 # some feedback to show all went well
 
-  export PROJECT="$PROJECT"_tester
+  export PROMPT_DECOR="$PROJECT"_tester
   export ENV=$(script_fp)
   echo ENV "$ENV"
   cd "$REPO_HOME"/tester/
diff --git a/tester/tool/make b/tester/tool/make
index 03f9b36..deae0a1 100755
--- a/tester/tool/make
+++ b/tester/tool/make
@@ -1,4 +1,5 @@
 #!/bin/env bash
+script_afp=$(realpath "${BASH_SOURCE[0]}")
 
 # input guards
 
@@ -12,18 +13,18 @@ echo "Compiling files..."
 
   set -x
   cd $REPO_HOME/tester
-  javac -d scratch_pad javac/*.java
-  jar cf jvm/TestBenchAriadne.jar -C scratch_pad .
+  javac -g -d scratchpad javac/*.java
+  jar cf jvm/Test_"$PROJECT".jar -C scratchpad .
   set +x 
 
 echo "Creating shell wrappers..."
   mkdir -p shell
   # wrapper is a space separated list
-  wrapper=TestTestBench
+  wrapper=$(shell_wrapper_list)
   for file in $wrapper;do
     cat > shell/$file << EOL
 #!/bin/env bash
-java com.ReasoningTechnology.Ariadne.TestBench.$file
+java $file
 EOL
     chmod +x shell/$file
   done
diff --git a/tester/tool/make_TestBench b/tester/tool/make_TestBench
deleted file mode 100755
index 291fdee..0000000
--- a/tester/tool/make_TestBench
+++ /dev/null
@@ -1,31 +0,0 @@
-#!/bin/env bash
-
-# input guards
-
-  env_must_be="tester/tool/env"
-  if [ "$ENV" != "$env_must_be" ]; then
-    echo "$(script_fp):: error: must be run in the $env_must_be environment"
-    exit 1
-  fi
-
-echo "Compiling files..."
-
-  set -x
-  cd $REPO_HOME/tester
-  javac -d scratch_pad javac/TestBench.java javac/TestTestBench.java
-  jar cf jvm/TestBench.jar -C scratch_pad com/ReasoningTechnology/TestBench
-  set +x 
-
-echo "Creating shell wrappers..."
-  mkdir -p shell
-  # wrapper is a space separated list
-  wrapper=TestTestBench
-  for file in $wrapper;do
-    cat > shell/$file << EOL
-#!/bin/env bash
-java com.ReasoningTechnology.TestBench.$file
-EOL
-    chmod +x shell/$file
-  done
-
-echo "$(script_fp) done."
diff --git a/tester/tool/run_jdb b/tester/tool/run_jdb
new file mode 100755
index 0000000..9c472f4
--- /dev/null
+++ b/tester/tool/run_jdb
@@ -0,0 +1,12 @@
+#!/bin/env bash
+script_afp=$(realpath "${BASH_SOURCE[0]}")
+
+# input guards
+env_must_be="tester/tool/env"
+if [ "$ENV" != "$env_must_be" ]; then
+  echo "$(script_fp):: error: must be run in the $env_must_be environment"
+  exit 1
+fi
+
+jdb -sourcepath "$SOURCEPATH" "$@"
+
diff --git a/tester/tool/run_tests b/tester/tool/run_tests
new file mode 100755
index 0000000..1e7182b
--- /dev/null
+++ b/tester/tool/run_tests
@@ -0,0 +1,23 @@
+#!/bin/env bash
+
+# Ensure REPO_HOME is set
+if [ -z "$REPO_HOME" ]; then
+  echo "Error: REPO_HOME is not set."
+  exit 1
+fi
+
+# Navigate to the shell directory
+cd "$REPO_HOME/tester/shell" || exit
+
+# Get the list of test scripts in the specific order from shell_wrapper_list
+test_list=$(shell_wrapper_list)
+
+# Execute each test in the specified order
+for file in $test_list; do
+  if [[ -x "$file" && ! -d "$file" ]]; then
+    echo -n "Running $file..."
+    ./"$file"
+  else
+    echo "Skipping $file (not executable or is a directory)"
+  fi
+done
diff --git a/tester/tool/shell_wrapper_list b/tester/tool/shell_wrapper_list
new file mode 100755
index 0000000..99bf5de
--- /dev/null
+++ b/tester/tool/shell_wrapper_list
@@ -0,0 +1,13 @@
+#!/bin/env bash
+script_afp=$(realpath "${BASH_SOURCE[0]}")
+
+# input guards
+env_must_be="tester/tool/env"
+if [ "$ENV" != "$env_must_be" ]; then
+  echo "$(script_fp):: error: must be run in the $env_must_be environment"
+  exit 1
+fi
+
+# space separated list of shell interface wrappers
+echo Test0 Test_Util Test_IO Test_TestBench Test_MockClass
+ 
diff --git a/tool/env b/tool/env
index 830913d..4f0c70f 100644
--- a/tool/env
+++ b/tool/env
@@ -1,27 +1,29 @@
 #!/usr/bin/env bash
-
-script_name=$(basename ${BASH_SOURCE[0]})
-if [[ "${BASH_SOURCE[0]}" == "$0" ]]; then
-  echo "$script_name must be sourced, not executed. Exiting."
-  exit 1
-fi
-
-if [ -z "$ENV_BASE" ]; then
-  script_path="$(dirname "$(realpath "${BASH_SOURCE[0]}")")"
-  source "${script_path}/env_base"
-fi
-
-ENV_PM=true
-
-PROJECT="$PROJECT"_administrator
+script_afp=$(realpath "${BASH_SOURCE[0]}")
+
+# input guards
+
+  env_must_be="tool_shared/bespoke/env"
+  error=false
+  if [ "$ENV" != "$env_must_be" ]; then
+    echo "$(script_fp):: error: must be run in the $env_must_be environment"
+    error=true
+  fi
+  if [[ "${BASH_SOURCE[0]}" == "$0" ]]; then
+    echo "$script_afp:: This script must be sourced, not executed."
+    error=true
+  fi
+  if $error; then exit 1; fi
 
 export PATH=\
-"$REPO_HOME"/tool\
+"$REPO_HOME"/tool_shared/bespoke/\
 :"$PATH"
 
-# no sneaky hidden files
+# expose sneaky hidden files
 alias ls="ls -a"
 
-export ENV_PM=true
-echo "$script_name done."
+# some feedback to show all went well
 
+  export PROMPT_DECOR="$PROJECT"_administrator
+  export ENV=$(script_fp)
+  echo ENV "$ENV"
diff --git a/tool_shared/bespoke/cat_w_fn b/tool_shared/bespoke/cat_w_fn
index 09931d1..3308525 100755
--- a/tool_shared/bespoke/cat_w_fn
+++ b/tool_shared/bespoke/cat_w_fn
@@ -1,8 +1,9 @@
-#!/bin/bash
+#!/usr/bin/env bash
+script_afp=$(realpath "${BASH_SOURCE[0]}")
 
 # Check if at least one file is provided
 if [ $# -eq 0 ]; then
-  echo "Usage: $0 <filename1> [filename2] ..."
+  echo "Usage: $(script_fp) <filename1> [filename2] ..."
   exit 1
 fi
 
diff --git a/tool_shared/bespoke/deprecate b/tool_shared/bespoke/deprecate
index 821e7ab..4713db5 100755
--- a/tool_shared/bespoke/deprecate
+++ b/tool_shared/bespoke/deprecate
@@ -1,12 +1,12 @@
-#!/bin/bash
+#!/usr/bin/env bash
+script_afp=$(realpath "${BASH_SOURCE[0]}")
 
 # cp subtree at <source> under file path <destination>, and make all the copied
 # files read-only. The intended use case is for moving files to a `deprecated`
 # directory. This helps prevent subsequent accidental editing.
 
-SCRIPT_NAME=$(basename "$0")
 if [ "$#" -lt 2 ]; then
-  echo "Usage: $SCRIPT_NAME <source> <destination>"
+  echo "Usage: $script_afp <source> <destination>"
   exit 1
 fi
 SRC="$1"
diff --git a/tool_shared/bespoke/emacs.el b/tool_shared/bespoke/emacs.el
new file mode 100644
index 0000000..5ca4331
--- /dev/null
+++ b/tool_shared/bespoke/emacs.el
@@ -0,0 +1,52 @@
+
+; The first time Emacs  encounters a link to a source file, Emacs asks if it should follow it.
+; This might suppress that initial question and follow the link.
+; (setq find-file-visit-truename t)
+
+(defun jdbx ()
+  "Set gud-jdb-sourcepath from the environment and run jdb with the correct source path."
+  (interactive)
+  (let* 
+    (
+      (sourcepath (getenv "SOURCEPATH"))
+      )
+    (if 
+      sourcepath
+      (setq gud-jdb-sourcepath (split-string sourcepath ":" t))
+      (message "Warning: SOURCEPATH is not set. `jdb` will run without source path information.")
+      )
+    (let 
+      (
+        (class-name (read-string "Enter the class to debug: " "Test_Util"))
+        )
+      (jdb (concat "jdb -sourcepath"
+             (if 
+               sourcepath 
+               (mapconcat 'identity gud-jdb-sourcepath ":") ""
+               )
+             " "
+             class-name
+             )
+        ))))
+
+(defun monitor-jdb-sourcepath (output)
+  "Monitor the jdb output for `sourcepath ARG` commands and update `gud-jdb-sourcepath` with each path in ARG."
+  (when 
+    (string-match "sourcepath \\(.+\\)" output)
+    (let* 
+      (
+        (new-paths (match-string 1 output))
+        (paths-list (split-string new-paths ":" t))
+        )
+      ;; Add each path in paths-list to gud-jdb-sourcepath if not already present
+      (dolist 
+        (path paths-list)
+        (unless 
+          (member path gud-jdb-sourcepath)
+          (setq gud-jdb-sourcepath (append gud-jdb-sourcepath (list path)))
+          )
+        )
+      (message "Updated gud-jdb-sourcepath: %s" gud-jdb-sourcepath)))
+  output)
+
+(add-hook 'gud-filter-functions 'monitor-jdb-sourcepath)
diff --git a/tool_shared/bespoke/env b/tool_shared/bespoke/env
index f36023e..4fa561b 100644
--- a/tool_shared/bespoke/env
+++ b/tool_shared/bespoke/env
@@ -1,57 +1,65 @@
 #!/usr/bin/env bash
-# environment shared by entire project
-# number one task, establish REPO_HOME
-# this is specific to this script being in the .../tools_shared/env directory
+script_afp=$(realpath "${BASH_SOURCE[0]}")
+if [[ "${BASH_SOURCE[0]}" == "$0" ]]; then
+  echo "$script_afp:: This script must be sourced, not executed."
+  exit 1
+fi
 
-  export PROJECT=$(basename "$REPO_HOME")
+# --------------------------------------------------------------------------------
+# project definition
 
-  ## set the shell prompt to show the project
-  PPS1="\n[$PROJECT]\n\u@\h§$(pwd)§\n> "
-  PPS2=">> "
+# actual absolute director path for this script file
 
-# some useful functions for environment scripts
-
-  ## path to script file
-  script_fp() {
-    eval "
-      local script_dp=\$(dirname \$(realpath \${BASH_SOURCE[1]}))
-      echo \$(realpath --relative-to=\"$REPO_HOME\" \"\$script_dp\")/\$(script_fn)
-    "
+  script_adp(){
+    dirname "$script_afp"
   }
 
-  ## path to script directory
-  script_dp() {
-    eval "
-      local script_dp=\$(dirname \$(realpath \${BASH_SOURCE[1]}))
-      echo \$(realpath --relative-to=\"$REPO_HOME\" \"\$script_dp\")
-    "
-  }
+# assume this script is located  $REPO_HOME/tools_shared/bespoke and work backwards
+# to get $REPO_HOME, etc.
 
-  ## an env script will be in workspace/tool/env, so
-  workspace(){
-    eval "echo \$(dirname \$(script_dp))"
-  }
+  REPO_HOME=$(dirname "$(dirname "$(script_adp)")")
+  echo REPO_HOME "$REPO_HOME"
 
-  ## script's filename
-  script_fn() {
-    eval "echo \$(basename \${BASH_SOURCE[1]})"
-  }
+  PROJECT=$(basename "$REPO_HOME")
+  echo PROJECT "$PROJECT"
 
-  export -f script_fp script_dp script_fn workspace
+  # set the prompt decoration to the name of the project
+  PROMPT_DECOR=$PROJECT
 
-# note to the programs which environment they are running.
+# --------------------------------------------------------------------------------
+# The project administrator sets up the following tools for all roles to use:
+#
+  export JAVA_HOME="$REPO_HOME/tool_shared/third_party/jdk-11"
 
-  export ENV=$(script_fp)
+# --------------------------------------------------------------------------------
+# the following functions are provided for other scripts to use.
+# at the top of files that make use of these functions put the following line:
+#  script_afp=$(realpath "${BASH_SOURCE[0]}")
+#
 
-# The project administrator setup these tools and environment settings for all
-# on the project to use:
+  ## script's filename
+  script_fn(){
+    basename "$script_afp"
+  }
 
-export JAVA_HOME="$REPO_HOME/tool_shared/third_party/jdk-11"
+  ## script's dirpath relative to $REPO_HOME
+  script_fp(){
+    realpath --relative-to="${REPO_HOME}" "$script_afp"
+  }
 
-# some feedback to show all went well
+  ## script's dirpath relative to $REPO_HOME
+  script_dp(){
+    dirname "$(script_fp)"
+  }
 
-echo ENV "$ENV"
-echo PROJECT "$PROJECT"
+# --------------------------------------------------------------------------------
+# Exports
+# Bash has no 'closure' hence when exporting a function, one must also export all the pieces.
+# do not export script_afp
 
+  export REPO_HOME PROJECT PROMPT_DECOR
+  export -f script_adp script_fn script_dp script_fp
 
+  export ENV=$(script_fp)
+  echo ENV "$ENV"
 
diff --git a/tool_shared/bespoke/test_env b/tool_shared/bespoke/test_env
new file mode 100755
index 0000000..18d75f9
--- /dev/null
+++ b/tool_shared/bespoke/test_env
@@ -0,0 +1,24 @@
+#!/bin/env bash
+script_afp=$(realpath "${BASH_SOURCE[0]}")
+
+# try both running and sourcing this test
+
+echo
+echo "--------------------------------------------------------------------------------"
+echo "from within test_shared/bespoke/test_env:"
+echo
+echo "REPO_HOME:" "$REPO_HOME"
+echo "PROJECT:" "$PROJECT"
+echo "script_afp:" "$script_afp"
+echo "script_adp:" "$(script_adp)"
+echo "script_fn:" "$(script_fn)"
+echo "script_fp:" "$(script_fp)"
+echo "script_dp:" "$(script_dp)"
+echo "ENV:" "$ENV"
+echo "-----------------------"
+echo "the BASH_SOURCE stack:"
+
+	  top_index=$(( ${#BASH_SOURCE[@]} - 1 ))
+	  for (( i=0; i<=top_index; i++ )); do
+	    echo "$i: ${BASH_SOURCE[$i]}"
+	  done
diff --git a/tool_shared/bespoke/version b/tool_shared/bespoke/version
index a2fede5..51abf9f 100755
--- a/tool_shared/bespoke/version
+++ b/tool_shared/bespoke/version
@@ -1,8 +1,9 @@
 #!/bin/env bash
+script_afp=$(realpath "${BASH_SOURCE[0]}")
 
 # 0.1 pulled groovy files from GQL_to_Cypher build.gradle
 # 0.2 conversion to Java
 # 0.3 refactored, split into smaller pieces, made into package
 
-echo 0.3
+echo v0.3
 
diff --git a/tool_shared/bespoke/vl b/tool_shared/bespoke/vl
index 94fe14d..2c968d3 100755
--- a/tool_shared/bespoke/vl
+++ b/tool_shared/bespoke/vl
@@ -1,4 +1,5 @@
 #!/usr/bin/env bash
+script_afp=$(realpath "${BASH_SOURCE[0]}")
 # vl 'vertical list'
 
 # Check if the command is provided
diff --git a/tool_shared/bespoke/wipe_release b/tool_shared/bespoke/wipe_release
index 4b92b4b..5bac0e7 100755
--- a/tool_shared/bespoke/wipe_release
+++ b/tool_shared/bespoke/wipe_release
@@ -1,4 +1,5 @@
-#!/bin/bash
+#!/usr/bin/env bash
+script_afp=$(realpath "${BASH_SOURCE[0]}")
 # remove all files in the release directory
 set -e