diff options
Diffstat (limited to 'lib/coderay.rb')
| -rw-r--r-- | lib/coderay.rb | 169 |
1 files changed, 169 insertions, 0 deletions
diff --git a/lib/coderay.rb b/lib/coderay.rb new file mode 100644 index 0000000..17c315d --- /dev/null +++ b/lib/coderay.rb @@ -0,0 +1,169 @@ +# = CodeRay +# +# 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, CodeRay::Scanner, CodeRay::Tokens, CodeRay::TokenStream, CodeRay::Encoder +# * the scanners in CodeRay::Scanners +# * the encoders in CodeRay::Encoders +# +# Here's a fancy graphic to light up this gray docu: +# +# http://rd.cYcnus.de/coderay/scheme.png +# +# == Documentation +# +# See CodeRay, Encoders, Scanners, Tokens. +# +# == Usage +# +# Remember you need RubyGems to use CodeRay. Run Ruby with -rubygems option +# if required. +# +# === Highlight Ruby code in a string as html +# +# require 'coderay' +# print CodeRay.scan('puts "Hello, world!"', :ruby).compact.html.page +# +# # 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).html.div +# # print CodeRay.scan_file('ruby.h').html.div ## not working yet +# +# You can include this div in your page. The used CSS styles can be printed with +# +# % ruby -rcoderay -e "print CodeRay::Encoders[:html]::CSS" +# +# === Highlight without typing too much +# +# If you are one of the hasty (or lazy, or extremely curious) people, just run this file: +# +# % ruby -rubygems coderay.rb +# +# If the output was to fast for you, try +# +# % ruby -rubygems coderay.rb > example.html +# +# and look at the file it created. +# +module CodeRay + + Version = '0.4.2' + + require 'coderay/tokens' + require 'coderay/scanner' + require 'coderay/encoder' + + + class << self + + # 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. + def scan code, lang, options = {}, &block + scanner = Scanners[lang].new code, options, &block + scanner.tokenize + end + + # 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 + def scan_file filename, lang = :auto, options = {}, &block + file = IO.read filename + if lang == :auto + require 'coderay/helpers/filetype' + lang = FileType.fetch filename, :plaintext, true + end + scan file, lang, options = {}, &block + end + + # Scan the +code+ (a string) with the scanner for +lang+. + # + # Calls scan. + # + # See CodeRay.scan. + def scan_stream code, lang, options = {}, &block + options[:stream] = true + scan code, lang, options, &block + end + + # Encode +code+ with the Encoder for +format+ and the Scanner for +lang+. + # +options+ will be passed to the Encoder. + # + # See CodeRay::Encoder.encode_stream + def encode_stream code, lang, format, options = {} + encoder(format, options).encode_stream code, lang, options + end + + def encode code, lang, format, options = {} + encoder(format, options).encode code, lang, options + end + + # Finds the Encoder class for +format+ and creates an instance, passing + # +options+ to it. + # + # Example: + # require 'coderay' + # token_count = CodeRay.encoder(:count).encodea("puts 17 + 4\n", :ruby).to_i #-> 8 + # 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. + def encoder format, options = {} + Encoders[format].new options + end + + end + + # This Exception is raised when you try to stream with something that is not + # capable of streaming. + class NotStreamableError < Exception + def initialize obj + @obj = obj + end + + def to_s + '%s is not Streamable!' % @obj.class + end + end + + # A dummy module that is included by subclasses of CodeRay::Scanner an CodeRay::Encoder + # to show that they are able to handle streams. + module Streamable + end + +end + +# Run a test script. +if $0 == __FILE__ + $stderr.print 'Press key to print demo.'; gets + code = File.read($0)[/module CodeRay.*/m] + print CodeRay.scan(code, :ruby).html +end |