Interface Where_Am_I

  • public interface Where_Am_I
    This interface is designed to be implemented, strictly, by Java 'enum' Types. The constants of enum's which implement the 'Where_Am_I' interface are intended to be used for BOTH giving a name to AND providing a simple description of the various points of program execution in a large scale Java-Application.


    • Field Summary

      Fields 
      Modifier and Type Field Description
      static String LABEL_COLOR
      This field holds the Text-Color & Text Background-Color for the Labels which are printed to the Terminal-Window.

    • Method Summary

       
      Returns a description for this location; must be implemented
      Modifier and Type Method Description
      String getDescription()
       
      Builds a formatted description string for use in enum constructors
      Modifier and Type Method Description
      static String generateDescriptionStr​(Enum<?> enumConstant, String categoryTitle, String description)
       
      Formats the description with indentation; used internally by Messager
      Modifier and Type Method Description
      default String messagerString​(int indentation)
      Prints the current location of program exeuction to an output String.

    • Field Detail

      • LABEL_COLOR

        🡇  ⇈  ⮫ 🗕  🗗  🗖 
        static final java.lang.String LABEL_COLOR
        This field holds the Text-Color & Text Background-Color for the Labels which are printed to the Terminal-Window. Labels which use this color are utilized for rendering & displaying Program-Execution Location - specifically: "Where am I?" in the application which is being executed.
        Code:
        Exact Field Declaration Expression:
         static final String LABEL_COLOR = RED_BKGND + BWHITE;

    • Method Detail

      • messagerString

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        default java.lang.String messagerString​(int indentation)
        Prints the current location of program exeuction to an output String.
        Parameters:
        indentation - The number / amount of Space-Characters (' ') to use when indenting the Program-Execution Location-Text which is being printed to the Terminal-Window.
        Returns:
        An output String which has been decorated using the UNIX-Terminal Color-Codes (offered in class 'C') and explicates the Program / Applications current execution path / location.
        Code:
        Exact Method Body:
         return StrIndent.indent(this.getDescription(), indentation);

      • getDescription

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        java.lang.String getDescription()
        To implement the getDescription() method required by the Where_Am_I interface, you must define an enum that contains the following:

        • A private final String description; field
        • A constructor that initializes this field by calling Where_Am_I.generateDescription(...)
        • An implementation of getDescription() that returns the description


        This approach enables simple, readable calls to your Messager methods, using enum constants to represent specific program locations.

        For example:

        Example:
        public enum MyModule implements Torello.JavaDoc.Messager.Where_Am_I
{
    // The "Where_Am_I" Enum-Constants.  These may be passed to a Messager's error methods.
    ClassLocation1("This does some checking"),
    ClassLocation2("This does some data writing");

    // All instances of Where_Am_I ought to define a field for "getDescription()""
    private final String description;

    // This constructor computes the description and saves it to the internal field
    MyModule(String rawDescription)
    { this.description = Where_Am_I.generateDescription(this, "My Module 1", rawDescription); }

    // This is THE ONLY OBLIGATORY method located in the Where_Am_I interface.
    public String getDescription()
    { return this.description; }
}


        With this setup, your code can simply call:

        Example:
        // Checking for an error case in your code.  If an error is detected, just pass the 
// Enum-Constant that correlates to the location in your code where this error was detected.
// When the Messager prints this error, it shall include a brief header explaining the exact 
// location in the code where this error has occured.

if (myBool == left) Messager.userErrorContinue(
    "Hey, your boolean turned out to be `left` rather than true or false!\n" +
    "How did you acheive that?",
    MyModule.ClassLocation1
);
        Returns:
        Returns the fully formatted description string that represents the program-execution location corresponding to this enum constant.

        This string is later used by the Messager class to label assertion-failure or user-error messages, typically as an indented header.

      • generateDescriptionStr

        🡅  ⇈  ⮫ 🗕  🗗  🗖 
        static java.lang.String generateDescriptionStr​
            (java.lang.Enum<?> enumConstant,
             java.lang.String categoryTitle,
             java.lang.String description)
        Generates a fully formatted description string for a particular enum constant that represents a location in the user’s code.

        This method is designed to be called from the constructor of an enum that implements Where_Am_I. It creates a standardized string used by Messager to show clear and labeled execution locations during error reporting.

        The generated string includes the enum name, a user-defined category label, and a wrapped description, all aligned and indented for clarity.
        Parameters:
        enumConstant - The enum constant representing the code location. Its name will be used in the formatted output.
        categoryTitle - A short label (e.g., "Parser Phase", "My Module") describing the module or context of the enum location.
        description - A detailed explanation of what this program location represents. This text is automatically wrapped and indented.
        Returns:
        Returns a formatted, indented string that includes:

        • The category title as a label (e.g., "My Module", "Parser Phase")
        • The enum constant name (e.g., ClassLocation1)
        • The wrapped user-provided description text


        This output is later consumed by the getDescription() method in user-defined enums, and ultimately used by Messager to provide helpful error context.
        Code:
        Exact Method Body:
         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
 );