ColourCode: Creating Formatters

Bored of plain old HTML, want the output in something jazzy for your latest app, or maybe you want to print it into a book using LaTeX, then what you can do is write your own Formatter for ColourCode. Its really simple, here's how

Getting Started

All Formatters are stored in the data/formatters directory in the root ColourCode directory. Your formatter should be named <format>formatter.rb where <format> is the string that the user will pass to ColourCode. For example if the formatter should be invoked by passing "-f latex" then you should name it latexformatter.rb.

Futhermore all formatters are expected to subclasses of class Formatter(data/formatters/formatter.rb). They should overload the methods defined by Formatter wherever necessary. The best thing to do would be to copy class Formatter and edit it, or take the template here (which is almost a direct copy of class Formatter)


class CustomFormatter < Formatter
    def format_keywords(token)
    end
    
    def format_datatypes(token)
    end
    
    def format_builtins(token)
    end
    
    def format_objects(token)
    end

    def begin_string
    end
    
    def end_string
    end
    
    def begin_comment
    end
    
    def end_comment
    end

    def begin_bold
    end
    
    def end_bold
    end

    def begin_italics
    end

    def end_italics
    end
    
    def begin_document(title)
    end
    
    def end_document()
    end
    
    def linebreak
        return "\n"
    end
    
    def escape(token)
        return token
    end

    def line_wrap(line, number)
        line
    end
end

In addition you should insert the following code at the top of your file

require 'utilities'
require FORMATTER_DIR + 'formatter'

You are encouraged to take a look at HTMLFormatter(data/formatters/htmlformatter.rb) to see how to create custom formatters.

Loading your class

ColourCode expects that a global function formatter_init is defined which returns the class (and not an instance of the class). For example, if your formatter is called LaTeXFormatter, then your function would be:

def formatter_init
    return LaTeXFormatter
end

Line numbers

The method line_wrap is called by ColourCode for every line. Your class should check the property @linenumbers (true/false) to decide whether to insert line numbers or not. You may also do other handling of the line before returning it.

Beginning the document

ColourCode will call the begin_document and pass the title of the page. begin_document should return any contents/markup required to begin a document for that formatter style along with the title in the right place.

Highlighting tokens

All the begin_ and end_ methods with suffixes keywords, datatypes, builtins, objects, string and comment should return the token with proper highlighting. Formatters can recieve colours in RGB format by calling Utilities.getColour with the type converted to a symbol. This will return a list in [R, G, B] format. Again, for the best understanding of what I'm talking about, you should look at the HTML Formatter.