1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
|
# com.zwitserloot.cmdreader
## How to use
First, create a class to represent your command line options. Create one field for each command line option you want, then use the annotations of the `com.zwitserloot.cmdreader` package on the field to configure that option. Then, create a `CmdReader` instance and use it to parse a command line into an instance of your class. You can also use a `CmdReader` instance to generate comprehensive command line help.
For the full manual, you should visit the javadoc, which you can build yourself with `ant javadoc`, after which it'll be available in `doc/api/index.html`. For a quick intro, check out the example program at the end of this documentation.
### Example program
import com.zwitserloot.cmdreader.*;
public class Test {
static class CmdArgs {
@Shorthand("x")
@Description("Excludes the given file.")
java.util.List<String> exclude;
@Sequential
@Mandatory
@Description("The directory to turn into a compressed archive.")
String compress;
}
public static void main(String[] rawArgs) {
CmdReader<CmdArgs> reader = CmdReader.of(CmdArgs.class);
CmdArgs args;
try {
args = reader.make(rawArgs);
} catch (InvalidCommandLineException e) {
System.err.println(e.getMessage());
System.err.println(reader.generateCommandLineHelp("java Test"));
return;
}
System.err.println("If this was a real program, I would now compress " + args.compress);
System.err.println("And I'd be excluding: " + args.exclude);
}
}
### All annotation options
#### @Description
Describes this option. This description is used by `CmdReader.generateCommandLineHelp` to generate the command line help message, and nowhere else.
#### @FullName
By default an option's full name is equal to its field name. If you want to override this, for example because you'd like your option to include a dash
which is not a legal java identifier character, you can do so here. Any option can be accessed using the "--fullname(=value)" syntax, and full names are also used
to refer to other options.
#### @Shorthand
A shorthand is a single character which can be used as a short alternative. For example:
@Shorthand("h") boolean help;
Can be set to true either via `--help` or via `-h`. You can include more than one shorthand character if you want.
Note that multiple shorthands can be chained together if they are booleans, i.e. if 'x' and 'y' are booleans, and 'b' is a String::
java -jar yourapp.jar -xyb valueForB
#### @Excludes
Tells CmdReader that this option cannot co-exist with the listed other options. For example:
String foo;
@Excludes("foo") boolean bar;
Means that an error will be generated when the user attempts to pass `--foo Hello --bar` on the command line.
Multiple options can be listed in one `@Excludes`.
#### @ExcludesGroup
List any number of unique group names as parameter to the `@ExcludesGroup` method. Any command line that lists more than one option that both share
an excludes group is treated as an invalid command line. This is useful if you have a number of 'modes' which are all mutually exclusive. For example, a
backup or unzip tool can various mutually exclusive modes:
@Shorthand("c") @ExcludesGroup("mode") boolean createArchive;
@Shorthand("x") @ExcludesGroup("mode") boolean extractArchive;
@Shorthand("v") @ExcludesGroup("mode") boolean verifyArchive;
#### @Mandatory
Used to indicate an option is required. Optionally you can include the `onlyIf` or `onlyIfNot` parameter, listing any number of other options, to fine-tune
when this option is mandatory and when it isn't. `@Mandatory` on a field with a collection type implies at least one such option must be present.
#### @Sequential
Used to indicate that this option is the 'default' and that no switch is required on the command line for it. For example, if your command line tool works on one
file, then you can allow your app to be invoked as `java -jar yourapp.jar filename` if you add this annotation:
@Mandatory @Sequential String fileName;
Multiple sequential arguments are allowed; exactly one such argument may be a collection type, and it does not have to be the last one. Example for a copy program:
@Mandatory @Sequential(1) List<String> from;
@Mandatory @Sequential(2) String to;
#### @Requires
Used to indicate that if this option is present, the listed option must also be present. Like `@Mandatory` but this one is put on the other option.
## How to compile / develop
run:
ant
and that's that. All dependencies will be downloaded automatically. The jar file you need will be in the `dist` directory. If you want to work on the code, run 'ant eclipse' or 'ant intellij' to set up the project dir as an eclipse or intellij project.
|
