Rack::Codehighlighter middleware

The Rack::Codehighlighter is a middleware which allows for easy connecting a code highlighter of somebody's choice to an HTML page containing pieces of programming code. Parameters to Rack::Codehighlighter are: the name of a highlighter and a specification of how to find the pieces of code in the page.

It supports the most popular Ruby code highlighters of today:

• ultraviolet
• coderay
• syntax
• pygments (through rygments)

As well as

• Unofficial Pygments API

To ease testing it implements censor highlighter.

How it works?

Rack::Codehighlighter looks for code blocks to be highlighted in the HTML produced by your application. For each block found it calls requested highlighter.

Installing and Usage

Install the gem with:

gem install rack-codehighlighter

In order for the highlighting to show up, you’ll need to include a highlighting stylesheet. For example stylesheets you can look at stylesheets in the examples/public/stylesheets directory.

Rails 2

In order to use, include the following code in a Rails application config/environment.rb file:

require 'coderay'               # get one of supported highlighters
require 'rack/codehighlighter'

Rails::Initializer.run do |config|
  config.gem 'coderay'
  config.gem 'rack-codehighlighter'

  config.middleware.use Rack::Codehighlighter, :coderay, :element => "pre", :pattern => /\A:::(\w+)\s*\n/
end

Rails 3

In order to use, update Gemfile with:

gem 'coderay'
gem 'rack-codehighlighter', :require => 'rack/codehighlighter'

Next, add Rack::Codehighlighter to the application middleware stack, updating config/environments/development.rb and config/environments/production.rb with:

config.middleware.use Rack::Codehighlighter, :coderay,
  :element => "pre", :pattern => /\A:::(\w+)\s*(\n|
)/i, :logging => false

(see Rails on Rack).

Any Rack application

The rack-codehighlighter gem can be used with any Rack application, for example with a Sinatra application. If your application includes a rackup file or uses Rack::Builder to construct the application pipeline, simply require and use as follows:

require 'coderay'  # get one of supported highlighters
require 'rack/codehighlighter'

use Rack::Codehighlighter, :coderay, :element => "pre", :pattern => /\A:::(\w+)\s*\n/
run app

Rack::Codehighlighter by an example

To colorize code in pre elements with well known coderay highlighter use the following:

use Rack::Codehighlighter, :coderay, :element => "pre", :pattern => /\A:::(\w+)\s*\n/

The first parenthesized expression from the pattern /\A:::(\w+)\s*\n/ will be used to match the language name. For example, from the pre element below:

<pre>:::ruby
puts "hello world"
</pre>

the ruby name is extracted.

To find the appropriate name to use for programming language, look at the lists below.

Next, the matched element is removed and the second line is passed to coderay highlighter for processing.

The highlighted code returned by the coderay highlighter is wrapped with pre element with attributes appropriate for the codehighlighter used.

More examples

In examples displayed below, the default value of each option is used.

Coderay:

use Rack::Codehighlighter, :coderay,
  :element => "pre", :pattern => /\A:::(\w+)\s*(\n|
)/i, :logging => false

Ultraviolet:

use Rack::Codehighlighter, :ultraviolet, :theme => "dawn", :lines => false,
  :element => "pre", :pattern => /\A:::(\w+)\s*(\n|
)/i, :logging => false

or

use Rack::Codehighlighter, :ultraviolet, :markdown => true,
  :theme => "minimal_theme", :lines => false, :element => "pre>code",
  :pattern => /\A:::([-_+\w]+)\s*(\n|
)/, :logging => false,
  :themes => {"vibrant_ink" => ["ruby"], "upstream_sunburst" => ["objective-c", "java"]}

Unofficial Pygments API (uses web service, no dependencies):

use Rack::Codehighlighter, :pygments_api, :element => "pre",
   :pattern => /\A:::([-_+\w]+)\s*(\n|
)/, :logging => false

Rygments (with the rygments gem):

use Rack::Codehighlighter, :rygments, :element => "pre",
   :pattern => /\A:::([-_+\w]+)\s*(\n|
)/, :logging => false

Pygments (with the pygments.rb gem):

use Rack::Codehighlighter, :pygments, :element => "pre>code",
    pattern => /\A:::([-_+\w]+)\s*(\n|
)/, :logging => false,
    options => { :linenos => 'inline' }

(the options hash can accept standard Pygments configuration options).

Syntax:

use Rack::Codehighlighter, :syntax,
  :element => "pre", :pattern => /\A:::(\w+)\s*(\n|
)/i, :logging => false

Censor:

use Rack::Codehighlighter, :censor, :reason => "[[--  ugly code removed  --]]",
  :element => "pre", :pattern => /\A:::(\w+)\s*(\n|
)/i, :logging => false

Markdown, Maruku and RDiscount processors, the code is wrapped with pre>code. To remove this extra one level of nesting the :markdown option should be used:

use Rack::Codehighlighter, :coderay, :markdown => true,
  :element => "pre>code", :pattern => /\A:::(\w+)\s*(\n|
)/i, :logging => false

Remark: Within pre tag, HAML replaces each new line characters with the 
 entity (line feed) so that it can ensure that it doesn't adversely affect indentation. This change confuses both rack-codehighlighter and the highlighters themselves (e.g. Ultraviolet and Coderay). So, to support pre tags as rendered by HAML, 
 was added to the default pattern.

The examples directory contains several rackup files. Each rackup file uses a different highlighter. Try, for example, the Pygments highlighter:

rackup coderay.ru

The results could be checked at http://localhost:9292.

Try it!

A simple Copy & Paste example.

# example.rb

require 'rubygems'
require 'sinatra'
require 'rack/codehighlighter'

use Rack::Codehighlighter, :censor, :reason => '[[--difficult code removed--]]'

get "/" do
  erb :hello
end

__END__
@@ hello
<h3>Fibonacci numbers in Ruby</h3>
<pre>:::ruby
def fib(n)
  if n < 2
    1
  else
    fib(n-2) + fib(n-1)
  end
end
</pre>

Run the example with:

ruby example.rb

and check the results at http://localhost:4567.

Supported highlighters

These currently include: Syntax (fast), Coderay (very fast), Ultraviolet (slow, but highlights almost any language), Pygments (via the rygments gem or unofficial api).

Syntax

Languages supported by Syntax:

• xml
• ruby

Coderay

Languages supported by the coderay library:

• C, C++, CSS
• Delphi, diff
• ERB+HTML, Groovy (beta), HTML
• Java, JavaScript, JSON
• Nitro-XHTML, PHP, Python
• Ruby, Scheme (beta), SQL
• XML, YAML

Ultraviolet and 1.8 tree of the Ruby programming language

The ultraviolet gem needs oniguruma regexp library.

On Fedora install the library with:

sudo yum install oniguruma oniguruma-devel

For installation instruction of the oniguruma library from sources, see Carbonica

Now, install the gem:

sudo gem install ultraviolet

Ultraviolet and 1.9 tree of the Ruby programming language

Install a fixed version of the Ultraviolet syntax highlighting library for the 1.9 tree of the Ruby programming language from here.

See also Ultraviolet themes gallery

Ultraviolet supports almost any language:

• actionscript, active4d, active4d_html, active4d_ini, active4d_library, ada, antlr, apache, applescript, asp, asp_vb.net
• bibtex, blog_html, blog_markdown, blog_text, blog_textile, build, bulletin_board
• c, c++, cake, camlp4, cm, coldusion, context_free, cs, css, css_experimental, csv
• d, diff, dokuwiki, dot, doxygen, dylan
• eiffel, erlang, f-script, fortran, fxscript
• greasemonkey, gri, groovy, gtd, gtdalt
• haml, haskell, html, html-asp, html_django, html_for_asp.net, html_mason, html_rails, html_tcl
• icalendar, inform, ini, installer_distribution_script, io
• java, javaproperties, javascript, javascript_+_prototype, javascript_+_prototype_bracketed, jquery_javascript, json
• languagedefinition, latex, latex_beamer, latex_log, latex_memoir, lexflex, lighttpd, lilypond, lisp, literate_haskell, logo, logtalk, lua
• m, macports_portfile, mail, makefile, man, markdown, mediawiki, mel, mips, mod_perl, modula-3, moinmoin, mootools, movable_type, multimarkdown
• objective-c, objective-c++, ocaml, ocamllex, ocamlyacc, opengl
• pascal, perl, php, plain_text, pmwiki, postscript, processing, prolog, property_list, python, python_django
• qmake_project, qt_c++, quake3_config
• r, r_console, ragel, rd_r_documentation, regexp, regular_expressions_oniguruma, regular_expressions_python, release_notes remind, restructuredtext, rez, ruby, ruby_experimental, ruby_on_rails
• s5, scheme, scilab, setext, shell-unix-generic, slate, smarty, sql, sql_rails, ssh-config, standard_ml, strings_file, subversion_commit_message, sweave, swig
• tcl, template_toolkit, tex, tex_math, textile, tsv, twiki, txt2tags
• vectorscript
• xhtml_1.0, xml, xml_strict, xsl
• yaml, yui_javascript