1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121

package Torello.Java;

/**
 * A Java {@code 'enum'} that is used in several locations in the {@code Java-HTML JAR} Library
 * to allow an end-user to request the quantity of text being produced by a tool or application.
 * The {@link Verbose} flag / constant is designed to request the maximum amount of information
 * when running a tool, while the {@link Silent} constant may be used to ask that no textual
 * output be sent to Standard-Output
 *
 * <BR /><BR />Primarily for convenience and ease-of-use, each of the four constants in this
 * {@code enum} are assigned an integer depicting the verbosity.  When deciding whether or not
 * to print a message to the user using this {@code enum}, using the {@link #level} integer is
 * usually a more exedient coding-solution.
 *
 * <BR /><BR >The following example should help elucidate using the {@link #level} field.  Note
 * that in this particular example, the settings for {@link #Quiet} and for {@link #Silent} are
 * simply not being used.  In this example, keep in mind that the programmer may simply include
 * a message for the {@link #Quiet} setting someplace else in the code, entirely!
 * 
 * <DIV CLASS=EXAMPLE>{@code
 * // This is an extremely verbose way of coding!
 * switch (verbosity)
 * {
 *      case Silent:    
 *      case Quiet:     break;
 *      case Normal:
 *      case Verbose:   System.out.println("Starting New Program Section");
 * }
 *
 * // From a programming-analysis perspective alone, this is a lot more succint
 * if (verbosity.level >= 2) System.out.println("Starting New Program Section");
 * }</DIV>
 */
public enum Verbosity
{
    /**
     * Indicates a user-request that an application or program should not produce any output, other
     * than error-output.  In the <B>{@code Java-HTML JAR}</B> Library, error output is rarely
     * abbreviated or eliminated.
     *
     * <BR /><BR />This constant is assigned "Level 0", and the {@link #level} constant-field will
     * always be zero.
     */
    Silent(0),

    /**
     * Indicates a user-request for an application or program to run producing the minimum amount
     * of text-output possible.  Error output may (or may not) be shunted, as per the capricious
     * whims of the software guys.
     *
     * <BR /><BR />This constant is assigned "Level 1", and the {@link #level} constant-field will
     * always be one.
     */
    Quiet(1),

    /**
     * The {@code enum}-constant should be used to indicate that the default output-text be sent to
     * Standard-Output and Error-Output.
     *
     * <BR /><BR />This constant is assigned "Level 2", and the {@link #level} constant-field will
     * always be two.
     */
    Normal(2),

    /**
     * If a programmer can produce additional information about the state of a program as it runs,
     * then the {@code 'Verbose'} constant / flag may be used to indicate a user-request as such.
     *
     * <BR /><BR />This constant is assigned "Level 3", and the {@link #level} constant-field will
     * always be three.
     */
    Verbose(3);

    /**
     * There are quite a number of situations where an integer is easier for doing the comparisons
     * an actual instance of {@code 'Verbosity'}.  Each of the four constants of this {@code enum}
     * have their own, ordered, {@code 'level'} setting (which is a number between {@code '0'} and
     * {@code '3'}).
     */
    public final int level;

    private Verbosity(int level) { this.level = level; }

    /**
     * Retrieves the Enum-Constant associated with the integer parameter {@code 'verbosityLevel'}.
     * 
     * @param verbosityLevel This must be a value between {@code '0'} and {@code '3'}, or an 
     * IllegalArgumentException will throw.
     * 
     * <BR /><BR />This is used to indicate which of the four constants are to be returned by this
     * method.
     * 
     * <BR /><BR /><TABLE CLASS=JDBriefTable>
     * <TR><TH>Constant</TH>            <TH>Integer Level</TH>  </TR>
     * <TR><TD>{@link #Silent}</TD>     <TD>{@code 0}</TD>      </TR>
     * <TR><TD>{@link #Quiet}</TD>      <TD>{@code 1}</TD>      </TR>
     * <TR><TD>{@link #Normal}</TD>     <TD>{@code 2}</TD>      </TR>
     * <TR><TD>{@link #Verbose}</TD>    <TD>{@code 3}</TD>      </TR>
     * </TABLE>
     * 
     * @return The Enum-Constant associated with the input {@code 'verbosityLevel'}
     * 
     * @throws IllegalArgumentException If an integer-value other than the above four possible
     * values is provided as input.
     */
    public static Verbosity get(int verbosityLevel)
    {
        if ((verbosityLevel < 0) || (verbosityLevel > 3)) throw new IllegalArgumentException
            ("verbosityLevel=" + verbosityLevel + ", but this value must be between 0 and 3.");

        switch (verbosityLevel)
        {
            case 0: return Silent;
            case 1: return Quiet;
            case 2: return Normal;
            case 3: return Verbose;

            default: throw new UnreachableError();
        }
    }
}