Module: CodeRay
- Defined in:
- lib/coderay.rb,
lib/coderay/duo.rb,
lib/coderay/style.rb,
lib/coderay/tokens.rb,
lib/coderay/encoder.rb,
lib/coderay/scanner.rb,
lib/coderay/version.rb,
lib/coderay/scanners/c.rb,
lib/coderay/styles/_map.rb,
lib/coderay/token_kinds.rb,
lib/coderay/encoders/div.rb,
lib/coderay/encoders/xml.rb,
lib/coderay/for_redcloth.rb,
lib/coderay/helpers/gzip.rb,
lib/coderay/scanners/cpp.rb,
lib/coderay/scanners/css.rb,
lib/coderay/scanners/erb.rb,
lib/coderay/scanners/sql.rb,
lib/coderay/scanners/xml.rb,
lib/coderay/styles/alpha.rb,
lib/coderay/tokens_proxy.rb,
lib/coderay/encoders/_map.rb,
lib/coderay/encoders/html.rb,
lib/coderay/encoders/json.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/haml.rb,
lib/coderay/scanners/html.rb,
lib/coderay/scanners/java.rb,
lib/coderay/scanners/json.rb,
lib/coderay/scanners/ruby.rb,
lib/coderay/scanners/text.rb,
lib/coderay/scanners/yaml.rb,
lib/coderay/encoders/count.rb,
lib/coderay/encoders/debug.rb,
lib/coderay/helpers/plugin.rb,
lib/coderay/scanners/debug.rb,
lib/coderay/encoders/filter.rb,
lib/coderay/scanners/delphi.rb,
lib/coderay/scanners/groovy.rb,
lib/coderay/scanners/python.rb,
lib/coderay/scanners/clojure.rb,
lib/coderay/encoders/html/css.rb,
lib/coderay/encoders/terminal.rb,
lib/coderay/helpers/file_type.rb,
lib/coderay/helpers/word_list.rb,
lib/coderay/scanners/raydebug.rb,
lib/coderay/encoders/statistic.rb,
lib/coderay/encoders/html/output.rb,
lib/coderay/scanners/java_script.rb,
lib/coderay/encoders/lines_of_code.rb,
lib/coderay/scanners/ruby/patterns.rb,
lib/coderay/encoders/comment_filter.rb,
lib/coderay/encoders/html/numbering.rb,
lib/coderay/encoders/token_kind_filter.rb,
lib/coderay/scanners/ruby/string_state.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, Encoders::Encoder)
-
the plugin system: PluginHost, Plugin
-
the scanners in CodeRay::Scanners
-
the encoders in CodeRay::Encoders
-
the styles in CodeRay::Styles
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.
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, GZip, Plugin, PluginHost, Scanners, Styles Classes: Duo, Tokens, TokensProxy, WordList
Constant Summary collapse
- CODERAY_PATH =
File.join File.dirname(__FILE__), 'coderay'
- VERSION =
'1.0.5'
- TokenKinds =
A Hash of all known token kinds and their associated CSS classes.
Hash.new do |h, k| warn 'Undefined Token kind: %p' % [k] if $CODERAY_DEBUG false end
Class Method Summary collapse
-
.coderay_path(*path) ⇒ Object
Assuming the path is a subpath of lib/coderay/.
-
.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_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>.
-
.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
. -
.scanner(lang, options = {}, &block) ⇒ Object
Finds the Scanner class for
lang
and creates an instance, passingoptions
to it.
Class Method Details
.coderay_path(*path) ⇒ Object
Assuming the path is a subpath of lib/coderay/
133 134 135 |
# File 'lib/coderay.rb', line 133 def self.coderay_path *path File.join CODERAY_PATH, *path end |
.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.
197 198 199 |
# File 'lib/coderay.rb', line 197 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
222 223 224 225 |
# File 'lib/coderay.rb', line 222 def encode_file filename, format, = {} tokens = scan_file filename, :auto, () encode_tokens tokens, format, end |
.encode_tokens(tokens, format, options = {}) ⇒ Object
210 211 212 |
# File 'lib/coderay.rb', line 210 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.
261 262 263 |
# File 'lib/coderay.rb', line 261 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.
279 280 281 |
# File 'lib/coderay.rb', line 279 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.
233 234 235 |
# File 'lib/coderay.rb', line 233 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.
243 244 245 |
# File 'lib/coderay.rb', line 243 def highlight_file filename, = { :css => :class }, format = :div encode_file filename, format, 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.
168 169 170 171 |
# File 'lib/coderay.rb', line 168 def scan code, lang, = {}, &block # FIXME: return a proxy for direct-stream encoding TokensProxy.new code, lang, , block 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::Text.
Calls CodeRay.scan.
Example:
require 'coderay'
page = CodeRay.scan_file('some_c_code.c').html
184 185 186 187 188 |
# File 'lib/coderay.rb', line 184 def scan_file filename, lang = :auto, = {}, &block lang = FileType.fetch filename, :text, true if lang == :auto code = File.read filename scan code, lang, , &block end |
.scanner(lang, options = {}, &block) ⇒ Object
Finds the Scanner class for lang
and creates an instance, passing options
to it.
See Scanner.new.
269 270 271 |
# File 'lib/coderay.rb', line 269 def scanner lang, = {}, &block Scanners[lang].new '', , &block end |