Merge pull request #25 from lainio/new-optimizations

Zig error return trace & extended samle app

Author: lainio

CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ### Version history
 
+##### 1.1.0
+- `assert` package:
+    - bug fix: call stack traversal during unit testing in some situations
+    - **all generics-based functions are inline expansed**
+    - *performance* is now *same as if-statements for all functions*
+    - new assert functions: `MNil`, `CNil`, `Less`, `Greater`, etc.
+    - all assert messages follow Go idiom: `got, want`
+    - `Asserter` can be set per goroutine: `PushAsserter`
+- `try` package:
+    - new check functions: `T`, `T1`, `T2`, `T3`, for quick refactoring from `To` functions to annotate an error locally
+    - **all functions are inline expansed**: if-statement equal performance
+
 ##### 1.0.0
 - **Finally! We are very happy, and thanks to all who have helped!**
 - Lots of documentation updates and cleanups for version 1.0.0

README.md

@@ -103,7 +103,8 @@ tolerant*. And, of course, it helps to make your code error-safe.
    handler.
 3. It helps us use design-by-contract type preconditions.
 4. It offers automatic stack tracing for every error, runtime error, or panic.
-   If you are familiar with Zig, the `err2` error traces are same as Zig's.
+   If you are familiar with Zig, the `err2` error return traces are same as
+   Zig's.
 
 You can use all of them or just the other. However, if you use `try` for error
 checks, you must remember to use Go's `recover()` by yourself, or your error
@@ -152,7 +153,11 @@ own purposes.
 
 #### Error Stack Tracing
 
-The err2 offers optional stack tracing. It's *automatic* and *optimized*. 
+The err2 offers optional stack tracing in two different formats:
+1. Optimized call stacks (`-err2-trace`)
+1. Error return traces similar to Zig (`-err2-ret-trace`)
+
+Both are *automatic* and fully *optimized*. 
 
 <details>
 <summary>The example of the optimized call stack:</summary>
@@ -177,12 +182,14 @@ main.main()
 
 </details>
 
-Just set the `err2.SetErrorTracer` or `err2.SetPanicTracer` to the stream you
-want traces to be written:
+Just set the `err2.SetErrorTracer`, `err2.SetErrRetTracer` or
+`err2.SetPanicTracer` to the stream you want traces to be written:
 
 ```go
 err2.SetErrorTracer(os.Stderr) // write error stack trace to stderr
 // or, for example:
+err2.SetErrRetTracer(os.Stderr) // write error return trace (like Zig)
+// or, for example:
 err2.SetPanicTracer(log.Writer()) // stack panic trace to std logger
 ```
 
@@ -382,12 +389,12 @@ func TestWebOfTrustInfo(t *testing.T) {
 	// And if there's violations during the test run they are reported as
 	// test failures for this TestWebOfTrustInfo -test.
 
-	assert.Equal(0, wot.CommonInvider)
-	assert.Equal(1, wot.Hops)
+	assert.Equal(wot.CommonInvider, 0)
+	assert.Equal(wot.Hops, 1)
 
 	wot = NewWebOfTrust(bob.Node, carol.Node)
-	assert.Equal(-1, wot.CommonInvider)
-	assert.Equal(-1, wot.Hops)
+	assert.Equal(wot.CommonInvider, hop.NotConnected)
+	assert.Equal(wot.Hops, hop.NotConnected)
 	...
 ```
 
@@ -592,6 +599,15 @@ been much easier.** There is an excellent [blog post](https://jesseduffield.com/
 about the issues you are facing with Go's error handling without the help of
 the err2 package.
 
+- If you don't want to bubble up error from every function, we have learned that
+`Try` prefix convention is pretty cool way to solve limitations of Go
+programming language help to make your code more skimmable. If your internal
+functions normally would be something like `func CopyFile(s, t string) (err
+error)`, you can replace them with `func TryCopyFile(s, t string)`, where `Try`
+prefix remind you that the function throws errors. You can decide at what level
+of the call stack you will catch them with `err2.Handle` or `err2.Catch`,
+depending your case and API.
+
 </details>
 
 ## Support And Contributions
@@ -607,14 +623,10 @@ Please see the full version history from [CHANGELOG](./CHANGELOG.md).
 
 ### Latest Release
 
-##### 1.1.0
-- `assert` package:
-    - bug fix: call stack traversal during unit testing in some situations
-    - **all generics-based functions are inline expansed**
-    - *performance* is now *same as if-statements for all functions*
-    - new assert functions: `MNil`, `CNil`, `Less`, `Greater`, etc.
-    - all assert messages follow Go idiom: `got, want`
-    - `Asserter` can be set per goroutine: `PushAsserter`
-- `try` package:
-    - new check functions: `T`, `T1`, `T2`, `T3`, for quick refactoring from `To` functions to annotate an error locally
-    - **all functions are inline expansed**: if-statement equal performance
+##### 1.2.0
+- Now `-err2-ret-trace` and `err2.SetErrRetTracer` gives us *error return traces*
+  which are even more readable than `-err2-trace`, `err2.SetErrorTracer` with
+  long error return traces
+- A new automatic error formatter/generator added for `TryCopyFile` convention
+- New features for `sample/` to demonstrate latest features
+- Extended documentation

assert/assert.go

@@ -1021,24 +1021,17 @@ func current() (curAsserter asserter) {
 	return curAsserter
 }
 
-// SetDefault sets the current default [Asserter] for assert pkg. It also
-// returns the previous [Asserter].
+// SetDefault sets the new default [Asserter] for the assert pkg instance you're
+// currently using. It also returns the previous [Asserter]. The default
+// asserter is [Production] that's best for most use cases and packages.
 //
-// Note that you should use this in TestMain function, and use [flag] package to
-// set it for the app. For the tests you can set it to panic about every
-// assertion fault, or to throw an error, or/and print the call stack
-// immediately when assert occurs. The err2 package helps you to catch and
-// report all types of the asserts.
+// Note that for most cases [PushAsserter] is most suitable. [PushAsserter]
+// allows you to set [Asserter] per goroutine or function, i.e., until you pop
+// the asserter out, and the assert package uses the current default [Asserter]
+// set by [SetDefault].
 //
-// Note that if you are using tracers you might get two call stacks, so test
-// what's best for your case.
-//
-// Tip. If our own packages (client packages for assert) have lots of parallel
-// testing and race detection, please try to use same [Asserter] for all of them
-// and set [Asserter] only one in TestMain, or in init.
-//
-//	func TestMain(m *testing.M) {
-//	     SetDefault(assert.TestFull)
+// Note that if you are using tracers you might get overlapping call stacks, so
+// test what's best for your case.
 func SetDefault(i Asserter) (old Asserter) {
 	// pkg lvl lock to allow only one pkg client call this at one of the time
 	// together with the indexing, i.e we don't need to switch asserter

doc.go

@@ -1,6 +1,6 @@
 /*
-Package err2 provides three main functionality:
- 1. err2 package includes helper functions for error handling & automatic error
+Package err2 is error handling solution including three main functionality:
+ 1. err2 package offers helper functions for error handling & automatic error
     stack tracing
  2. [github.com/lainio/err2/try] sub-package is for error checking
  3. [github.com/lainio/err2/assert] sub-package is for design-by-contract and