feat: add be familly of functions. add exampes. (#6)

Author: xiegeo

README.md

@@ -19,19 +19,25 @@ Occasionally a little more, so made a home for them, DRY.
 
 - Error handling is not always necessary. Panic on error should be
   easier than ignoring them.
-- Lightweight assertions.
-
+- Lightweight assertions. No deps, 3 digit loc count.
+- `must` is designed to stand out like `unsafe`.
+  So normal error handling and none panicky helper functions should live else where.
+  
 ### Turn errors into panics
 
 ``` go
 // NoError panics on error.
+//
+// Use this because test coverage.
 func NoError(err error) {
     if err != nil {
         panic(err)
     }
 }
 
 // Value panics on error, otherwise returns the first value.
+//
+// Use this instead of writing a Must version of your function.
 func Value[T any](out T, err error) T {
     if err != nil {
         panic(err)
@@ -40,27 +46,31 @@ func Value[T any](out T, err error) T {
 }
 ```
 
-Also Value2 is available for longer function signatures.
+Also `Value2` is available for longer function signatures.
+`V` and `V2` are their short aliases since the `must.` prefix already stands out enough.
 
 ### Turn assertions into panics
 
-`must.True` and friends.
+Functions like `True(bool)` and friends. To assert a condition or panic.
+
+`B1`, `B2`... are generic assertions that pass their first inputs unmodified with compile time type info preserved.
+They return a function to specify what assertions are made on each field.
 
 Assertions have optional debug arguments, to provide additional information when
 violated. Usually, just pass in the line comment as string.
 
 ### Panic test helpers
 
-`must.Panic` and `must.Recover`. Useful for writing tests for panics cases.
+`must.Panic` and `must.Recover`. Useful for writing tests for panicky cases.
 
 ## Compatibility
 
-Since this library is heavily dependent on generics. 1.18 is the minimum Go version supported for now.
+Since this library is heavily dependent on generics. **1.18** is the minimum Go version supported until a new go version has a feature too good to pass.
 
-Tagged versions will follow sematic versioning. Untagged master/main branch is for development.
+Tagged versions follow **sematic versioning**. Untagged master/main branch is for development.
 
-Values set in panics are only for debugging. No guarantees are provided on how panics are argumented.
+Values used in panics are only for debugging. No guarantees are provided on how panics are constructed. This means the recovered value and stack track could change even in bugfix versions.
 
-## Planning
+## Version 1.0 milestone
 
-Generic assertions ;-)
+- Gain enough downstream usage cases to prove API fitness and stability.

be.go

@@ -0,0 +1,98 @@
+package must
+
+import (
+	"fmt"
+	"reflect"
+)
+
+type allowAll struct{}
+
+// Any implements a Checker that always returns true.
+var Any = allowAll{}
+
+const anyDebugMessage = "Any allows all values"
+
+func (allowAll) MustBe(v any) bool {
+	return true
+}
+
+func (allowAll) Debug(v any) any {
+	return anyDebugMessage
+}
+
+// Checker can be used by B# functions to check if value is allowed.
+type Checker interface {
+	// MustBe returns true iff value is allowed.
+	MustBe(v any) bool
+	// Debug is used to explain why the value is not allowed.
+	Debug(v any) any
+}
+
+// B1 asserts on one value.
+//
+// v is the value to be checked. If check is passed v is returned, otherwise panics.
+//
+// b checks v, there are a few cases:
+//
+//   - A Checker (such as must.Any for all values); or
+//   - a literal value to test for equality using `==`,
+//     if types are the same and literal is comparable; or
+//   - a nil value, which will match nil of any type.
+//   - All other cases panic, room for future expansion.
+//
+// v and b are separated to two function calls for clarity,
+// v has to go first so the compiler can auto type it.
+//
+// debug does not participate in functionality. If the assert need a line comment,
+// then use it as the debug message is suggested.
+func B1[V any](v V) func(b any, debug ...any) V {
+	return func(b any, debug ...any) V {
+		checker, ok := b.(Checker)
+		if ok {
+			if !checker.MustBe(v) {
+				panicWith(debug, checker.Debug(v))
+			}
+			return v
+		}
+		if b == nil {
+			value := reflect.ValueOf(v)
+			if value.IsValid() && !value.IsNil() {
+				panicWith(append(debug, v), "value must be nil")
+			}
+			return v
+		}
+		bAsV, ok := b.(V)
+		if ok {
+			var equal bool
+			r := Recover(func() { equal = any(bAsV) == any(v) })
+			if r != nil {
+				debug = append(debug, fmt.Sprintf("type(%T) is not comparable", bAsV), r)
+			}
+			if !equal {
+				panicWith(append(debug, v, b), "values must equal")
+			}
+			return v
+		}
+		panicWith(debug, fmt.Sprintf("must use Checker interface or the same comparable type as input. expected %T got %T", v, b))
+		return v // unreachable
+	}
+}
+
+// B2 is 2 valued version of B1. To only Check one value, use must.Any on the other value to skip it.
+func B2[V1 any, V2 any](v1 V1, v2 V2) func(b1, b2 any, debug ...any) (V1, V2) {
+	return func(b1, b2 any, debug ...any) (V1, V2) {
+		B1(v1)(b1, append(debug, "#1")...)
+		B1(v2)(b2, append(debug, "#2")...)
+		return v1, v2
+	}
+}
+
+// B3 is 3 valued version of B1. To only Check some value, use must.Any on the other values to skip it.
+func B3[V1 any, V2 any, V3 any](v1 V1, v2 V2, v3 V3) func(b1, b2, b3 any, debug ...any) (V1, V2, V3) {
+	return func(b1, b2, b3 any, debug ...any) (V1, V2, V3) {
+		B1(v1)(b1, append(debug, "#1")...)
+		B1(v2)(b2, append(debug, "#2")...)
+		B1(v3)(b3, append(debug, "#3")...)
+		return v1, v2, v3
+	}
+}

be_test.go

@@ -0,0 +1,21 @@
+package must_test
+
+import (
+	"fmt"
+
+	"github.com/xiegeo/must"
+)
+
+func ExampleB3() {
+	// lets say we have an io.RuneReader
+	readRune := func() (r rune, size int, err error) {
+		return 'a', 1, nil
+	}
+
+	// that must return 1 byte runes and never err out
+	char, _, _ := must.B3(readRune())(must.Any, 1, nil)
+	fmt.Println(string(char))
+
+	// output:
+	// a
+}

bool_test.go

@@ -0,0 +1,45 @@
+package must_test
+
+import (
+	"fmt"
+
+	"github.com/xiegeo/must"
+)
+
+func ExampleTrue() {
+	trueFunc := func() bool {
+		return true
+	}
+
+	must.True(trueFunc(), "a no-op")
+	fmt.Printf("True:%#v\n", must.Panic(func() {
+		must.True(false, "this will panic")
+	}))
+
+	// True can also be written using B1
+	must.B1(trueFunc())(true)
+	fmt.Printf("B1:%#v\n", must.Panic(func() {
+		must.B1(false)(true, "this will also panic")
+	}))
+
+	// Output:
+	// True:[]interface {}{"this will panic", "must be true"}
+	// B1:[]interface {}{"this will also panic", false, true, "values must equal"}
+}
+
+func ExampleFalse() {
+	must.False(false, "a no-op")
+	fmt.Printf("False:%#v\n", must.Panic(func() {
+		must.False(true, "this will panic")
+	}))
+
+	// False can also be written using B1
+	must.B1(false)(false)
+	fmt.Printf("B1:%#v\n", must.Panic(func() {
+		must.B1(true)(false, "this will also panic")
+	}))
+
+	// Output:
+	// False:[]interface {}{"this will panic", "must be false"}
+	// B1:[]interface {}{"this will also panic", true, false, "values must equal"}
+}

error.go

@@ -1,13 +1,17 @@
 package must
 
 // NoError panics on error.
+//
+// Use this because test coverage.
 func NoError(err error) {
 	if err != nil {
 		panic(err)
 	}
 }
 
 // Value panics on error, otherwise returns the first value.
+//
+// Use this instead of writing a Must version of your function.
 func Value[T any](out T, err error) T {
 	if err != nil {
 		panic(err)
@@ -17,10 +21,7 @@ func Value[T any](out T, err error) T {
 
 // V is short for Value, which panics on error, otherwise returns the first value.
 func V[T any](out T, err error) T {
-	if err != nil {
-		panic(err)
-	}
-	return out
+	return Value(out, err)
 }
 
 // Value2 panics on error, otherwise returns the first 2 values.
@@ -33,8 +34,5 @@ func Value2[T any, U any](out1 T, out2 U, err error) (T, U) {
 
 // V2 is short for Value2, which panics on error, otherwise returns the first 2 values.
 func V2[T any, U any](out1 T, out2 U, err error) (T, U) {
-	if err != nil {
-		panic(err)
-	}
-	return out1, out2
+	return Value2(out1, out2, err)
 }

error_test.go

@@ -0,0 +1,47 @@
+package must_test
+
+import (
+	"fmt"
+	"io"
+
+	"github.com/xiegeo/must"
+)
+
+func ExampleNoError() {
+	var err error // create nil error
+	must.NoError(err)
+	fmt.Printf("NoError:%#v\n", must.Panic(func() {
+		must.NoError(io.EOF)
+	}))
+
+	// NoError can also be written using B1
+	_ = must.B1(err)(nil)
+	fmt.Printf("B1:%v\n", must.Panic(func() { // use %v because %#v prints out pointer address
+		_ = must.B1(io.EOF)(nil)
+	}))
+
+	// Output:
+	// NoError:&errors.errorString{s:"EOF"}
+	// B1:[EOF value must be nil]
+}
+
+func ExampleValue() {
+	var err error // create nil error
+	fmt.Printf("Value nil error:%#v\n", must.Value(5, err))
+	fmt.Printf("Value with error:%#v\n", must.Panic(func() {
+		_ = must.V(6, io.EOF)
+	}))
+
+	// Value can also be written using B2
+	value, _ := must.B2(7, err)(must.Any, nil)
+	fmt.Printf("B2 nil error:%#v\n", value)
+	fmt.Printf("B2 with error:%v\n", must.Panic(func() { // use %v because %#v prints out pointer address
+		_, _ = must.B2(8, io.EOF)(must.Any, nil)
+	}))
+
+	// Output:
+	// Value nil error:5
+	// Value with error:&errors.errorString{s:"EOF"}
+	// B2 nil error:7
+	// B2 with error:[#2 EOF value must be nil]
+}

panic.go

@@ -15,6 +15,9 @@ func Panic(f func(), debug ...any) (r any) {
 
 func panicWith(debug []any, last any) {
 	if len(debug) > 0 {
+		if last == nil {
+			panic(debug)
+		}
 		panic(append(debug, last))
 	}
 	panic(last)

panic_test.go

@@ -0,0 +1,23 @@
+package must_test
+
+import (
+	"fmt"
+
+	"github.com/xiegeo/must"
+)
+
+func ExamplePanic() {
+	// must.Panic caches a panic and returns the thrown value
+	fmt.Println(must.Panic(func() { panic("foo") }))
+
+	// must.Panic will panic if function did not panic
+	fmt.Println(must.Panic(func() { must.Panic(func() {}) }))
+
+	// use must.Recover instead if function might not panic
+	fmt.Println(must.Recover(func() {}))
+
+	// output:
+	// foo
+	// function expected to panic but did not
+	// <nil>
+}