panda.args.Option Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of panda-core Show documentation

Panda Core is the core module of Panda Framework, it contains commonly used utility classes similar to apache-commons.

There is a newer version: 1.8.0

package panda.args;

import static java.lang.annotation.ElementType.FIELD;
import static java.lang.annotation.ElementType.METHOD;
import static java.lang.annotation.ElementType.PARAMETER;
import static java.lang.annotation.RetentionPolicy.RUNTIME;

import java.lang.annotation.Retention;
import java.lang.annotation.Target;
import java.util.ResourceBundle;

/**
 * Marks a field/setter that receives a command line switch value.
 *  * class Foo {
 * 	@Option(name = 'c')
 * 	public boolean coin;
 * }
 * 
 */
@Retention(RUNTIME)
@Target({ FIELD, METHOD, PARAMETER })
public @interface Option {
	/**
	 * short form option, such as -f.
	 */
	char opt() default ' ';

	/**
	 * long form option, such as --long-option-name.
	 */
	String option() default "";

	/**
	 * Sets the display name for the argument value.
	 *
	 * 	 * -x FOO  : blah blah blah
	 * 
	 *
	 * You can replace the FOO token by using this parameter.
	 * 
	 * If unspecified, means this is a FLAG without VALUE.
	 */
	String arg() default "";

	/**
	 * Help string used to display the usage screen.
	 * 

	 * This parameter works in two ways. For a simple use, you can just encode the human-readable
	 * help string directly, and that will be used as the message. This is easier, but it doesn't
	 * support localization.
	 * 

	 * For more advanced use, this property is set to a key of a {@link ResourceBundle}. The actual
	 * message is obtained by querying a {@link ResourceBundle} instance supplied to
	 * {@link CmdLineParser} by this key. This allows the usage screen to be properly localized.
	 * 

	 * If this value is empty, the option will not be displayed in the usage screen.
	 */
	String usage() default "";

	/**
	 * Specify that the option is mandatory. a {@link CmdLineException} will
	 * be thrown if a required option is not present.
	 * 

	 * Note that in most of the command line interface design principles, options should be really
	 * optional. So use caution when using this flag.
	 */
	boolean required() default false;

	/**
	 * Specify that the option is hidden from the usage, by default.
	 */
	boolean hidden() default false;

	/**
	 * List of other options that this option depends on.
	 * 
Example
	 *
	 * 	 * @Option(name = "-a")
	 * int a;
	 * // -b is not required but if it's provided, then a becomes required
	 * @Option(name = "-b", depends = { "-a" })
	 * int b;
	 * 
	 * 
	 * A {@link CmdLineException} will be thrown if options required by another one are not present.
	 * 
	 */
//TODO:	String[] depends() default {};

	/**
	 * List of other options that this option is incompatible with..
	 * Example
	 *
	 * 	 * @Option(name = "-a")
	 * int a;
	 * // -h and -a cannot be specified together
	 * @Option(name = "-h", forbids = { "-a" })
	 * boolean h;
	 * 
	 * 
	 * A {@link CmdLineException} will be thrown if forbidden option combinations are present.
	 * 
	 */
//TODO:	String[] forbids() default {};
}