more error handling docs

doc/handbook/dataflow.facts

@@ -161,7 +161,14 @@ $terpri
 { $subsection catch }
 "Caught errors can be logged in human-readable form:"
 { $subsection error. }
-{ $subsection try } ;
+{ $subsection try }
+"Information relating to the most recently thrown error is stored in a pair of global variables:"
+{ $subsection error }
+{ $subsection error-continuation }
+"When an error is thrown and caught by the listener, a number of words facilitate interactive debugging of the error:"
+{ $subsection :s }
+{ $subsection :r }
+{ $subsection :get } ;
 
 ARTICLE: "threads" "Multitasking"
 "Continuations are used to implements co-operative multitasking, where the runtime switches between threads during I/O calls, and explicit yields."

library/bootstrap/boot-stage1.factor

@@ -224,6 +224,7 @@ vectors words ;
         "/library/syntax/parse-syntax.facts"
         "/library/syntax/prettyprint.facts"
         "/library/syntax/see.facts"
+        "/library/tools/debugger.facts"
 
         "/doc/handbook/collections.facts"
         "/doc/handbook/dataflow.facts"

library/tools/debugger.factor

@@ -119,11 +119,9 @@ M: object error. ( error -- ) . ;
     flush ;
 
 : flush-error-handler ( -- )
-    #! Last resort.
     [ "Error in default error handler!" print ] when ;
 
 : print-error ( error -- )
-    #! Print the error.
     [ dup error. ] catch nip flush-error-handler ;
 
 : try ( quot -- )

library/tools/debugger.facts

@@ -0,0 +1,23 @@
+USING: errors help ;
+
+HELP: error f
+{ $description "Global variable holding most-recently thrown error." }
+{ $notes "Only updated by " { $link throw } ", not " { $link rethrow } "." ;
+
+HELP: error-continuation f
+{ $description "Global variable holding current continuation of most-recently thrown error." }
+{ $notes "Only updated by " { $link throw } ", not " { $link rethrow } "." ;
+
+HELP: :s "( -- )"
+{ $description "Prints the datastack at the time of the most recent error. Used for interactive debugging." } ;
+
+HELP: :r "( -- )"
+{ $description "Prints the callstack at the time of the most recent error. Used for interactive debugging." } ;
+
+HELP: :get "( variable -- value )"
+{ $values { "variable" "an object" } { "value" "the value, or f" } }
+{ $description "Looks up the value of a variable at the time of the most recent error." } ;
+
+HELP: try "( quot -- )"
+{ $values { "quot" "a quotation" } }
+{ $description "Calls the quotation. If it throws an error, logs the error to the default stream and restores the datastack." } ;