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