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

package Torello.JavaDoc.Messager;

import Torello.Java.StrIndent;
import Torello.Java.StrPrint;

import static Torello.Java.C.RED_BKGND;
import static Torello.Java.C.BCYAN;
import static Torello.Java.C.BWHITE;
import static Torello.Java.C.RESET;

/**
 * This interface is designed to be implemented, strictly, by Java {@code 'enum'} Types.  The 
 * constants of {@code enum's} which implement the {@code 'Where_Am_I'} interface are intended 
 * to be used for <B STYLE='color:red;'><I>BOTH</I></B> giving a name to
 * <B STYLE='color:red;'><I>AND</I></B> providing a simple description of the various points of 
 * program execution in a large scale Java-Application.
 */
public interface Where_Am_I
{
    /**
     * This field holds the Text-Color &amp; Text Background-Color for the Labels which are printed 
     * to the Terminal-Window.  Labels which use this color are utilized for rendering &amp;
     * displaying Program-Execution Location - <B STYLE='color:red'><I>specifically: "Where am
     * I?"</I></B> in the application which is being executed.
     * */
    static final String LABEL_COLOR = RED_BKGND + BWHITE;

    /**
     * Prints the current location of program exeuction to an output {@code String}.  
     * 
     * @param indentation The number / amount of Space-Characters ({@code ' '}) to use when
     * indenting the Program-Execution Location-Text which is being printed to the Terminal-Window.
     * 
     * @return An output {@code String} which has been decorated using the UNIX-Terminal 
     * Color-Codes (offered in class {@link Torello.Java.C 'C'}) and explicates the Program / 
     * Applications current execution path / location.
     */
    default String messagerString(int indentation)
    { return StrIndent.indent(this.getDescription(), indentation); }

    /**
     *          <EMBED CLASS='external-html' DATA-FILE-ID=WAI_GET_DESC_DESC>
     * @return  <EMBED CLASS='external-html' DATA-FILE-ID=WAI_GET_DESC_RET>
     */
    String getDescription();

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=WAI_GEN_DESC_STR_DESC>
     * 
     * @param enumConstant The enum constant representing the code location. Its name will be used
     * in the formatted output.
     *
     * @param categoryTitle A short label (e.g., "Parser Phase", "My Module") describing the module
     * or context of the enum location.
     *
     * @param description A detailed explanation of what this program location represents. This
     * text is automatically wrapped and indented.
     *
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=WAI_GEN_DESC_STR_RET>
     */
    static String generateDescriptionStr(
            final Enum<?>   enumConstant,
            final String    categoryTitle,
            final String    description
        )
    {
        final String title = ' ' + categoryTitle + ' ';

        return StrIndent.indentAfter2ndLine(
            LABEL_COLOR + title + RESET +
                " [" + BCYAN + enumConstant.name() + RESET + "]: " +
                StrPrint.wrap(description, 60, 80) + '\n',
            title.length() + 1, // "+1" Space-Character
            true,
            true
        );
    }

}