Module: CodeRay

Defined in:
lib/coderay.rb,
lib/coderay/style.rb,
lib/coderay/encoder.rb,
lib/coderay/scanner.rb,
lib/coderay/scanners/c.rb,
lib/coderay/encoders/div.rb,
lib/coderay/encoders/xml.rb,
lib/coderay/encoders/_map.rb,
lib/coderay/encoders/null.rb,
lib/coderay/encoders/span.rb,
lib/coderay/encoders/text.rb,
lib/coderay/encoders/yaml.rb,
lib/coderay/scanners/_map.rb,
lib/coderay/scanners/ruby.rb,
lib/coderay/styles/cycnus.rb,
lib/coderay/styles/murphy.rb,
lib/coderay/encoders/count.rb,
lib/coderay/encoders/debug.rb,
lib/coderay/encoders/tokens.rb,
lib/coderay/scanners/delphi.rb,
lib/coderay/encoders/html/css.rb,
lib/coderay/encoders/statistic.rb,
lib/coderay/scanners/plaintext.rb,
lib/coderay/encoders/html/output.rb,
lib/coderay/encoders/html/classes.rb,
lib/coderay/scanners/ruby/patterns.rb,
lib/coderay/encoders/html/numerization.rb

Overview

CodeRay Library

$Id: coderay.rb 96 2005-11-13 06:24:54Z murphy $

CodeRay is a Ruby library for syntax highlighting.

I try to make CodeRay easy to use and intuitive, but at the same time fully featured, complete, fast and efficient.

See README.

It consists mainly of

  • the main engine: CodeRay (Scanners::Scanner, Tokens/TokenStream, Encoders::Encoder), PluginHost

  • the scanners in CodeRay::Scanners

  • the encoders in CodeRay::Encoders

Here’s a fancy graphic to light up this gray docu:

Documentation

See CodeRay, Encoders, Scanners, Tokens.

Usage

Remember you need RubyGems to use CodeRay. Run Ruby with -rubygems option if required.

Highlight Ruby code in a string as html

require 'coderay'
print CodeRay.scan('puts "Hello, world!"', :ruby).html

# prints something like this:
puts <span class="s">&quot;Hello, world!&quot;</span>

Highlight C code from a file in a html div

require 'coderay'
print CodeRay.scan(File.read('ruby.h'), :c).div
print CodeRay.scan_file('ruby.h').html.div

You can include this div in your page. The used CSS styles can be printed with

% ruby -rcoderay -e "print CodeRay::Encoders[:html]::CSS"

Highlight without typing too much

If you are one of the hasty (or lazy, or extremely curious) people, just run this file:

% ruby -rubygems coderay.rb

If the output was to fast for you, try

% ruby -rubygems coderay.rb > example.html

and look at the file it created.

CodeRay Module

The CodeRay module provides convenience methods for the engine.

  • The lang and format arguments select Scanner and Encoder to use. These are simply lower-case symbols, like :python or :html.

  • All methods take an optional hash as last parameter, options, that is send to the Encoder / Scanner.

  • Input and language are always sorted in this order: code, lang.

(This is in alphabetical order, if you need a mnemonic ;)

You should be able to highlight everything you want just using this methods; so there is no need to dive into CodeRay’s deep class hierarchy.

The exmaples in the demo/ directory demonstrate common cases using this interface.

Basic Access Ways

Read this to get a general view what CodeRay provides.

Scanning

Scanning means analysing an input string, splitting it up into Tokens. Each Token knows about what type it is: string, comment, class name, etc.

Each lang (language) has its own Scanner; for example, :ruby code is handled by CodeRay::Scanners::RubyScanner.

CodeRay.scan

Scan a string in a given language into Tokens. This is the most common method to use.

CodeRay.scan_file

Scan a file and guess the language using FileType.

The Tokens object you get from these methods can encode itself; see Tokens.

Encoding

Encoding means compiling Tokens into an output. This can be colored HTML or LaTeX, a textual statistic or just the number of non-whitespace tokens.

Each Encoder provides output in a specific format, so you select Encoders via formats like :html or :statistic.

CodeRay.encode

Scan and encode a string in a given language.

CodeRay.encode_tokens

Encode the given tokens.

CodeRay.encode_file

Scan a file, guess the language using FileType and encode it.

Streaming

Streaming saves RAM by running Scanner and Encoder in some sort of pipe mode; see TokenStream.

CodeRay.scan_stream

Scan in stream mode.

All-in-One Encoding

CodeRay.encode

Highlight a string with a given input and output format.

Instanciating

You can use an Encoder instance to highlight multiple inputs. This way, the setup for this Encoder must only be done once.

CodeRay.encoder

Create an Encoder instance with format and options.

There is no CodeRay.scanner method because Scanners are bound to an input string on creation; you can’t re-use them with another string.

The scanning methods provide more flexibility; we recommend to use these.

Defined Under Namespace

Modules: Encoders, Scanners, Streamable, Styles Classes: NotStreamableError

Constant Summary collapse

Version =

Version: Major.Minor.Teeny[.Revision] Major: 0 for pre-release Minor: odd for beta, even for stable Teeny: development state Revision: Subversion Revision number (generated on rake)

'0.6.0'

Class Method Summary collapse

Class Method Details

.encode(code, lang, format, options = {}) ⇒ Object

Encode a string.

This scans code with the the Scanner for lang and then encodes it with the Encoder for format. options will be passed to the Encoder.

See CodeRay::Encoder.encode



206
207
208
 
# File 'lib/coderay.rb', line 206

def encode code, lang, format, options = {}
  encoder(format, options).encode code, lang, options
end

.encode_file(filename, format, options = {}) ⇒ Object

Encodes filename (a path to a code file) with the Scanner for lang.

See CodeRay.scan_file. Notice that the second argument is the output format, not the input language.

Example:

require 'coderay'
page = CodeRay.encode_file 'some_c_code.c', :html



241
242
243
244
 
# File 'lib/coderay.rb', line 241

def encode_file filename, format, options = {}
  tokens = scan_file filename, :auto, get_scanner_options(options)
  encode_tokens tokens, format, options
end

.encode_stream(code, lang, format, options = {}) ⇒ Object

Encode a string in Streaming mode.

This starts scanning code with the the Scanner for lang while encodes the output with the Encoder for format. options will be passed to the Encoder.

See CodeRay::Encoder.encode_stream



195
196
197
 
# File 'lib/coderay.rb', line 195

def encode_stream code, lang, format, options = {}
  encoder(format, options).encode_stream code, lang, options
end

.encode_tokens(tokens, format, options = {}) ⇒ Object

Encode pre-scanned Tokens. Use this together with CodeRay.scan:

require 'coderay'

# Highlight a short Ruby code example in a HTML span
tokens = CodeRay.scan '1 + 2', :ruby
puts CodeRay.encode_tokens(tokens, :span)



229
230
231
 
# File 'lib/coderay.rb', line 229

def encode_tokens tokens, format, options = {}
  encoder(format, options).encode_tokens tokens, options
end

.encoder(format, options = {}) ⇒ Object

Finds the Encoder class for format and creates an instance, passing options to it.

Example:

require 'coderay'

stats = CodeRay.encoder(:statistic)
stats.encode("puts 17 + 4\n", :ruby)

puts '%d out of %d tokens have the kind :integer.' % [
  stats.type_stats[:integer].count,
  stats.real_token_count
]
#-> 2 out of 4 tokens have the kind :integer.



270
271
272
 
# File 'lib/coderay.rb', line 270

def encoder format, options = {}
  Encoders[format].new options
end

.get_scanner_options(options) ⇒ Object

Extract the options for the scanner from the options hash.

Returns an empty Hash if :scanner_options is not set.

This is used if a method like CodeRay.encode has to provide options for Encoder and scanner.



280
281
282
 
# File 'lib/coderay.rb', line 280

def get_scanner_options options
  options.fetch :scanner_options, {}
end

.highlight(code, lang, options = { :css => :class }, format = :div) ⇒ Object

Highlight a string into a HTML <div>.

CSS styles use classes, so you have to include a stylesheet in your output.

See encode.



216
217
218
 
# File 'lib/coderay.rb', line 216

def highlight code, lang, options = { :css => :class }, format = :div
  encode code, lang, format, options
end

.highlight_file(filename, options = { :css => :class }, format = :div) ⇒ Object

Highlight a file into a HTML <div>.

CSS styles use classes, so you have to include a stylesheet in your output.

See encode.



252
253
254
 
# File 'lib/coderay.rb', line 252

def highlight_file filename, options = { :css => :class }, format = :div
  encode_file filename, format, options
end

.scan(code, lang, options = {}, &block) ⇒ Object

Scans the given code (a String) with the Scanner for lang.

This is a simple way to use CodeRay. Example:

require 'coderay'
page = CodeRay.scan("puts 'Hello, world!'", :ruby).html

See also demo/demo_simple.



153
154
155
156
 
# File 'lib/coderay.rb', line 153

def scan code, lang, options = {}, &block
  scanner = Scanners[lang].new code, options, &block
  scanner.tokenize
end

.scan_file(filename, lang = :auto, options = {}, &block) ⇒ Object

Scans filename (a path to a code file) with the Scanner for lang.

If lang is :auto or omitted, the CodeRay::FileType module is used to determine it. If it cannot find out what type it is, it uses CodeRay::Scanners::Plaintext.

Calls CodeRay.scan.

Example:

require 'coderay'
page = CodeRay.scan_file('some_c_code.c').html



169
170
171
172
173
174
175
176
 
# File 'lib/coderay.rb', line 169

def scan_file filename, lang = :auto, options = {}, &block
  file = IO.read filename
  if lang == :auto
    require 'coderay/helpers/filetype'
    lang = FileType.fetch filename, :plaintext, true
  end
  scan file, lang, options = {}, &block
end

.scan_stream(code, lang, options = {}, &block) ⇒ Object

Scan the code (a string) with the scanner for lang.

Calls scan.

See CodeRay.scan.



183
184
185
186
 
# File 'lib/coderay.rb', line 183

def scan_stream code, lang, options = {}, &block
  options[:stream] = true
  scan code, lang, options, &block
end