github.com/haraldrudell/parl@v0.4.176/perrors/perrors.go (about)

     1  /*
     2  © 2018–present Harald Rudell <harald.rudell@gmail.com> (https://haraldrudell.github.io/haraldrudell/)
     3  ISC License
     4  */
     5  
     6  /*
     7  Package perrors enrichens error values with string data, stack traces, associated errors,
     8  less severe warnings, thread-safe containers and
     9  comprehensive error string representations.
    10  
    11  Creating errors with stack traces:
    12  
    13  	err := error116.New("error message") // adds a stacktrace contained inside of err
    14  	err = error116.Errorf("Some text: '%w'", err) // adds a stacktrace if err does not already have it
    15  	err = error116.Stackn(err, 0) // adds a stack trace even if err already has it
    16  
    17  Enriching errors:
    18  
    19  	err = error116.AddKeyValue(err, "record", "123") // adds a key-value string, last key wins
    20  	err = error116.AddKeyValue(err, "", "2022-03-19 11:10:00") // adds a string to a list, oldest first
    21  
    22  Encapsulating associated errors allowing for a single error value to contain multiple errors:
    23  
    24  	err = error116.AppendError(err, err2) // err2 is inside of err, can be printed and retrieved
    25  	fn := error116.Errp(&err) // fn(error) can be repeatedly invoked, aggregating errors in err
    26  	error116.ParlError.AddError(err) // thread-safe error encapsulation
    27  
    28  Marking errors as less severe:
    29  
    30  	warning := error116.Warning(err) // warning should not terminate the thread
    31  	error116.IsWarning(err) // Determine severity of an error value
    32  
    33  Printing rich errors:
    34  
    35  	error116.Long(err)
    36  	→ error-message
    37  	→ github.com/haraldrudell/parl/error116.(*csTypeName).FuncName
    38  	→   /opt/sw/privates/parl/error116/chainstring_test.go:26
    39  	→ runtime.goexit
    40  	→   /opt/homebrew/Cellar/go/1.17.8/libexec/src/runtime/asm_arm64.s:1133
    41  	→ record: 1234
    42  	→ Other error: Close failed
    43  	error116.Short(err)
    44  	→ error-message at error116.(*csTypeName).FuncName-chainstring_test.go:26
    45  	fmt.Println(err)
    46  	→ error-message
    47  
    48  Can be used with Printf, but only works if last error in chain is from error116:
    49  
    50  	fmt.Printf("err: %+v", err) // same as Long()
    51  	fmt.Printf("err: %-v", err) // save as Short()
    52  
    53  Is compatible:
    54  
    55  	fmt.Println(err) // no change
    56  	fmt.Printf("err: %v", err) // no change
    57  	err.Error() // no change
    58  	fmt.Printf("err: %s", err) // no change
    59  	fmt.Printf("err: %q", err) // no change
    60  
    61  perrors used to be called error116 becaue Rob Pike was going to put it into go1.16
    62  
    63  © 2020–present Harald Rudell <harald.rudell@gmail.com> (https://haraldrudell.github.io/haraldrudell/)
    64  */
    65  package perrors
    66  
    67  // SupportsIs is used for type assertions determining if an error value
    68  // implements the Is() method, therefore supports errors.Is()
    69  type SupportsIs interface {
    70  	error
    71  	Is(target error) (isThisType bool)
    72  }