Skip to content

Commit d0ba466

Browse files
chenmingyong0423chenmingyong0423
authored
Merge pull request #6 from chenmingyong0423/feature/readme
Readme Document Update
2 parents 44cee50 + ba5c513 commit d0ba466

File tree

2 files changed

+270
-194
lines changed

2 files changed

+270
-194
lines changed

‎README-zh_CN.md‎

Lines changed: 131 additions & 95 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,8 @@
11
<h1 align="center">
22
go-optioner
33
</h1>
4-
go-optioner 是一个在 Go 代码中生成函数选项模式代码的工具。该工具可以根据给定的结构定义自动生成相应的选项代码。
4+
5+
`go-optioner` 是一个在 Go 代码中生成函数选项模式代码的工具。该工具可以根据给定的结构定义自动生成相应的选项代码。
56

67
---
78

@@ -12,121 +13,156 @@ go-optioner 是一个在 Go 代码中生成函数选项模式代码的工具。
1213
- 2、执行 `optioner` 命令检查是否安装成功
1314
```
1415
> optioner
15-
go-optioner is a tool for generating functional options pattern.
16-
Usage:
16+
optioner is a tool for generating functional options pattern.
17+
Usage:
1718
optioner [flags]
1819
Flags:
1920
-type <struct name>
2021
-output <output path>, default: srcDir/opt_xxx_gen.go
22+
-mode <the file writing mode>, default: write
23+
there are two available modes:
24+
- write(Write/Overwrite): Overwrites or creates a new file.
25+
- append (Append): Adds to the end of the file.
2126
```
2227
如果你安装成功了，但是提示 `optioner` 命令找不到，请确认是否已将 `$GOPATH/bin` 添加到环境变量中。
28+
# 参数
29+
使用 `Optioner` 时，你可以通过以下参数定制其行为：
30+
31+
- `-type`: 指定目标结构体的名称，这是一个必需参数。
32+
- `-output`: 设置生成代码的输出文件路径。这是一个可选参数，默认生成的文件名格式为 `opt_{StructName}_gen.go`，其中 `{StructName}` 是结构体的名称，文件位于当前目录下。
33+
- `mode`: 定义文件写入方式，接受的值有：
34+
- `write`（写入/覆盖）：如果文件已存在，将其覆盖；如果文件不存在，创建新文件。
35+
- `append`（追加）：将内容追加到现有文件的末尾。
2336

2437
# 使用教程
2538
你可以直接使用 `optioner` 命令生成对应结构体的 `functional options` 代码，也可以使用 `go generate` 进行批量生成。
2639
## optioner 命令
27-
- 1、首先，你需要创建一个包含需要生成函数选项模式代码的结构体的 `Go` 文件。在结构体字段中，您可以使用 `opt` 标签来控制是否为 `NewXXX()` 函数的必传参数和生成相应的函数。
28-
```go
29-
package example
30-
31-
type User struct {
32-
Name string `opt:"-"`
33-
Age int
34-
Gender string
35-
}
36-
37-
```
38-
如果字段定义了 `opt` 标签，并且值为 `-`，则它将作为 `NewXXX` 函数的必要参数，并且不会生成该字段的 `WithXXX` 函数。
39-
40-
注意：必须声明 `package`。
41-
- 2、在包含结构体定义的文件目录下，执行 `optioner -type XXX` 命令，其中 `XXX` 是结构体的名称。执行命令之后，`optioner` 工具会根据结构体定义生成相应的函数选项模式代码。内容如下所示：
42-
```go
43-
// Generated by optioner -type User; DO NOT EDIT
44-
// If you have any questions, please create issues and submit contributions at:
45-
// https://github.com/chenmingyong0423/go-optioner
46-
47-
package example
48-
49-
type UserOption func(*User)
50-
51-
func NewUser(name string, opts ...UserOption) *User {
52-
user := &User{
53-
Name: name,
40+
- 1、首先，假定您已经准备好一个 `Go` 文件，其中包含了您希望生成函数选项模式代码的结构体。在该结构体的字段上，您可以利用 `opt` 标签来标记哪些字段应作为 `New{FieldName}` 函数的必要参数。
41+
```go
42+
package example
43+
44+
type User[T any, R any] struct {
45+
Name string `opt:"-"`
46+
NecGenericFiled T `opt:"-"`
47+
Age int
48+
Gender string
49+
GenericFiled R
5450
}
55-
56-
for _, opt := range opts {
57-
opt(user)
51+
52+
```
53+
54+
如果结构体字段使用了 `opt` 标签并将其值设置为 `-`，则该字段成为 `New{FieldName}` 函数的必需参数，同时不会为该字段生成 `With{FieldName}` 函数。
55+
56+
注意：必须声明 `package`。
57+
- 2、在包含结构体定义的文件所在目录下，执行 `optioner -type {StructName}` 命令，将 `{StructName}` 替换为实际的结构体名称，例如 `optioner -type User`。此命令执行后，`optioner` 工具会根据结构体定义自动创建默认的 `opt_user_gen.go` 文件，并在其中生成函数选项模式代码。生成的代码结构如下所示：
58+
```go
59+
// Generated by [optioner] command-line tool; DO NOT EDIT
60+
// If you have any questions, please create issues and submit contributions at:
61+
// https://github.com/chenmingyong0423/go-optioner
62+
63+
package example
64+
65+
type UserOption[T any, R any] func(*User[T, R])
66+
67+
func NewUser[T any, R any](name string, necGenericFiled T, opts ...UserOption[T, R]) *User[T, R] {
68+
user := &User[T, R]{
69+
Name: name,
70+
NecGenericFiled: necGenericFiled,
71+
}
72+
73+
for _, opt := range opts {
74+
opt(user)
75+
}
76+
77+
return user
5878
}
59-
60-
return user
61-
}
62-
63-
func WithAge(age int) UserOption {
64-
return func(user *User) {
65-
user.Age = age
79+
80+
func WithAge[T any, R any](age int) UserOption[T, R] {
81+
return func(user *User[T, R]) {
82+
user.Age = age
83+
}
6684
}
67-
}
68-
69-
func WithGender(gender string) UserOption {
70-
return func(user *User) {
71-
user.Gender = gender
85+
86+
func WithGender[T any, R any](gender string) UserOption[T, R] {
87+
return func(user *User[T, R]) {
88+
user.Gender = gender
89+
}
7290
}
73-
}
74-
75-
```
76-
`optioner` 工具将会生成一个名为 `opt_xxx_gen.go` 的文件，其中 `xxx` 是结构体的名称，例如 `opt_user_gen.go`。该文件包含生成的函数选项代码，用于初始化结构体和设置结构体字段的值。
91+
92+
func WithGenericFiled[T any, R any](genericFiled R) UserOption[T, R] {
93+
return func(user *User[T, R]) {
94+
user.GenericFiled = genericFiled
95+
}
96+
}
97+
98+
```
99+
100+
如果需要自定义生成代码的输出文件路径，可以通过指定 `output` 和 `mode` 参数进行配置。
77101
## go generate 命令
78102
请注意，在执行 `go generate` 命令之前，确保您的项目已经初始化 `Go Modules` 或正确设置了 `GOPATH`，并且您的项目结构符合 `Go Modules` 或 `GOPATH` 的要求。
79103

80-
- 1、首先，你需要创建一个包含需要生成函数选项模式代码的结构体的 `Go` 文件。在结构体定义之上，你需要添加 `//go:generate optioner -type XXX` 的注释，其中 `XXX` 是结构体的名称。这样工具就能根据参数生成相应的代码。在结构体字段中，您可以使用 `opt` 标签来控制是否为 `NewXXX()` 函数的必传参数和生成相应的函数。
81-
```go
82-
package example
83-
84-
//go:generate optioner -type User
85-
type User struct {
86-
Name string `opt:"-"`
87-
Age int
88-
Gender string
89-
}
90-
```
91-
如果字段定义了 `opt` 标签，并且值为 `-`，则它将作为 `NewXXX` 函数的必要参数，并且不会生成该字段的 `WithXXX` 函数。
92-
93-
注意：必须声明 `package`。
94-
- 2、在包含结构体定义的文件目录下，执行 `go generate` 命令，这将调用 `optioner` 工具并根据结构体定义生成相应的函数选项模式代码。内容如下所示：
95-
```go
96-
// Generated by optioner -type User; DO NOT EDIT
97-
// If you have any questions, please create issues and submit contributions at:
98-
// https://github.com/chenmingyong0423/go-optioner
99-
100-
package example
101-
102-
type UserOption func(*User)
103-
104-
func NewUser(name string, opts ...UserOption) *User {
105-
user := &User{
106-
Name: name,
104+
- 1、首先，假定您已经准备好一个 `Go` 文件，其中包含了您希望生成函数选项模式代码的结构体。在该结构体定义之上，添加注释 `//go:generate optioner -type {StructName}`，并把 `{StructName}` 替换为您的实际结构体名称。例如，使用 `//go:generate optioner -type User` 来为 `User` 结构体生成代码。在该结构体的字段上，您可以利用 `opt` 标签来标记哪些字段应作为 `New{FieldName}` 函数的必要参数。
105+
```go
106+
package example
107+
108+
//go:generate optioner -type User
109+
type User[T any, R any] struct {
110+
Name string `opt:"-"`
111+
NecGenericFiled T `opt:"-"`
112+
Age int
113+
Gender string
114+
GenericFiled R
107115
}
108-
109-
for _, opt := range opts {
110-
opt(user)
116+
117+
```
118+
119+
如果结构体字段使用了 `opt` 标签并将其值设置为 `-`，则该字段成为 `New{FieldName}` 函数的必需参数，同时不会为该字段生成 `With{FieldName}` 函数。
120+
121+
注意：必须声明 `package`。
122+
- 2、在包含结构体定义的文件所在目录下，运行 `go generate` 命令，这个命令将触发 `optioner` 工具，并根据结构体定义自动创建默认的 `opt_user_gen.go` 文件，同时在该文件中生成函数选项模式的代码。生成的代码结构如下所示：
123+
```go
124+
// Generated by [optioner] command-line tool; DO NOT EDIT
125+
// If you have any questions, please create issues and submit contributions at:
126+
// https://github.com/chenmingyong0423/go-optioner
127+
128+
package example
129+
130+
type UserOption[T any, R any] func(*User[T, R])
131+
132+
func NewUser[T any, R any](name string, necGenericFiled T, opts ...UserOption[T, R]) *User[T, R] {
133+
user := &User[T, R]{
134+
Name: name,
135+
NecGenericFiled: necGenericFiled,
136+
}
137+
138+
for _, opt := range opts {
139+
opt(user)
140+
}
141+
142+
return user
111143
}
112-
113-
return user
114-
}
115-
116-
func WithAge(age int) UserOption {
117-
return func(user *User) {
118-
user.Age = age
144+
145+
func WithAge[T any, R any](age int) UserOption[T, R] {
146+
return func(user *User[T, R]) {
147+
user.Age = age
148+
}
119149
}
120-
}
121-
122-
func WithGender(gender string) UserOption {
123-
return func(user *User) {
124-
user.Gender = gender
150+
151+
func WithGender[T any, R any](gender string) UserOption[T, R] {
152+
return func(user *User[T, R]) {
153+
user.Gender = gender
154+
}
125155
}
126-
}
127-
128-
```
129-
`optioner` 工具将会生成一个名为 `opt_xxx_gen.go` 的文件，其中 `xxx` 是结构体的名称，例如 `opt_user_gen.go`。该文件包含生成的函数选项代码，用于初始化结构体和设置结构体字段的值。
156+
157+
func WithGenericFiled[T any, R any](genericFiled R) UserOption[T, R] {
158+
return func(user *User[T, R]) {
159+
user.GenericFiled = genericFiled
160+
}
161+
}
162+
163+
```
164+
165+
如果需要自定义生成代码的输出文件路径，可以修改 `//go:generate optioner -type User` 的内容，通过指定 `output` 和 `mode` 参数进行配置。
130166
# 如何贡献
131167
我非常欢迎其他人对这个项目做出贡献！如果你有任何问题、改进建议或发现了 bug，请通过提交 issue 来与我们交流。如果你想提交代码贡献，请按照以下步骤：
132168

0 commit comments

Comments
 (0)