Skip to content

Latest commit

 

History

History
269 lines (183 loc) · 8.13 KB

README.markdown

File metadata and controls

269 lines (183 loc) · 8.13 KB
Raw

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

As well as

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:

sudo 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

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

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:

gem 'coderay'       # get one of supported highlighters 
require 'coderay'   
       
gem 'rack-codehighlighter'
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|&#x000A;)/i, :logging => false

Ultraviolet:

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

or

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

Unofficial Pygments API:

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

Syntax:

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

Censor:

use Rack::Codehighlighter, :censor, :reason => "[[--  ugly code removed  --]]",
  :element => "pre", :pattern => /\A:::(\w+)\s*(\n|&#x000A;)/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|&#x000A;)/i, :logging => false

Remark: Within pre tag, HAML replaces each new line characters with the &#x000A; 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, &#x000A; was added to the default pattern.

The examples directory contains several rackup files. Each rackup file uses a different highlighter. Install the shotgun gem and try, for example, the Pygments highlighter:

shotgun pygments.ru

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

Try it!

A simple Copy & Paste example.

# example.rb

require 'rubygems'
gem 'sinatra'
require 'sinatra'
gem 'rack-codehighlighter'
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 results at http://localhost:4567.

Supported highlighters

These currently include: Syntax (fast), Coderay (very fast), Ultraviolet (slow, but highlights almost any language).

Syntax

Languages supported by Syntax:

  • xml
  • ruby

Coderay

Languages supported by Coderay:

  • C, CSS
  • Delphi, diff
  • HTML, RHTML (Rails), Nitro-XHTML
  • Java, JavaScript, JSON
  • Ruby
  • YAML

Ultraviolet

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

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