Chris@0: # = CodeRay Library Chris@0: # Chris@0: # CodeRay is a Ruby library for syntax highlighting. Chris@0: # Chris@0: # I try to make CodeRay easy to use and intuitive, but at the same time fully featured, complete, Chris@0: # fast and efficient. Chris@0: # Chris@0: # See README. Chris@0: # Chris@0: # It consists mainly of Chris@0: # * the main engine: CodeRay (Scanners::Scanner, Tokens/TokenStream, Encoders::Encoder), PluginHost Chris@0: # * the scanners in CodeRay::Scanners Chris@0: # * the encoders in CodeRay::Encoders Chris@0: # Chris@0: # Here's a fancy graphic to light up this gray docu: Chris@0: # Chris@0: # http://cycnus.de/raindark/coderay/scheme.png Chris@0: # Chris@0: # == Documentation Chris@0: # Chris@0: # See CodeRay, Encoders, Scanners, Tokens. Chris@0: # Chris@0: # == Usage Chris@0: # Chris@0: # Remember you need RubyGems to use CodeRay, unless you have it in your load path. Run Ruby with Chris@0: # -rubygems option if required. Chris@0: # Chris@0: # === Highlight Ruby code in a string as html Chris@0: # Chris@0: # require 'coderay' Chris@0: # print CodeRay.scan('puts "Hello, world!"', :ruby).html Chris@0: # Chris@0: # # prints something like this: Chris@0: # puts "Hello, world!" Chris@0: # Chris@0: # Chris@0: # === Highlight C code from a file in a html div Chris@0: # Chris@0: # require 'coderay' Chris@0: # print CodeRay.scan(File.read('ruby.h'), :c).div Chris@0: # print CodeRay.scan_file('ruby.h').html.div Chris@0: # Chris@0: # You can include this div in your page. The used CSS styles can be printed with Chris@0: # Chris@0: # % coderay_stylesheet Chris@0: # Chris@0: # === Highlight without typing too much Chris@0: # Chris@0: # If you are one of the hasty (or lazy, or extremely curious) people, just run this file: Chris@0: # Chris@0: # % ruby -rubygems /path/to/coderay/coderay.rb > example.html Chris@0: # Chris@0: # and look at the file it created in your browser. Chris@0: # Chris@0: # = CodeRay Module Chris@0: # Chris@0: # The CodeRay module provides convenience methods for the engine. Chris@0: # Chris@0: # * The +lang+ and +format+ arguments select Scanner and Encoder to use. These are Chris@0: # simply lower-case symbols, like :python or :html. Chris@0: # * All methods take an optional hash as last parameter, +options+, that is send to Chris@0: # the Encoder / Scanner. Chris@0: # * Input and language are always sorted in this order: +code+, +lang+. Chris@0: # (This is in alphabetical order, if you need a mnemonic ;) Chris@0: # Chris@0: # You should be able to highlight everything you want just using these methods; Chris@0: # so there is no need to dive into CodeRay's deep class hierarchy. Chris@0: # Chris@0: # The examples in the demo directory demonstrate common cases using this interface. Chris@0: # Chris@0: # = Basic Access Ways Chris@0: # Chris@0: # Read this to get a general view what CodeRay provides. Chris@0: # Chris@0: # == Scanning Chris@0: # Chris@0: # Scanning means analysing an input string, splitting it up into Tokens. Chris@0: # Each Token knows about what type it is: string, comment, class name, etc. Chris@0: # Chris@0: # Each +lang+ (language) has its own Scanner; for example, :ruby code is Chris@0: # handled by CodeRay::Scanners::Ruby. Chris@0: # Chris@0: # CodeRay.scan:: Scan a string in a given language into Tokens. Chris@0: # This is the most common method to use. Chris@0: # CodeRay.scan_file:: Scan a file and guess the language using FileType. Chris@0: # Chris@0: # The Tokens object you get from these methods can encode itself; see Tokens. Chris@0: # Chris@0: # == Encoding Chris@0: # Chris@0: # Encoding means compiling Tokens into an output. This can be colored HTML or Chris@0: # LaTeX, a textual statistic or just the number of non-whitespace tokens. Chris@0: # Chris@0: # Each Encoder provides output in a specific +format+, so you select Encoders via Chris@0: # formats like :html or :statistic. Chris@0: # Chris@0: # CodeRay.encode:: Scan and encode a string in a given language. Chris@0: # CodeRay.encode_tokens:: Encode the given tokens. Chris@0: # CodeRay.encode_file:: Scan a file, guess the language using FileType and encode it. Chris@0: # Chris@0: # == Streaming Chris@0: # Chris@0: # Streaming saves RAM by running Scanner and Encoder in some sort of Chris@0: # pipe mode; see TokenStream. Chris@0: # Chris@0: # CodeRay.scan_stream:: Scan in stream mode. Chris@0: # Chris@0: # == All-in-One Encoding Chris@0: # Chris@0: # CodeRay.encode:: Highlight a string with a given input and output format. Chris@0: # Chris@0: # == Instanciating Chris@0: # Chris@0: # You can use an Encoder instance to highlight multiple inputs. This way, the setup Chris@0: # for this Encoder must only be done once. Chris@0: # Chris@0: # CodeRay.encoder:: Create an Encoder instance with format and options. Chris@0: # CodeRay.scanner:: Create an Scanner instance for lang, with '' as default code. Chris@0: # Chris@0: # To make use of CodeRay.scanner, use CodeRay::Scanner::code=. Chris@0: # Chris@0: # The scanning methods provide more flexibility; we recommend to use these. Chris@0: # Chris@0: # == Reusing Scanners and Encoders Chris@0: # Chris@0: # If you want to re-use scanners and encoders (because that is faster), see Chris@0: # CodeRay::Duo for the most convenient (and recommended) interface. Chris@0: module CodeRay Chris@0: Chris@0: $CODERAY_DEBUG ||= false Chris@0: Chris@0: # Version: Major.Minor.Teeny[.Revision] Chris@0: # Major: 0 for pre-stable, 1 for stable Chris@0: # Minor: feature milestone Chris@0: # Teeny: development state, 0 for pre-release Chris@0: # Revision: Subversion Revision number (generated on rake gem:make) Chris@0: VERSION = '0.9.2' Chris@0: Chris@0: require 'coderay/tokens' Chris@0: require 'coderay/token_classes' Chris@0: require 'coderay/scanner' Chris@0: require 'coderay/encoder' Chris@0: require 'coderay/duo' Chris@0: require 'coderay/style' Chris@0: Chris@0: Chris@0: class << self Chris@0: Chris@0: # Scans the given +code+ (a String) with the Scanner for +lang+. Chris@0: # Chris@0: # This is a simple way to use CodeRay. Example: Chris@0: # require 'coderay' Chris@0: # page = CodeRay.scan("puts 'Hello, world!'", :ruby).html Chris@0: # Chris@0: # See also demo/demo_simple. Chris@0: def scan code, lang, options = {}, &block Chris@0: scanner = Scanners[lang].new code, options, &block Chris@0: scanner.tokenize Chris@0: end Chris@0: Chris@0: # Scans +filename+ (a path to a code file) with the Scanner for +lang+. Chris@0: # Chris@0: # If +lang+ is :auto or omitted, the CodeRay::FileType module is used to Chris@0: # determine it. If it cannot find out what type it is, it uses Chris@0: # CodeRay::Scanners::Plaintext. Chris@0: # Chris@0: # Calls CodeRay.scan. Chris@0: # Chris@0: # Example: Chris@0: # require 'coderay' Chris@0: # page = CodeRay.scan_file('some_c_code.c').html Chris@0: def scan_file filename, lang = :auto, options = {}, &block Chris@0: file = IO.read filename Chris@0: if lang == :auto Chris@0: require 'coderay/helpers/file_type' Chris@0: lang = FileType.fetch filename, :plaintext, true Chris@0: end Chris@0: scan file, lang, options = {}, &block Chris@0: end Chris@0: Chris@0: # Scan the +code+ (a string) with the scanner for +lang+. Chris@0: # Chris@0: # Calls scan. Chris@0: # Chris@0: # See CodeRay.scan. Chris@0: def scan_stream code, lang, options = {}, &block Chris@0: options[:stream] = true Chris@0: scan code, lang, options, &block Chris@0: end Chris@0: Chris@0: # Encode a string in Streaming mode. Chris@0: # Chris@0: # This starts scanning +code+ with the the Scanner for +lang+ Chris@0: # while encodes the output with the Encoder for +format+. Chris@0: # +options+ will be passed to the Encoder. Chris@0: # Chris@0: # See CodeRay::Encoder.encode_stream Chris@0: def encode_stream code, lang, format, options = {} Chris@0: encoder(format, options).encode_stream code, lang, options Chris@0: end Chris@0: Chris@0: # Encode a string. Chris@0: # Chris@0: # This scans +code+ with the the Scanner for +lang+ and then Chris@0: # encodes it with the Encoder for +format+. Chris@0: # +options+ will be passed to the Encoder. Chris@0: # Chris@0: # See CodeRay::Encoder.encode Chris@0: def encode code, lang, format, options = {} Chris@0: encoder(format, options).encode code, lang, options Chris@0: end Chris@0: Chris@0: # Highlight a string into a HTML
. Chris@0: # Chris@0: # CSS styles use classes, so you have to include a stylesheet Chris@0: # in your output. Chris@0: # Chris@0: # See encode. Chris@0: def highlight code, lang, options = { :css => :class }, format = :div Chris@0: encode code, lang, format, options Chris@0: end Chris@0: Chris@0: # Encode pre-scanned Tokens. Chris@0: # Use this together with CodeRay.scan: Chris@0: # Chris@0: # require 'coderay' Chris@0: # Chris@0: # # Highlight a short Ruby code example in a HTML span Chris@0: # tokens = CodeRay.scan '1 + 2', :ruby Chris@0: # puts CodeRay.encode_tokens(tokens, :span) Chris@0: # Chris@0: def encode_tokens tokens, format, options = {} Chris@0: encoder(format, options).encode_tokens tokens, options Chris@0: end Chris@0: Chris@0: # Encodes +filename+ (a path to a code file) with the Scanner for +lang+. Chris@0: # Chris@0: # See CodeRay.scan_file. Chris@0: # Notice that the second argument is the output +format+, not the input language. Chris@0: # Chris@0: # Example: Chris@0: # require 'coderay' Chris@0: # page = CodeRay.encode_file 'some_c_code.c', :html Chris@0: def encode_file filename, format, options = {} Chris@0: tokens = scan_file filename, :auto, get_scanner_options(options) Chris@0: encode_tokens tokens, format, options Chris@0: end Chris@0: Chris@0: # Highlight a file into a HTML
. Chris@0: # Chris@0: # CSS styles use classes, so you have to include a stylesheet Chris@0: # in your output. Chris@0: # Chris@0: # See encode. Chris@0: def highlight_file filename, options = { :css => :class }, format = :div Chris@0: encode_file filename, format, options Chris@0: end Chris@0: Chris@0: # Finds the Encoder class for +format+ and creates an instance, passing Chris@0: # +options+ to it. Chris@0: # Chris@0: # Example: Chris@0: # require 'coderay' Chris@0: # Chris@0: # stats = CodeRay.encoder(:statistic) Chris@0: # stats.encode("puts 17 + 4\n", :ruby) Chris@0: # Chris@0: # puts '%d out of %d tokens have the kind :integer.' % [ Chris@0: # stats.type_stats[:integer].count, Chris@0: # stats.real_token_count Chris@0: # ] Chris@0: # #-> 2 out of 4 tokens have the kind :integer. Chris@0: def encoder format, options = {} Chris@0: Encoders[format].new options Chris@0: end Chris@0: Chris@0: # Finds the Scanner class for +lang+ and creates an instance, passing Chris@0: # +options+ to it. Chris@0: # Chris@0: # See Scanner.new. Chris@0: def scanner lang, options = {} Chris@0: Scanners[lang].new '', options Chris@0: end Chris@0: Chris@0: # Extract the options for the scanner from the +options+ hash. Chris@0: # Chris@0: # Returns an empty Hash if :scanner_options is not set. Chris@0: # Chris@0: # This is used if a method like CodeRay.encode has to provide options Chris@0: # for Encoder _and_ scanner. Chris@0: def get_scanner_options options Chris@0: options.fetch :scanner_options, {} Chris@0: end Chris@0: Chris@0: end Chris@0: Chris@0: # This Exception is raised when you try to stream with something that is not Chris@0: # capable of streaming. Chris@0: class NotStreamableError < Exception Chris@0: def initialize obj Chris@0: @obj = obj Chris@0: end Chris@0: Chris@0: def to_s Chris@0: '%s is not Streamable!' % @obj.class Chris@0: end Chris@0: end Chris@0: Chris@0: # A dummy module that is included by subclasses of CodeRay::Scanner an CodeRay::Encoder Chris@0: # to show that they are able to handle streams. Chris@0: module Streamable Chris@0: end Chris@0: Chris@0: end Chris@0: Chris@0: # Run a test script. Chris@0: if $0 == __FILE__ Chris@0: $stderr.print 'Press key to print demo.'; gets Chris@0: # Just use this file as an example of Ruby code. Chris@0: code = File.read(__FILE__)[/module CodeRay.*/m] Chris@0: print CodeRay.scan(code, :ruby).html Chris@0: end