Document and add tests for "attempt"

Author: d-torrance

M2/Macaulay2/packages/Macaulay2Doc/ov_debugging.m2

@@ -327,6 +327,51 @@ document {
 	  }
      }
 
+doc ///
+  Key
+    Error
+  Headline
+    error information
+  Description
+    Text
+      An instance of this class is a hash table containing the position and
+      message of an error caught by @TO symbol attempt@.
+    Example
+      attempt 1/0
+  SeeAlso
+    symbol attempt
+///
+
+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,6 @@
+(val, err) = attempt error "foo"
+assert Equation(err#"message", "foo")
+
 stderr << "--testing the error messages must be done manually" << endl
 end