Class Pygmentize

  • All Implemented Interfaces:
    java.lang.Cloneable
    public class Pygmentize
extends OSCommands
    Java-Adapter for a Python-Tool which Hi-Lites Source Code.

    Visit http://Pygments.org for details.

    Command-Line Help Message:
    The following block of text has been copied directly from the output of the pygmentize command. It will shall hopefully provide some light into what it is doing. 

    usage: pygmentize [-l LEXER | -g] [-F FILTER[:options]] [-f FORMATTER]
                  [-O OPTION=value[,OPTION=value,...]] [-P OPTION=value]
                  [-o OUTPUTFILE] [-v] [-s] [-x] [--json]
                  [-S STYLE -f formatter | -L [WHAT ...] | -N FILENAME | -C |
                  -H NAME TYPE | -V | -h] [-a ARG]
                  [INPUTFILE]

Highlight an input file and write the result to an output file.

Main operation:
  -l LEXER      Specify the lexer to use. (Query names with -L.) If not given
                and -g is not present, the lexer is guessed from the filename.
  -g            Guess the lexer from the file contents, or pass through as
                plain text if nothing can be guessed.
  -F FILTER[:options]
                Add a filter to the token stream. (Query names with -L.)
                Filter options are given after a colon if necessary.
  -f FORMATTER  Specify the formatter to use. (Query names with -L.) If not
                given, the formatter is guessed from the output filename, and
                defaults to the terminal formatter if the output is to the
                terminal or an unknown file extension.
  -O OPTION=value[,OPTION=value,...]
                Give options to the lexer and formatter as a comma-separated
                list of key-value pairs. Example: `-O bg=light,python=cool`.
  -P OPTION=value
                Give a single option to the lexer and formatter - with this
                you can pass options whose value contains commas and equal
                signs. Example: `-P "heading=Pygments, the Python
                highlighter"`.
  -o OUTPUTFILE
                Where to write the output. Defaults to standard output.
  INPUTFILE     Where to read the input. Defaults to standard input.

Operation flags:
  -v            Print a detailed traceback on unhandled exceptions, which is
                useful for debugging and bug reports.
  -s            Process lines one at a time until EOF, rather than waiting to
                process the entire file. This only works for stdin, only for
                lexers with no line-spanning constructs, and is intended for
                streaming input such as you get from `tail -f`. Example usage:
                `tail -f sql.log | pygmentize -s -l sql`.
  -x            Allow custom lexers and formatters to be loaded from a .py
                file relative to the current working directory. For example,
                `-l ./customlexer.py -x`. By default, this option expects a
                file with a class named CustomLexer or CustomFormatter; you
                can also specify your own class name with a colon (`-l
                ./lexer.py:MyLexer`). Users should be very careful not to use
                this option with untrusted files, because it will import and
                run them.
  --json        Output as JSON. This can be only used in conjunction with -L.

Special modes - do not do any highlighting:
  -S STYLE -f formatter
                Print style definitions for STYLE for a formatter given with
                -f. The argument given by -a is formatter dependent.
  -L [WHAT ...]
                List lexers, formatters, styles or filters -- give additional
                arguments for the thing(s) you want to list (e.g. "styles"),
                or omit them to list everything.
  -N FILENAME   Guess and print out a lexer name based solely on the given
                filename. Does not take input or highlight anything. If no
                specific lexer can be determined, "text" is printed.
  -C            Like -N, but print out a lexer name based solely on a given
                content from standard input.
  -H NAME TYPE  Print detailed help for the object  of type ,
                where  is one of "lexer", "formatter" or "filter".
  -V            Print the package version.
  -h, --help    Print this help.
  -a ARG        Formatter-specific additional argument for the -S (print style
                sheet) mode.
    See Also:
    OSCommands, OSJavaPipe


    • Field Detail

      • CODE_TYPES

        🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static final ReadOnlyList<java.lang.String> CODE_TYPES
        Code:
        Exact Field Declaration Expression:
         public static final ReadOnlyList<String> CODE_TYPES = new ReadOnlyArrayList<>(
         "java", "html", "js", "css", "json", "properties", "xml", "py", "c", "cpp", "csharp", "go",
         "php", "ruby", "bash", "sh", "sql", "yaml", "toml", "ini", "docker", "make", "gradle",
         "swift", "kotlin", "rust", "scala", "perl", "r", "ts", "tsx", "jsx", "md", "txt"
     );

    • Method Detail

      • main

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static void main​(java.lang.String[] argv)
                 throws java.io.IOException
        Throws:
        java.io.IOException
        Code:
        Exact Method Body:
         if (argv.length != 1)
 {
     System.out.println("You must pass the file-name of a Java-File");
     System.exit(1);
 }

 final Pygmentize        p = new Pygmentize();
 final String            f = FileRW.loadFileToString(argv[0]);
 final Vector<HTMLNode>  h = p.hiLite(f, "java", true, (byte) 1);
 final String            s = Util.pageToString(h);

 System.out.println(s);

      • clone

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public Pygmentize clone()
        Description copied from class: OSCommands
        Creates a clone of 'this' instance. Though unlikely of much use, this could conceivably have some function if similar, but non-identical, output mechanisms were being used.
        Specified by:
        clone in class OSCommands
        Returns:
        An exact copy of 'this' instance - one in which all output Appendable's have had their references copied into the new instance.
        Code:
        Exact Method Body:
         throw new RuntimeException(new CloneNotSupportedException());

      • hiLite

        🡅  🡇  ⇈  ⮫     External-Java:   ⮫ 🗕  🗗  🗖 
        public java.util.Vector<HTMLNode> hiLite​(java.lang.String codeText,
                                         java.lang.String codeTypeParam,
                                         boolean useLineNumbers,
                                         byte styleNum)
                                  throws java.io.IOException
        Throws:
        java.io.IOException
        Code:
        Exact Method Body:
         Objects.requireNonNull(codeText,        "'codeText' Parameter has been passed null.");
 Objects.requireNonNull(codeTypeParam,   "'codeTypeParam' Parameter has been passed null.");

 final String dashO =
     "classprefix=H" + styleNum + "-" +
     (useLineNumbers ? ",linenos=table" : "");

 final String[] cmdArr =
     { "pygmentize", "-l", codeTypeParam, "-f", "html",  "-O", dashO };

 // This "Pipes" the input to the CLI Command
 this.osExtras           = new OSExtras();
 this.osExtras.javaPipe  = new OSJavaPipe(codeText);

 // Run Python's "pygmentize" - downloaded via 'pip' from Pygments.org
 final OSResponse osr = super.printAndRun(cmdArr);

 if (osr.response != 0) throw new PygmentizeException(
     "The O/S Process for 'pygmentize' has returned a non-zero Status\n" +
     THROW.HORIZ_SEP +
     "OSResponse.response: " +       osr.response + '\n' +
     "OSResponse.errorOutpu:\n" +    osr.errorOutput + '\n' +
     THROW.paramsAsStr(codeText, codeTypeParam, styleNum, useLineNumbers)
 );

 try 
 {
     final String html               = osr.standardOutput;
     final Vector<HTMLNode> retVec   = HTMLPage.getPageTokens(html, false);

     CleanHTML.clean(retVec, useLineNumbers);

     return retVec;
 }

 catch (Exception e) 
 {
     throw new PygmentizeException(
         "An error has occured while attempting to parse and simplify the returned HTML" +
         THROW.paramsAsStr(codeText, codeTypeParam, styleNum, useLineNumbers),
         e
     );
 }

      • hiLite

        🡅  ⇈  ⮫ 🗕  🗗  🗖 
        public java.util.Vector<HTMLNode> hiLite​(java.lang.String codeText,
                                         java.lang.String codeTypeParam,
                                         boolean includeLineNumbers,
                                         byte styleNum,
                                         HiLiteCache cache)
                                  throws java.io.IOException
        Throws:
        java.io.IOException
        Code:
        Exact Method Body:
         Objects.requireNonNull(codeText,        "'codeText' Parameter has been passed null.");
 Objects.requireNonNull(codeTypeParam,   "'codeTypeParam' Parameter has been passed null.");
 Objects.requireNonNull(cache,           "'cache' Parameter has been passed null.");

 // FIRST: Check the Cache, to see if the exact String has been hilited!
 final String cached =
     cache.get(codeText, codeTypeParam, includeLineNumbers, styleNum);

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


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

 final Vector<HTMLNode> html =
     this.hiLite(codeText, codeTypeParam, includeLineNumbers, styleNum);

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

 return html;