增加英文文档

.gitignore

@@ -0,0 +1,36 @@
+*.a
+*.so
+*.exe
+*.pyc
+*.log
+*.dll
+*.out
+*.key
+_test
+*.test
+*.cert
+*.exe~
+go.work
+.Trash-*
+.DS_Store
+go.work.sum
+main.out.bin
+*gitignore*secrets*
+*gitignore*outputs*
+ehthumbs.db
+Thumbs.db
+.gitkeep
+.vscode/
+*.dylib
+vendor/
+.idea/
+*.err
+*.swp
+_obj
+tmp/
+bin/
+tags
+*.DB
+*.db
+*.o
+*~

README.md

@@ -1,52 +1,142 @@
-# must
-must means assert means require. while the assert/require are using in testcase. must is using in main code.
+# `must` – A Simple, Yet Powerful Assertion Library for Go
 
-这个包的作用就是断言，比如该为真的地方返回假，或者该没有err的地方返回错误，就直接崩掉就行。
+### Why settle for less when you can be sure?
 
-## 安装
-```
+In Go, errors are part of the game, but sometimes you want to enforce guarantees that your code must meet—without the need for extensive checks or verbose error-handling. That's where `must` comes in: a lightweight package that ensures certain conditions *must* be true for your program to continue, panic-free. If the condition fails, you get an immediate and clear failure, saving time debugging or testing edge cases.
+
+## README
+[中文说明](README.zh.md)
+
+## Install
+
+Quickly integrate `must` into your Go project by running:
+
+```bash
 go get github.com/yyle88/must
 ```
 
-## 简单样例
-```
-res, err := run()
-must.Done(err) //假如出现错误-就崩掉
-must.Nice(res) //假如结果为空-就崩掉
-```
+## Core Philosophy
 
+The premise behind `must` is simple: **assert the unassertable**.
+
+In many cases, Go developers use error handling to validate that conditions are met, but what if you don’t want to write multiple checks for simple conditions? What if certain things in your codebase *must* happen, and anything less should halt the program?
+
+That’s exactly what `must` does. It brings you immediate feedback if something goes wrong with minimal boilerplate, ensuring you catch bugs early in the development cycle.
+
+## Features
+
+- **Enforce Certain Conditions**: Assert that a value or state must meet specific criteria (e.g., non-nil, non-zero).
+- **Clear Failures**: Panic when an assertion fails, providing an explicit and actionable message.
+- **Optimized for Speed**: Perfect for prototypes and small applications where fast feedback is critical.
+
+## Usage
+
+Here’s how you can use `must` in your code to handle assertions concisely:
+
+### Example 1: Validate Non-Nil Values
+
+```go
+package main
+
+import (
+	"fmt"
+	"github.com/yyle88/must"
+)
+
+func main() {
+	// Simulate a function that may return an error
+	result, err := someFunction()
+	must.Done(err)   // Panics if err is non-nil
+	must.Nice(result) // Panics if result is the zero value (nil or empty)
+
+	fmt.Println("Result is:", result)
+}
+
+func someFunction() (string, error) {
+	// For demonstration, returning a result and no error
+	return "Hello, must!", nil
+}
 ```
-res, ok := run()
-must.True(ok)  //假如结果非真-就崩掉
-must.Nice(res) //假如结果为空-就崩掉
-```
 
-## 特别注意
-在代码里随意 panic 是不规范的，或者说，是不道德的，就像随地内个啥。
+### Example 2: Assert a Boolean Condition
+
+```go
+package main
 
-因此这个包只建议在写 demo/test 时用，而不建议在写 service 时用。
+import (
+	"fmt"
+	"github.com/yyle88/must"
+)
 
-## 起名思路
+func main() {
+	// Simulate a check that should return true
+	isActive := checkStatus()
+	must.True(isActive)  // Panics if isActive is false
 
-因为这俩是我常用的包，因此我就不用 assert 或者 require 作为模块名啦。
+	fmt.Println("Status is active:", isActive)
+}
+
+func checkStatus() bool {
+	// Returning true for demonstration
+	return true
+}
 ```
-"github.com/stretchr/testify/assert"
-"github.com/stretchr/testify/require"
+
+### Example 3: Ensure Length Matches
+
+```go
+package main
+
+import (
+	"fmt"
+	"github.com/yyle88/must"
+)
+
+func main() {
+	// Simulating an array
+	arr := []int{1, 2, 3}
+	must.Length(arr, 3) // Panics if the length is not 3
+
+	fmt.Println("Array length is correct:", len(arr))
+}
 ```
 
-相比之下我觉得 `must` 是不错的选择。
+## Why `must`?
+
+- **Simplicity Over Verbosity**: In Go, error handling is often verbose. `must` simplifies assertions into short, easy-to-understand statements.
+- **Immediate Feedback**: Perfect for scenarios where you need to catch conditions early—be it during development or in fast-paced prototypes.
+- **Zero-Cost Abstraction**: `must` introduces no additional complexity and is highly idiomatic, keeping your Go codebase clean and easy to maintain.
+
+## Core Assertions
+
+- **`must.True(condition bool)`**: Asserts that a boolean condition is `true`. Panics if `false`.
+- **`must.Done(err error)`**: Verifies that an error is `nil`. Panics if the error is not `nil`.
+- **`must.Nice(value interface{})`**: Asserts that the value is not the zero value (i.e., empty or uninitialized). Panics if zero.
+- **`must.Length(array interface{}, length int)`**: Ensures the provided array or slice has the expected length.
+- **`must.Equals(a, b interface{})`**: Compares two values for equality and panics if they are not equal.
+
+## A Word of Caution
+
+While `must` is great for quick feedback during development or testing, **it should not be used for production error handling**. If you need fine-grained control over errors, consider using traditional Go error-handling techniques.
+
+## Future Plans
+
+- Expand assertion types, like checking for non-empty strings or range conditions.
+- Improve documentation with more complex examples and use cases.
+- Introduce integrations with logging frameworks to output detailed panics in production environments (if needed).
+
+## Conclusion
 
-在汉语式英语里，must表示必然/必须，相对更强硬些，但是在英语里，似乎表示务必，但真搞不定就搞不定吧，这就是非母语编程不得劲的地方。
+With `must`, Go developers get a tool that prioritizes **assertive correctness**. Whether you're in the middle of a prototype or just testing, you don’t need to check everything manually. Let `must` take care of the basic sanity checks for you so you can focus on building great software.
 
-因此在这里说明下起名的思路。
+For now, `must` might be small, but it’ll make sure your foundations are solid.
 
-我只认识4个字母的单词，5个字母的都认识不全，因此我还是倾向于使用4个字母的单词做模块名/函数名，这样用起来也方便。
+---
 
-## 断言三剑客
-现在已经有 `done` 和 `sure` 两个基础包，现在再有 `must` 就相当于有三剑客啦。
+## Give stars
 
-sure: [软硬兼施](https://github.com/yyle88/sure)
+Feel free to contribute or improve the package! Your stars and pull requests are welcome.
 
-done: [确保结果](https://github.com/yyle88/done)
+## Thank You
 
-must: [不对就崩](https://github.com/yyle88/must)
+If you find this package valuable, give it a star on GitHub! Thank you!!!

README.zh.md

@@ -0,0 +1,52 @@
+# must
+must means assert means require. while the assert/require are using in testcase. must is using in main code.
+
+这个包的作用就是断言，比如该为真的地方返回假，或者该没有err的地方返回错误，就直接崩掉就行。
+
+## 安装
+```
+go get github.com/yyle88/must
+```
+
+## 简单样例
+```
+res, err := run()
+must.Done(err) //假如出现错误-就崩掉
+must.Nice(res) //假如结果为空-就崩掉
+```
+
+```
+res, ok := run()
+must.True(ok)  //假如结果非真-就崩掉
+must.Nice(res) //假如结果为空-就崩掉
+```
+
+## 特别注意
+在代码里随意 panic 是不规范的，或者说，是不道德的，就像随地内个啥。
+
+因此这个包只建议在写 demo/test 时用，而不建议在写 service 时用。
+
+## 起名思路
+
+因为这俩是我常用的包，因此我就不用 assert 或者 require 作为模块名啦。
+```
+"github.com/stretchr/testify/assert"
+"github.com/stretchr/testify/require"
+```
+
+相比之下我觉得 `must` 是不错的选择。
+
+在汉语式英语里，must表示必然/必须，相对更强硬些，但是在英语里，似乎表示务必，但真搞不定就搞不定吧，这就是非母语编程不得劲的地方。
+
+因此在这里说明下起名的思路。
+
+我只认识4个字母的单词，5个字母的都认识不全，因此我还是倾向于使用4个字母的单词做模块名/函数名，这样用起来也方便。
+
+## 断言三剑客
+现在已经有 `done` 和 `sure` 两个基础包，现在再有 `must` 就相当于有三剑客啦。
+
+sure: [软硬兼施](https://github.com/yyle88/sure)
+
+done: [确保结果](https://github.com/yyle88/done)
+
+must: [不对就崩](https://github.com/yyle88/must)

go.mod

@@ -5,14 +5,14 @@ go 1.22.6
 require (
 	github.com/pkg/errors v0.9.1
 	github.com/stretchr/testify v1.9.0
-	github.com/yyle88/zaplog v0.0.10
+	github.com/yyle88/zaplog v0.0.14
 	go.uber.org/zap v1.27.0
 )
 
 require (
 	github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect
 	github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 // indirect
-	github.com/yyle88/mutexmap v1.0.4 // indirect
+	github.com/yyle88/mutexmap v1.0.7 // indirect
 	go.uber.org/multierr v1.11.0 // indirect
 	gopkg.in/natefinch/lumberjack.v2 v2.2.1 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect

go.sum

@@ -12,10 +12,10 @@ github.com/rogpeppe/go-internal v1.12.0 h1:exVL4IDcn6na9z1rAb56Vxr+CgyK3nn3O+epU
 github.com/rogpeppe/go-internal v1.12.0/go.mod h1:E+RYuTGaKKdloAfM02xzb0FW3Paa99yedzYV+kq4uf4=
 github.com/stretchr/testify v1.9.0 h1:HtqpIVDClZ4nwg75+f6Lvsy/wHu+3BoSGCbBAcpTsTg=
 github.com/stretchr/testify v1.9.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
-github.com/yyle88/mutexmap v1.0.4 h1:Y4VfNE28HBYwpw/UaZyTUZAjYcob3qPMubQWxgdYl9s=
-github.com/yyle88/mutexmap v1.0.4/go.mod h1:lAEDkpXe9iSU0/8L/SaXAQ6TUa+4A9nnl9OQ56zHEQY=
-github.com/yyle88/zaplog v0.0.10 h1:4jzeWB7h7IQ126hcE5mRMjVo99k8+xpLjQTtbie8JZ8=
-github.com/yyle88/zaplog v0.0.10/go.mod h1:dS72cgivcfuXM6ExW6+f/YiPVGOzQ7spQL5jECrEdcU=
+github.com/yyle88/mutexmap v1.0.7 h1:i4inpmq0fEvwxG9XGunxBVQBt0eAZEWL7ezurkQifqY=
+github.com/yyle88/mutexmap v1.0.7/go.mod h1:lAEDkpXe9iSU0/8L/SaXAQ6TUa+4A9nnl9OQ56zHEQY=
+github.com/yyle88/zaplog v0.0.14 h1:AN7pcBbo+QsHU3jYdu6NJdhckZ5OsnCBB5Wf8xQpBz8=
+github.com/yyle88/zaplog v0.0.14/go.mod h1:EVbOBQhJ0kn7dPa7bpJs/8zEY5N6XQS9SodeojwQmdE=
 go.uber.org/goleak v1.3.0 h1:2K3zAYmnTNqV73imy9J1T3WC+gmCePx2hEGkimedGto=
 go.uber.org/goleak v1.3.0/go.mod h1:CoHD4mav9JJNrW/WLlf7HGZPjdw8EucARQHekz1X6bE=
 go.uber.org/multierr v1.11.0 h1:blXXJkSxSSfBVBlC76pxqeO+LN3aDfLQo+309xJstO0=