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;
13
14 import java.io.PrintStream;
15 import java.lang.annotation.Annotation;
16 import java.text.MessageFormat;
17 import java.util.List;
18
19 import org.hyphenType.datastructure.annotations.ArgumentsObject;
20 import org.hyphenType.datastructure.lexer.LexToken;
21 import org.hyphenType.exit.ExitStatusHelper;
22 import org.hyphenType.exit.StatusCode;
23
24 /**
25 * Interface that should be extended by
26 * all options interfaces.
27 *
28 * @author Aurelio Akira M. Matsui
29 * @param <T> The enumeration for status codes
30 */
31 public interface Options<T extends Enum<?> & StatusCode> {
32
33 /**
34 * Prints the documentation using the preferred documentation formatter
35 * to the standard {@link System#out}. Note: if not explicitly set,
36 * the preferred formatter is the one defined as the default value of
37 * the {@link ArgumentsObject#preferredDocumentationFormatter()}
38 * property.
39 */
40 void printDocumentation();
41
42 /**
43 * Prints the documentation using the preferred documentation formatter.
44 * Note: if not explicitly set, the preferred formatter is the one
45 * defined as the default value of the
46 * {@link ArgumentsObject#preferredDocumentationFormatter()} property.
47 *
48 * @param pw
49 */
50 void printDocumentation(PrintStream pw);
51
52 /**
53 * Prints the documentation using the given documentation formatter
54 * to the standard {@link System#out}. Uses the given documentation
55 * formatter.
56 *
57 * TODO What happens if we try to load the annotation from the resource bundles but the annotation is not complete?
58 *
59 * @param formatterClass
60 */
61 void printDocumentation(Class<? extends Annotation> formatterClass);
62
63 /**
64 * Prints the documentation using the given documentation formatter.
65 * Uses the given {@link PrintStream} instead of {@link System#out}.
66 *
67 * TODO What happens if we try to load the annotation from the resource bundles but the annotation is not complete?
68 *
69 * @param formatterClass
70 * @param pw
71 */
72 void printDocumentation(Class<? extends Annotation> formatterClass, PrintStream pw);
73
74 /**
75 * All the arguments that were ignored by the parsing process.
76 *
77 * @return
78 */
79 List<LexToken> unparsedArguments();
80
81 /**
82 * Terminates the JVM or other current environment
83 *
84 * @param status The status code to terminate the JVM
85 * @param arguments The arguments that will be passed to {@link StatusCode#beforeExit()}.
86 */
87 void exit(T status, Object... arguments);
88
89 /**
90 * Terminates the JVM or other current environment
91 *
92 * @param code The status code to terminate the JVM
93 * @param arguments The arguments that will be passed to {@link StatusCode#beforeExit()}.
94 */
95 void exit(int code, Object... args);
96
97 /**
98 * Terminates the JVM or other current environment. This method searches for one exit
99 * status (enumeration constant) that receives the given throwable.
100 *
101 * @param throwable The throwable object that will be carried to the {@link ExitStatusHelper}.
102 * @return True if the throwable could be visited by any enumeration constant.
103 */
104 boolean exit(Throwable throwable);
105
106 /**
107 * Retrieves the array of arguments as they were received
108 * from the user.
109 *
110 * @return The raw array of arguments.
111 */
112 String[] rawArguments();
113
114 /**
115 * Gets a message from the resource bundle of the current locale.
116 * This method is merely a convenience to allow for users to
117 * easily access extra messages inside of the resource bundles
118 * of hyphenType.
119 *
120 * @param key The key to search for.
121 * @return The message related to the key.
122 */
123 String localeMessage(String key);
124
125 /**
126 * Gets a message from the resource bundle of the current locale.
127 * This method is merely a convenience to allow for users to
128 * easily access extra messages inside of the resource bundles
129 * of hyphenType.
130 *
131 * @param key The key to search for.
132 * @param defaultValue The default value, in case the key was not found.
133 * @return The message related to the key.
134 */
135 String localeMessage(String key, String defaultValue);
136
137 /**
138 * Equivalent to {@link Options#localeMessage(String)}, but
139 * wraps a procedure that allows for replacement of variables
140 * within the messages. This procedure uses a {@link MessageFormat}
141 * to replace variables.
142 *
143 * @see MessageFormat
144 * @param key The key to search for.
145 * @param values The values to replace each variable.
146 * @return The message related to the key and formatted according to the values.
147 */
148 String formattedLocaleMessage(String key, Object... values);
149
150 /**
151 * Equivalent to {@link Options#localeMessage(String)}, but
152 * wraps a procedure that allows for replacement of variables
153 * within the messages. This procedure uses a {@link MessageFormat}
154 * to replace variables.
155 *
156 * @see MessageFormat
157 * @param key The key to search for.
158 * @param defaultValue The default value, in case the key was not found.
159 * @param values The values to replace each variable.
160 * @return The message related to the key and formatted according to the values.
161 */
162 String formattedLocaleMessageDefault(String key, String defaultValue, Object... values);
163 }