Additional features for wrapped try errors.

Add OriginalError convenience accessor.  Rename data key var to make more sense.  Add package level documentation pointing out CatchAll's error wrapping behavior.

Author: warpfork

try/try.go

@@ -33,8 +33,10 @@
 	(no special treatment; they'll hit `CatchAll` blocks and `Finally` blocks;
 	it would of course be silly for them to hit `Catch` blocks since those
 	use spacemonkey-errors types).  Panics with values that are not of golang's
-	`error` type at all will trigger `Finally` blocks but otherwise
-	be immediately repanicked.
+	`error` type at all will be wrapped in a spacemonkey error for the purpose
+	of handling (as an interface design, `CatchAll(interface{})` is unpleasant).
+	See `OriginalError` and `Repanic` for more invormation on handling these
+	wrapped panic objects.
 
 	A `try.Do(func() {...})` with no attached errors handlers is legal but
 	pointless.  A `try.Do(func() {...})` with no `Done()` will never run the
@@ -61,7 +63,7 @@ var (
 	UnknownPanicError = errors.NewClass("Unknown Error")
 
 	// The spacemonkey error key to get the original data out of an UnknownPanicError.
-	OriginalPanic = errors.GenSym()
+	OriginalErrorKey = errors.GenSym()
 )
 
 type Plan struct {
@@ -153,14 +155,14 @@ func (p *Plan) Done() {
 				if catch.match == nil {
 					consumed = true
 					msg := fmt.Sprintf("%v", rec)
-					pan := UnknownPanicError.NewWith(msg, errors.SetData(OriginalPanic, rec))
+					pan := UnknownPanicError.NewWith(msg, errors.SetData(OriginalErrorKey, rec))
 					catch.anyhandler(pan)
 					return
 				}
 				if UnknownPanicError.Is(catch.match) {
 					consumed = true
 					msg := fmt.Sprintf("%v", rec)
-					pan := UnknownPanicError.NewWith(msg, errors.SetData(OriginalPanic, rec))
+					pan := UnknownPanicError.NewWith(msg, errors.SetData(OriginalErrorKey, rec))
 					catch.handler(pan.(*errors.Error))
 					return
 				}
@@ -170,9 +172,26 @@ func (p *Plan) Done() {
 	p.main()
 }
 
+/*
+	If `err` was originally another value coerced to an error by `CatchAll`,
+	this will return the original value.  Otherwise, it returns the same error
+	again.
+
+	See also `Repanic()`.
+*/
+func OriginalError(err error) interface{} {
+	data := errors.GetData(err, OriginalErrorKey)
+	if data == nil {
+		return err
+	}
+	return data
+}
+
 /*
 	Panics again with the original error.
 
+	Shorthand, equivalent to calling `panic(OriginalError(err))`
+
 	If the error is a `UnknownPanicError` (i.e., a `CatchAll` block that's handling something
 	that wasn't originally an `error` type, so it was wrapped), it will unwrap that re-panic
 	with that original error -- in other words, this is a "do the right thing" method in all scenarios.
@@ -192,9 +211,9 @@ func Repanic(err error) {
 	if !wrapper.Is(UnknownPanicError) {
 		panic(err)
 	}
-	data := errors.GetData(err, OriginalPanic)
+	data := errors.GetData(err, OriginalErrorKey)
 	if data == nil {
-		panic(errors.ProgrammerError.New("misuse of try internals", errors.SetData(OriginalPanic, err)))
+		panic(errors.ProgrammerError.New("misuse of try internals", errors.SetData(OriginalErrorKey, err)))
 	}
 	panic(data)
 }

try/try_test.go

@@ -173,7 +173,7 @@ func ExampleIntOriginalPanic() {
 	}).Finally(func() {
 		fmt.Println("finally block called")
 	}).CatchAll(func(e error) {
-		data := errors.GetData(e, try.OriginalPanic)
+		data := errors.GetData(e, try.OriginalErrorKey)
 		fmt.Println("catch wildcard called:", data)
 		switch data.(type) {
 		case int:
@@ -197,7 +197,7 @@ func ExampleCatchingUnknownErrorsByType() {
 	}).Catch(RockError, func(e *errors.Error) {
 		fmt.Println("catch a rock")
 	}).Catch(try.UnknownPanicError, func(e *errors.Error) {
-		data := errors.GetData(e, try.OriginalPanic)
+		data := errors.GetData(e, try.OriginalErrorKey)
 		fmt.Println("catch UnknownPanicError called:", data)
 		switch data.(type) {
 		case int:
@@ -276,7 +276,7 @@ func ExampleStringRepanicCoversFinally() {
 		}).Finally(func() {
 			fmt.Println("finally block called")
 		}).Catch(try.UnknownPanicError, func(e *errors.Error) {
-			data := errors.GetData(e, try.OriginalPanic)
+			data := errors.GetData(e, try.OriginalErrorKey)
 			fmt.Println("catch UnknownPanicError called:", data)
 			switch data.(type) {
 			case string:
@@ -316,7 +316,7 @@ func ExampleObjectRepanicOriginal() {
 	}).CatchAll(func(e error) {
 		// this example is a little funny, because it got re-wrapped again
 		// but the important part is yes, the (pointer equal!) object is in there.
-		data := errors.GetData(e, try.OriginalPanic)
+		data := errors.GetData(e, try.OriginalErrorKey)
 		fmt.Printf("outer error equals original: %v\n", data == obj)
 	}).Done()