README

Syntaxi is a class for formatting code blocks in your HTML. It can:

• Add line numbers
• Wrap long lines automatically
• Perform syntax coloring using Jamis Buck’s Syntax gem

Installation

Installing Syntaxi is as easy as installing the gem. From your command line run the following:

  gem install syntaxi

This will download and install Syntaxi and Jamis Buck’s Syntax gem.

Syntaxi requires the Syntax library to do syntax coloring, and will not function without it. For more information on Syntax, visit syntax.rubyforge.org.

How to Write your Code Block

In order for Syntaxi to do its magic, you’ll need to write your code blocks like this:

  [code lang="ruby"]
  def foo
    puts 'bar'
  end
  [/code]

The square bracket syntax allows Syntaxi to work seamlessly in HTML, Markdown, and Textile alike. The lang attribute specifies the language of the code block.

How to Process the Text

Having Syntaxi format your code containing the special code blocks is easy. Lets say your text is stored in text. To format this text simply do the following:

  require 'syntaxi'
  formatted_text = Syntaxi.new(text).process

Syntax coloring

If the lang attribute you specified in your opening code block tag is recognized by Jamis Buck’s Syntax gem, the block will have syntax coloring applied to it automatically. See the documentation for Syntax to learn more about how to style the different spans it produces.

Line Numbers

Syntaxi can also add line numbers to your code blocks. It can do this in two different ways:

• Inline line numbering will add line numbers at the beginning of each line.
• Floating line numbering will create a <div> to contain the line numbers and float that <div> left, so that selecting text from the code block will select only the code, and not the line numbers.

By default, line numbering is set to inline. To change the line number method, simply call line_number_method= like so:

  Syntaxi::line_number_method = 'floating'

Valid values are ‘none’, ‘inline’, and ‘floating’

Line Wrap

Because your code blocks will often have lines that are longer than the available width, Syntaxi can wrap long lines for you. If possible the line break will be done on a space. No line numbers will appear on the wrapped portions of long lines (but subsequent lines will still have the right line numbers).

By default, line wrap is enabled and wraps on column 60. To disable line wrap, simply use wrap_enabled= like this:

  Syntaxi::wrap_enabled = false

To change the column on which to wrap, call wrap_at_column= like this:

  Syntaxi::wrap_at_column = 70

Where to set the Options

Since the configuration options are stored as class variables, you need only change them once, and all future instances of Syntaxi will use the new values. If your entire application will use the same values, simply set the values to your liking at the beginning of execution. In Ruby on Rails, an ideal place to do this is in [RAILS_ROOT]/config/environment.rb. It would look something like this:

  require 'syntaxi'
  Syntaxi::line_number_method = 'floating'
  Syntaxi::wrap_enabled = false
  Syntaxi::wrap_at_column = 70