1 /*
2 * This file is part of hyphenType. hyphenType is free software: you can
3 * redistribute it and/or modify it under the terms of the GNU General Public
4 * License as published by the Free Software Foundation, either version 3 of the
5 * License, or (at your option) any later version. hyphenType is distributed in
6 * the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the
7 * implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See
8 * the GNU General Public License for more details. You should have received a
9 * copy of the GNU General Public License along with hyphenType. If not, see
10 * <http://www.gnu.org/licenses/>.
11 */
12 package org.hyphenType.datastructure.annotations;
13
14 import java.lang.annotation.Annotation;
15 import java.lang.annotation.ElementType;
16 import java.lang.annotation.Retention;
17 import java.lang.annotation.RetentionPolicy;
18 import java.lang.annotation.Target;
19
20 import org.hyphenType.documentation.lib.StandardFormatterEngine.StandardFormatter;
21 import org.hyphenType.exit.CanonicalExitCode;
22 import org.hyphenType.exit.StatusCode;
23
24 /**
25 * @author Aurelio Akira M. Matsui
26 */
27 @Retention(RetentionPolicy.RUNTIME)
28 @Target(ElementType.TYPE)
29 public @interface ArgumentsObject {
30
31 /**
32 * Default encoding for the resource bundles.
33 */
34 String DEFAULT_RB_ENCODING = "UTF-8";
35 /**
36 * Default single hyphen.
37 */
38 String DEFAULT_SINGLE_HYPHEN = "-";
39 /**
40 * Default double hyphen.
41 */
42 String DEFAULT_DOUBLE_HYPHEN = "--";
43 /**
44 * Default equals string.
45 */
46 String DEFAULT_EQUALS = "=";
47
48 /**
49 * The path to find the resource bundles containing the documentation. If
50 * this property is empty, will search for the resource bundles in the same
51 * package as the arguments object interface is. Paths are directly
52 * forwarded to {@link ResourceBundle#getBundle(String)}, and therefore,
53 * should be fully qualified names pointing to a set of property files. This
54 * property is useful when the same set of resource bundles are shared
55 * between several classes.<br>
56 * <br>
57 * If the value of this property is the empty string (the default value),
58 * the fully qualified name of the options interface will be used instead.
59 * In other words, if the options interface is <code>a.b.C</code>, and if
60 * this property is an empty string, then files such as
61 * <code>a.b.C.properties</code>, <code>a.b.C_es.properties</code>, etc...
62 * (in other words, the files /a/b/C.properties and /a/b/C_es.properties
63 * where / is the root of the JAR file) will be used.<br>
64 * <br>
65 * See {@link ResourceBundle#getBundle(String baseName, Locale locale, ClassLoader loader)}
66 * for more information.
67 *
68 * @see ResourceBundle#getBundle(String baseName, Locale locale, ClassLoader
69 * loader)
70 */
71 String resourceBundlesLocation() default "";
72
73 /**
74 * Configures which encoding will be used to read resource bundle files.
75 */
76 String resourceBundlesEncoding() default DEFAULT_RB_ENCODING;
77
78 /**
79 * Documentation of the options interface. This documentation is overridden
80 * by data from resource bundles, if present.
81 */
82 String description() default "";
83
84 /**
85 * Whether long options (those with more than one character) will
86 * automatically receive two hyphens.
87 */
88 boolean doubleHyphenInLongOptions() default true;
89
90 /**
91 * The string that will be used as the single hyphen. A single hyphen is the
92 * prefix for single character options. A single hyphen is used not only to
93 * mark the start of an option whose name is a single character (e.g.: "-n"
94 * for an option named "n"), but also to start a cluster of single character
95 * options (e.g.: "-xcvf" which is short for "-x -c -v -f").
96 */
97 String singleHyphen() default DEFAULT_SINGLE_HYPHEN;
98
99 /**
100 *
101 */
102 String doubleHyphen() default DEFAULT_DOUBLE_HYPHEN;
103
104 /**
105 * The string that will be used as the equals sign. In other words, the
106 * symbol that will be used to separate keys from values.
107 */
108 String equals() default DEFAULT_EQUALS;
109
110 /**
111 * The class that will format the documentation. The formatter class will
112 * be used when the following methods are called:
113 * <ul>
114 * <li>{@link Options#printDocumentation()}</li>
115 * <li>{@link Options#printDocumentation(java.io.PrintStream)}</li>
116 * </ul>
117 * Which are mapped by {@link ArgumentsInvocationHandler} to these methods:
118 * <ul>
119 * <li>{@link DocumentationFormatterEngine#printDocumentation()}</li>
120 * <li>
121 * {@link DocumentationFormatterEngine#printDocumentation(java.io.PrintStream)}
122 * </li>
123 * </ul>
124 */
125 Class<? extends Annotation> preferredDocumentationFormatter() default StandardFormatter.class;
126
127 /**
128 * The status code enumeration for this arguments object.
129 */
130 Class<? extends StatusCode> statusCodeEnum() default CanonicalExitCode.class;
131
132 /**
133 * Sets whether or not calls to {@link Options#printDocumentation()}, or
134 * {@link Options#printDocumentation(java.io.PrintStream)} should generate
135 * documentation for status codes. The standard interpretation for status
136 * codes is that a zero means a successful program termination while any
137 * non-zero number is a unique error code. A caller program or shell could
138 * then read this error code and act accordingly, or show a custom message
139 * to a user.<br>
140 * <br>
141 * Nevertheless, there are cases in which status codes are not important.<br>
142 * <br>
143 * Status codes may be simply ignored by programmers (perhaps because they
144 * simply return zero despite of what happened during program execution).
145 * Finally, status codes may be used to return some numerical value
146 * (although this is considered a violation of the convention). In all these
147 * cases above, the programmer may chose to simply omit information about
148 * status codes from his/her documentation. This flags allows the programmer
149 * to do so, although the actual behavior of this flag will depend upon the
150 * implementation of {@link DocumentationFormatterEngine} in use.
151 *
152 * @see ArgumentsObject#statusCodeEnum()
153 * @see ArgumentsObject#preferredDocumentationFormatter()
154 */
155 boolean documentStatusCodes() default false;
156 }