Class CodeRay::Encoders::Encoder
In: lib/coderay/encoder.rb
Parent: Object

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.

Methods

Constants

DEFAULT_OPTIONS = { :stream => false }   Subclasses are to store their default options in this constant.

Attributes

options  [RW]  The options you gave the Encoder at creating.
token_stream  [R] 

Public Class methods

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

[Source]

    # File lib/coderay/encoder.rb, line 41
41:         def const_missing sym
42:           if sym == :FILE_EXTENSION
43:             plugin_id
44:           else
45:             super
46:           end
47:         end

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:

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

[Source]

    # File lib/coderay/encoder.rb, line 68
68:       def initialize options = {}
69:         @options = self.class::DEFAULT_OPTIONS.merge options
70:         raise "I am only the basic Encoder class. I can't encode "\
71:           "anything. :( Use my subclasses." if self.class == Encoder
72:       end

Returns if the Encoder can be used in streaming mode.

[Source]

    # File lib/coderay/encoder.rb, line 35
35:         def streamable?
36:           is_a? Streamable
37:         end

Public Instance methods

Encode the given code after tokenizing it using the Scanner for lang.

[Source]

    # File lib/coderay/encoder.rb, line 84
84:       def encode code, lang, options = {}
85:         options = @options.merge options
86:         scanner_options = CodeRay.get_scanner_options(options)
87:         tokens = CodeRay.scan code, lang, scanner_options
88:         encode_tokens tokens, options
89:       end

Encode the given code using the Scanner for lang in streaming mode.

[Source]

     # File lib/coderay/encoder.rb, line 97
 97:       def encode_stream code, lang, options = {}
 98:         raise NotStreamableError, self unless kind_of? Streamable
 99:         options = @options.merge options
100:         setup options
101:         scanner_options = CodeRay.get_scanner_options options
102:         @token_stream =
103:           CodeRay.scan_stream code, lang, scanner_options, &self
104:         finish options
105:       end

Encode a Tokens object.

[Source]

    # File lib/coderay/encoder.rb, line 75
75:       def encode_tokens tokens, options = {}
76:         options = @options.merge options
77:         setup options
78:         compile tokens, options
79:         finish options
80:       end

Return the default file extension for outputs of this encoder.

[Source]

     # File lib/coderay/encoder.rb, line 113
113:       def file_extension
114:         self.class::FILE_EXTENSION
115:       end
highlight(code, lang, options = {})

Alias for encode

Behave like a proc. The token method is converted to a proc.

[Source]

     # File lib/coderay/encoder.rb, line 108
108:       def to_proc
109:         method(:token).to_proc
110:       end

Protected Instance methods

[Source]

     # File lib/coderay/encoder.rb, line 144
144:       def append_encoded_token_to_output encoded_token
145:         @out << encoded_token if encoded_token && defined?(@out) && @out
146:       end

Called for each line token block at the start of the line ([:begin_line, kind]).

[Source]

     # File lib/coderay/encoder.rb, line 181
181:       def begin_line kind
182:       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.

[Source]

     # File lib/coderay/encoder.rb, line 157
157:       def block_token action, kind
158:         case action
159:         when :open
160:           open_token kind
161:         when :close
162:           close_token kind
163:         when :begin_line
164:           begin_line kind
165:         when :end_line
166:           end_line kind
167:         else
168:           raise 'unknown block action: %p' % action
169:         end
170:       end

Called for each block token end of the block ([:close, kind]).

[Source]

     # File lib/coderay/encoder.rb, line 177
177:       def close_token kind
178:       end

[Source]

     # File lib/coderay/encoder.rb, line 199
199:         def compile tokens, options
200:           for text, kind in tokens
201:             token text, kind
202:           end
203:         end

[Source]

     # File lib/coderay/encoder.rb, line 205
205:         def compile tokens, options
206:           tokens.each(&self)
207:         end

Called for each line token block at the end of the line ([:end_line, kind]).

[Source]

     # File lib/coderay/encoder.rb, line 185
185:       def end_line kind
186:       end

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

[Source]

     # File lib/coderay/encoder.rb, line 190
190:       def finish options
191:         @out
192:       end

Called for each block token at the start of the block ([:open, kind]).

[Source]

     # File lib/coderay/encoder.rb, line 173
173:       def open_token kind
174:       end

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

See the HTML Encoder for an example of option caching.

[Source]

     # File lib/coderay/encoder.rb, line 123
123:       def setup options
124:         @out = ''
125:       end

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

[Source]

     # File lib/coderay/encoder.rb, line 149
149:       def text_token text, kind
150:       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.

[Source]

     # File lib/coderay/encoder.rb, line 132
132:       def token content, kind
133:         encoded_token =
134:           if content.is_a? ::String
135:             text_token content, kind
136:           elsif content.is_a? ::Symbol
137:             block_token content, kind
138:           else
139:             raise 'Unknown token content type: %p' % [content]
140:           end
141:         append_encoded_token_to_output encoded_token
142:       end

[Validate]