From 85db17e96d6aa1e2ea184bad07425b96d3d7d22c Mon Sep 17 00:00:00 2001 From: lufia Date: Sun, 23 Aug 2026 16:14:08 +0900 Subject: [PATCH] update documents Change-Id: I3bbb9c9abe1a47ea8517a89eeee0bb5451aa88f4 --- README.md | 48 ++++++++++++++++++++++++++++++-------------- example_opts_test.go | 20 ++++++++++++++++++ 2 files changed, 53 insertions(+), 15 deletions(-) create mode 100644 example_opts_test.go diff --git a/README.md b/README.md index 0a231e5..2b95702 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,21 @@ # try + An experimental error handling library. [![GoDev][godev-image]][godev-url] [![Actions Status][actions-image]][actions-url] +This library, **try**, aims to reduce `if err != nil`, and its design is inspired by [Russ's Error Handling proposal](https://go.googlesource.com/proposal/+/master/design/go2draft-error-handling-overview.md). + +[godev-image]: https://pkg.go.dev/badge/github.com/lufia/try +[godev-url]: https://pkg.go.dev/github.com/lufia/try +[actions-image]: https://github.com/lufia/try/actions/workflows/test.yml/badge.svg +[actions-url]: https://github.com/lufia/try/actions/workflows/test.yml + ## Supported Architectures +For now it supports only three architectures: + * amd64 * arm64 * 386 @@ -33,16 +43,15 @@ func Run(file string) (string, error) { } ``` -*try.Handle* creates a fallback point, called "checkpoint", then return nil error - at the first time. +*try.Handle* creates a fallback point, called "checkpoint", then returns a nil error the first time. -After that, above code calls *os.ReadFile* and *url.Parse* with *try.Check1*. If either these functions returns an error, *try.Check1* rewind the program to the checkpoint, then *try.Handle* will return the error. +After that, the above code calls *os.ReadFile* and *url.Parse* with *try.Check1*. If either of these functions returns an error, *try.Check1* rewinds the program to the checkpoint, and *try.Handle* then returns the error. -**I strongly recommend that Check and Handle should call on the same stack.** +**I strongly recommend calling *Check* and *Handle* on the same stack.** ## Example -Error handling in Go sometimes gets flustrated. For instance: +Error handling in Go sometimes makes developers frustrated. For instance: ```go func GetAlerts(w http.ResponseWriter, r *http.Request) { @@ -73,26 +82,35 @@ The example above can rewrite more simple with **try**. ```go func GetAlerts(w http.ResponseWriter, r *http.Request) { - cp400, err := try.Handle() + on400, err := try.Handle() if err != nil { http.Error(w, err.Error(), http.StatusBadRequest) return } - cp500, err := try.Handle() + on500, err := try.Handle() if err != nil { http.Error(w, err.Error(), http.InternalServerError) return } - try.Raise(r.ParseForm())(cp400) - orgID := try.Check1(strconv.Atoi(r.Form.Get("orgId")))(cp400) - alerts := try.Check1(repository.FetchAlerts(orgID))(cp500) - body := try.Check1(json.Marshal(alerts))(cp500) + try.Check(r.ParseForm())(on400) + orgID := try.Check1(strconv.Atoi(r.Form.Get("orgId")))(on400) + alerts := try.Check1(repository.FetchAlerts(orgID))(on500) + body := try.Check1(json.Marshal(alerts))(on500) ... } ``` -[godev-image]: https://pkg.go.dev/badge/github.com/lufia/try -[godev-url]: https://pkg.go.dev/github.com/lufia/try -[actions-image]: https://github.com/lufia/try/actions/workflows/test.yml/badge.svg -[actions-url]: https://github.com/lufia/try/actions/workflows/test.yml +### Options + +There are three options for *Check* and its variants. + +```go +cp, err := try.Handle() +if err != nil { + return nil, err +} +buf := make([]byte, 1<<8) +n := try.Check1(os.Stdin.Read(buf))(cp, try.WithIgnore(io.EOF), try.WithDescription("failed to read")) +return buf[:n], nil +``` diff --git a/example_opts_test.go b/example_opts_test.go new file mode 100644 index 0000000..af952e3 --- /dev/null +++ b/example_opts_test.go @@ -0,0 +1,20 @@ +package try_test + +import ( + "fmt" + "os" + + "github.com/lufia/try" +) + +func ExampleCheck1_withOptions() { + s, err := try.Handle() + if err != nil { + fmt.Println(err) + return + } + v := try.Check1(os.ReadFile("NOFILE"))(s, try.WithDescription("failed to read a file")) + fmt.Println("value:", v) + // Output: + // failed to read a file: open NOFILE: no such file or directory +}