You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: README.md
+95-111
Original file line number
Diff line number
Diff line change
@@ -46,97 +46,76 @@ dependencies {
46
46
47
47
### Parse without configurations
48
48
49
-
This library provides the method `CliArgs#parse` which parses command line arguments without configurations.
50
-
This method automatically divides command line arguments to options and command arguments.
49
+
This library provides the method `Cmd#parse` which parses command line arguments without configurations.
50
+
This method automatically divides command line arguments to command options and command arguments.
51
51
52
-
Command line arguments starting with `-` or `--` are options, and others are command arguments.
52
+
Command line arguments starting with `-` or `--` are command options, and others are command arguments.
53
53
If you want to specify a value to an option, follows `"="` and the value after the option, like `foo=123`.
54
54
55
55
All command line arguments after `--` are command arguments, even they starts
56
56
with `-` or `--`.
57
57
58
58
```java
59
-
var args =newString[]{"--foo-bar", "hoge", "--baz=1", "-z=2", "-xyz=3", "fuga"};
60
-
var cliargs =newCliArgs("path/to/app", args);
61
-
var result = cliargs.parse();
62
-
63
-
if (result.exception() ==null) {
64
-
var cmd = result.cmd();
65
-
cmd.getName(); // "app"
66
-
cmd.getArgs(); // ["hoge", "fuga"]
67
-
cmd.hasOpt("foo-bar"); // true
68
-
cmd.hasOpt("baz"); // true
69
-
cmd.hasOpt("x"); // true
70
-
cmd.hasOpt("y"); // true
71
-
cmd.hasOpt("z"); // true
72
-
cmd.getOptArg("foo-bar"); // null
73
-
cmd.getOptArg("baz"); // "1"
74
-
cmd.getOptArg("x"); // null
75
-
cmd.getOptArg("y"); // null
76
-
cmd.getOptArg("z"); // "2"
77
-
cmd.getOptArgs("foo-bar"); // []
78
-
cmd.getOptArgs("baz"); // [1]
79
-
cmd.getOptArgs("x"); // []
80
-
cmd.getOptArgs("y"); // []
81
-
cmd.getOptArgs("z"); // ["2", "3"]
82
-
}
83
-
```
84
-
85
-
Or
86
-
87
-
```java
88
-
var args =newString[]{"--foo-bar", "hoge", "--baz", "1", "-z=2", "-xyz=3", "fuga"};
89
-
var cliargs =newCliArgs("path/to/app", args);
59
+
var osArgs =newString[]{"--foo-bar", "hoge", "--baz=1", "-z=2", "-xyz=3", "fuga"};
60
+
var cmd =newCmd("path/to/app", osArgs);
90
61
try {
91
-
var cmd = cliargs.parse().cmdOrThrow();
92
-
cmd.getName(); // "app"
93
-
cmd.getArgs(); // ["hoge", "fuga"]
94
-
cmd.hasOpt("foo-bar"); // true
95
-
// ...
96
-
97
-
} catch (ReasonedException e) {
62
+
cmd.parse();
63
+
} catch (InvalidOption e) {
98
64
...
99
65
}
100
-
```
101
66
67
+
cmd.name(); // "app"
68
+
cmd.args(); // ["hoge", "fuga"]
69
+
cmd.hasOpt("foo-bar"); // true
70
+
cmd.hasOpt("baz"); // true
71
+
cmd.hasOpt("x"); // true
72
+
cmd.hasOpt("y"); // true
73
+
cmd.hasOpt("z"); // true
74
+
cmd.optArg("foo-bar"); // null
75
+
cmd.optArg("baz"); // "1"
76
+
cmd.optArg("x"); // null
77
+
cmd.optArg("y"); // null
78
+
cmd.optArg("z"); // "2"
79
+
cmd.optArgs("foo-bar"); // []
80
+
cmd.optArgs("baz"); // [1]
81
+
cmd.optArgs("x"); // []
82
+
cmd.optArgs("y"); // []
83
+
cmd.optArgs("z"); // ["2", "3"]
84
+
```
102
85
103
86
### Parse with configurations
104
87
105
-
This library provides the method `CliArgs#parseWith` which parses command line arguments with configurations.
106
-
This method takes an array of option configurations: `OptCfg[]`as the argument, and divides command line arguments to options and command arguments with this configurations.
88
+
This library provides the method `Cmd#parseWith` which parses command line arguments with option configurations.
89
+
This method takes an `OptCfg` array as the argument, and divides command line arguments to command options and command arguments with this configurations.
107
90
108
-
And option cnfiguration has fields: `storeKey`, `names`, `hasArg`, `isArray`, `type`, `defaults`, `decc`, `argInHelp`, `converter`, and `postparser`.
91
+
And option configuration has fields: `storeKey`, `names`, `hasArg`, `isArray`, `type`, `defaults`, `desc`, `argInHelp`, and `validator`.
109
92
110
-
`storeKey` field is specified the key name to store the option value in the option map.
93
+
`storeKey` field is to specify the key name to store the option value in the option map.
111
94
If this field is not specified the first element of `names` field is set instead.
112
95
113
-
`names` field is a string array and specified the option names, that are both long options and short options.
96
+
`names` field is a string array and is to specify the option names, that are long options or short options.
114
97
The order of elements in this field is used in a help text.
115
98
If you want to prioritize the output of short option name first in the help text, like `-f, --foo-bar`, but use the long option name as the key in the option map, write `storekey` and `names` fields as follows:
116
99
`OptCfg(field("foo-bar", names("f", "foo-bar"))`.
117
100
118
-
`hasArg` field indicates the option requires one or more values.
119
-
120
-
`isArray` field indicates the option can have multiple values.
101
+
`hasArg` field is to specify the option requires one or more values.
121
102
122
-
`types` field is set the data type of the option value(s).
103
+
`isArray` field is to specify the option can have multiple values.
123
104
124
-
`defaults` field is an array which is used as default one or more values if the
105
+
`defaults` field is to specify an array which is used as default one or more values if the
125
106
option is not specified in command line arguments.
126
107
127
-
`desc` field is a description of the option for help text.
128
-
129
-
`argInHelp` field is a text which is output after option name and aliases as an option value in help text.
108
+
`desc` field is to specify a description of the option for help text.
130
109
131
-
`converter` field is a functional interface which converts an option argument string to the instance of the class specified by `type` field.
110
+
`argInHelp` field is to specify a text which is output after option name and aliases as an option value in help text.
132
111
133
-
`postparser` field is a functional interface which processes option argument(s) after parsing if this field is specified.
112
+
`validator` field is to specify an instance of a functional interface which validates an option argument string as a value of the desired type.
This library provides `Help` class which generates help text from an `OptCfg` array.
160
+
This library provides `Help` class which generates a help text from an `OptCfg` array.
180
161
The following help text is generated from the above `optCfgs`.
181
162
182
163
```java
183
164
var help =newHelp();
184
165
help.addText("This is the usage description.");
185
-
help.addOpts(optCfgs, 0, 2);
166
+
help.addOptsWithMargins(optCfgs, 2, 0);
186
167
help.print();
187
168
188
169
// (stdout)
@@ -193,8 +174,9 @@ The following help text is generated from the above `optCfgs`.
193
174
194
175
### Parse for an option store with `@Opt` annoatation
195
176
196
-
This library provides the method `CliArgs#parseFor` which takes an option store object as the argument, and puts option values by parsing command line arguments to it.
197
-
The `@Opt` annotations are needed for the fields of the option store.
177
+
This library provides the method `Cmd#parseFor` which takes an option store object as the argument, and puts option values by parsing command line arguments to it.
178
+
The `@Opt` annotations can be attached to the fields of the option store for their option
179
+
configurations.
198
180
199
181
This `@Opt` annotations can have the attributes: `cfg`, `desc`, and `arg`.
200
182
`cfg` can be specified the option name, aliases and default value(s).
@@ -209,11 +191,11 @@ The format of the `cfg` attribute is as follows:
209
191
```
210
192
211
193
`desc` is what to specify a option description.
212
-
And `arg` is what to specify a text for an option argument value in help text.
194
+
And `arg` is what to specify a text for an option argument value in a help text.
@@ -300,34 +286,31 @@ The following help text is generated from the above optCfgs.
300
286
301
287
### Parse command line arguments including sub commands
302
288
303
-
This library provides the static method `CliArgs.findFirstArg` which returns the index of the first command argument.
304
-
If this index is negative, there is no command argument.
305
-
This static method enables to parse command line arguments with supporting sub
306
-
command, as follows:
289
+
This library provides the methods `Cmd#parseUntilSubCmd`, `Cmd#parseUntilSubCmdWith`, `Cmd#parseUntilSubCmdFor` that parses command line arguments until a sub command is found.
290
+
The return of those methods is an `Optional<Cmd>` object.
291
+
If no sub command is found, the returned object is empty.
307
292
308
293
```java
309
-
var args =newString[]{"--foo-bar", "hoge", "--baz", "1", "-z=2", "-x", "abcd"};
310
-
int index =CliArgs.findFirstArg(args); // index => 1
311
-
if (index <0) throws ...; // no sub command
294
+
var osArgs =newString[]{"--foo-bar", "hoge", "--baz", "1", "-z=2", "-x", "abcd"};
312
295
313
-
var topArgs =Arrays.copyOf(args, index);
314
-
var subArgs =Arrays.copyOfRange(args, index +1, args.length);
296
+
var cmd =newCmd("path/to/app", osArgs);
315
297
316
-
var cliargs =newCliArgs("app", topArgs);
317
-
var result = cliargs.parseFor(topOptions);
318
-
var topOptCfgs = result.optCfgs();
319
-
var topCmd = result.cmdOrThrow();
298
+
var optional = cmd.parseUntilSubCmdWith(topOptCfgs);
299
+
300
+
if (optional.isEmpty()) {
301
+
...// no sub command
302
+
}
303
+
var subCmd = optional.get();
320
304
321
-
cliargs =newCliArgs(args.get(index), subArgs);
322
-
switch (args.get(index)) {
305
+
switch subCmd.name() {
323
306
case"hoge":
324
-
result = cliargs.parseFor(hogeOptions);
325
-
var hogeOptCfgs = result.optCfgs();
326
-
var hogeCmd = result.cmdOrThrow();
307
+
subCmd.parseWith(hogeOptCfgs);
327
308
...
328
309
break;
329
310
case"fuga":
311
+
subCmd.parseWith(fugaOptCfgs);
330
312
...
313
+
break;
331
314
}
332
315
```
333
316
@@ -337,12 +320,12 @@ And the help text can be generated as follows:
337
320
var help =newHelp();
338
321
help.addText("This is the usage of this command.");
@@ -365,7 +348,7 @@ And the help text can be generated as follows:
365
348
## Native build
366
349
367
350
This library supports native build with GraalVM.
368
-
However, since it utilizes reflection for the option store object passed to `CliArgs#parseFor`, the reflection configurations for the classof this object need to be specified in `reflect-config.json`. The configuration are as follows:
351
+
However, since it utilizes reflection for the option store object passed to `Cmd#parseFor`, the reflection configurations for the class of this object need to be specified in `reflect-config.json`. The configuration are as follows:
369
352
370
353
```json
371
354
[
@@ -391,8 +374,9 @@ This framework supports JDK 21 or later.
0 commit comments