Package Torello.Java

Class HiLiteMe

  • public class HiLiteMe
extends java.lang.Object
    Wraps a basic on-line syntax-hiliter named HiLite.ME (which, itself, wraps the on-line hiliter pygments.org).

    This class puts a front-end on the web-server http://HiLite.ME. The site pretty-prints a wide variety (266, to be exact) different versions of software code files. If you wish to write a Java method to hi-light your Java code, quickly, and automatically, then use the methods in this class. HiLite.ME not only pretty-prints Java Code - it can handle most modern programming languages.

    • public Iterator<String> getCodeTypes()
    • public Iterator<String> getStyleTypes()
    • public Iterator<String> getCodeTypeDescriptions()

    The above Iterator<String> will provide a complete list of all parameters that this code-hiliter will accept as a 'Code Type'. Click the link below to see the complete list of available programming-type codes.

    Programming Language Codes

    Example:
    // This is how to hi-lite an entire Source-Code directory.
// NOTE: IT ISN'T NECCESSARY To USE GSUTIL (Google Cloud Sever Utility) to HiLite code with
// HiLite.ME, but Google Cloud Server Storage Buckets are where these files put after being
// hi-lited, so that they may be viewed on the web.

String FILEROOT_HILITEME = "data/HiLite.ME/";   // Store output html files here!

FileNode root = FileNode
     .createRoot("Torello/");
     .loadTree(-1, (file, name) -> name.endsWith(".java"), null);

HiLiteMe.Params hlmp = new HiLiteMe.Params();
hlmp.targetDirectory = FILEROOT_HILITEME;

HiLiteMe.prettyPrintRecurseTree(root, hlmp);
HiLiteMe.createIndex(hlmp.fileIndexList, hlmp.targetDirectory);

// *** These lines copy the HiLited code to my Google Cloud Server Storage Bucket
// *** But you may move it to wherever you like - you don't need to use Google at all.

String gcsDir = "gs://developer.torello.directory/MY_MANDARIN_LANGUAGE_PROJECT/";
GSUTIL.RM(gcsDir + "HiLite.ME/**");
GSUTIL.CP(FILEROOT_HILITEME + "Torello/", gcsDir + "HiLite.ME/");
GSUTIL.CP(FILEROOT_HILITEME + "index.html", gcsDir + "HiLite.ME/");


    • Method Summary

       
      Methods: Code-Type Parameter
      Modifier and Type Method
      static String deduceCodeType​(String fileName)
      static String deduceCodeType​(String fileName, TreeMap<String,​String> customMappings)
      static String getCodeDescription​(String codeType)
      static boolean isCodeType​(String s)
       
      Methods: Style Parameter
      Modifier and Type Method
      static boolean isStyleType​(String s)
       
      View / List All Code-Type & Style Parameters
      Modifier and Type Method
      static Iterator<String> getCodeTypeDescriptions()
      static Iterator<String> getCodeTypes()
      static Iterator<String> getStyleTypes()
       
      HiLiting Source Code, Return HTML String
      Modifier and Type Method
      static String prettyPrintScrape​(String codeText, String codeTypeParam, String styleTypeParam, boolean includeLineNumbers)
      static String prettyPrintScrapeAndSimplify​(String codeText, String codeTypeParam, String styleTypeParam, boolean includeLineNumbers)
       
      HiLiting Source Code, Return HTML String, Use File-System Cache
      Modifier and Type Method
      static String prettyPrintScrape​(String codeText, String codeTypeParam, String styleTypeParam, boolean includeLineNumbers, HiLiteMe.Cache cache)
      static String prettyPrintScrapeAndSimplify​(String codeText, String codeTypeParam, String styleTypeParam, boolean includeLineNumbers, HiLiteMe.Cache cache)
       
      HiLiting Source Code, Return Vectorized-HTML
      Modifier and Type Method
      static Vector<HTMLNode> prettyPrintScrapeToVector​(String codeText, String codeTypeParam, String styleTypeParam, boolean includeLineNumbers)
      static Vector<HTMLNode> prettyPrintScrapeToVectorAndSimplify​(String codeText, String codeTypeParam, String styleTypeParam, boolean includeLineNumbers)
       
      HiLiting Source Code, Return Vectorized-HTML, Use File-System Cache
      Modifier and Type Method
      static Vector<HTMLNode> prettyPrintScrapeToVector​(String codeText, String codeTypeParam, String styleTypeParam, boolean includeLineNumbers, HiLiteMe.Cache cache)
      static Vector<HTMLNode> prettyPrintScrapeToVectorAndSimplify​(String codeText, String codeTypeParam, String styleTypeParam, boolean includeLineNumbers, HiLiteMe.Cache cache)
       
      Replacing In-Line STYLE Attributes with CSS CLASS Attributes
      Modifier and Type Method
      static void main​(String[] argv)
      static Vector<HTMLNode> simplifyColorSpans​(Vector<HTMLNode> page, String styleTypeParam)
      static String styleParamCSSClasses​(String styleParam)
       
      HiLiting All Files in Directory Tree
      Modifier and Type Method
      static void createIndex​(TreeSet<String> fileIndexList, String targetDirectory)
      static void prettyPrintRecurseTree​(FileNode node, HiLiteMe.Params hlmp)

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Field Detail

      • INDEX_HEADER_HTML

        🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static java.lang.String INDEX_HEADER_HTML
        If you choose to call the method createIndex(TreeSet<String> fileIndexList, String targetDirectory), then this String will be used as the header for that file.

        NOTE: It may be changed, as it has not been declared 'final'.

    • Method Detail

      • getCodeTypes

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static java.util.Iterator<java.lang.String> getCodeTypes()
        Each time a piece of code is to be pretty-printed, HiLite.ME expects to receive a "type of software" or "type of code" descriptor String that identifies what type of textual-code it is receiving. There are exactly 266 different types of software files that may be passed to the HiLite.ME server. These String-tag for these 'Code Types' may be viewed here.

        Click the link below to see the complete list of programming-type codes.

        Programming Language Codes
        Returns:
        An Iterator<String> that produces each String-tag that may be passed as a 'Code Type' to http://HiLite.ME
        Code:
        Exact Method Body:
         // The 'RemoveUnsupportedIterator' wrapper class prohibits modifications to this TreeMap
 return new RemoveUnsupportedIterator<String>(codeTypeDescriptions.keySet().iterator());

      • getCodeTypeDescriptions

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static java.util.Iterator<java.lang.String> getCodeTypeDescriptions
            ()
        This will iterate over the full-name descriptions of the software types available for parsing with the HiLite.ME server
        Returns:
        An Iterator<String> that produces a String-description of each software-types available for parsing.
        Code:
        Exact Method Body:
         // The 'RemoveUnsupportedIterator' wrapper class prohibits modifications to this TreeMap
 return new RemoveUnsupportedIterator<String>(codeTypeDescriptions.values().iterator());

      • getStyleTypes

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static java.util.Iterator<java.lang.String> getStyleTypes()
        This will iterate over the "Defining Style-Output Types" available to users of the http://HiLite.ME server.

        Click the link below to see the complete list of 'Style Codes'

        HiLiting Style Codes
        Returns:
        An Iterator<String> over the different available String-tags that may be passed as a 'Style Tag' when performing a "pretty print" operation.
        Code:
        Exact Method Body:
         // The 'RemoveUnsupportedIterator' wrapper class prohibits modifications to this Vector
 return new RemoveUnsupportedIterator<String>(styleTypes.iterator());

      • getCodeDescription

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static java.lang.String getCodeDescription​
            (java.lang.String codeType)
        Returns the description for a specific 'Code Type'
        Returns:
        the long-form of the 'codeType' as a java String
        Code:
        Exact Method Body:
         return codeTypeDescriptions.get(codeType);

      • isCodeType

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static boolean isCodeType​(java.lang.String s)
        Checks whether the passed String-parameter is a recognized 'Code Type'

        Click the link below to see the complete list of programming-type codes.

        Programming Language Codes
        Parameters:
        s - This may be any java.lang.String. It is intended to be one of the listed 'Code Types' available for use with the HiLite.ME server.
        Returns:
        This will return TRUE if the passed String-tag is one of the tags listed with the HiLite.ME server for Software Types, or 'Code Types' - and FALSE otherwise. Use the Iterator to get the complete list of available 'Code Tags' (or click the link, above, to view them in this browser).
        See Also:
        getCodeTypes(), getCodeTypeDescriptions()
        Code:
        Exact Method Body:
         return codeTypeDescriptions.containsKey(s);

      • isStyleType

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static boolean isStyleType​(java.lang.String s)
        Checks whether the passed String-parameter is a recognized 'Style Type'

        Click the link below to see the complete list of 'Style Codes'

        HiLiting Style Codes
        Parameters:
        s - This may be any java.lang.String. It is intended to be one of the listed 'Style Types' available for use with the HiLite.ME server.
        Returns:
        This will return TRUE if the passed String-tag is one of the tags listed with the HiLite.ME server for Style Types, and FALSE otherwise. Use the Iterator to get the complete list of available 'Style Tags' (or click the link, above, to view them in this browser).
        See Also:
        getStyleTypes()
        Code:
        Exact Method Body:
         return styleTypes.contains(s);

      • createIndex

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static void createIndex​
            (java.util.TreeSet<java.lang.String> fileIndexList,
             java.lang.String targetDirectory)
        throws java.io.IOException
        This will generate an 'index.html' file of all the recently generated '.html' files.
        Parameters:
        targetDirectory - This is simply the save-location for this 'index.html' file
        fileIndexList - This must be a list of file-names that were generated by the class HiLiteMe
        Throws:
        java.io.IOException
        Code:
        Exact Method Body:
         StringBuilder out = new StringBuilder();

 out.append(INDEX_HEADER_HTML);
 out.append("<UL>");

 for (String f : fileIndexList) out.append(
     "<LI><A HREF=\"" + f + (f.endsWith(".txt") ? "" : ".html") +
     "\" TARGET=\"_blank\">\n" + f +"</A></LI>\n"
 );

 out.append("</UL>");
 out.append(Params.DEFAULT_ENDING_HTML);

 FileRW.writeFile(out, targetDirectory + "index.html");

      • prettyPrintRecurseTree

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static void prettyPrintRecurseTree​(FileNode node,
                                          HiLiteMe.Params hlmp)
                                   throws java.io.IOException
        This will take a FileNode tree, and iterate through all of it - calling the http://HiLite.ME/ server for each software file that it finds / discovers and recognizes. Each source-code file that is within the FileNode tree that is passed, after being pretty-printed, will be saved as a '.html' file in the HiLiteMe.Params.targetDirectory

        IMPORTANT NOTE: The provided java class FileNode has some very simple filter operations for making sure that only the code-files that you want to be transmitted will actually be sent. Each and every file in the FileNode tree whose 'Code Type' can be deduced (by it's file-extension, or via the HiLiteMe.Params.customMappings) will be sent to the HiLite.ME server for hiliting.

        It should be easy to call the fileNodeRoot.prune(...) method to make sure you are only transmitting/hiliting the files you want.

        FURTHERMORE: The means by which files are copied from a "Source" source-code directory to a "Target" hilited-HTML directory is simply via the FileRW.copyFile method. Because the copy operations preserves the directory-tree structure of the input source-code file-system tree, it is imperative to use a relative directory-location when loading the source-code FileNode tree.
        Parameters:
        node - This is the root node of a FileNode directory tree. Every operating-system file that is found inside this tree will have it's code-hilited using the HiLite.Me server.
        hlmp - Please review the inner-class Params to configure the extra parameters for storing and saving the results of the code hiliting operation.
        Throws:
        java.io.IOException
        See Also:
        prettyPrintScrape(String, String, String, boolean), HiLiteMe.Params
        Code:
        Exact Method Body:
         (new File(hlmp.targetDirectory + node.getFullPathName())).mkdirs();

 // This "flattens" the source-code FileNode tree into an Iterator.  The Iterator will not
 // iterate "FileNodes" - but rather String's - where each String is the relative path
 // name of the source code file.

 Iterator<String> files = node.getDirContentsFiles(RTC.FULLPATH_ITERATOR());

 while (files.hasNext())
 {
     String fileName = files.next();

     if (hlmp.verbose) System.out.printf("%1$-80s", fileName);

     // Sometimes it helps to have any text-files copied to output / target directory
     if (hlmp.copyTextFiles && fileName.toLowerCase().endsWith(".txt"))
     {
         // Again, put this in the "Complete List" of files for the "creatIndex" method.
         // If the user wants an 'index.html' file that lists all of the files that have
         // been hilited, this list is necessary.

         if (hlmp.fileIndexList != null) hlmp.fileIndexList.add(fileName);

         if (hlmp.verbose)
             System.out.println( "\nCOPYING " + BCYAN + "TEXT-FILE " + RESET);

         // This is why a "relative FileNode" is mandatory.  All that is happening is that
         // the "Full Path Name" of the source-code file is being appended to the
         // "Target Directory" name.
    
         FileRW.copyFile(fileName, hlmp.targetDirectory + fileName, true);

         // Text files are not actually hilited, just copied.
         continue;
     }

     // This checks the file-extension - '.java', '.js', '.html' - and uses that extension
     // String as a 'Code Type' with the HiLite server.
     //
     // If there are files where that system doesn't work - the mapping of a file-extension
     // to a 'Code Type' should be put into the "Custom Mappings" TreeMap in class
     // HiLiteMe.Params and passed to this 

     String codeTypeParam = deduceCodeType(fileName, hlmp.customMappings);

     if (codeTypeParam == null)
     {
         // Without a 'Code Type' there isn't any way to hilite the file...  Let the user
         // know and continue

         if (hlmp.verbose)
             System.out.println(
                 "\nUNKNOWN FILE TYPE FOUND: " + BCYAN + fileName + RESET +
                 BYELLOW + "\nNOT CONVERTING FILE..." + RESET
             );

         continue; // next source code file loop iteration
     }

     // Loads the source-code file to a String
     String fileText     = FileRW.loadFileToString(fileName);
     String hilitedCode  = null;

     // It is always faster to use a Cache with big projects...
     // If there is a 'Cache' check that first...

     if (hlmp.cache == null)

         // NOTE: The 'true' (last parameter) is passed to "includeLineNumbers"
         hilitedCode = prettyPrintScrape(fileText, codeTypeParam, hlmp.styleTag, true);

     else
     {
         // Check the Cache.  Note that it is pretty efficient, and doesn't do a 
         // character-by-character check - unless there is an exact hashCode match first.
         //
         // NOTE: The 'true' (last parameter) is passed to "includeLineNumbers"

         hilitedCode = hlmp.cache.get(fileText, codeTypeParam, hlmp.styleTag, true);

         // The Cache did not have an exact match for the Source Code File
         if (hilitedCode == null)
         {
             // NOTE: The 'true' (last parameter) is passed to "includeLineNumbers"
             //       This 'true' is the last parameter for both of the method calls below

             hilitedCode = prettyPrintScrape(fileText, codeTypeParam, hlmp.styleTag, true);
             hlmp.cache.checkIn(fileText, hilitedCode, codeTypeParam, hlmp.styleTag, true);
         }
     }

     // Now just write the hilited code to disk... Make sure to insert the HTML header
     // and tail/footer text.

     hilitedCode = hlmp.headerHTML.replace("INSERT HERE", fileName) + 
         hilitedCode + hlmp.endingHTML;

     FileRW.writeFile(hilitedCode, hlmp.targetDirectory + fileName + ".html");

     // Add this file-name to the list of files that have been converted/hilited
     // (but only if there is such a list being kep!)  This list can be used by the
     // method createIndex(TreeSet, String) to create an 'index.html' file

     if (hlmp.fileIndexList != null) hlmp.fileIndexList.add(fileName);

     // Let the user know this file has been successfully hilited.
     if (hlmp.verbose) System.out.println(BRED + "Completed." + RESET);
 }

 // After having iterated all the files in a directory, use recursion to iterate through the
 // files in any sub directories...
 //
 // The iterator of sub-dirs is an 'Iterator<FileNode>' rather than an 'Iterator<String>'
 // (which was used in the loop above)

 Iterator<FileNode> dirs = node.getDirContentsDirs(RTC.ITERATOR());

 while (dirs.hasNext()) prettyPrintRecurseTree(dirs.next(), hlmp);

      • deduceCodeType

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static java.lang.String deduceCodeType​
            (java.lang.String fileName,
             java.util.TreeMap<java.lang.String,​java.lang.String> customMappings)
        This attempts to guess the 'Code Type' parameter for the file, based on the input file name. The file is loaded from disk, so be sure to include the full path to the file in the fileName.
        Parameters:
        fileName - The full-path name of a Source-Code / Software file. It will be loaded from disk, and transmitted to HiLite.ME servers and "pretty-printed" into HTML.
        customMappings - This parameter may be null, and if it is, then it is ignored. If this parameter is not null, then the file-extension obtained from the String 'fileName' field will be "looked up" in the TreeMap, and if it matches one of these custom-mappings of file-extension to HiLite.ME code-type parameters, that 'Code Type' parameter will be used in the call to the Pretty Print Server.
        Returns:
        the 'Code Type' that is associated with the file-name extension - or null if there is no file-name extension, or the file-name extension is not found.
        Code:
        Exact Method Body:
         int extStartPos = fileName.lastIndexOf('.');

 if (extStartPos == -1) return null;

 String ext = fileName.substring(extStartPos + 1);

 if (ext == null) return null;

 if ((customMappings != null) && customMappings.containsKey(ext))
     return customMappings.get(ext);

 return isCodeType(ext) ? ext : null;

      • prettyPrintScrape

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static java.lang.String prettyPrintScrape​
            (java.lang.String codeText,
             java.lang.String codeTypeParam,
             java.lang.String styleTypeParam,
             boolean includeLineNumbers)
        throws java.io.IOException
        Convenience Method
        Invokes: prettyPrintScrapeToVector(String, String, String, boolean)
        And: Util.pageToString(Vector)
        Returns: HTML as a java.lang.String
        No cache is expected.
        Code:
        Exact Method Body:
         // NOTE: Util.pageToString(...) accepts a 'Vector<HTMLNode>' and returns the input HTML
 //       as a java.lang.String

 return Util.pageToString(

     // NOTE: prettyPrintScrapeToVector Inserts HTML <SPAN> Elements into PLAIN-TEXT Source
     //       code.  Afterwards it converts the HTML from a 'String' to a 'Vector<HTMLNode>'

     prettyPrintScrapeToVector
         (codeText, codeTypeParam, styleTypeParam, includeLineNumbers)
 );

      • prettyPrintScrape

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static java.lang.String prettyPrintScrape​
            (java.lang.String codeText,
             java.lang.String codeTypeParam,
             java.lang.String styleTypeParam,
             boolean includeLineNumbers,
             HiLiteMe.Cache cache)
        throws java.io.IOException
        Convenience Method
        Invokes: prettyPrintScrapeToVector(String, String, String, boolean, Cache)
        And: Util.pageToString(Vector)
        Returns: HTML as a java.lang.String
        Cache required.
        Code:
        Exact Method Body:
         // NOTE: Util.pageToString(...) accepts a 'Vector<HTMLNode>' and returns the input HTML
 //       as a java.lang.String

 return Util.pageToString(

     // NOTE: prettyPrintScrapeToVector Inserts HTML <SPAN> Elements into PLAIN-TEXT Source
     //       code.  Afterwards it converts the HTML from a 'String' to a 'Vector<HTMLNode>'
     //
     // ALSO: There are two versions of the method 'prettyPrintScrapeToVector.'  The one
     //       used here accepts and make-use-of a Cache.  In the method above, that version
     //       of this method DOES NOT utilize the Cache.

     prettyPrintScrapeToVector
         (codeText, codeTypeParam, styleTypeParam, includeLineNumbers, cache)
 );

      • prettyPrintScrapeAndSimplify

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static java.lang.String prettyPrintScrapeAndSimplify​
            (java.lang.String codeText,
             java.lang.String codeTypeParam,
             java.lang.String styleTypeParam,
             boolean includeLineNumbers)
        throws java.io.IOException
        Convenience Method
        Invokes: prettyPrintScrapeToVector(String, String, String, boolean, Cache)
        And: simplifyColorSpans(Vector, String)
        And: Util.pageToString(Vector)
        Returns: HTML as a java.lang.String
        No cache is expected.
        Code:
        Exact Method Body:
         // NOTE: Util.pageToString(...) accepts a 'Vector<HTMLNode>' and returns the input HTML
 //       as a java.lang.String

 return Util.pageToString(

     // The method 'simplifyColorSpans' modifies the HTML that is received from the HiLite
     // Server, and replaces each of the In-Line Style-Spans so that rather than containing
     // 'STYLE= ...' HTML Attributes, they contains a brief 'CLASS=...'.  This makes the
     // output HTML look cleaner, nicer, and easier to manage / modify.

     simplifyColorSpans(

         // NOTE: prettyPrintScrapeToVector Inserts HTML <SPAN> Elements into PLAIN-TEXT
         //       Source-Code.  Afterwards it converts the HTML from a 'String' to a
         //       'Vector<HTMLNode>'
    
         prettyPrintScrapeToVector
             (codeText, codeTypeParam, styleTypeParam, includeLineNumbers),

         // simplifyColorSpans(...) needs to know which style-parameter was passed to the HiLite
         // server in order convert the STYLE Assignments into CSS Classes.
        
         styleTypeParam
     ));

      • prettyPrintScrapeAndSimplify

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static java.lang.String prettyPrintScrapeAndSimplify​
            (java.lang.String codeText,
             java.lang.String codeTypeParam,
             java.lang.String styleTypeParam,
             boolean includeLineNumbers,
             HiLiteMe.Cache cache)
        throws java.io.IOException
        Convenience Method
        Invokes: prettyPrintScrapeToVectorAndSimplify(String, String, String, boolean, Cache)
        And: Util.pageToString(Vector)
        Returns: HTML as a java.lang.String
        Cache required.
        Code:
        Exact Method Body:
         // NOTE: Util.pageToString(...) accepts a 'Vector<HTMLNode>' and returns the input HTML
 //       as a java.lang.String

 return Util.pageToString(

     // Method 'prettyPrintScrapeToVectorAndSimplify' does:
     //
     // ONE: Invokes the HiLite Server, and Converts the HTML-String which is returned by
     ///     that server (or found inside the Cache), and converts that HTML-String to a
     //      Vector<HTMLNode>
     //
     // TWO: Replaces all inline <SPAN STYLE='...'> elements to <SPAN CLASS='...'> in order
     //      to make the HTML nicer looking, more compact, and easier to control
 
     prettyPrintScrapeToVectorAndSimplify
         (codeText, codeTypeParam, styleTypeParam, includeLineNumbers, cache)
 );

      • prettyPrintScrapeToVectorAndSimplify

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static java.util.Vector<HTMLNode> prettyPrintScrapeToVectorAndSimplify​
            (java.lang.String codeText,
             java.lang.String codeTypeParam,
             java.lang.String styleTypeParam,
             boolean includeLineNumbers)
        throws java.io.IOException
        Convenience Method
        Invokes: prettyPrintScrapeToVector(String, String, String, boolean, Cache)
        And: simplifyColorSpans(Vector, String)
        Returns: Vector<HTMLNode>
        No cache is expected.
        Code:
        Exact Method Body:
         // The method 'simplifyColorSpans' modifies the HTML that is received from the HiLite
 // Server, and replaces each of the In-Line Style-Spans so that rather than containing
 // 'STYLE= ...' HTML Attributes, they contains a brief 'CLASS=...'.  This makes the
 // output HTML look cleaner, nicer, and easier to manage / modify.

 return simplifyColorSpans(

     // The method 'prettyPrintScrapeToVector' sends the 'codeText' to the HiLite Server,
     // and receives the HiLited Source-Code HTML.  Afterwards it simple converts the HTML
     // which it received as a java.lang.String *INTO* a Vector<HTMLNode>

     prettyPrintScrapeToVector
         (codeText, codeTypeParam, styleTypeParam, includeLineNumbers),

     // simplifyColorSpans(...) needs to know which style-parameter was passed to the HiLite
     // server in order convert the STYLE Assignments into CSS Classes.

     styleTypeParam
 );

      • prettyPrintScrapeToVector

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static java.util.Vector<HTMLNode> prettyPrintScrapeToVector​
            (java.lang.String codeText,
             java.lang.String codeTypeParam,
             java.lang.String styleTypeParam,
             boolean includeLineNumbers)
        throws java.io.IOException
        This will take a java.lang.String of code - in almost any coding language - and generate an HTML-"ified" version of that code. This is often called "Pretty-Printing" code. The software-platform/engine that does the transformation of source code to "nice-looking HTML code" is just a site called http://HiLite.me.

        This method takes three parameters, and the first is the code itself (passed as a java.lang.String.) The second is the "descriptor" - which is a short text-String that identifies what type (programming-language) is being passed to HiLite.ME. The complete list of available Code Types can be found in the Raw HTML of HiLite.ME's main page.

        • 'java' => Java Code!
        • 'css' => CSS - Cascading Style Sheets
        • 'js' => Java-Script code
        • The list contains at least 75 languages, select "View Code Source" in Google-Chrome or Internet-Explorer to see complete set of options!


        The third parameter is a 'style' name / type parameter. Again, view the http://HiLite.ME website to see the complete list of available styles. My preferred / defaults are 'vim' and 'native'
        Parameters:
        codeText - This is the software-code (like CSS, Java, SQL, Python, etc..) saved as a single text-String
        codeTypeParam - This variable indicates what type of code this is. Usually, I use 'java'

        NOTE: To view the complete list of Code Types available, just view the returned results of (Iterator<String>) method getCodeTypes()

        You may also click the link below to see the complete list of 'Code Types'

        Programming Language Codes
        styleTypeParam - This variable identifies which of HiLite.ME's styles to choose. Go to the website to see the list of available options.

        NOTE: To view the complete list of 'Style Types'available, just view the returned results of (Iterator<String>) method getStyleTypes()

        You may also click the link below to see the complete list of 'Style Codes'

        HiLiting Style Codes
        includeLineNumbers - When this parameter receives TRUE, line-numbers are appended to the HTML output.
        Returns:
        The HTML is returned as a Vector<HTMLNode>

        The "HTML with formatting and colors" version of the code. May be saved as an HTML-file, and put on a website to see your own code.

        NOTE: HTML Header and Footer information (for the returned page itself, not the hilited code!) is not included as part of the returned HTML. HTML header elements should be added before writing this String to a '.html' text file!

        SPECIFICALLY: The String that is returned has a single HTML <DIV> element that wraps a large code-hiliting section. The HTML itself, though, does not have any of the usual <HEAD>, <TITLE>, <BODY> tag-elements yet, though.
        Throws:
        java.io.IOException - If there are any problems communicating with the HiLite Server.
        See Also:
        URLs.toProperURLV2(String), HTMLPage.getPageTokens(BufferedReader, boolean), InnerTagGetInclusive, TagNodeRemoveInclusive
        Code:
        Exact Method Body:
         codeText = URLs.toProperURLV2(codeText);

 URL             url         = new URL("http://hilite.me");
 URLConnection   connection  = url.openConnection();

 connection.setDoOutput(true);  
        
 OutputStreamWriter out = new OutputStreamWriter(connection.getOutputStream(), "UTF-8");

 out.write(
     "lexer=" + codeTypeParam + 
     "&style=" + styleTypeParam + 
     (includeLineNumbers ? "&linenos=false" : "") +
     "&divstyles=border:solid gray;border-width:.1em .1em .1em .8em;padding:.2em .6em;" +
     "&code=" + codeText 
 );
 out.flush();   

 BufferedReader br = new BufferedReader
     (new InputStreamReader(connection.getInputStream(), Charset.forName("UTF-8")));

 // Read the HTML String response and Parse the JTML into Vectorized-HTML.
 Vector<HTMLNode> v = HTMLPage.getPageTokens(br, false);

 // First, find the divider where the HiLited Code is located.  It still has some extra
 // bluff-and-bluster, fluff-and-fanfare, a bunch-of-crap to filter.

 // The response is inside of the <DIV ID=preview> ... </DIV>
 // However, there is another 'outer-div' that contains an Inline CSS Style Attribute. The
 // inner <DIV> ... </DIV> is the one to return.  If there are line-numbers, that inner
 // <DIV> will have a <TABLE> that has one row with two columns.  The first column will have
 // all of the line-numbers, and the second column will have the Hi-Lited Source Code.

 int idDIVPos = InnerTagFind.first(v, "div", "id", TextComparitor.EQ_CI, "preview");

 v = TagNodeGetInclusive.first(v, idDIVPos + 1, -1, "div");

 /*
 if (includeLineNumbers)
 {
     int end = v.size();
     System.out.println(
         "******* DEBUG *******\n" +
         Debug.print(v, 0, ((end < 20) ? end : 20), Debug::K) +
         "******* DEBUG *******\n" +
         Debug.print(v, ((end < 20) ? 0 : (end - 20)), end, Debug::K)
     );
     if (! Q.YN("continue?")) System.exit(0);
 }
 */

 return v;

      • prettyPrintScrapeToVector

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static java.util.Vector<HTMLNode> prettyPrintScrapeToVector​
            (java.lang.String codeText,
             java.lang.String codeTypeParam,
             java.lang.String styleTypeParam,
             boolean includeLineNumbers,
             HiLiteMe.Cache cache)
        throws java.io.IOException
        This performs an identical operation to method: prettyPrintScrapeToVector(String, String, String), but it checks the provided cache first, before querying the server.
        Parameters:
        codeText - This is the software-code (like CSS, Java, SQL, Python, etc..) saved as a single text-String.
        codeTypeParam - This variable indicates what type of code this is. Usually, I use 'java'

        NOTE: To view the complete list of Code Types available, just view the returned results of (Iterator<String>) method getCodeTypes()

        You may also click the link below to see the complete list of 'Code Types'

        Programming Language Codes
        styleTypeParam - This variable identifies which of HiLite.ME's styles to choose. Go to the website to see the list of available options.

        NOTE: To view the complete list of 'Style Types'available, just view the returned results of (Iterator<String>) method getStyleTypes()

        You may also click the link below to see the complete list of 'Style Codes'

        HiLiting Style Codes
        includeLineNumbers - When this parameter receives TRUE, line-numbers are appended to the HTML output.
        cache - This is the cache that must be passed. Read about the HiLiteMe.Cache static inner class for an explanation about how caching results from the server works. Save time on the build by caching results that have not changed.
        Returns:
        The HTML is returned as a Vector<HTMLNode>

        The "HTML with formatting and colors" version of the code. May be saved as an HTML-file, and put on a website to see your own code.

        NOTE: HTML Header and Footer information (for the returned page itself, not the hilited code!) is not included as part of the returned HTML. HTML header elements should be added before writing this String to a '.html' text file!

        SPECIFICALLY: The String that is returned has a single HTML <DIV> element that wraps a large code-hiliting section. The HTML itself, though, does not have any of the usual <HEAD>, <TITLE>, <BODY> tag-elements yet, though.
        Throws:
        java.io.IOException - If there are any problems communicating with the HiLite Server.
        See Also:
        prettyPrintScrapeToVector(String, String, String, boolean), HTMLPage.getPageTokens(CharSequence, boolean)
        Code:
        Exact Method Body:
         // FIRST: Check the Cache, to see if the exact String has been hilited!
 String ret = cache.get(codeText, codeTypeParam, styleTypeParam, includeLineNumbers);

 // If there was a Cache hit -> return that String rather than querying the server.
 if (ret != null) return HTMLPage.getPageTokens(ret, false);

 // NO? Then query the server.
 Vector<HTMLNode> retVec = prettyPrintScrapeToVector
     (codeText, codeTypeParam, styleTypeParam, includeLineNumbers);

 // Make sure to save the response in the Cache for next time
 cache.checkIn(
     codeText, Util.pageToString(retVec), codeTypeParam, styleTypeParam,
     includeLineNumbers
 );

 return retVec;

      • prettyPrintScrapeToVectorAndSimplify

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static java.util.Vector<HTMLNode> prettyPrintScrapeToVectorAndSimplify​
            (java.lang.String codeText,
             java.lang.String codeTypeParam,
             java.lang.String styleTypeParam,
             boolean includeLineNumbers,
             HiLiteMe.Cache cache)
        throws java.io.IOException
        This performs an identical operation to method: prettyPrintScrapeToVector(String, String, String), but it checks the provided cache first, before querying the server. Furthermore, the HTML that is returned has been simplified, using the method simplifyColorSpans(Vector, String).

        Using this version of Pretty Print mandates that the user provide a Cache.
        Parameters:
        codeText - This is the software-code (like CSS, Java, SQL, Python, etc..) saved as a single text-String.
        codeTypeParam - This variable indicates what type of code this is. Usually, I use 'java'

        NOTE: To view the complete list of Code Types available, just view the returned results of (Iterator<String>) method getCodeTypes()

        You may also click the link below to see the complete list of 'Code Types'

        Programming Language Codes
        styleTypeParam - This variable identifies which of HiLite.ME's styles to choose. Go to the website to see the list of available options.

        NOTE: To view the complete list of 'Style Types'available, just view the returned results of (Iterator<String>) method getStyleTypes()

        You may also click the link below to see the complete list of 'Style Codes'

        HiLiting Style Codes
        includeLineNumbers - When this parameter receives TRUE, line-numbers are appended to the HTML output.
        cache - This is the cache that must be passed. Read about the HiLiteMe.Cache static inner class for an explanation about how caching results from the server works. Save time on the build by caching results that have not changed.
        Returns:
        The HTML is returned as a Vector<HTMLNode>

        The "HTML with formatting and colors" version of the code. May be saved as an HTML-file, and put on a website to see your own code.

        NOTE: HTML Header and Footer information (for the returned page itself, not the hilited code!) is not included as part of the returned HTML. HTML header elements should be added before writing this String to a '.html' text file!

        SPECIFICALLY: The String that is returned has a single HTML <DIV> element that wraps a large code-hiliting section. The HTML itself, though, does not have any of the usual <HEAD>, <TITLE>, <BODY> tag-elements yet, though.
        Throws:
        java.io.IOException - If there are any problems communicating with the HiLite Server.
        See Also:
        prettyPrintScrapeToVector(String, String, String, boolean), HTMLPage.getPageTokens(CharSequence, boolean), simplifyColorSpans(Vector, String)
        Code:
        Exact Method Body:
         // FIRST: Check the Cache, to see if the exact String has been hilited!
 String ret = cache.get(codeText, codeTypeParam, styleTypeParam, includeLineNumbers);

 // If there was a Cache hit -> return that String rather than querying the server.
 if (ret != null) return HTMLPage.getPageTokens(ret, false);

 // NO? Then query the server.
 Vector<HTMLNode> retVec =
     prettyPrintScrapeToVector(codeText, codeTypeParam, styleTypeParam, includeLineNumbers);

 // Replace all of the STYLE=... attributes to CLASS=... attributes
 simplifyColorSpans(retVec, styleTypeParam);

 // Make sure to save the response in the Cache for next time
 cache.checkIn(
     codeText, Util.pageToString(retVec), codeTypeParam, styleTypeParam,
     includeLineNumbers
 );

 return retVec;

      • styleParamCSSClasses

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static java.lang.String styleParamCSSClasses​
            (java.lang.String styleParam)
        Will return a java.lang.String containing all of the CSS STYLE definitions for a particular 'Style Type'.

        NOTE: These definitions are only useful if the HiLited Source Code that you have used has been simplified from in-line 'STYLE=...' attributes into a CLASS=... version of the hiliting.
        Parameters:
        styleParam - This may be any of the valid 'Style Tags' available for hiliting source-code. The complete list of 'Style Tags' may be viewed here:

        HiLiting Style Codes
        Returns:
        The CSS Class definitions as a String

        NOTE: The RETURN VALUES (as String's) can actually be viewed right here by clicking the link below. Each 'Style Type' is followed by a list of CSS Definitions that must be included in order for the Code HiLiting to work (if-and-only-if) you have opted to use the "Simplified Color Spans."

        Style Tag CSS Definitions
        Throws:
        java.lang.IllegalArgumentException - If an invalid 'Style Type' has been passed to the 'styleParam' parameter.
        Code:
        Exact Method Body:
         if (! isStyleType(styleParam)) throw new IllegalArgumentException
     ("The Style Type Parameter passed [" + styleParam + "] is not a valid Style Type");

 if (styleCSSDefinitions == null)
     styleCSSDefinitions = (TreeMap<String, String>) LFEC.readObjectFromFile_JAR
         (HiLiteMe.class, "data-files/HLMClasses.tmdat", true, TreeMap.class);

 return styleCSSDefinitions.get(styleParam);

      • main

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static void main​(java.lang.String[] argv)
        This may be called from the command line. It will print the CSS Definitions for a 'Style Type' parameter. The complete list of valid Style Types may be viewed here:

        Style Tag CSS Definitions

      • simplifyColorSpans

        🡅  ⇈  ⮫ 🗕  🗗  🗖 
        public static java.util.Vector<HTMLNode> simplifyColorSpans​
            (java.util.Vector<HTMLNode> page,
             java.lang.String styleTypeParam)
        This method converts the HiLite.ME output to a simplified-version where the inline 'STYLE' attributes are converted to 'CLASS' attributes. The HTML that results looks a lot cleaner and is more simple. Furthermore, the HiLiter itself is not perfect in that the HTML generated by that site has quite a number of "Redundant SPAN" elements. This method will also eliminate redundant HTML <SPAN>'s.

        The conversion that is done here will make one issue more complicated, though. Since the original <SPAN STYLE='color: #...'> [source-code] </SPAN> elements use inline CSS-STYLE declarations (as may be seen in the line directly above), and the output-page from this method uses inline CSS CLASS declarations, it will be necessary to include the CSS CLASSES either in your HTML Page Header somewhere.

        These CSS CLASS definitions may be obtained by calling the method styleParamCSSClasses(String). The return value for this method is a java.lang.String, and it literally will be text that should be placed between two HTML <STYLE> ... </STYLE> tags somewhere in your header.

        The complete list of CSS Definitions Required to use the "Simplified Version" of the code HiLiting may be viewed here:

        Style Tag CSS Definitions

        Below is an example of what the HTML looks like for a piece of Java Source Code that has been hilited - both BEFORE and AFTER this method has been invoked. The first window here is the Java Source Code that is being hilited:


        public class SomeClass
{
    public static void main(String[] argv) throws IOException
    {
        URL url = new URL("https://some.url.com/index.html");
        Vector<HTMLNode> page = HTMLPage.getPageTokens(url, false);

        for (HTMLNode n : page)
            if (n.str.contains("FOO"))
                System.out.println(n);
    }
}

        The above Java Source Code example, when hilited by this class, will produce (HiLited) HTML that looks as below:

        HTML Elements:
        <!-- HTML generated using hilite.me --><div style="background: #ffffff; overflow:auto;width:auto;border:solid gray;border-width:.1em .1em .1em .8em;padding:.2em .6em;"><pre style="margin: 0; line-height: 125%"><span style="color: #008800; font-weight: bold">public</span> <span style="color: #008800; font-weight: bold">class</span> <span style="color: #BB0066; font-weight: bold">SomeClass</span>
    <span style="color: #333333">{</span>
        <span style="color: #008800; font-weight: bold">public</span> <span style="color: #008800; font-weight: bold">static</span> <span style="color: #333399; font-weight: bold">void</span> <span style="color: #0066BB; font-weight: bold">main</span><span style="color: #333333">(</span>String<span style="color: #333333">[]</span> argv<span style="color: #333333">)</span> <span style="color: #008800; font-weight: bold">throws</span> IOException
        <span style="color: #333333">{</span>
            URL url <span style="color: #333333">=</span> <span style="color: #008800; font-weight: bold">new</span> URL<span style="color: #333333">(</span><span style="background-color: #fff0f0">&quot;https://some.url.com/index.html&quot;</span><span style="color: #333333">);</span>
            Vector<span style="color: #333333">&lt;</span>HTMLNode<span style="color: #333333">&gt;</span> page <span style="color: #333333">=</span> HTMLPage<span style="color: #333333">.</span><span style="color: #0000CC">getPageTokens</span><span style="color: #333333">(</span>url<span style="color: #333333">,</span> <span style="color: #008800; font-weight: bold">false</span><span style="color: #333333">);</span>
    
            <span style="color: #008800; font-weight: bold">for</span> <span style="color: #333333">(</span>HTMLNode n <span style="color: #333333">:</span> page<span style="color: #333333">)</span>
                <span style="color: #008800; font-weight: bold">if</span> <span style="color: #333333">(</span>n<span style="color: #333333">.</span><span style="color: #0000CC">str</span><span style="color: #333333">.</span><span style="color: #0000CC">contains</span><span style="color: #333333">(</span><span style="background-color: #fff0f0">&quot;FOO&quot;</span><span style="color: #333333">))</span>
                    System<span style="color: #333333">.</span><span style="color: #0000CC">out</span><span style="color: #333333">.</span><span style="color: #0000CC">println</span><span style="color: #333333">(</span>n<span style="color: #333333">);</span>
        <span style="color: #333333">}</span>
    <span style="color: #333333">}</span>
    </pre></div>

        It is important to note that each of the hilited sections above have an HTML <SPAN STYLE=...> wrapped around key-words inside the source-code. However, after invoking this "Simplify" method, the SPAN elements would look as below:

        HTML Elements:
        <!-- HTML generated using hilite.me --><div style="background: #ffffff; overflow:auto;width:auto;border:solid gray;border-width:.1em .1em .1em .8em;padding:.2em .6em;"><pre style="margin: 0; line-height: 125%"><SPAN CLASS=H136>public class</span> <SPAN CLASS=H143>SomeClass</span>
    <SPAN CLASS=H138>{</span>
        <SPAN CLASS=H136>public static</span> <SPAN CLASS=H139>void</span> <SPAN CLASS=H135>main</span><SPAN CLASS=H138>(String[] argv)</span> <SPAN CLASS=H136>throws</span> IOException
        <SPAN CLASS=H138>{
            URL url =</span> <SPAN CLASS=H136>new</span> URL<SPAN CLASS=H138>(</span><SPAN CLASS=H131>&quot;https://some.url.com/index.html&quot;</span><SPAN CLASS=H138>);
            Vector&lt;HTMLNode&gt; page = HTMLPage.</span><SPAN CLASS=H132>getPageTokens</span><SPAN CLASS=H138>(url,</span> <SPAN CLASS=H136>false</span><SPAN CLASS=H138>);</span>
    
            <SPAN CLASS=H136>for</span> <SPAN CLASS=H138>(HTMLNode n : page)</span>
                <SPAN CLASS=H136>if</span> <SPAN CLASS=H138>(n.</span><SPAN CLASS=H132>str</span><SPAN CLASS=H138>.</span><SPAN CLASS=H132>contains</span><SPAN CLASS=H138>(</span><SPAN CLASS=H131>&quot;FOO&quot;</span><SPAN CLASS=H138>))
                    System.</span><SPAN CLASS=H132>out</span><SPAN CLASS=H138>.</span><SPAN CLASS=H132>println</span><SPAN CLASS=H138>(n);
        }
    }</span>
    </pre></div>

        See that the STYLE=... attribute within each SPAN have been replaced by a CLASS=... attribute instead. It is important to remember to retrieve the CSS CLASS definitions for this change, or the hiliting will not be visible!

        IN FACT:

        • A total of 48 STYLE attributes were removed and replaced with CLASS attributes.

        • Of that: 34 <SPAN> and </SPAN> elements were removed completely.

        • The original String-Length of that snippet was 2616 Characters, but the shortened snippet has been cut in half to 1382 Characters
        Parameters:
        page - This should be Vectorized-HTML that was produced by the 'prettyPrintScrapeToVector' method.
        styleTypeParam - This has to be the same value for 'styleTypeParam' that was used to convert the HTML for the 'page' parameter. If a different 'Style Type' is accidentally passed to this method, none of the HTML <SPAN> elements will be replaced.
        Returns:
        The original page Vector<HTMLNode>
        Throws:
        java.lang.IllegalArgumentException - If the passed 'styleTypeParam' is not recognized by the internal list of available 'Style Types'.
        Code:
        Exact Method Body:
         if (! isStyleType(styleTypeParam)) throw new IllegalArgumentException(
     "The passed 'styleTypeParam' value [" + styleTypeParam + "] is not a registered " +
     "Style Type Code known by this class."
 );

 // Lazy
 if (allMaps == null)
 {
     allMaps = 
         (TreeMap<String, TreeMap<String, TagNode>>)
         LFEC.readObjectFromFile_JAR
             (HiLiteMe.class, "data-files/HLMSpans.tmdat", true, TreeMap.class);
 }

 // Retrieves the a TreeMap that maps STYLE-ATTRIBUTE values (retrieved from <SPAN>
 // elements) directly to replacement TagNode's that use a CLASS=... instead.

 TreeMap<String, TagNode> map = allMaps.get(styleTypeParam);

 // This should never happen, but if it does, this error is better than NullPointerException
 if (map == null) throw new InternalError(
     "The style parameter you have passed IS VALID, but unfortunately, the map file for " +
     "that style is not loading properly."
 );

 // Retrieve all HTML "<SPAN STYLE=...>" elements. Specifically, retrieve all <SPAN>
 // that actually contain a STYLE attribute.  Afterwards, retrieve all of the values of
 // that style-element, and store that in the 'styles' String-Array.

 int[]       spans       = InnerTagFind.all(page, "span", "style");
 String[]    styles      = Attributes.retrieve(page, spans, "style");
 TagNode     replacement = null;

 // Minor optimization that's inside the data-file.  The "STYLE='color: #123456;...'
 // eliminates the leading characters "color: #" in the style-attribute.  Here we need
 // to do the EXACT-SAME removal, or else the lookup-table will not find that
 // style-attribute.

 for (int i=0; i < styles.length; i++)
     if (styles[i].startsWith("color: #"))
         styles[i] = styles[i].substring("color: #".length());

 // Replace all of the <SPAN STYLE=...> TagNode's with the simplified TagNode's.

 for (int i=0; i < spans.length; i++)
     if ((replacement = map.get(styles[i])) != null)
         page.setElementAt(replacement, spans[i]);

 removeDuplicateColorSpans(page);

 return page;