Document run_module_predicate and handle critical failure in toplevel.pl

src/machine/mod.rs

@@ -271,6 +271,11 @@ impl Machine {
             .unwrap()
     }
 
+    /// Runs the predicate `key` in `module_name` until completion.
+    /// Siltently ignores failure, thrown errors and choice points.
+    ///
+    /// Consider using [`Machine::run_query`] if you wish to handle
+    /// predicates that may fail, leave a choice point or throw.
     pub(crate) fn run_module_predicate(
         &mut self,
         module_name: Atom,
@@ -279,6 +284,7 @@ impl Machine {
         if let Some(module) = self.indices.modules.get(&module_name) {
             if let Some(code_index) = module.code_dir.get(&key) {
                 let p = code_index.local().unwrap();
+                // Leave a halting choice point to backtrack to in case the predicate fails or throws.
                 self.allocate_stub_choice_point();
 
                 self.machine_st.cp = BREAK_FROM_DISPATCH_LOOP_LOC;

src/toplevel.pl

@@ -29,6 +29,19 @@
     ).
 
 '$repl' :-
+    catch(
+        start_repl,
+        _,
+        % Something bad enough happened that the REPL itself threw an error.
+        % This can be caused by a broken user_output stream, so we cannot
+        % print an error.
+        %
+        % The best we can do now is halt with an error code,
+        % so that users can try to diagnose the issue:
+        halt(99)
+    ).
+
+start_repl :-
     asserta('$toplevel':started),
     raw_argv(Args0),
     (   append(Args1, ["--"|_], Args0) ->