Debian Codegraph @

lib/coderay.rb

raw
1 # encoding: utf-8
2 # Encoding.default_internal = 'UTF-8'
3
4 # = CodeRay Library
5 #
6 # CodeRay is a Ruby library for syntax highlighting.
7 #
8 # I try to make CodeRay easy to use and intuitive, but at the same time fully
9 # featured, complete, fast and efficient.
10 #
11 # See README.
12 #
13 # It consists mainly of
14 # * the main engine: CodeRay (Scanners::Scanner, Tokens, Encoders::Encoder)
15 # * the plugin system: PluginHost, Plugin
16 # * the scanners in CodeRay::Scanners
17 # * the encoders in CodeRay::Encoders
18 # * the styles in CodeRay::Styles
19 #
20 # Here's a fancy graphic to light up this gray docu:
21 #
22 # http://cycnus.de/raindark/coderay/scheme.png
23 #
24 # == Documentation
25 #
26 # See CodeRay, Encoders, Scanners, Tokens.
27 #
28 # == Usage
29 #
30 # Remember you need RubyGems to use CodeRay, unless you have it in your load
31 # path. Run Ruby with -rubygems option if required.
32 #
33 # === Highlight Ruby code in a string as html
34 #
35 # require 'coderay'
36 # print CodeRay.scan('puts "Hello, world!"', :ruby).html
37 #
38 # # prints something like this:
39 # puts <span class="s">&quot;Hello, world!&quot;</span>
40 #
41 #
42 # === Highlight C code from a file in a html div
43 #
44 # require 'coderay'
45 # print CodeRay.scan(File.read('ruby.h'), :c).div
46 # print CodeRay.scan_file('ruby.h').html.div
47 #
48 # You can include this div in your page. The used CSS styles can be printed with
49 #
50 # % coderay_stylesheet
51 #
52 # === Highlight without typing too much
53 #
54 # If you are one of the hasty (or lazy, or extremely curious) people, just run this file:
55 #
56 # % ruby -rubygems /path/to/coderay/coderay.rb > example.html
57 #
58 # and look at the file it created in your browser.
59 #
60 # = CodeRay Module
61 #
62 # The CodeRay module provides convenience methods for the engine.
63 #
64 # * The +lang+ and +format+ arguments select Scanner and Encoder to use. These are
65 # simply lower-case symbols, like <tt>:python</tt> or <tt>:html</tt>.
66 # * All methods take an optional hash as last parameter, +options+, that is send to
67 # the Encoder / Scanner.
68 # * Input and language are always sorted in this order: +code+, +lang+.
69 # (This is in alphabetical order, if you need a mnemonic ;)
70 #
71 # You should be able to highlight everything you want just using these methods;
72 # so there is no need to dive into CodeRay's deep class hierarchy.
73 #
74 # The examples in the demo directory demonstrate common cases using this interface.
75 #
76 # = Basic Access Ways
77 #
78 # Read this to get a general view what CodeRay provides.
79 #
80 # == Scanning
81 #
82 # Scanning means analysing an input string, splitting it up into Tokens.
83 # Each Token knows about what type it is: string, comment, class name, etc.
84 #
85 # Each +lang+ (language) has its own Scanner; for example, <tt>:ruby</tt> code is
86 # handled by CodeRay::Scanners::Ruby.
87 #
88 # CodeRay.scan:: Scan a string in a given language into Tokens.
89 # This is the most common method to use.
90 # CodeRay.scan_file:: Scan a file and guess the language using FileType.
91 #
92 # The Tokens object you get from these methods can encode itself; see Tokens.
93 #
94 # == Encoding
95 #
96 # Encoding means compiling Tokens into an output. This can be colored HTML or
97 # LaTeX, a textual statistic or just the number of non-whitespace tokens.
98 #
99 # Each Encoder provides output in a specific +format+, so you select Encoders via
100 # formats like <tt>:html</tt> or <tt>:statistic</tt>.
101 #
102 # CodeRay.encode:: Scan and encode a string in a given language.
103 # CodeRay.encode_tokens:: Encode the given tokens.
104 # CodeRay.encode_file:: Scan a file, guess the language using FileType and encode it.
105 #
106 # == All-in-One Encoding
107 #
108 # CodeRay.encode:: Highlight a string with a given input and output format.
109 #
110 # == Instanciating
111 #
112 # You can use an Encoder instance to highlight multiple inputs. This way, the setup
113 # for this Encoder must only be done once.
114 #
115 # CodeRay.encoder:: Create an Encoder instance with format and options.
116 # CodeRay.scanner:: Create an Scanner instance for lang, with '' as default code.
117 #
118 # To make use of CodeRay.scanner, use CodeRay::Scanner::code=.
119 #
120 # The scanning methods provide more flexibility; we recommend to use these.
121 #
122 # == Reusing Scanners and Encoders
123 #
124 # If you want to re-use scanners and encoders (because that is faster), see
125 # CodeRay::Duo for the most convenient (and recommended) interface.
126 module CodeRay
127
128 $CODERAY_DEBUG ||= false
129
130 CODERAY_PATH = File.expand_path('../coderay', __FILE__)
131
132 # Assuming the path is a subpath of lib/coderay/
133 def self.coderay_path *path
134 File.join CODERAY_PATH, *path
135 end
136
137 autoload :VERSION, 'coderay/version'
138
139 # helpers
140 autoload :FileType, coderay_path('helpers', 'file_type')
141
142 # Tokens
143 autoload :Tokens, coderay_path('tokens')
144 autoload :TokensProxy, coderay_path('tokens_proxy')
145 autoload :TokenKinds, coderay_path('token_kinds')
146
147 # Plugin system
148 autoload :PluginHost, coderay_path('helpers', 'plugin_host')
149 autoload :Plugin, coderay_path('helpers', 'plugin')
150
151 # Plugins
152 autoload :Scanners, coderay_path('scanners')
153 autoload :Encoders, coderay_path('encoders')
154 autoload :Styles, coderay_path('styles')
155
156 # convenience access and reusable Encoder/Scanner pair
157 autoload :Duo, coderay_path('duo')
158
159 class << self
160
161 # Scans the given +code+ (a String) with the Scanner for +lang+.
162 #
163 # This is a simple way to use CodeRay. Example:
164 # require 'coderay'
165 # page = CodeRay.scan("puts 'Hello, world!'", :ruby).html
166 #
167 # See also demo/demo_simple.
168 def scan code, lang, options = {}, &block
169 CodeRay::TokensProxy.new code, lang, options, block
170 end
171
172 # Scans +filename+ (a path to a code file) with the Scanner for +lang+.
173 #
174 # If +lang+ is :auto or omitted, the CodeRay::FileType module is used to
175 # determine it. If it cannot find out what type it is, it uses
176 # CodeRay::Scanners::Text.
177 #
178 # Calls CodeRay.scan.
179 #
180 # Example:
181 # require 'coderay'
182 # page = CodeRay.scan_file('some_c_code.c').html
183 def scan_file filename, lang = :auto, options = {}, &block
184 lang = CodeRay::FileType.fetch filename, :text, true if lang == :auto
185 code = File.read filename
186 scan code, lang, options, &block
187 end
188
189 # Encode a string.
190 #
191 # This scans +code+ with the the Scanner for +lang+ and then
192 # encodes it with the Encoder for +format+.
193 # +options+ will be passed to the Encoder.
194 #
195 # See CodeRay::Encoder.encode.
196 def encode code, lang, format, options = {}
197 encoder(format, options).encode code, lang, options
198 end
199
200 # Encode pre-scanned Tokens.
201 # Use this together with CodeRay.scan:
202 #
203 # require 'coderay'
204 #
205 # # Highlight a short Ruby code example in a HTML span
206 # tokens = CodeRay.scan '1 + 2', :ruby
207 # puts CodeRay.encode_tokens(tokens, :span)
208 #
209 def encode_tokens tokens, format, options = {}
210 encoder(format, options).encode_tokens tokens, options
211 end
212
213 # Encodes +filename+ (a path to a code file) with the Scanner for +lang+.
214 #
215 # See CodeRay.scan_file.
216 # Notice that the second argument is the output +format+, not the input language.
217 #
218 # Example:
219 # require 'coderay'
220 # page = CodeRay.encode_file 'some_c_code.c', :html
221 def encode_file filename, format, options = {}
222 tokens = scan_file filename, :auto, get_scanner_options(options)
223 encode_tokens tokens, format, options
224 end
225
226 # Highlight a string into a HTML <div>.
227 #
228 # CSS styles use classes, so you have to include a stylesheet
229 # in your output.
230 #
231 # See encode.
232 def highlight code, lang, options = { :css => :class }, format = :div
233 encode code, lang, format, options
234 end
235
236 # Highlight a file into a HTML <div>.
237 #
238 # CSS styles use classes, so you have to include a stylesheet
239 # in your output.
240 #
241 # See encode.
242 def highlight_file filename, options = { :css => :class }, format = :div
243 encode_file filename, format, options
244 end
245
246 # Finds the Encoder class for +format+ and creates an instance, passing
247 # +options+ to it.
248 #
249 # Example:
250 # require 'coderay'
251 #
252 # stats = CodeRay.encoder(:statistic)
253 # stats.encode("puts 17 + 4\n", :ruby)
254 #
255 # puts '%d out of %d tokens have the kind :integer.' % [
256 # stats.type_stats[:integer].count,
257 # stats.real_token_count
258 # ]
259 # #-> 2 out of 4 tokens have the kind :integer.
260 def encoder format, options = {}
261 CodeRay::Encoders[format].new options
262 end
263
264 # Finds the Scanner class for +lang+ and creates an instance, passing
265 # +options+ to it.
266 #
267 # See Scanner.new.
268 def scanner lang, options = {}, &block
269 CodeRay::Scanners[lang].new '', options, &block
270 end
271
272 # Extract the options for the scanner from the +options+ hash.
273 #
274 # Returns an empty Hash if <tt>:scanner_options</tt> is not set.
275 #
276 # This is used if a method like CodeRay.encode has to provide options
277 # for Encoder _and_ scanner.
278 def get_scanner_options options
279 options.fetch :scanner_options, {}
280 end
281
282 end
283
284 end