001package Torello.Java;
002
003/**
004 * A Java {@code 'enum'} that is used in several locations in the {@code Java-HTML JAR} Library
005 * to allow an end-user to request the quantity of text being produced by a tool or application.
006 * The {@link Verbose} flag / constant is designed to request the maximum amount of information
007 * when running a tool, while the {@link Silent} constant may be used to ask that no textual
008 * output be sent to Standard-Output
009 *
010 * <BR /><BR />Primarily for convenience and ease-of-use, each of the four constants in this
011 * {@code enum} are assigned an integer depicting the verbosity.  When deciding whether or not
012 * to print a message to the user using this {@code enum}, using the {@link #level} integer is
013 * usually a more exedient coding-solution.
014 *
015 * <BR /><BR >The following example should help elucidate using the {@link #level} field.  Note
016 * that in this particular example, the settings for {@link #Quiet} and for {@link #Silent} are
017 * simply not being used.  In this example, keep in mind that the programmer may simply include
018 * a message for the {@link #Quiet} setting someplace else in the code, entirely!
019 * 
020 * <DIV CLASS=EXAMPLE>{@code
021 * // This is an extremely verbose way of coding!
022 * switch (verbosity)
023 * {
024 *      case Silent:    
025 *      case Quiet:     break;
026 *      case Normal:
027 *      case Verbose:   System.out.println("Starting New Program Section");
028 * }
029 *
030 * // From a programming-analysis perspective alone, this is a lot more succint
031 * if (verbosity.level >= 2) System.out.println("Starting New Program Section");
032 * }</DIV>
033 */
034public enum Verbosity
035{
036    /**
037     * Indicates a user-request that an application or program should not produce any output, other
038     * than error-output.  In the <B>{@code Java-HTML JAR}</B> Library, error output is rarely
039     * abbreviated or eliminated.
040     *
041     * <BR /><BR />This constant is assigned "Level 0", and the {@link #level} constant-field will
042     * always be zero.
043     */
044    Silent(0),
045
046    /**
047     * Indicates a user-request for an application or program to run producing the minimum amount
048     * of text-output possible.  Error output may (or may not) be shunted, as per the capricious
049     * whims of the software guys.
050     *
051     * <BR /><BR />This constant is assigned "Level 1", and the {@link #level} constant-field will
052     * always be one.
053     */
054    Quiet(1),
055
056    /**
057     * The {@code enum}-constant should be used to indicate that the default output-text be sent to
058     * Standard-Output and Error-Output.
059     *
060     * <BR /><BR />This constant is assigned "Level 2", and the {@link #level} constant-field will
061     * always be two.
062     */
063    Normal(2),
064
065    /**
066     * If a programmer can produce additional information about the state of a program as it runs,
067     * then the {@code 'Verbose'} constant / flag may be used to indicate a user-request as such.
068     *
069     * <BR /><BR />This constant is assigned "Level 3", and the {@link #level} constant-field will
070     * always be three.
071     */
072    Verbose(3);
073
074    /**
075     * There are quite a number of situations where an integer is easier for doing the comparisons
076     * an actual instance of {@code 'Verbosity'}.  Each of the four constants of this {@code enum}
077     * have their own, ordered, {@code 'level'} setting (which is a number between {@code '0'} and
078     * {@code '3'}).
079     */
080    public final int level;
081
082    private Verbosity(int level) { this.level = level; }
083
084    /**
085     * Retrieves the Enum-Constant associated with the integer parameter {@code 'verbosityLevel'}.
086     * 
087     * @param verbosityLevel This must be a value between {@code '0'} and {@code '3'}, or an 
088     * IllegalArgumentException will throw.
089     * 
090     * <BR /><BR />This is used to indicate which of the four constants are to be returned by this
091     * method.
092     * 
093     * <BR /><BR /><TABLE CLASS=JDBriefTable>
094     * <TR><TH>Constant</TH>            <TH>Integer Level</TH>  </TR>
095     * <TR><TD>{@link #Silent}</TD>     <TD>{@code 0}</TD>      </TR>
096     * <TR><TD>{@link #Quiet}</TD>      <TD>{@code 1}</TD>      </TR>
097     * <TR><TD>{@link #Normal}</TD>     <TD>{@code 2}</TD>      </TR>
098     * <TR><TD>{@link #Verbose}</TD>    <TD>{@code 3}</TD>      </TR>
099     * </TABLE>
100     * 
101     * @return The Enum-Constant associated with the input {@code 'verbosityLevel'}
102     * 
103     * @throws IllegalArgumentException If an integer-value other than the above four possible
104     * values is provided as input.
105     */
106    public static Verbosity get(int verbosityLevel)
107    {
108        if ((verbosityLevel < 0) || (verbosityLevel > 3)) throw new IllegalArgumentException
109            ("verbosityLevel=" + verbosityLevel + ", but this value must be between 0 and 3.");
110
111        switch (verbosityLevel)
112        {
113            case 0: return Silent;
114            case 1: return Quiet;
115            case 2: return Normal;
116            case 3: return Verbose;
117
118            default: throw new UnreachableError();
119        }
120    }
121}