001package Torello.JavaDoc.Messager;
002
003import Torello.Java.StrIndent;
004import Torello.Java.StrPrint;
005
006import static Torello.Java.C.RED_BKGND;
007import static Torello.Java.C.BCYAN;
008import static Torello.Java.C.BWHITE;
009import static Torello.Java.C.RESET;
010
011/**
012 * This interface is designed to be implemented, strictly, by Java {@code 'enum'} Types.  The 
013 * constants of {@code enum's} which implement the {@code 'Where_Am_I'} interface are intended 
014 * to be used for <B STYLE='color:red;'><I>BOTH</I></B> giving a name to
015 * <B STYLE='color:red;'><I>AND</I></B> providing a simple description of the various points of 
016 * program execution in a large scale Java-Application.
017 */
018public interface Where_Am_I
019{
020    /**
021     * This field holds the Text-Color &amp; Text Background-Color for the Labels which are printed 
022     * to the Terminal-Window.  Labels which use this color are utilized for rendering &amp;
023     * displaying Program-Execution Location - <B STYLE='color:red'><I>specifically: "Where am
024     * I?"</I></B> in the application which is being executed.
025     * */
026    static final String LABEL_COLOR = RED_BKGND + BWHITE;
027
028    /**
029     * Prints the current location of program exeuction to an output {@code String}.  
030     * 
031     * @param indentation The number / amount of Space-Characters ({@code ' '}) to use when
032     * indenting the Program-Execution Location-Text which is being printed to the Terminal-Window.
033     * 
034     * @return An output {@code String} which has been decorated using the UNIX-Terminal 
035     * Color-Codes (offered in class {@link Torello.Java.C 'C'}) and explicates the Program / 
036     * Applications current execution path / location.
037     */
038    default String messagerString(int indentation)
039    { return StrIndent.indent(this.getDescription(), indentation); }
040
041    /**
042     *          <EMBED CLASS='external-html' DATA-FILE-ID=WAI_GET_DESC_DESC>
043     * @return  <EMBED CLASS='external-html' DATA-FILE-ID=WAI_GET_DESC_RET>
044     */
045    String getDescription();
046
047    /**
048     * <EMBED CLASS='external-html' DATA-FILE-ID=WAI_GEN_DESC_STR_DESC>
049     * 
050     * @param enumConstant The enum constant representing the code location. Its name will be used
051     * in the formatted output.
052     *
053     * @param categoryTitle A short label (e.g., "Parser Phase", "My Module") describing the module
054     * or context of the enum location.
055     *
056     * @param description A detailed explanation of what this program location represents. This
057     * text is automatically wrapped and indented.
058     *
059     * @return <EMBED CLASS='external-html' DATA-FILE-ID=WAI_GEN_DESC_STR_RET>
060     */
061    static String generateDescriptionStr(
062            final Enum<?>   enumConstant,
063            final String    categoryTitle,
064            final String    description
065        )
066    {
067        final String title = ' ' + categoryTitle + ' ';
068
069        return StrIndent.indentAfter2ndLine(
070            LABEL_COLOR + title + RESET +
071                " [" + BCYAN + enumConstant.name() + RESET + "]: " +
072                StrPrint.wrap(description, 60, 80) + '\n',
073            title.length() + 1, // "+1" Space-Character
074            true,
075            true
076        );
077    }
078
079}