git/lancet
1
0
Fork 0
mirror of https://github.com/duke-git/lancet.git synced 2026-02-09 23:22:28 +08:00
Code Issues Projects Releases Wiki Activity

doc: update doc for website

Browse Source
This commit is contained in:
dudaodong
2023-08-30 11:46:16 +08:00
parent ef79e1305e
commit 03d331dfb6
13 changed files with 6385 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

308
docs/en/api/packages/system.md Normal file
View File

@@ -0,0 +1,308 @@
# System
Package system contains some functions about os, runtime, shell command.
<div STYLE="page-break-after: always;"></div>
## Source:
- [https://github.com/duke-git/lancet/blob/main/system/os.go](https://github.com/duke-git/lancet/blob/main/system/os.go)
<div STYLE="page-break-after: always;"></div>
## Usage:
```go
import (
"github.com/duke-git/lancet/v2/system"
)
```
<div STYLE="page-break-after: always;"></div>
## Index
- [IsWindows](#IsWindows)
- [IsLinux](#IsLinux)
- [IsMac](#IsMac)
- [GetOsEnv](#GetOsEnv)
- [SetOsEnv](#SetOsEnv)
- [RemoveOsEnv](#RemoveOsEnv)
- [CompareOsEnv](#CompareOsEnv)
- [ExecCommand](#ExecCommand)
- [GetOsBits](#GetOsBits)
<div STYLE="page-break-after: always;"></div>
## Documentation
### <span id="IsWindows">IsWindows</span>
<p>Check if current os is windows.</p>
<b>Signature:</b>
```go
func IsWindows() bool
```
<b>Example:<span style="float:right;display:inline-block">[Run](https://go.dev/play/p/zIflQgZNuxD)</span></b>
```go
import (
"fmt"
"github.com/duke-git/lancet/v2/system"
)
func main() {
isOsWindows := system.IsWindows()
fmt.Println(isOsWindows)
}
```
### <span id="IsLinux">IsLinux</span>
<p>Check if current os is linux.</p>
<b>Signature:</b>
```go
func IsLinux() bool
```
<b>Example:<span style="float:right;display:inline-block">[Run](https://go.dev/play/p/zIflQgZNuxD)</span></b>
```go
import (
"fmt"
"github.com/duke-git/lancet/v2/system"
)
func main() {
isOsLinux := system.IsLinux()
fmt.Println(isOsLinux)
}
```
### <span id="IsMac">IsMac</span>
<p>Check if current os is macos.</p>
<b>Signature:</b>
```go
func IsMac() bool
```
<b>Example:<span style="float:right;display:inline-block">[Run](https://go.dev/play/p/Mg4Hjtyq7Zc)</span></b>
```go
import (
"fmt"
"github.com/duke-git/lancet/v2/system"
)
func main() {
isOsMac := system.IsMac()
fmt.Println(isOsMac)
}
```
### <span id="GetOsEnv">GetOsEnv</span>
<p>Gets the value of the environment variable named by the key.</p>
<b>Signature:</b>
```go
func GetOsEnv(key string) string
```
<b>Example:<span style="float:right;display:inline-block">[Run](https://go.dev/play/p/D88OYVCyjO-)</span></b>
```go
import (
"fmt"
"github.com/duke-git/lancet/v2/system"
)
func main() {
err := system.SetOsEnv("foo", "abc")
result := system.GetOsEnv("foo")
fmt.Println(err)
fmt.Println(result)
// Output:
// <nil>
// abc
}
```
### <span id="SetOsEnv">SetOsEnv</span>
<p>Sets the value of the environment variable named by the key.</p>
<b>Signature:</b>
```go
func SetOsEnv(key, value string) error
```
<b>Example:<span style="float:right;display:inline-block">[Run](https://go.dev/play/p/D88OYVCyjO-)</span></b>
```go
import (
"fmt"
"github.com/duke-git/lancet/v2/system"
)
func main() {
err := system.SetOsEnv("foo", "abc")
result := system.GetOsEnv("foo")
fmt.Println(err)
fmt.Println(result)
// Output:
// <nil>
// abc
}
```
### <span id="RemoveOsEnv">RemoveOsEnv</span>
<p>Remove a single environment variable.</p>
<b>Signature:</b>
```go
func RemoveOsEnv(key string) error
```
<b>Example:<span style="float:right;display:inline-block">[Run](https://go.dev/play/p/fqyq4b3xUFQ)</span></b>
```go
import (
"fmt"
"github.com/duke-git/lancet/v2/system"
)
func main() {
err1 := system.SetOsEnv("foo", "abc")
result1 := GetOsEnv("foo")
err2 := system.RemoveOsEnv("foo")
result2 := GetOsEnv("foo")
fmt.Println(err1)
fmt.Println(err2)
fmt.Println(result1)
fmt.Println(result2)
// Output:
// <nil>
// <nil>
// abc
//
}
```
### <span id="CompareOsEnv">CompareOsEnv</span>
<p>Get env named by the key and compare it with comparedEnv.</p>
<b>Signature:</b>
```go
func CompareOsEnv(key, comparedEnv string) bool
```
<b>Example:<span style="float:right;display:inline-block">[Run](https://go.dev/play/p/BciHrKYOHbp)</span></b>
```go
import (
"fmt"
"github.com/duke-git/lancet/v2/system"
)
func main() {
err := system.SetOsEnv("foo", "abc")
if err != nil {
return
}
result := system.CompareOsEnv("foo", "abc")
fmt.Println(result)
// Output:
// true
}
```
### <span id="ExecCommand">ExecCommand</span>
<p>Execute shell command, return the stdout and stderr string of command, and error if error occur. param `command` is a complete command string, like, ls -a (linux), dir(windows), ping 127.0.0.1. In linux, use /bin/bash -c to execute command, In windows, use powershell.exe to execute command.</p>
<b>Signature:</b>
```go
type (
Option func(*exec.Cmd)
)
func ExecCommand(command string, opts ...Option) (stdout, stderr string, err error)
```
<b>Example:<span style="float:right;display:inline-block">[Run](https://go.dev/play/p/n-2fLyZef-4)</span></b>
```go
import (
"fmt"
"github.com/duke-git/lancet/v2/system"
)
func main() {
// linux or mac
stdout, stderr, err := system.ExecCommand("ls")
fmt.Println("std out: ", stdout)
fmt.Println("std err: ", stderr)
assert.Equal("", stderr)
// windows
stdout, stderr, err = system.ExecCommand("dir")
fmt.Println("std out: ", stdout)
fmt.Println("std err: ", stderr)
// error command
stdout, stderr, err = system.ExecCommand("abc")
fmt.Println("std out: ", stdout)
fmt.Println("std err: ", stderr)
if err != nil {
fmt.Println(err.Error())
}
}
```
### <span id="GetOsBits">GetOsBits</span>
<p>Get current os bits, 32bit or 64bit. return 32 or 64</p>
<b>Signature:</b>
```go
func GetOsBits() int
```
<b>Example:<span style="float:right;display:inline-block">[Run](https://go.dev/play/p/ml-_XH3gJbW)</span></b>
```go
import (
"fmt"
"github.com/duke-git/lancet/v2/system"
)
func main() {
osBit := system.GetOsBits()
fmt.Println(osBit) // 32 or 64
}
```

1198
docs/en/api/packages/tuple.md Normal file
View File

File diff suppressed because it is too large Load Diff

1190
docs/en/api/packages/validator.md Normal file
View File

File diff suppressed because it is too large Load Diff

489
docs/en/api/packages/xerror.md Normal file
View File

@@ -0,0 +1,489 @@
# Xerror
Package xerror implements helpers for errors.
<div STYLE="page-break-after: always;"></div>
## Source:
- [https://github.com/duke-git/lancet/blob/main/xerror/xerror.go](https://github.com/duke-git/lancet/blob/main/xerror/xerror.go)
<div STYLE="page-break-after: always;"></div>
## Usage:
```go
import (
"github.com/duke-git/lancet/v2/xerror"
)
```
<div STYLE="page-break-after: always;"></div>
## Index
- [New](#New)
- [Wrap](#Wrap)
- [Unwrap](#Unwrap)
- [XError_Wrap](#XError_Wrap)
- [XError_Unwrap](#XError_Unwrap)
- [XError_With](#XError_With)
- [XError_Is](#XError_Is)
- [XError_Id](#XError_Id)
- [XError_Values](#XError_Values)
- [XError_StackTrace](#XError_StackTrace)
- [XError_Info](#XError_Info)
- [XError_Error](#XError_Error)
- [TryUnwrap](#TryUnwrap)
<div STYLE="page-break-after: always;"></div>
## Documentation
### <span id="New">New</span>
<p>Creates a new XError pointer instance with message.</p>
<b>Signature:</b>
```go
type XError struct {
id string
message string
stack *stack
cause error
values map[string]any
}
func New(format string, args ...any) *XError
```
<b>Example:<span style="float:right;display:inline-block">[Run](https://go.dev/play/p/w4oWZts7q7f)</span></b>
```go
package main
import (
"fmt"
"github.com/duke-git/lancet/v2/xerror"
)
func main() {
err := xerror.New("error")
fmt.Println(err.Error())
// Output:
// error
}
```
### <span id="Wrap">Wrap</span>
<p>Creates a new XError pointer instance based on error object, and add message.</p>
<b>Signature:</b>
```go
func Wrap(cause error, message ...any) *XError
```
<b>Example:<span style="float:right;display:inline-block">[Run](https://go.dev/play/p/5385qT2dCi4)</span></b>
```go
package main
import (
"fmt"
"github.com/duke-git/lancet/v2/xerror"
)
func main() {
err := xerror.New("wrong password")
wrapErr := xerror.Wrap(err, "error")
fmt.Println(wrapErr.Error())
// Output:
// error: wrong password
}
```
### <span id="Unwrap">Unwrap</span>
<p>Returns unwrapped XError from err by errors.As. If no XError, returns nil.</p>
<b>Signature:</b>
```go
func Unwrap(err error) *XError
```
<b>Example:<span style="float:right;display:inline-block">[Run](https://go.dev/play/p/LKMLep723tu)</span></b>
```go
package main
import (
"fmt"
"github.com/pkg/errors"
"github.com/duke-git/lancet/v2/xerror"
)
func main() {
err1 := xerror.New("error").With("level", "high")
wrapErr := errors.Wrap(err1, "oops")
err := xerror.Unwrap(wrapErr)
values := err.Values()
fmt.Println(values["level"])
// Output:
// high
}
```
### <span id="XError_Wrap">XError_Wrap</span>
<p>Creates a new XError and copy message and id to new one.</p>
<b>Signature:</b>
```go
func (e *XError) Wrap(cause error) *XError
```
<b>Example:<span style="float:right;display:inline-block">[Run](https://go.dev/play/p/RpjJ5u5sc97)</span></b>
```go
package main
import (
"fmt"
"errors"
"github.com/duke-git/lancet/v2/xerror"
)
func main() {
err1 := xerror.New("error").With("level", "high")
err2 := err1.Wrap(errors.New("invalid username"))
fmt.Println(err2.Error())
// Output:
// error: invalid username
}
```
### <span id="XError_Unwrap">XError_Unwrap</span>
<p>Compatible with github.com/pkg/errors.</p>
<b>Signature:</b>
```go
func (e *XError) Unwrap() error
```
<b>Example:<span style="float:right;display:inline-block">[Run](https://go.dev/play/p/VUXJ8BST4c6)</span></b>
```go
package main
import (
"fmt"
"github.com/duke-git/lancet/v2/xerror"
)
func main() {
err1 := xerror.New("error").With("level", "high")
err2 := err1.Wrap(errors.New("invalid username"))
err := err2.Unwrap()
fmt.Println(err.Error())
// Output:
// invalid username
}
```
### <span id="XError_With">XError_With</span>
<p>Adds key and value related to the XError object.</p>
<b>Signature:</b>
```go
func (e *XError) With(key string, value any) *XError
```
<b>Example:<span style="float:right;display:inline-block">[Run](https://go.dev/play/p/ow8UISXX_Dp)</span></b>
```go
package main
import (
"fmt"
"github.com/duke-git/lancet/v2/xerror"
)
func main() {
err := xerror.New("error").With("level", "high")
errLevel := err.Values()["level"]
fmt.Println(errLevel)
// Output:
// high
}
```
### <span id="XError_Id">XError_Id</span>
<p>Sets XError object id to check equality in XError.Is.</p>
<b>Signature:</b>
```go
func (e *XError) Id(id string) *XError
```
<b>Example:<span style="float:right;display:inline-block">[Run](https://go.dev/play/p/X6HBlsy58U9)</span></b>
```go
package main
import (
"fmt"
"github.com/duke-git/lancet/v2/xerror"
)
func main() {
err1 := xerror.New("error").Id("e001")
err2 := xerror.New("error").Id("e001")
err3 := xerror.New("error").Id("e003")
equal := err1.Is(err2)
notEqual := err1.Is(err3)
fmt.Println(equal)
fmt.Println(notEqual)
// Output:
// true
// false
}
```
### <span id="XError_Is">XError_Is</span>
<p>Checks if target error is XError and Error.id of two errors are matched.</p>
<b>Signature:</b>
```go
func (e *XError) Is(target error) bool
```
<b>Example:<span style="float:right;display:inline-block">[Run](https://go.dev/play/p/X6HBlsy58U9)</span></b>
```go
package main
import (
"fmt"
"github.com/duke-git/lancet/v2/xerror"
)
func main() {
err1 := xerror.New("error").Id("e001")
err2 := xerror.New("error").Id("e001")
err3 := xerror.New("error").Id("e003")
equal := err1.Is(err2)
notEqual := err1.Is(err3)
fmt.Println(equal)
fmt.Println(notEqual)
// Output:
// true
// false
}
```
### <span id="XError_Values">XError_Values</span>
<p>Returns map of key and value that is set by With. All wrapped xerror.XError key and values will be merged. Key and values of wrapped error is overwritten by upper xerror.XError.</p>
<b>Signature:</b>
```go
func (e *XError) Values() map[string]any
```
<b>Example:<span style="float:right;display:inline-block">[Run](https://go.dev/play/p/ow8UISXX_Dp)</span></b>
```go
package main
import (
"fmt"
"github.com/duke-git/lancet/v2/xerror"
)
func main() {
err := xerror.New("error").With("level", "high")
errLevel := err.Values()["level"]
fmt.Println(errLevel)
// Output:
// high
}
```
### <span id="XError_StackTrace">XError_StackTrace</span>
<p>Returns stack trace which is compatible with pkg/errors.</p>
<b>Signature:</b>
```go
func (e *XError) StackTrace() StackTrace
```
<b>Example:<span style="float:right;display:inline-block">[Run](https://go.dev/play/p/6FAvSQpa7pc)</span></b>
```go
package main
import (
"fmt"
"github.com/duke-git/lancet/v2/xerror"
)
func main() {
err := xerror.New("error")
stacks := err.Stacks()
fmt.Println(stacks[0].Func)
fmt.Println(stacks[0].Line)
containFile := strings.Contains(stacks[0].File, "xxx.go")
fmt.Println(containFile)
}
```
### <span id="XError_Info">XError_Info</span>
<p>Returns information of xerror, which can be printed.</p>
<b>Signature:</b>
```go
func (e *XError) Info() *errInfo
```
<b>Example:<span style="float:right;display:inline-block">[Run](https://go.dev/play/p/1ZX0ME1F-Jb)</span></b>
```go
package main
import (
"fmt"
"github.com/duke-git/lancet/v2/xerror"
)
func main() {
cause := errors.New("error")
err := xerror.Wrap(cause, "invalid username").Id("e001").With("level", "high")
errInfo := err.Info()
fmt.Println(errInfo.Id)
fmt.Println(errInfo.Cause)
fmt.Println(errInfo.Values["level"])
fmt.Println(errInfo.Message)
// Output:
// e001
// error
// high
// invalid username
}
```
### <span id="XError_Error">XError_Error</span>
<p>Error implements standard error interface.</p>
<b>Signature:</b>
```go
func (e *XError) Error() string
```
<b>Example:<span style="float:right;display:inline-block">[Run](https://go.dev/play/p/w4oWZts7q7f)</span></b>
```go
package main
import (
"fmt"
"github.com/duke-git/lancet/v2/xerror"
)
func main() {
err := xerror.New("error")
fmt.Println(err.Error())
// Output:
// error
}
```
### <span id="TryUnwrap">TryUnwrap</span>
<p>TryUnwrap if err is nil then it returns a valid value. If err is not nil, Unwrap panics with err.</p>
<b>Signature:</b>
```go
func TryUnwrap[T any](val T, err error) T
```
<b>Example:<span style="float:right;display:inline-block">[Run](https://go.dev/play/p/acyZVkNZEeW)</span></b>
```go
package main
import (
"fmt"
"github.com/duke-git/lancet/v2/xerror"
)
func main() {
result1 := xerror.TryUnwrap(strconv.Atoi("42"))
fmt.Println(result1)
_, err := strconv.Atoi("4o2")
defer func() {
v := recover()
result2 := reflect.DeepEqual(err.Error(), v.(*strconv.NumError).Error())
fmt.Println(result2)
}()
xerror.TryUnwrap(strconv.Atoi("4o2"))
// Output:
// 42
// true
}
```