214 lines
6.4 KiB
Ruby
214 lines
6.4 KiB
Ruby
module CodeRay
|
|
|
|
# This module holds the Encoder class and its subclasses.
|
|
# For example, the HTML encoder is named CodeRay::Encoders::HTML
|
|
# can be found in coderay/encoders/html.
|
|
#
|
|
# Encoders also provides methods and constants for the register
|
|
# mechanism and the [] method that returns the Encoder class
|
|
# belonging to the given format.
|
|
module Encoders
|
|
extend PluginHost
|
|
plugin_path File.dirname(__FILE__), 'encoders'
|
|
|
|
# = 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.
|
|
class Encoder
|
|
extend Plugin
|
|
plugin_host Encoders
|
|
|
|
attr_reader :token_stream
|
|
|
|
class << self
|
|
|
|
# Returns if the Encoder can be used in streaming mode.
|
|
def streamable?
|
|
is_a? Streamable
|
|
end
|
|
|
|
# If FILE_EXTENSION isn't defined, this method returns the
|
|
# downcase class name instead.
|
|
def const_missing sym
|
|
if sym == :FILE_EXTENSION
|
|
plugin_id
|
|
else
|
|
super
|
|
end
|
|
end
|
|
|
|
end
|
|
|
|
# Subclasses are to store their default options in this constant.
|
|
DEFAULT_OPTIONS = { :stream => false }
|
|
|
|
# The options you gave the Encoder at creating.
|
|
attr_accessor :options
|
|
|
|
# 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
|
|
# - encode_stream is like encode, but uses streaming mode.
|
|
#
|
|
# Each method has an optional +options+ parameter. These are
|
|
# added to the options you passed at creation.
|
|
def initialize options = {}
|
|
@options = self.class::DEFAULT_OPTIONS.merge options
|
|
raise "I am only the basic Encoder class. I can't encode "\
|
|
"anything. :( Use my subclasses." if self.class == Encoder
|
|
end
|
|
|
|
# Encode a Tokens object.
|
|
def encode_tokens tokens, options = {}
|
|
options = @options.merge options
|
|
setup options
|
|
compile tokens, options
|
|
finish options
|
|
end
|
|
|
|
# Encode the given +code+ after tokenizing it using the Scanner
|
|
# for +lang+.
|
|
def encode code, lang, options = {}
|
|
options = @options.merge options
|
|
scanner_options = CodeRay.get_scanner_options(options)
|
|
tokens = CodeRay.scan code, lang, scanner_options
|
|
encode_tokens tokens, options
|
|
end
|
|
|
|
# You can use highlight instead of encode, if that seems
|
|
# more clear to you.
|
|
alias highlight encode
|
|
|
|
# Encode the given +code+ using the Scanner for +lang+ in
|
|
# streaming mode.
|
|
def encode_stream code, lang, options = {}
|
|
raise NotStreamableError, self unless kind_of? Streamable
|
|
options = @options.merge options
|
|
setup options
|
|
scanner_options = CodeRay.get_scanner_options options
|
|
@token_stream =
|
|
CodeRay.scan_stream code, lang, scanner_options, &self
|
|
finish options
|
|
end
|
|
|
|
# Behave like a proc. The token method is converted to a proc.
|
|
def to_proc
|
|
method(:token).to_proc
|
|
end
|
|
|
|
# Return the default file extension for outputs of this encoder.
|
|
def file_extension
|
|
self.class::FILE_EXTENSION
|
|
end
|
|
|
|
protected
|
|
|
|
# Called with merged options before encoding starts.
|
|
# Sets @out to an empty string.
|
|
#
|
|
# See the HTML Encoder for an example of option caching.
|
|
def setup options
|
|
@out = ''
|
|
end
|
|
|
|
# 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 or block_token, depending on
|
|
# whether +content+ is a String.
|
|
def token content, kind
|
|
encoded_token =
|
|
if content.is_a? ::String
|
|
text_token content, kind
|
|
elsif content.is_a? ::Symbol
|
|
block_token content, kind
|
|
else
|
|
raise 'Unknown token content type: %p' % [content]
|
|
end
|
|
append_encoded_token_to_output encoded_token
|
|
end
|
|
|
|
def append_encoded_token_to_output encoded_token
|
|
@out << encoded_token if encoded_token && defined?(@out) && @out
|
|
end
|
|
|
|
# Called for each text token ([text, kind]), where text is a String.
|
|
def text_token text, kind
|
|
end
|
|
|
|
# Called for each block (non-text) token ([action, kind]),
|
|
# where +action+ is a Symbol.
|
|
#
|
|
# Calls open_token, close_token, begin_line, and end_line according to
|
|
# the value of +action+.
|
|
def block_token action, kind
|
|
case action
|
|
when :open
|
|
open_token kind
|
|
when :close
|
|
close_token kind
|
|
when :begin_line
|
|
begin_line kind
|
|
when :end_line
|
|
end_line kind
|
|
else
|
|
raise 'unknown block action: %p' % action
|
|
end
|
|
end
|
|
|
|
# Called for each block token at the start of the block ([:open, kind]).
|
|
def open_token kind
|
|
end
|
|
|
|
# Called for each block token end of the block ([:close, kind]).
|
|
def close_token kind
|
|
end
|
|
|
|
# Called for each line token block at the start of the line ([:begin_line, kind]).
|
|
def begin_line kind
|
|
end
|
|
|
|
# Called for each line token block at the end of the line ([:end_line, kind]).
|
|
def end_line kind
|
|
end
|
|
|
|
# Called with merged options after encoding starts.
|
|
# The return value is the result of encoding, typically @out.
|
|
def finish options
|
|
@out
|
|
end
|
|
|
|
# Do the encoding.
|
|
#
|
|
# The already created +tokens+ object must be used; it can be a
|
|
# TokenStream or a Tokens object.
|
|
if RUBY_VERSION >= '1.9'
|
|
def compile tokens, options
|
|
for text, kind in tokens
|
|
token text, kind
|
|
end
|
|
end
|
|
else
|
|
def compile tokens, options
|
|
tokens.each(&self)
|
|
end
|
|
end
|
|
|
|
end
|
|
|
|
end
|
|
end
|