Merge pull request #17 from lainio/v0-9-40

v0 9 40

Author: lainio

.github/workflows/test.yml

@@ -5,24 +5,39 @@ jobs:
     name: lint
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
-      - name: golangci-lint
-        uses: golangci/golangci-lint-action@v2
-        with:
-          version: latest
-          args: --timeout=5m
+    - uses: actions/checkout@v3
+    - name: golangci-lint
+      uses: golangci/golangci-lint-action@v2
+      with:
+        version: latest
+        args: --timeout=5m
   test:
+    strategy:
+      matrix:
+        go-version: [1.18.x, 1.19.x, 1.20.x, 1.21.x]
+        os: [windows-latest, ubuntu-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+    - name: setup go
+      uses: actions/setup-go@v2
+      with:
+        go-version: ${{ matrix.go-version }}
+    - name: checkout
+      uses: actions/checkout@v2
+    - name: test
+      run: make test
+  test-cov:
     runs-on: ubuntu-latest
     steps:
-      - name: setup
-        uses: actions/setup-go@v2
-        with:
-          go-version: 1.19.x
-      - name: checkout
-        uses: actions/checkout@v2
-      - name: test
-        run: make test_cov_out
-      - name: upload
-        uses: codecov/codecov-action@v2
-        with:
-          files: ./coverage.txt
+    - name: setup
+      uses: actions/setup-go@v2
+      with:
+        go-version: 1.19.x
+    - name: checkout
+      uses: actions/checkout@v2
+    - name: test
+      run: make test_cov_out
+    - name: upload
+      uses: codecov/codecov-action@v2
+      with:
+        files: ./coverage.txt

.gitignore

@@ -15,3 +15,5 @@ coverage.*
 
 # Output of the go coverage tool, specifically when used with LiteIDE
 *.out
+
+dist/

.goreleaser.yaml

@@ -0,0 +1,22 @@
+# This is an example .goreleaser.yml file with some sensible defaults.
+# Make sure to check the documentation at https://goreleaser.com
+before:
+  hooks:
+    # You may remove this if you don't use go modules.
+    - go mod tidy
+    # you may remove this if you don't need go generate
+    - go generate ./...
+builds:
+- skip: true
+
+changelog:
+  sort: asc
+  filters:
+    exclude:
+      - '^docs:'
+      - '^test:'
+
+# The lines beneath this are called `modelines`. See `:help modeline`
+# Feel free to remove those if you don't want/use them.
+# yaml-language-server: $schema=https://goreleaser.com/static/schema.json
+# vim: set ts=2 sw=2 tw=0 fo=cnqoj

CHANGELOG.md

@@ -1,4 +1,4 @@
-## Cangelog
+## Changelog
 
 ### Version history
 

Makefile

@@ -4,9 +4,10 @@ PKG_ERR2 := github.com/lainio/err2
 PKG_ASSERT := github.com/lainio/err2/assert
 PKG_TRY := github.com/lainio/err2/try
 PKG_DEBUG := github.com/lainio/err2/internal/debug
+PKG_HANDLER := github.com/lainio/err2/internal/handler
 PKG_STR := github.com/lainio/err2/internal/str
 PKG_X := github.com/lainio/err2/internal/x
-PKGS := $(PKG_ERR2) $(PKG_ASSERT) $(PKG_TRY) $(PKG_DEBUG) $(PKG_STR) $(PKG_X)
+PKGS := $(PKG_ERR2) $(PKG_ASSERT) $(PKG_TRY) $(PKG_DEBUG) $(PKG_HANDLER) $(PKG_STR) $(PKG_X)
 
 SRCDIRS := $(shell go list -f '{{.Dir}}' $(PKGS))
 
@@ -29,50 +30,71 @@ test_try:
 test_debug:
 	$(GO) test $(TEST_ARGS) $(PKG_DEBUG)
 
+test_handler:
+	$(GO) test $(TEST_ARGS) $(PKG_HANDLER)
+
 test_str:
 	$(GO) test $(TEST_ARGS) $(PKG_STR)
 
 test_x:
 	$(GO) test $(TEST_ARGS) $(PKG_X)
 
+testv:
+	$(GO) test -v $(TEST_ARGS) $(PKGS)
+
 test:
 	$(GO) test $(TEST_ARGS) $(PKGS)
 
+inline_err2:
+	$(GO) test -c -gcflags=-m=2 $(PKG_ERR2) 2>&1 | ag 'inlin' 
+
+tinline_err2:
+	$(GO) test -c -gcflags=-m=2 $(PKG_ERR2) 2>&1 | ag 'inlin' | ag 'err2_test'
+
+inline_handler:
+	$(GO) test -c -gcflags=-m=2 $(PKG_HANDLER) 2>&1 | ag 'inlin' 
+
+tinline_handler:
+	$(GO) test -c -gcflags=-m=2 $(PKG_HANDLER) 2>&1 | ag 'inlin'
+
 bench:
-	$(GO) test -bench=. $(PKGS)
+	$(GO) test $(TEST_ARGS) -bench=. $(PKGS)
 
 bench_goid:
-	$(GO) test -bench='BenchmarkGoid' $(PKG_ASSERT)
+	$(GO) test $(TEST_ARGS) -bench='BenchmarkGoid' $(PKG_ASSERT)
+
+bench_reca:
+	$(GO) test $(TEST_ARGS) -bench='BenchmarkRecursion.*' $(PKG_ERR2)
 
 bench_out:
-	$(GO) test -bench='BenchmarkTryOut_.*' $(PKG_ERR2)
+	$(GO) test $(TEST_ARGS) -bench='BenchmarkTryOut_.*' $(PKG_ERR2)
 
 bench_go:
-	$(GO) test -bench='BenchmarkTry_StringGenerics' $(PKG_ERR2)
-
-bench_arec:
-	$(GO) test -bench='BenchmarkRecursion.*' $(PKG_ERR2)
+	$(GO) test $(TEST_ARGS) -bench='BenchmarkTry_StringGenerics' $(PKG_ERR2)
 
 bench_that:
-	$(GO) test -bench='BenchmarkThat.*' $(PKG_ASSERT)
+	$(GO) test $(TEST_ARGS) -bench='BenchmarkThat.*' $(PKG_ASSERT)
 
 bench_copy:
-	$(GO) test -bench='Benchmark_CopyBuffer' $(PKG_TRY)
+	$(GO) test $(TEST_ARGS) -bench='Benchmark_CopyBuffer' $(PKG_TRY)
+
+bench_rece:
+	$(GO) test $(TEST_ARGS) -bench='BenchmarkRecursionWithTryAnd_Empty_Defer' $(PKG_ERR2)
 
 bench_rec:
-	$(GO) test -bench='BenchmarkRecursionWithOldErrorIfCheckAnd_Defer' $(PKG_ERR2)
+	$(GO) test $(TEST_ARGS) -bench='BenchmarkRecursionWithOldErrorIfCheckAnd_Defer' $(PKG_ERR2)
 
 bench_err2:
-	$(GO) test -bench=. $(PKG_ERR2)
+	$(GO) test $(TEST_ARGS) -bench=. $(PKG_ERR2)
 
 bench_assert:
-	$(GO) test -bench=. $(PKG_ASSERT)
+	$(GO) test $(TEST_ARGS) -bench=. $(PKG_ASSERT)
 
 bench_str:
-	$(GO) test -bench=. $(PKG_STR)
+	$(GO) test $(TEST_ARGS) -bench=. $(PKG_STR)
 
 bench_x:
-	$(GO) test -bench=. $(PKG_X)
+	$(GO) test $(TEST_ARGS) -bench=. $(PKG_X)
 
 vet: | test
 	$(GO) vet $(PKGS)

README.md

@@ -24,9 +24,9 @@ func CopyFile(src, dst string) (err error) {
 	if err != nil {
 		return fmt.Errorf("mixing traditional error checking: %w", err)
 	}
-	defer err2.Handle(&err, func() {
-		os.Remove(dst)
-	})
+	defer err2.Handle(&err, err2.Err(func(error) {
+		try.Out1(os.Remove(dst)).Logf("cleaning error")
+	}))
 	defer w.Close()
 	try.To1(io.Copy(w, r))
 	return nil
@@ -254,7 +254,8 @@ We also mark functions deprecated before they become obsolete. Usually, one
 released version before. We have tested this with a large code base in our
 systems, and it works wonderfully.
 
-More information can be found in the scripts' [readme file](./scripts/README.md).
+More information can be found in the `scripts/` directory [readme
+file](./scripts/README.md).
 
 ## Assertion
 
@@ -429,18 +430,41 @@ Please see the full version history from [CHANGELOG](./CHANGELOG.md).
 
 ### Latest Release
 
-##### 0.9.29
-- New API for immediate error handling: `try out handle/catch err`
-  ```go
-  val := try.Out1(strconv.Atoi(s)).Catch(10)
-  ```
-- New err2.Catch API for automatic logging
-- Performance boost for assert pkg: `defer assert.PushTester(t)()`
-- Our API has now *all the same features Zig's error handling has*
+##### 0.9.40
+- Significant performance boost for: `defer err2.Handle/Catch()` 
+  - **3x faster happy path than the previous version, which is now equal to
+    simplest `defer` function in the `err`-returning function** . (Please see
+    the `defer` benchmarks in the `err2_test.go` and run `make bench_reca`)
+  - the solution caused a change to API, where the core reason is Go's
+    optimization "bug". (We don't have confirmation yet.)
+- Changed API for deferred error handling: `defer err2.Handle/Catch()`
+  - *Obsolete*:
+    ```go
+    defer err2.Handle(&err, func() {}) // <- relaying closure to access err val
+    ```
+  - Current version:
+    ```go
+    defer err2.Handle(&err, func(err error) error { return err }) // not a closure
+    ```
+    Because handler function is not relaying closures any more, it opens a new
+    opportunity to use and build general helper functions: `err2.Noop`, etc.
+  - Use auto-migration scripts especially for large code-bases. More information
+    can be found in the `scripts/` directory's [readme file](./scripts/README.md).
+  - Added a new (*experimental*) API:
+    ```go
+    defer err2.Handle(&err, func(noerr bool) {
+            assert.That(noerr) // noerr is always true!!
+            doSomething()
+    })
+    ```
+    This is experimental because we aren't sure if this is something we want to
+    have in the `err2` package.
+- Bug fixes: `ResultX.Logf()` now works as it should
+- More documentation
 
 ### Upcoming releases
 
-##### 0.9.3 
-- Go's standard lib's flag pkg integration (similar to `glog`)
+##### 0.9.5
+- Idea: Go's standard lib's flag pkg integration (similar to `glog`)
 - Continue removing unused parts from `assert` pkg
 - More documentation, repairing for some sort of marketing

assert/assert.go

@@ -16,10 +16,52 @@ import (
 type defInd = uint32
 
 const (
+	// Production is the best asserter for most uses. The assertion violations
+	// are treated as Go error values. And only a pragmatic caller info is
+	// automatically included into the error message like file name, line
+	// number, and caller function.
 	Production defInd = 0 + iota
+
+	// Development is the best asserter for most development uses. The
+	// assertion violations are treated as Go error values. And a formatted
+	// caller info is automatically included to the error message like file
+	// name, line number, and caller function.
 	Development
+
+	// Test minimalistic asserter for unit test use. More pragmatic is the
+	// TestFull asserter (default).
+	//
+	// Use this asserter if your IDE/editor doesn't support long file names, or
+	// for temporary problem solving for your programming environment.
 	Test
+
+	// TestFull asserter (default). The TestFull asserter includes caller info
+	// and call stack for unit testing, similarly like err2's error traces.
+	//
+	// The call stack produced by the test asserts can be used over Go module
+	// boundaries. For example, if your app and it's sub packages both use
+	// err2/assert for unit testing and runtime checks, the runtime assertions
+	// will be automatically converted to test asserts on the fly. If any of
+	// the runtime asserts in sub packages fails during the app tests, the
+	// current app test fails too.
+	//
+	// Note, that the cross-module assertions produce long file names (path
+	// included), and some of the Go test result parsers cannot handle that.
+	// A proper test result parser like 'github.com/lainio/nvim-go' (fork)
+	// works very well. Also most of the make result parsers can process the
+	// output properly and allow traverse of locations of the error trace.
 	TestFull
+
+	// Debug asserter transforms assertion violations to panics which is the
+	// patter that e.g. Go's standard library uses:
+	//
+	//   if p == nil {
+	//        panic("pkg: ptr cannot be nil")
+	//   }
+	//
+	// is equal to:
+	//
+	//   assert.NotNil(p)
 	Debug
 )
 
@@ -93,14 +135,18 @@ const (
 //
 // Because PushTester returns PopTester it allows us to merge these two calls to
 // one line. See the first t.Run call. NOTE. More information in PopTester.
+//
+// PushTester allows you to change the current default asserter by accepting it
+// as a second argument. NOTE. That it change the default asserter for whole
+// package. The argument is mainly for temporary development use and isn't not
+// preferrred API usage.
 func PushTester(t testing.TB, a ...defInd) function {
 	if len(a) > 0 {
 		SetDefault(a[0])
 	} else if Default()&AsserterUnitTesting == 0 {
 		// if this is forgotten or tests don't have proper place to set it
 		// it's good to keep the API as simple as possible
-		SetDefault(Test)
-		// TODO: parallel testing is something we should test.
+		SetDefault(TestFull)
 	}
 	testers.Tx(func(m testersMap) {
 		rid := goid()

assert/assert_test.go

@@ -18,7 +18,7 @@ func ExampleThat() {
 	}
 	err := sample()
 	fmt.Printf("%v", err)
-	// Output: testing run example: assertion test
+	// Output: testing: run example: assertion test
 }
 
 func ExampleNotNil() {

doc.go

@@ -34,9 +34,9 @@ them. The CopyFile example shows how it works:
 	     w := try.To1(os.Create(dst))
 	     // Add error handler to clean up the destination file. Place it here that
 	     // the next deferred close is called before our Remove call.
-	     defer err2.Handle(&err, func() {
+	     defer err2.Handle(&err, err2.Err(func(error) {
 	     	os.Remove(dst)
-	     })
+	     }))
 	     defer w.Close()
 
 	     // Try to copy the file. If error occurs now, all previous error handlers