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 = { }   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

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

[Source]

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

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

[Source]

    # File lib/coderay/encoder.rb, line 44
44:         def file_extension
45:           self::FILE_EXTENSION
46:         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 66
66:       def initialize options = {}
67:         @options = self.class::DEFAULT_OPTIONS.merge options
68:         @@CODERAY_TOKEN_INTERFACE_DEPRECATION_WARNING_GIVEN = false
69:       end

Public Instance methods

[Source]

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

Starts a token group with the given kind.

[Source]

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

Starts a new line token group with the given kind.

[Source]

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

Encode the given code using the Scanner for lang.

[Source]

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

Encode a Tokens object.

[Source]

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

Ends a token group with the given kind.

[Source]

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

Ends a new line token group with the given kind.

[Source]

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

The default file extension for this encoder.

[Source]

    # File lib/coderay/encoder.rb, line 94
94:       def file_extension
95:         self.class.file_extension
96:       end
highlight(code, lang, options = {})

Alias for encode

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

[Source]

     # File lib/coderay/encoder.rb, line 129
129:       def text_token text, kind
130:         @out << text
131:       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, begin_group, end_group, begin_line, or end_line, depending on the content.

[Source]

     # File lib/coderay/encoder.rb, line 111
111:       def token content, kind
112:         case content
113:         when String
114:           text_token content, kind
115:         when :begin_group
116:           begin_group kind
117:         when :end_group
118:           end_group kind
119:         when :begin_line
120:           begin_line kind
121:         when :end_line
122:           end_line kind
123:         else
124:           raise ArgumentError, 'Unknown token content type: %p, kind = %p' % [content, kind]
125:         end
126:       end
tokens(tokens, options = {})

Alias for compile

Protected Instance methods

Do the encoding.

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

[Source]

     # File lib/coderay/encoder.rb, line 179
179:       def compile tokens, options = {}
180:         content = nil
181:         for item in tokens
182:           if item.is_a? Array
183:             raise ArgumentError, 'Two-element array tokens are no longer supported.'
184:           end
185:           if content
186:             token content, item
187:             content = nil
188:           else
189:             content = item
190:           end
191:         end
192:         raise 'odd number list for Tokens' if content
193:       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 171
171:       def finish options
172:         @out
173:       end

[Source]

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

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

[Source]

     # File lib/coderay/encoder.rb, line 164
164:       def output data
165:         @out << data.to_s
166:         data
167:       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 155
155:       def setup options
156:         @out = get_output(options)
157:       end

[Validate]