Skip to content

Commit 18b8084

Browse files
sttksttk
authored
doc: moved usage from README.md to doc.go (#34)
1 parent 1d46e0e commit 18b8084

File tree

2 files changed

+264
-187
lines changed

2 files changed

+264
-187
lines changed

‎README.md

+8-186
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,9 @@ This library provides the following functionalities:
88
- This library supports `--` option.
99
- This library doesn't support numeric short option.
1010
- This library supports not `-ofoo` but `-o=foo` as an alternative to `-o foo` for short option.
11+
- Supports parsing with option configurations.
12+
- Supports parsing with a struct which stores option values and has struct tags of fields.
13+
- Is able to parse command line arguments including sub commands.
1114
- Generates help text from option configurations.
1215

1316

@@ -20,191 +23,10 @@ import "github.com/sttk-go/cliargs"
2023

2124
## Usage examples
2225

23-
This library provides three ways to parse command line arguments.
26+
The usage of this library is described on the overview in the go package document.
2427

25-
### 1. Parse CLI arguments without configurations
28+
See https://pkg.go.dev/github.com/sttk-go/cliargs#pkg-overview
2629

27-
This way uses `Parse` function.
28-
This function automatically divides command line arguments to options and command arguments.
29-
30-
Command line arguments starting with `-` or `--` are options, and others are command arguments.
31-
If an option is wanted to have an argument, make `=` and the argument follow the option name, e.g. `foo=123`.
32-
33-
`--` makes all command line arguments after it command arguments, even they start with `-` or `--`.
34-
35-
```
36-
// osArgs := []string{"path/to/app", "--foo-bar", "hoge", "--baz", "1", "-z=2", "-xyz=3", "fuga"}
37-
38-
cmd, err := cliargs.Parse()
39-
cmd.Name // app
40-
cmd.Args() // [hoge fuga]
41-
cmd.HasOpt("foo-bar") // true
42-
cmd.HasOpt("baz") // true
43-
cmd.HasOpt("x") // true
44-
cmd.HasOpt("y") // true
45-
cmd.HasOpt("z") // true
46-
cmd.OptArg("foo-bar") // true
47-
cmd.OptArg("baz") // 1
48-
cmd.OptArg("x") // true
49-
cmd.OptArg("y") // true
50-
cmd.OptArg("z") // 2
51-
cmd.OptArgs("foo-bar") // []
52-
cmd.OptArgs("baz") // [1]
53-
cmd.OptArgs("x") // []
54-
cmd.OptArgs("y") // []
55-
cmd.OptArgs("z") // [2 3]
56-
```
57-
58-
### 2. Parse CLI arguments with configurations
59-
60-
This way uses `ParseWith` function.
61-
This function takes an array of option configurations: `[]OptCfg` as the second argument, and divides command line arguments with this configurations.
62-
63-
An option configuration has fields: `.Name`, `.Aliases`, `.HasArg`, `.IsArray`, `.Default`, `.Desc`, and `.ArgHelp`.
64-
65-
```
66-
// osArgs := []string{"app", "--foo-bar", "hoge", "--baz", "1", "-z=2", "-x", "fuga"}
67-
68-
optCfgs := []cliargs.OptCfg{
69-
cliargs.OptCfg{
70-
Name:"foo-bar",
71-
Desc:"This is description of foo-bar.",
72-
},
73-
cliargs.OptCfg{
74-
Name:"baz",
75-
Aliases:[]string{"z"},
76-
HasArg:true,
77-
IsArray: true,
78-
Default: [9,8,7],
79-
Desc:"This is description of baz.",
80-
ArgHelp:"<text>",
81-
},
82-
cliargs.OptCfg{
83-
Name:"*",
84-
Desc: "(Any options are accepted)",
85-
},
86-
}
87-
88-
cmd, err := cliargs.ParseWith(optCfgs)
89-
cmd.Name // app
90-
cmd.Args() // [hoge fuga]
91-
cmd.HasOption("foo-bar") // true
92-
cmd.HasOption("baz") // true
93-
cmd.HasOption("x") // true, due to "*" config
94-
cmd.OptionArg("foo-bar") // true
95-
cmd.OptionArg("baz") // 1
96-
cmd.OptionArg("x") // true
97-
cmd.OptionArgs("foo-bar") // []
98-
cmd.OptionArgs("baz") // [1 2]
99-
cmd.OptionArgs("x") // []
100-
```
101-
102-
This library provides `Help` struct which generates help text from a `OptCfg` array.
103-
104-
The following help text is generated from the above `optCfgs`.
105-
106-
```
107-
help := cliargs.NewHelp()
108-
help.AddText("This is the usage description.")
109-
help.AddOpts(optCfgs, 0, 2)
110-
help.Print()
111-
```
112-
113-
(stdout)
114-
```
115-
This is the usage description.
116-
--foo-bar, -f This is description of foo-bar.
117-
--baz, -z <text> This is description of baz.
118-
```
119-
120-
121-
### 3. Parse CLI arguments for an option store with struct tags
122-
123-
This way uses `ParseFor` function.
124-
This function takes a pointer of a structure which holds option values after parsing as the second argument.
125-
This structure is needed to have struct tags for its fields.
126-
`ParseFor` creates an option configuration array (`[]OptCfg`) from these struct tags, and uses it to parse command line arguments.
127-
128-
```
129-
// osArgs := []string{"app", "--foo-bar", "hoge", "--baz", "1", "-z=2", "-x", "fuga"}
130-
131-
type Options struct {
132-
FooBar bool `optcfg:"foo-bar" optdesc:"This is description of foo-bar."`
133-
Baz []int `optcfg:"baz,z=[9,8,7]" optdesc:"This is description of baz." optarg:"<num>"`
134-
Qux bool `optcfg:"qux,x" optdesc:"This is description of qux"`
135-
}
136-
137-
options := Options{}
138-
139-
cmd, optCfgs, err := cliargs.ParseFor(osArgs, &options)
140-
cmd.Name // app
141-
cmd.Args() // [hoge fuga]
142-
cmd.HasOpt("foo-bar") // true
143-
cmd.HasOpt("baz") // true
144-
cmd.HasOpt("x") // true
145-
cmd.OptArg("foo-bar") // true
146-
cmd.OptArg("baz") // 1
147-
cmd.OptArg("x") // true
148-
cmd.OptArgs("foo-bar") // []
149-
cmd.OptArgs("baz") // [1 2]
150-
cmd.OptArgs("x") // []
151-
152-
options.FooBar // true
153-
options.Baz // [1 2]
154-
options.Qux // true
155-
156-
optCfgs // []OptCfg{
157-
// OptCfg{
158-
// Name: "foo-bar",
159-
// Aliases: []string{},
160-
// Desc: "This is description of foo-bar.",
161-
// HasArg: false,
162-
// IsArray: false,
163-
// Default: []string(nil),
164-
// ArgHelp: "",
165-
// },
166-
// OptCfg{
167-
// Name: "baz",
168-
// Aliases: []string{"z"},
169-
// Desc: "This is description of baz.",
170-
// HasArg: true,
171-
// IsArray: true,
172-
// Default: []string{"9","8","7"},
173-
// ArgHelp: "<num>",
174-
// },
175-
// OptCfg{
176-
// Name: "qux",
177-
// Aliases: []string{"x"},
178-
// Desc: "This is description of qux.",
179-
// HasArg: false,
180-
// IsArray: false,
181-
// Default: []string(nil),
182-
// ArgHelp: "",
183-
// },
184-
// }
185-
```
186-
187-
The following help text is generated from the above `optCfgs` (without `Help#Print` but `Help#Iter`).
188-
189-
```
190-
help := cliargs.NewHelp()
191-
help.AddText("This is the usage description.")
192-
help.AddOpts(optCfgs, 12, 1)
193-
iter := help.Iter()
194-
for line, status := iter.Next() {
195-
fmt.Println(line)
196-
if status == cliargs.ITER_NO_MORE { break }
197-
}
198-
```
199-
200-
(stdout)
201-
```
202-
This is the usage description.
203-
--foo-bar This is description of foo-bar.
204-
--baz, -z <num>
205-
This is description of baz.
206-
--qux This is description of qux.
207-
```
20830

20931
## Supporting Go versions
21032

@@ -216,15 +38,15 @@ This library supports Go 1.18 or later.
21638
% gvm-fav
21739
Now using version go1.18.10
21840
go version go1.18.10 darwin/amd64
219-
ok github.com/sttk-go/cliargs 0.143s coverage: 99.1% of statements
41+
ok github.com/sttk-go/cliargs 0.135s coverage: 99.2% of statements
22042
22143
Now using version go1.19.5
22244
go version go1.19.5 darwin/amd64
223-
ok github.com/sttk-go/cliargs 0.134s coverage: 99.1% of statements
45+
ok github.com/sttk-go/cliargs 0.136s coverage: 99.2% of statements
22446
22547
Now using version go1.20
22648
go version go1.20 darwin/amd64
227-
ok github.com/sttk-go/cliargs 0.138s coverage: 99.1% of statements
49+
ok github.com/sttk-go/cliargs 0.139s coverage: 99.2% of statements
22850
22951
Back to go1.20
23052
Now using version go1.20

0 commit comments

Comments
 (0)