class CodeRay::Encoders::Encoder

Encoder

The Encoder base class. Together with Scanner and Tokens, it forms the highlighting triad.

Encoder instances take a Tokens object and do something with it.

The most common Encoder is surely the HTML encoder (CodeRay::Encoders::HTML). It highlights the code in a colorful html page. If you want the highlighted code in a div or a span instead, use its subclasses Div and Span.

Constants

DEFAULT_OPTIONS: Subclasses are to store their default options in this constant.

Attributes

options[RW]

The options you gave the Encoder at creating.

scanner[RW]

The options you gave the Encoder at creating.

Public Class Methods

const_missing(sym) click to toggle source

If FILE_EXTENSION isn’t defined, this method returns the downcase class name instead.

# File lib/coderay/encoder.rb, line 35
def const_missing sym
  if sym == :FILE_EXTENSION
    (defined?(@plugin_id) && @plugin_id || name[%r\w+$/].downcase).to_s
  else
    super
  end
end

file_extension() click to toggle source

The default file extension for output file of this encoder class.

# File lib/coderay/encoder.rb, line 44
def file_extension
  self::FILE_EXTENSION
end

new(options = {}) click to toggle source

Creates a new Encoder. options is saved and used for all encode operations, as long as you don’t overwrite it there by passing additional options.

Encoder objects provide three encode methods:

encode simply takes a code string and a lang
#encode_tokens expects a tokens object instead

Each method has an optional options parameter. These are added to the options you passed at creation.

# File lib/coderay/encoder.rb, line 66
def initialize options = {}
  @options = self.class::DEFAULT_OPTIONS.merge options
  @@CODERAY_TOKEN_INTERFACE_DEPRECATION_WARNING_GIVEN = false
end

Public Instance Methods

<<(token) click to toggle source

# File lib/coderay/encoder.rb, line 98
def << token
  unless @@CODERAY_TOKEN_INTERFACE_DEPRECATION_WARNING_GIVEN
    warn 'Using old Tokens#<< interface.'
    @@CODERAY_TOKEN_INTERFACE_DEPRECATION_WARNING_GIVEN = true
  end
  self.token(*token)
end

begin_group(kind) click to toggle source

Starts a token group with the given kind.

# File lib/coderay/encoder.rb, line 134
def begin_group kind
end

begin_line(kind) click to toggle source

Starts a new line token group with the given kind.

# File lib/coderay/encoder.rb, line 142
def begin_line kind
end

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

Encode the given code using the Scanner for lang.

# File lib/coderay/encoder.rb, line 81
def encode code, lang, options = {}
  options = @options.merge options
  @scanner = Scanners[lang].new code, CodeRay.get_scanner_options(options).update(:tokens => self)
  setup options
  @scanner.tokenize
  finish options
end

Also aliased as: highlight

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

Encode a Tokens object.

# File lib/coderay/encoder.rb, line 72
def encode_tokens tokens, options = {}
  options = @options.merge options
  @scanner = tokens.scanner if tokens.respond_to? :scanner
  setup options
  compile tokens, options
  finish options
end

end_group(kind) click to toggle source

Ends a token group with the given kind.

# File lib/coderay/encoder.rb, line 138
def end_group kind
end

end_line(kind) click to toggle source

Ends a new line token group with the given kind.

# File lib/coderay/encoder.rb, line 146
def end_line kind
end

file_extension() click to toggle source

The default file extension for this encoder.

# File lib/coderay/encoder.rb, line 94
def file_extension
  self.class.file_extension
end

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

You can use highlight instead of encode, if that seems more clear to you.

Alias for: encode

text_token(text, kind) click to toggle source

Called for each text token ([text, kind]), where text is a String.

# File lib/coderay/encoder.rb, line 129
def text_token text, kind
  @out << text
end

token(content, kind) click to toggle source

Called with content and kind of the currently scanned token. For simple scanners, it’s enougth to implement this method.

By default, it calls #text_token, #begin_group, #end_group, #begin_line, or #end_line, depending on the content.

# File lib/coderay/encoder.rb, line 111
def token content, kind
  case content
  when String
    text_token content, kind
  when :begin_group
    begin_group kind
  when :end_group
    end_group kind
  when :begin_line
    begin_line kind
  when :end_line
    end_line kind
  else
    raise ArgumentError, 'Unknown token content type: %p, kind = %p' % [content, kind]
  end
end

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

Alias for: compile

Protected Instance Methods

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

Do the encoding.

The already created tokens object must be used; it must be a Tokens object.

# File lib/coderay/encoder.rb, line 179
def compile tokens, options = {}
  content = nil
  for item in tokens
    if item.is_a? Array
      raise ArgumentError, 'Two-element array tokens are no longer supported.'
    end
    if content
      token content, item
      content = nil
    else
      content = item
    end
  end
  raise 'odd number list for Tokens' if content
end

Also aliased as: tokens

finish(options) click to toggle source

Called with merged options after encoding starts. The return value is the result of encoding, typically @out.

# File lib/coderay/encoder.rb, line 171
def finish options
  @out
end

get_output(options) click to toggle source

# File lib/coderay/encoder.rb, line 159
def get_output options
  options[:out] || ''
end

output(data) click to toggle source

Append data.to_s to the output. Returns the argument.

# File lib/coderay/encoder.rb, line 164
def output data
  @out << data.to_s
  data
end

setup(options) click to toggle source

Called with merged options before encoding starts. Sets @out to an empty string.

See the HTML Encoder for an example of option caching.

# File lib/coderay/encoder.rb, line 155
def setup options
  @out = get_output(options)
end