1 package org.kohsuke.args4j;
2
3 import org.kohsuke.args4j.spi.OptionHandler;
4
5 import java.io.File;
6 import java.lang.annotation.Retention;
7 import java.lang.annotation.Target;
8 import java.lang.reflect.AccessibleObject;
9 import java.util.ResourceBundle;
10
11 import static java.lang.annotation.ElementType.FIELD;
12 import static java.lang.annotation.ElementType.METHOD;
13 import static java.lang.annotation.RetentionPolicy.RUNTIME;
14
15 /***
16 * Marks a field/setter that receives a command line switch value.
17 *
18 * <p>
19 * This annotation can be placed on a field of type T or the method
20 * of the form <tt>void <i>methodName</i>(T value)</tt>. Its access
21 * modified can be anything, but if it's not public, your application
22 * needs to run in a security context that allows args4j to access
23 * the field/method (see {@link AccessibleObject#setAccessible(boolean)}.
24 *
25 * <p>
26 * The behavior of the annotation differs depending on T --- the type
27 * of the field or the parameter of the method.
28 *
29 * <h2>Boolean Switch</h2>
30 * <p>
31 * When T is boolean , it represents
32 * a boolean option that takes the form of "-OPT". When this option is set,
33 * the property will be set to true.
34 *
35 * <h2>String Switch</h2>
36 * <p>
37 * When T is {@link String}, it represents
38 * an option that takes one operand. The value of the operand is set
39 * to the property.
40 *
41 * <h2>Enum Switch</h2>
42 * <p>
43 * When T is derived from {@link Enum}, it represents an option that takes
44 * an operand, which must be one of the enum constant. The comparion between
45 * the operand and the enum constant name is done in a case insensitive fashion.
46 * <p>
47 * For example, the following definition will represent command line options
48 * like "-coin penny" or "-coin DIME" but things like "-coin" or "-coin abc" are
49 * errors.
50 *
51 * <pre>
52 * enum Coin { PENNY,NICKEL,DIME,QUARTER }
53 *
54 * class Option {
55 * @Option(name="-coin")
56 * public Coin coin;
57 * }
58 * </pre>
59 *
60 * <h2>File Switch</h2>
61 * <p>
62 * When T is a {@link File}, it represents an option that takes a file/directory
63 * name as an operand.
64 *
65 * @author Kohsuke Kawaguchi
66 */
67 @Retention(RUNTIME)
68 @Target({FIELD,METHOD})
69 public @interface Option {
70 /***
71 * Name of the option, such as "-foo" or "-bar".
72 */
73 String name();
74
75 /***
76 * Help string used to display the usage screen.
77 *
78 * <p>
79 * This parameter works in two ways. For a simple use,
80 * you can just encode the human-readable help string directly,
81 * and that will be used as the message. This is easier,
82 * but it doesn't support localization.
83 *
84 * <p>
85 * For more advanced use, this property is set to a key of a
86 * {@link ResourceBundle}. The actual message is obtained
87 * by querying a {@link ResourceBundle} instance supplied to
88 * {@link CmdLineParser} by this key. This allows the usage
89 * screen to be properly localized.
90 *
91 * <p>
92 * If this value is empty, the option will not be displayed
93 * in the usage screen.
94 */
95 String usage() default "";
96
97 /***
98 * When the option takes an operand, the usage screen will show something like this:
99 * <pre>
100 * -x FOO : blah blah blah
101 * </pre>
102 * You can replace the 'FOO' token by using this parameter.
103 *
104 * <p>
105 * If left unspecifiied, this value is infered from the type of the option.
106 *
107 * <p>
108 * Just like {@link #usage()}, normally, this value is printed as is.
109 * But if a {@link ResourceBundle} is given to the {@link CmdLineParser},
110 * it will be used to obtain the locale-specific value.
111 */
112 String metaVar() default "";
113
114 /***
115 * Specify that the option is mandatory.
116 *
117 * <p>
118 * At the end of {@link CmdLineParser#parseArgument(String...)},
119 * a {@link CmdLineException} will be thrown if a required option
120 * is not present.
121 *
122 * <p>
123 * Note that in most of the command line interface design principles,
124 * options should be really optional. So use caution when using this
125 * flag.
126 */
127 boolean required() default false;
128
129 /***
130 * Specify the {@link OptionHandler} that processes the command line arguments.
131 *
132 * <p>
133 * The default value {@link OptionHandler} indicates that
134 * the {@link OptionHandler} will be infered from
135 * the type of the field/method where a {@link Option} annotation
136 * is placed.
137 *
138 * <p>
139 * If this annotation element is used, it overrides the inference
140 * and determines the handler to be used. This is convenient for
141 * defining a non-standard option parsing semantics.
142 *
143 * <h3>Example</h3>
144 * <pre>
145 * // this is a normal "-r" option
146 * @Option(name="-r")
147 * boolean value;
148 *
149 * // this causes arg4j to use MyHandler, not the default
150 * // handler provided for boolean
151 * @Option(name="-b",handler=MyHandler.class)
152 * boolean value;
153 * </pre>
154 */
155 Class<? extends OptionHandler> handler() default OptionHandler.class;
156 }