Document and add tests for "attempt" and "Error"

Author: d-torrance

M2/Macaulay2/packages/Macaulay2Doc/functions/locate-doc.m2

@@ -16,6 +16,7 @@ Node
    (locate, Package)
    (locate, List)
    (locate, ZZ)
+   (locate, Error)
   Headline
     locate source code
   Usage

M2/Macaulay2/packages/Macaulay2Doc/ov_debugging.m2

@@ -293,7 +293,7 @@ document {
      }
 
 document {
-     Key => error,
+     Key => {error, (error, Thing), (error, Error), (error, String)},
      Headline => "deliver error message",
 	Usage => "error s",
 	Inputs => {
@@ -327,6 +327,73 @@ document {
 	  }
      }
 
+doc ///
+  Key
+    Error
+    (NewFromMethod, Error, String)
+    (NewFromMethod, Error, Thing)
+  Headline
+    error information
+  Description
+    Text
+      An instance of this class is returned as the second element when
+      @TO symbol attempt@ catches an error.  The error message may be recovered
+      using @TO toString@ and the location using @TO locate@.
+    Example
+      (val, err) = attempt 1/0
+      toString err
+      locate err
+    Text
+      An @CODE "Error"@ object may be constructed from an error message.
+    Example
+      err = new Error from "foo"
+    Text
+      An error may be raised from an @CODE "Error"@ object using @TO error@.
+    Example
+      stopIfError = false
+      error err
+    Text
+      It is possible to create subclasses of @CODE "Error"@ for finer error
+      handling.
+    Example
+      MyError = new SelfInitializingType of Error
+      (val, err)  = attempt error MyError "bar"
+      err
+  SeeAlso
+    symbol attempt
+    error
+///
+
+doc ///
+  Key
+    symbol attempt
+  Headline
+    attempt to evaluate code and get information about any errors that occur
+  Usage
+    attempt c
+  Description
+    Text
+      The code @VAR "c"@ is evaluated and a sequence containing two elements
+      is returned.  If the evaluation completes successfully, then the first
+      element is the value and the second element is null.
+    Example
+      attempt 5
+    Text
+      If an error occurs, then the first element is null and the second element
+      is an @TO Error@ object containing information about the error is
+      returned.
+    Example
+      attempt 1/0
+    Text
+      Note that this is a @TO Keyword@, not a method, and so it is not
+      necessary to enclose @VAR "c"@ in parentheses.
+    Example
+      attempt 5 == "foo"
+      {attempt error "bar", 1/2}
+      attempt 1/0; 1/2
+  SeeAlso
+    symbol try
+///
 
 document {
      Key => "recursionLimit",

M2/Macaulay2/packages/Macaulay2Doc/ov_language.m2

@@ -704,6 +704,8 @@ document {
 	  TO "error",
 	  TO "try",
 	  TO "throw",
+	  TO "attempt",
+	  TO "Error",
 	  }
      }
 
@@ -733,7 +735,8 @@ document {
      "The behavior of interrupts (other than alarms) is unaffected.",
      EXAMPLE "apply(-3..3,i->try 1/i else infinity)",
      Caveat => "We will change the behavior of this function soon so that it will be possible to catch errors of a particular type.  Meanwhile, users are
-     recommended to use this function sparingly, if at all."
+     recommended to use this function sparingly, if at all.",
+     SeeAlso => {"attempt"},
      }
 
 document {

M2/Macaulay2/tests/normal/error-messages.m2

@@ -1,3 +1,10 @@
+(val, err) = attempt error "foo"
+assert Equation(toString err, "foo")
+
+MyError = new SelfInitializingType of Error
+(val, err) = attempt error MyError "foo"
+assert instance(err, MyError)
+
 stderr << "--testing the error messages must be done manually" << endl
 end