Module: CodeRay

### Home Classes Methods

### In Files

- lib/coderay.rb
- lib/coderay/duo.rb
- lib/coderay/encoder.rb
- lib/coderay/encoders/_map.rb
- lib/coderay/encoders/comment_filter.rb
- lib/coderay/encoders/count.rb
- lib/coderay/encoders/debug.rb
- lib/coderay/encoders/debug_lint.rb
- lib/coderay/encoders/div.rb
- lib/coderay/encoders/filter.rb
- lib/coderay/encoders/html.rb
- lib/coderay/encoders/html/css.rb
- lib/coderay/encoders/html/numbering.rb
- lib/coderay/encoders/html/output.rb
- lib/coderay/encoders/json.rb
- lib/coderay/encoders/lines_of_code.rb
- lib/coderay/encoders/lint.rb
- lib/coderay/encoders/null.rb
- lib/coderay/encoders/page.rb
- lib/coderay/encoders/span.rb
- lib/coderay/encoders/statistic.rb
- lib/coderay/encoders/terminal.rb
- lib/coderay/encoders/text.rb
- lib/coderay/encoders/token_kind_filter.rb
- lib/coderay/encoders/xml.rb
- lib/coderay/encoders/yaml.rb
- lib/coderay/for_redcloth.rb
- lib/coderay/helpers/file_type.rb
- lib/coderay/helpers/plugin.rb
- lib/coderay/helpers/word_list.rb
- lib/coderay/scanner.rb
- lib/coderay/scanners/_map.rb
- lib/coderay/scanners/c.rb
- lib/coderay/scanners/clojure.rb
- lib/coderay/scanners/cpp.rb
- lib/coderay/scanners/css.rb
- lib/coderay/scanners/debug.rb
- lib/coderay/scanners/delphi.rb
- lib/coderay/scanners/diff.rb
- lib/coderay/scanners/erb.rb
- lib/coderay/scanners/go.rb
- lib/coderay/scanners/groovy.rb
- lib/coderay/scanners/haml.rb
- lib/coderay/scanners/html.rb
- lib/coderay/scanners/java.rb
- lib/coderay/scanners/java/builtin_types.rb
- lib/coderay/scanners/java_script.rb
- lib/coderay/scanners/json.rb
- lib/coderay/scanners/python.rb
- lib/coderay/scanners/raydebug.rb
- lib/coderay/scanners/ruby.rb
- lib/coderay/scanners/ruby/string_state.rb
- lib/coderay/scanners/sass.rb
- lib/coderay/scanners/sql.rb
- lib/coderay/scanners/taskpaper.rb
- lib/coderay/scanners/text.rb
- lib/coderay/scanners/xml.rb
- lib/coderay/scanners/yaml.rb
- lib/coderay/style.rb
- lib/coderay/styles/_map.rb
- lib/coderay/styles/alpha.rb
- lib/coderay/token_kinds.rb
- lib/coderay/tokens.rb
- lib/coderay/tokens_proxy.rb
- lib/coderay/version.rb

### Namespace

- MODULE CodeRay::Encoders
- MODULE CodeRay::FileType
- MODULE CodeRay::ForRedCloth
- MODULE CodeRay::Plugin
- MODULE CodeRay::PluginHost
- MODULE CodeRay::Scanners
- MODULE CodeRay::Styles
- CLASS CodeRay::Duo
- CLASS CodeRay::Tokens
- CLASS CodeRay::TokensProxy
- CLASS CodeRay::WordList

### Methods

- ::coderay_path
- ::encode
- ::encode_file
- ::encode_tokens
- ::encoder
- ::get_scanner_options
- ::highlight
- ::highlight_file
- ::scan
- ::scan_file
- ::scanner

### Class/Module Index

Quicksearch

- CodeRay
- CodeRay::Duo
- CodeRay::Encoders
- CodeRay::Encoders::CommentFilter
- CodeRay::Encoders::Count
- CodeRay::Encoders::Debug
- CodeRay::Encoders::DebugLint
- CodeRay::Encoders::Div
- CodeRay::Encoders::Encoder
- CodeRay::Encoders::Filter
- CodeRay::Encoders::HTML
- CodeRay::Encoders::HTML::Output
- CodeRay::Encoders::JSON
- CodeRay::Encoders::LinesOfCode
- CodeRay::Encoders::Lint
- CodeRay::Encoders::Null
- CodeRay::Encoders::Page
- CodeRay::Encoders::Span
- CodeRay::Encoders::Statistic
- CodeRay::Encoders::Terminal
- CodeRay::Encoders::Text
- CodeRay::Encoders::TokenKindFilter
- CodeRay::Encoders::XML
- CodeRay::Encoders::YAML
- CodeRay::FileType
- CodeRay::ForRedCloth
- CodeRay::Plugin
- CodeRay::PluginHost
- CodeRay::Scanners
- CodeRay::Scanners::C
- CodeRay::Scanners::CPlusPlus
- CodeRay::Scanners::CSS
- CodeRay::Scanners::Clojure
- CodeRay::Scanners::Debug
- CodeRay::Scanners::Delphi
- CodeRay::Scanners::Diff
- CodeRay::Scanners::ERB
- CodeRay::Scanners::Go
- CodeRay::Scanners::Groovy
- CodeRay::Scanners::HAML
- CodeRay::Scanners::HTML
- CodeRay::Scanners::JSON
- CodeRay::Scanners::Java
- CodeRay::Scanners::JavaScript
- CodeRay::Scanners::Python
- CodeRay::Scanners::Raydebug
- CodeRay::Scanners::Ruby
- CodeRay::Scanners::SQL
- CodeRay::Scanners::Sass
- CodeRay::Scanners::Scanner
- CodeRay::Scanners::Taskpaper
- CodeRay::Scanners::Text
- CodeRay::Scanners::XML
- CodeRay::Scanners::YAML
- CodeRay::Styles
- CodeRay::Styles::Alpha
- CodeRay::Styles::Style
- CodeRay::Tokens
- CodeRay::TokensProxy
- CodeRay::WordList
- CodeRay::WordList::CaseIgnoring

No matching classes.

# CodeRay

# CodeRay Library

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, Encoders::Encoder)

- the plugin system: PluginHost, Plugin

- the scanners in CodeRay::Scanners

- the encoders in CodeRay::Encoders

- the styles in CodeRay::Styles

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, unless you have it in your load path. 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

    % coderay_stylesheet

### Highlight without typing too much

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

    % ruby -rubygems /path/to/coderay/coderay.rb > example.html

and look at the file it created in your browser.

# 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 these methods; so there is no need to dive into CodeRay's deep class hierarchy.

The examples 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::Ruby.

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.

## 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.
CodeRay.scanner | Create an Scanner instance for lang, with " as default code.

To make use of CodeRay.scanner, use CodeRay::Scanner::code=.

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

## Reusing Scanners and Encoders

If you want to re-use scanners and encoders (because that is faster), see CodeRay::Duo for the most convenient (and recommended) interface.

### Constants

CODERAY_PATH
TokenKinds

  A Hash of all known token kinds and their associated CSS classes.

VERSION

### Public Class Methods

coderay_path(*path) click to toggle source

Assuming the path is a subpath of lib/coderay/

    # File lib/coderay.rb, line 132
    def self.coderay_path *path
      File.join CODERAY_PATH, *path
    end

encode(code, lang, format, options = {}) click to toggle source

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.

    # File lib/coderay.rb, line 195
    def encode code, lang, format, options = {}
      encoder(format, options).encode code, lang, options
    end

encode_file(filename, format, options = {}) click to toggle source

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

    # File lib/coderay.rb, line 220
    def encode_file filename, format, options = {}
      tokens = scan_file filename, :auto, get_scanner_options(options)
      encode_tokens tokens, format, options
    end

encode_tokens(tokens, format, options = {}) click to toggle source

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)

    # File lib/coderay.rb, line 208
    def encode_tokens tokens, format, options = {}
      encoder(format, options).encode_tokens tokens, options
    end

encoder(format, options = {}) click to toggle source

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.

    # File lib/coderay.rb, line 259
    def encoder format, options = {}
      Encoders[format].new options
    end

get_scanner_options(options) click to toggle source

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.

    # File lib/coderay.rb, line 277
    def get_scanner_options options
      options.fetch :scanner_options, {}
    end

highlight(code, lang, options = { :css => :class }) click to toggle source

Highlight a string into a HTML <div>.

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

See encode.

    # File lib/coderay.rb, line 231
    def highlight code, lang, options = { :css => :class }, format = :div
      encode code, lang, format, options
    end

highlight_file(filename, options = { :css => :class }) click to toggle source

Highlight a file into a HTML <div>.

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

See encode.

    # File lib/coderay.rb, line 241
    def highlight_file filename, options = { :css => :class }, format = :div
      encode_file filename, format, options
    end

scan(code, lang, options = {}) click to toggle source

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.

    # File lib/coderay.rb, line 167
    def scan code, lang, options = {}, &block
      TokensProxy.new code, lang, options, block
    end

scan_file(filename, lang = :auto, options = {}) click to toggle source

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::Text.

Calls CodeRay.scan.

Example:

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

    # File lib/coderay.rb, line 182
    def scan_file filename, lang = :auto, options = {}, &block
      lang = FileType.fetch filename, :text, true if lang == :auto
      code = File.read filename
      scan code, lang, options, &block
    end

scanner(lang, options = {}) click to toggle source

Finds the Scanner class for `lang` and creates an instance, passing `options` to it.

See Scanner.new.

    # File lib/coderay.rb, line 267
    def scanner lang, options = {}, &block
      Scanners[lang].new '', options, &block
    end

[Validate]

Generated with the Darkfish Rdoc Generator 2.