1 /*
2 * Copyright 2014 Theo Willows
3 *
4 * This file is part of JArgP.
5 *
6 * JArgP is free software: you can redistribute it and/or modify it under the
7 * terms of the GNU Lesser General Public License as published by the Free
8 * Software Foundation, either version 3 of the License, or (at your option) any
9 * later version.
10 *
11 * JArgP is distributed in the hope that it will be useful, but WITHOUT ANY
12 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
13 * A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
14 * details.
15 *
16 * You should have received a copy of the GNU Lesser General Public License
17 * along with JArgP. If not, see <http://www.gnu.org/licenses/>.
18 */
19
20 package com.munkei;
21
22 import com.munkei.exception.ArgumentParsingException;
23 import java.lang.annotation.ElementType;
24 import java.lang.annotation.Retention;
25 import java.lang.annotation.RetentionPolicy;
26 import java.lang.annotation.Target;
27
28 /**
29 * An annotation to use for command line options.
30 * <p>
31 * All elements are optional. Thus the simplest usage is:
32 * <pre>
33 * {@literal @}CommandLineOption<br/>
34 * private Boolean verbose;
35 * </pre> The above will match the option
36 * <code>--verbose</code> when parsing
37 * ({@link JArgP#parse(java.lang.String[])}), and if it is present, the field
38 * <code>verbose</code> (of the "subject", see
39 * {@link JArgP#JArgP(java.lang.Object)}) will be set to
40 * <code>true</code>.
41 * <p>
42 * If you want the command line option to use the next argument as a value for a
43 * field, make the field something other than a {@link Boolean}. Values are
44 * converted in {@link Option#convert(java.lang.String, java.lang.Class)}, see
45 * its documentation for details.
46 * <p>
47 * To configure the specifics of the command line option and how it is parsed,
48 * see each element:
49 * <ul>
50 * <li>To specify which command line options match a field, see {@link #names()}
51 * and {@link #pattern()}.</li>
52 * <li>To specify how the documentation for the field is printed
53 * ({@link JArgP#printUsage(java.io.PrintStream)}), see
54 * {@link #placeholder()}, {@link #description()}, {@link #defaultValue()} and
55 * {@link #defaultValue()}.</li>
56 * </ul>
57 *
58 * @see JArgP
59 *
60 * @author Theo 'Biffen' Willows <theo@willows.se>
61 *
62 * @since 0.0.1
63 */
64 @Retention(RetentionPolicy.RUNTIME)
65 @Target(ElementType.FIELD)
66 public @interface CommandLineOption {
67
68 /**
69 * The names of the option. These names will be accepted as options when
70 * parsing.
71 * <p>
72 * If no names are specified (and no {@link #pattern()} is specified), the
73 * name of the field itself is used.
74 * <p>
75 * Single character names will be short options (
76 * <code>-[...]</code>), others will be long options (
77 * <code>--[...]</code>), with the exception of
78 * <code>-</code>, which will be just that.
79 *
80 * @see #pattern()
81 */
82 String[] names() default {};
83
84 /**
85 * Specifies a method to set the value. Must take either two {@link String}
86 * parameters, where the first one is the name and the second one is the
87 * value:
88 * <pre><setter>({@link String} name, {@link String} value)</pre> or a
89 * single {@link String} parameter that is the value:
90 * <pre><setter>({@link String} value)</pre>
91 * <p>
92 * For multiples ({@link java.util.Collection}s) it is assumed the setter
93 * appends a single value.
94 * <p>
95 * One reason to use a setter would be to do some kind of validation of the
96 * value. You <em>may</em> throw an exception in the setter if the value is
97 * considered invalid. E.g. an {@link ArgumentParsingException}, but any type
98 * can be used, just make sure to catch it wherever you call
99 * {@link JArgP#parse(java.lang.String[])}.
100 * <p>
101 * If not used, members will be set directly.
102 */
103 String setter() default "";
104
105 /**
106 * For complex names match this pattern. Patterns will be matched
107 * <em>after</em> names and aliases.
108 * <p>
109 * E.g:
110 * <code>[0-9]+</code> for options like
111 * <code>-1</code>,
112 * <code>-2</code>, etc.
113 *
114 * @see #shortPattern()
115 *
116 * @see #names()
117 */
118 String pattern() default "";
119
120 /**
121 * For complex names match this pattern. <code>shortPattern</code>s are matched against short options (<code>--[...]</code>). Patterns will be matched
122 * <em>after</em> names and aliases.
123 * <p>
124 * E.g:
125 * <code>[0-9]+</code> for options like
126 * <code>-1</code>,
127 * <code>-2</code>, etc.
128 *
129 * @see #pattern()
130 */
131 String shortPattern() default "";
132
133 /**
134 * Creates a
135 * <code>--no-[...]</code> alias that sets it to
136 * <code>false</code>.
137 * <p>
138 * <em>Switches only.</em>
139 */
140 boolean opposite() default false;
141
142 /**
143 * Text to use as a placeholder when printing the usage.
144 * <p>
145 * E.g. for an option called
146 * <code>file</code> one might set the placeholder to "FILE", to get a usage
147 * like:
148 * <pre>--file FILE</pre>
149 * <p>
150 * The default is "VALUE".
151 * <p>
152 * <em>Only used for options that take a value, i.e. not
153 * {@link Boolean}s.</em>
154 *
155 * @see JArgP#printUsage(java.io.PrintStream)
156 */
157 String placeholder() default "VALUE";
158
159 /**
160 * A description of the option to use for the usage text.
161 *
162 * @see JArgP#printUsage(java.io.PrintStream)
163 */
164 String description() default "";
165
166 /**
167 * A default value. Will be documented in the usage text. Will be set by
168 * {@link JArgP#parse(java.lang.String[])} to any member that has not been set
169 * by the arguments.
170 *
171 * @see JArgP#printUsage(java.io.PrintStream)
172 */
173 String defaultValue() default "";
174
175 }