Interface HiLiter

  • Functional Interface:
    This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.
    @FunctionalInterface
public interface HiLiter
    A simple Functional-Interface allowing a user to swap in any customized, alternate or proprietary Syntax HiLiter to replace the default HiLiter used by this Upgrader Tool.

    This interface can be replaced if there are other HiLiter's that seem compatible with this JavaDoc Upgrade Tool. All that is expected is that whatever mechanism is used - it needs to be able to convert Source-Code into HTML given the inputs below.

    Implementations of this Functional Interface should be expected to receive Source-Code in many formats, along with a 'Code Type' that identifies what language is included in the Source-Code File. A 'Style Type' may also provided (if needed), but only two styles are used, internally, by the HiLiter itself - one for "Complete File" Source-Code String's, and one for "Snippet."

    The default HiLiter is the one in the Torello.Java package named HiLiteMe. This class is capable of providing a 'Cache' to avoid making internet-connections for code that has already been hilited and hasn't changed. Any subsequent / alternate implementations inserted into this JavaDoc Upgrader do not need to provide a Cache, but if HTTP Connections are utilized, it is of tremendous benefit.


    • Method Detail

      • hiLite

        🡇  ⇈  ⮫ 🗕  🗗  🗖 
        java.util.Vector<HTMLNode> hiLite​(java.lang.String code,
                                  java.lang.String codeType,
                                  boolean snippetOrComplete)
                           throws java.io.IOException,
                                  HiLiteException
        This Functional Interface expects this method to be implemented. Any HiLiter that would be "plugged into" this Documentation Tool must be able to Pretty-Print HiLite input Source-Code (passed as a java.lang.String) and return HTML.

        NOTE: Any Code HiLiter that can operate with this input may be plugged in here. In order to "Vectorize" HTML, just use the HTMLPage.getPageTokens(String, false) method.
        Parameters:
        code - This is the Source-Code as a java.lang.String
        codeType - This is a short descriptor of what kind of code is being passed. The most frequent values for this parameter are: 'java', 'html', 'js' etc...
        snippetOrComplete - This is a boolean that when TRUE, indicates that a code-snippet has been passed, and when FALSE indicates that a complete source code file has been passed.
        Returns:
        The intention is to return a Vectorized-HTML page (or sub-page) that contains a HiLited & Pretty-Printed version of the source-code.
        Throws:
        java.io.IOException - This method is not defined, but it is permitted to throw IOException - if there have been I/O problems when attempting to transform the source-code.
        HiLiteException - This exception may be used if other problems occur during the transformation process.

      • getDefault

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        static HiLiter getDefault​(HiLiteMe.Cache c,
                          java.lang.String snippetStyleCode,
                          java.lang.String completeStyleCode)
        The Default Code HiLiter uses the class HiLiteMe. This method is invoked by the Upgrade class and used to HiLite BOTH code-snippets AND complete source-code files.
        Parameters:
        c - This is the Server-Cache that may or may not be used. If this parameter is passed 'null', it will be ignored.
        snippetStyleCode - Some of the source-code passed to this HiLiter will be short code-snippets, while other passed values of source-code will be complete source-code files. This String is the 'Style Parameter' used for code-snippets.

        You may view the complete-list of valid Style Parameters in use with this HiLiter with HiLiteMe.getStyleTypes().
        completeStyleCode - When the HiLiter is asked to Hi-Lite and entire source code file, this parameter will be used for a 'Style Parameter' with the HiLiter.
        Returns:
        An instance of HiLiter that can be used by the Upgrade Tool
        Throws:
        java.lang.IllegalArgumentException - If invalid Styling-Parameters were passed either to 'snippetStyleCode' or 'completeStyleCode'.
        See Also:
        HiLiteMe.prettyPrintScrapeToVectorAndSimplify(String, String, String, boolean), HiLiteMe.prettyPrintScrapeToVectorAndSimplify(String, String, String, boolean, HiLiteMe.Cache)
        Code:
        Exact Method Body:
         // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
 // FAIL-FAST: Make sure that VALID Code-Styling Parameters were passed before building
 //            the HiLiter
 // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

 if (! HiLiteMe.isStyleType(snippetStyleCode)) throw new IllegalArgumentException(
     "You have passed \"" + snippetStyleCode + "\" to parameter 'snippetStyleCode', but " +
     "this is not actually a valid Style Parameter for class HiLite.Me.  Review the list " +
     "Style Types in that class using HiLiteMe.getStyleTypes(), or look at the docs for " +
     "that class"
 );

 if (! HiLiteMe.isStyleType(completeStyleCode)) throw new IllegalArgumentException(
     "You have passed \"" + completeStyleCode + "\" to parameter 'completeStyleCode', but " +
     "this is not actually a valid Style Parameter for class HiLite.Me.  Review the list " +
     "Style Types in that class using HiLiteMe.getStyleTypes(), or look at the docs for " +
     "that class"
 );

 // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
 // Return a HiLiter instance that uses Torello.Java.HiLiteMe
 // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

 return (c == null)
     ? new HiLiter()
     {
         private final String snippetSC  = snippetStyleCode;
         private final String completeSC = completeStyleCode;

         public Vector<HTMLNode> hiLite
             (String code, String codeType, boolean snippetOrComplete)
             throws IOException
         { 
             return snippetOrComplete

                 ? HiLiteMe.prettyPrintScrapeToVectorAndSimplify
                     (code, codeType, snippetSC, false)

                 : addAnchorIDs(
                     HiLiteMe.prettyPrintScrapeToVectorAndSimplify
                         (code, codeType, completeSC, true));
         }
     }
     : new HiLiter()
     {
         // This one has a Cache
         private final Torello.Java.HiLiteMe.Cache cache = c;

         private final String snippetSC  = snippetStyleCode;
         private final String completeSC = completeStyleCode;

         public Vector<HTMLNode> hiLite
             (String code, String codeType, boolean snippetOrComplete)
             throws IOException
         {
             // The Parameters to this Invokation are identical to the call above.  See
             // comments above...  This method includes 'cache' parameter, which is the last
             // parameter to this method.

             return snippetOrComplete

                 ? HiLiteMe.prettyPrintScrapeToVectorAndSimplify
                     (code, codeType, snippetSC, false /* no line nums */,  cache)

                 : addAnchorIDs(
                     HiLiteMe.prettyPrintScrapeToVectorAndSimplify
                         (code, codeType, completeSC, true /* line nums */,  cache));
         }
     };