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
         );