Hotfix/small improvements

flipjump/fjm/fjm_reader.py

@@ -146,13 +146,11 @@ def _get_memory_word(self, word_address: int) -> int:
                     return 0
 
             garbage_val = _new_garbage_val()
-            garbage_message = (
-                f'Reading garbage word at mem[{hex(word_address << self.memory_width)[2:]}]'
-                f' = {hex(garbage_val)[2:]}'
-            )
+            memory_address = word_address << self.memory_width
+            garbage_message = f'Reading garbage word at mem[{hex(memory_address)[2:]}] = {hex(garbage_val)[2:]}'
 
             if GarbageHandling.Stop == self.garbage_handling:
-                raise FlipJumpRuntimeMemoryException(garbage_message)
+                raise FlipJumpRuntimeMemoryException(garbage_message, memory_address)
             elif GarbageHandling.OnlyWarning == self.garbage_handling:
                 print(f'\nWarning:  {garbage_message}')
             elif GarbageHandling.SlowRead == self.garbage_handling:
@@ -210,7 +208,7 @@ def get_word(self, bit_address: int) -> int:
         if bit_offset == 0:
             return self._get_memory_word(word_address)
         if word_address == ((1 << self.memory_width) - 1):
-            raise FlipJumpRuntimeMemoryException('Accessed outside of memory (beyond the last bit).')
+            raise FlipJumpRuntimeMemoryException('Accessed outside of memory (beyond the last bit).', bit_address)
 
         lsw = self._get_memory_word(word_address)
         msw = self._get_memory_word(word_address + 1)

flipjump/interpretter/fjm_run.py

@@ -20,7 +20,13 @@ class TerminationStatistics:
     also saves the program's output.
     """
 
-    def __init__(self, run_statistics: RunStatistics, termination_cause: TerminationCause):
+    def __init__(
+        self,
+        run_statistics: RunStatistics,
+        termination_cause: TerminationCause,
+        *,
+        memory_error_address: Optional[int] = None,
+    ) -> None:
         self.run_time = run_statistics.get_run_time()
 
         self.op_counter = run_statistics.op_counter
@@ -29,6 +35,7 @@ def __init__(self, run_statistics: RunStatistics, termination_cause: Termination
         self.last_ops_addresses: Optional[Deque[int]] = run_statistics.last_ops_addresses
 
         self.termination_cause = termination_cause
+        self.memory_error_address = memory_error_address
 
     @staticmethod
     def beautify_address(address: int, breakpoint_handler: Optional[BreakpointHandler]) -> str:
@@ -74,10 +81,13 @@ def print(
             if output_to_print is not None:
                 output_str = f"Program's output before it was terminated:  {output_to_print!r}\n\n"
 
+        termination_cause_str = str(self.termination_cause)
+        if self.memory_error_address is not None:
+            termination_cause_str += f" (address {hex(self.memory_error_address)})"
         print(
             f'\n'
             f'{output_str}'
-            f'Finished by {str(self.termination_cause)} after {self.run_time:.3f}s '
+            f'Finished by {termination_cause_str} after {self.run_time:.3f}s '
             f'('
             f'{self.op_counter:,} ops executed; '
             f'{flips_percentage:.2f}% flips, '
@@ -192,8 +202,10 @@ def run(
             # JUMP!
             ip = jump_address
 
-    except FlipJumpRuntimeMemoryException:
-        return TerminationStatistics(statistics, TerminationCause.RuntimeMemoryError)
+    except FlipJumpRuntimeMemoryException as mem_e:
+        return TerminationStatistics(
+            statistics, TerminationCause.RuntimeMemoryError, memory_error_address=mem_e.memory_address
+        )
     except FlipJumpException as fj_exception:
         raise fj_exception
     except KeyboardInterrupt:

flipjump/stl/hex/math.fj

@@ -40,6 +40,7 @@ ns hex {
     // Space Complexity: n_const(2.5@+39) + (dst_n - hex_shift)(1.5@+13) + 4@+29
     //   dst[:n] += const
     // @requires hex.add.init (or hex.init)
+    // const must be a positive constant.
     // n_const is the hex-length of const, without all of it's least-significant-hexes zeros.
     def add_constant n, dst, const @ end {
         rep(const!=0, _) .add.add_constant_with_leading_zeros n, dst, const, (#(const&(0-const)))-1

flipjump/utils/exceptions.py

@@ -31,7 +31,9 @@ class FlipJumpRuntimeException(FlipJumpException):
 
 
 class FlipJumpRuntimeMemoryException(FlipJumpRuntimeException):
-    pass
+    def __init__(self, message: str, memory_address: int):
+        super().__init__(message)
+        self.memory_address = memory_address
 
 
 class FlipJumpMissingImportException(FlipJumpException):