001: package org.kohsuke.args4j;
002:
003: import org.kohsuke.args4j.spi.OptionHandler;
004:
005: import java.io.File;
006: import java.lang.annotation.Retention;
007: import java.lang.annotation.Target;
008: import java.lang.reflect.AccessibleObject;
009: import java.util.ResourceBundle;
010:
011: import static java.lang.annotation.ElementType.FIELD;
012: import static java.lang.annotation.ElementType.METHOD;
013: import static java.lang.annotation.RetentionPolicy.RUNTIME;
014:
015: /**
016: * Marks a field/setter that receives a command line switch value.
017: *
018: * <p>
019: * This annotation can be placed on a field of type T or the method
020: * of the form <tt>void <i>methodName</i>(T value)</tt>. Its access
021: * modified can be anything, but if it's not public, your application
022: * needs to run in a security context that allows args4j to access
023: * the field/method (see {@link AccessibleObject#setAccessible(boolean)}.
024: *
025: * <p>
026: * The behavior of the annotation differs depending on T --- the type
027: * of the field or the parameter of the method.
028: *
029: * <h2>Boolean Switch</h2>
030: * <p>
031: * When T is boolean , it represents
032: * a boolean option that takes the form of "-OPT". When this option is set,
033: * the property will be set to true.
034: *
035: * <h2>String Switch</h2>
036: * <p>
037: * When T is {@link String}, it represents
038: * an option that takes one operand. The value of the operand is set
039: * to the property.
040: *
041: * <h2>Enum Switch</h2>
042: * <p>
043: * When T is derived from {@link Enum}, it represents an option that takes
044: * an operand, which must be one of the enum constant. The comparion between
045: * the operand and the enum constant name is done in a case insensitive fashion.
046: * <p>
047: * For example, the following definition will represent command line options
048: * like "-coin penny" or "-coin DIME" but things like "-coin" or "-coin abc" are
049: * errors.
050: *
051: * <pre>
052: * enum Coin { PENNY,NICKEL,DIME,QUARTER }
053: *
054: * class Option {
055: * @Option(name="-coin")
056: * public Coin coin;
057: * }
058: * </pre>
059: *
060: * <h2>File Switch</h2>
061: * <p>
062: * When T is a {@link File}, it represents an option that takes a file/directory
063: * name as an operand.
064: *
065: * @author Kohsuke Kawaguchi
066: */
067: @Retention(RUNTIME)
068: @Target({FIELD,METHOD})
069: public @interface Option {
070: /**
071: * Name of the option, such as "-foo" or "-bar".
072: */
073: String name();
074:
075: /**
076: * Aliases for the options, such as "--long-option-name".
077: */
078: String[] aliases() default {};
079:
080: /**
081: * Help string used to display the usage screen.
082: *
083: * <p>
084: * This parameter works in two ways. For a simple use,
085: * you can just encode the human-readable help string directly,
086: * and that will be used as the message. This is easier,
087: * but it doesn't support localization.
088: *
089: * <p>
090: * For more advanced use, this property is set to a key of a
091: * {@link ResourceBundle}. The actual message is obtained
092: * by querying a {@link ResourceBundle} instance supplied to
093: * {@link CmdLineParser} by this key. This allows the usage
094: * screen to be properly localized.
095: *
096: * <p>
097: * If this value is empty, the option will not be displayed
098: * in the usage screen.
099: */
100: String usage() default "";
101:
102: /**
103: * When the option takes an operand, the usage screen will show something like this:
104: * <pre>
105: * -x FOO : blah blah blah
106: * </pre>
107: * You can replace the 'FOO' token by using this parameter.
108: *
109: * <p>
110: * If left unspecifiied, this value is infered from the type of the option.
111: *
112: * <p>
113: * Just like {@link #usage()}, normally, this value is printed as is.
114: * But if a {@link ResourceBundle} is given to the {@link CmdLineParser},
115: * it will be used to obtain the locale-specific value.
116: */
117: String metaVar() default "";
118:
119: /**
120: * Specify that the option is mandatory.
121: *
122: * <p>
123: * At the end of {@link CmdLineParser#parseArgument(String...)},
124: * a {@link CmdLineException} will be thrown if a required option
125: * is not present.
126: *
127: * <p>
128: * Note that in most of the command line interface design principles,
129: * options should be really optional. So use caution when using this
130: * flag.
131: */
132: boolean required() default false;
133:
134: /**
135: * Specify the {@link OptionHandler} that processes the command line arguments.
136: *
137: * <p>
138: * The default value {@link OptionHandler} indicates that
139: * the {@link OptionHandler} will be infered from
140: * the type of the field/method where a {@link Option} annotation
141: * is placed.
142: *
143: * <p>
144: * If this annotation element is used, it overrides the inference
145: * and determines the handler to be used. This is convenient for
146: * defining a non-standard option parsing semantics.
147: *
148: * <h3>Example</h3>
149: * <pre>
150: * // this is a normal "-r" option
151: * @Option(name="-r")
152: * boolean value;
153: *
154: * // this causes arg4j to use MyHandler, not the default
155: * // handler provided for boolean
156: * @Option(name="-b",handler=MyHandler.class)
157: * boolean value;
158: * </pre>
159: */
160: Class<? extends OptionHandler> handler() default OptionHandler.class;
161:
162: /**
163: * Whether the option is multi-valued.
164: * For mappings to List<...>, this defaults to true, otherwise false
165: */
166: boolean multiValued() default false;
167: }
|