Module: CodeRay
- Defined in:
- lib/coderay.rb,
lib/coderay/duo.rb,
lib/coderay/style.rb,
lib/coderay/encoder.rb,
lib/coderay/scanner.rb,
lib/coderay/scanners/c.rb,
lib/coderay/styles/_map.rb,
lib/coderay/encoders/div.rb,
lib/coderay/encoders/xml.rb,
lib/coderay/for_redcloth.rb,
lib/coderay/scanners/xml.rb,
lib/coderay/encoders/_map.rb,
lib/coderay/encoders/html.rb,
lib/coderay/encoders/null.rb,
lib/coderay/encoders/page.rb,
lib/coderay/encoders/span.rb,
lib/coderay/encoders/text.rb,
lib/coderay/encoders/yaml.rb,
lib/coderay/scanners/_map.rb,
lib/coderay/scanners/diff.rb,
lib/coderay/scanners/html.rb,
lib/coderay/scanners/java.rb,
lib/coderay/scanners/json.rb,
lib/coderay/scanners/ruby.rb,
lib/coderay/scanners/yaml.rb,
lib/coderay/styles/cycnus.rb,
lib/coderay/styles/murphy.rb,
lib/coderay/token_classes.rb,
lib/coderay/encoders/count.rb,
lib/coderay/encoders/debug.rb,
lib/coderay/helpers/plugin.rb,
lib/coderay/scanners/debug.rb,
lib/coderay/scanners/rhtml.rb,
lib/coderay/encoders/tokens.rb,
lib/coderay/scanners/delphi.rb,
lib/coderay/scanners/scheme.rb,
lib/coderay/encoders/html/css.rb,
lib/coderay/helpers/file_type.rb,
lib/coderay/helpers/word_list.rb,
lib/coderay/encoders/statistic.rb,
lib/coderay/scanners/plaintext.rb,
lib/coderay/encoders/html/output.rb,
lib/coderay/scanners/java_script.rb,
lib/coderay/scanners/nitro_xhtml.rb,
lib/coderay/scanners/ruby/patterns.rb,
lib/coderay/encoders/html/numerization.rb,
lib/coderay/scanners/java/builtin_types.rb
Overview
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/TokenStream, Encoders::Encoder), PluginHost
-
the scanners in CodeRay::Scanners
-
the encoders in CodeRay::Encoders
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">"Hello, world!"</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
andformat
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, <tt>:ruby</tt> 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.
Streaming
Streaming saves RAM by running Scanner and Encoder in some sort of pipe mode; see TokenStream.
- CodeRay.scan_stream
-
Scan in stream mode.
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.
Defined Under Namespace
Modules: Encoders, FileType, ForRedCloth, Plugin, PluginHost, Scanners, Streamable, Styles Classes: CaseIgnoringWordList, Duo, NotStreamableError, Tokens, WordList
Constant Summary collapse
- VERSION =
Version: Major.Minor.Teeny Major: 0 for pre-stable, 1 for stable Minor: feature milestone Teeny: development state, 0 for pre-release Revision: Subversion Revision number (generated on rake gem:make)
'0.8'
Class Method Summary collapse
-
.encode(code, lang, format, options = {}) ⇒ Object
Encode a string.
-
.encode_file(filename, format, options = {}) ⇒ Object
Encodes
filename
(a path to a code file) with the Scanner forlang
. -
.encode_stream(code, lang, format, options = {}) ⇒ Object
Encode a string in Streaming mode.
-
.encode_tokens(tokens, format, options = {}) ⇒ Object
Encode pre-scanned Tokens.
-
.encoder(format, options = {}) ⇒ Object
Finds the Encoder class for
format
and creates an instance, passingoptions
to it. -
.get_scanner_options(options) ⇒ Object
Extract the options for the scanner from the
options
hash. -
.highlight(code, lang, options = { :css => :class }, format = :div) ⇒ Object
Highlight a string into a HTML <div>.
-
.highlight_file(filename, options = { :css => :class }, format = :div) ⇒ Object
Highlight a file into a HTML <div>.
-
.require_plugin(path) ⇒ Object
Convenience method for plugin loading.
-
.scan(code, lang, options = {}, &block) ⇒ Object
Scans the given
code
(a String) with the Scanner forlang
. -
.scan_file(filename, lang = :auto, options = {}, &block) ⇒ Object
Scans
filename
(a path to a code file) with the Scanner forlang
. -
.scan_stream(code, lang, options = {}, &block) ⇒ Object
Scan the
code
(a string) with the scanner forlang
. -
.scanner(lang, options = {}) ⇒ Object
Finds the Scanner class for
lang
and creates an instance, passingoptions
to it.
Class Method Details
.encode(code, lang, format, options = {}) ⇒ Object
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
206 207 208 |
# File 'lib/coderay.rb', line 206 def encode code, lang, format, = {} encoder(format, ).encode code, lang, end |
.encode_file(filename, format, options = {}) ⇒ Object
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
241 242 243 244 |
# File 'lib/coderay.rb', line 241 def encode_file filename, format, = {} tokens = scan_file filename, :auto, () encode_tokens tokens, format, end |
.encode_stream(code, lang, format, options = {}) ⇒ Object
Encode a string in Streaming mode.
This starts scanning code
with the the Scanner for lang
while encodes the output with the Encoder for format
. options
will be passed to the Encoder.
See CodeRay::Encoder.encode_stream
195 196 197 |
# File 'lib/coderay.rb', line 195 def encode_stream code, lang, format, = {} encoder(format, ).encode_stream code, lang, end |
.encode_tokens(tokens, format, options = {}) ⇒ Object
229 230 231 |
# File 'lib/coderay.rb', line 229 def encode_tokens tokens, format, = {} encoder(format, ).encode_tokens tokens, end |
.encoder(format, options = {}) ⇒ Object
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.
270 271 272 |
# File 'lib/coderay.rb', line 270 def encoder format, = {} Encoders[format].new end |
.get_scanner_options(options) ⇒ Object
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.
288 289 290 |
# File 'lib/coderay.rb', line 288 def .fetch :scanner_options, {} end |
.highlight(code, lang, options = { :css => :class }, format = :div) ⇒ Object
Highlight a string into a HTML <div>.
CSS styles use classes, so you have to include a stylesheet in your output.
See encode.
216 217 218 |
# File 'lib/coderay.rb', line 216 def highlight code, lang, = { :css => :class }, format = :div encode code, lang, format, end |
.highlight_file(filename, options = { :css => :class }, format = :div) ⇒ Object
Highlight a file into a HTML <div>.
CSS styles use classes, so you have to include a stylesheet in your output.
See encode.
252 253 254 |
# File 'lib/coderay.rb', line 252 def highlight_file filename, = { :css => :class }, format = :div encode_file filename, format, end |
.require_plugin(path) ⇒ Object
Convenience method for plugin loading. The syntax used is:
CodeRay.require_plugin '<Host ID>/<Plugin ID>'
Returns the loaded plugin.
323 324 325 326 327 328 329 |
# File 'lib/coderay/helpers/plugin.rb', line 323 def self.require_plugin path host_id, plugin_id = path.split '/', 2 host = PluginHost.host_by_id(host_id) raise PluginHost::HostNotFound, "No host for #{host_id.inspect} found." unless host host.load plugin_id end |
.scan(code, lang, options = {}, &block) ⇒ Object
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.
153 154 155 156 |
# File 'lib/coderay.rb', line 153 def scan code, lang, = {}, &block scanner = Scanners[lang].new code, , &block scanner.tokenize end |
.scan_file(filename, lang = :auto, options = {}, &block) ⇒ Object
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::Plaintext.
Calls CodeRay.scan.
Example:
require 'coderay'
page = CodeRay.scan_file('some_c_code.c').html
169 170 171 172 173 174 175 176 |
# File 'lib/coderay.rb', line 169 def scan_file filename, lang = :auto, = {}, &block file = IO.read filename if lang == :auto require 'coderay/helpers/file_type' lang = FileType.fetch filename, :plaintext, true end scan file, lang, = {}, &block end |
.scan_stream(code, lang, options = {}, &block) ⇒ Object
Scan the code
(a string) with the scanner for lang
.
Calls scan.
See CodeRay.scan.
183 184 185 186 |
# File 'lib/coderay.rb', line 183 def scan_stream code, lang, = {}, &block [:stream] = true scan code, lang, , &block end |
.scanner(lang, options = {}) ⇒ Object
Finds the Scanner class for lang
and creates an instance, passing options
to it.
See Scanner.new.
278 279 280 |
# File 'lib/coderay.rb', line 278 def scanner lang, = {} Scanners[lang].new '', end |