Ray

module CodeRay
  
  $CODERAY_DEBUG ||= false
  
  CODERAY_PATH = File.join File.dirname(__FILE__), 'coderay'
  
  # Assuming the path is a subpath of lib/coderay/
  def self.coderay_path *path
    File.join CODERAY_PATH, *path
  end
  
  require coderay_path('version')
  
  # helpers
  autoload :FileType, coderay_path('helpers', 'file_type')
  
  # Tokens
  autoload :Tokens, coderay_path('tokens')
  autoload :TokensProxy, coderay_path('tokens_proxy')
  autoload :TokenKinds, coderay_path('token_kinds')
  
  # Plugin system
  autoload :PluginHost, coderay_path('helpers', 'plugin')
  autoload :Plugin, coderay_path('helpers', 'plugin')
  
  # Plugins
  autoload :Scanners, coderay_path('scanner')
  autoload :Encoders, coderay_path('encoder')
  autoload :Styles, coderay_path('style')
  
  # convenience access and reusable Encoder/Scanner pair
  autoload :Duo, coderay_path('duo')
  
  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
      # FIXME: return a proxy for direct-stream encoding
      TokensProxy.new code, lang, options, block
    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::Text.
    #
    # Calls CodeRay.scan.
    #
    # Example:
    # require 'coderay'
    # page = CodeRay.scan_file('some_c_code.c').html
    def scan_file filename, lang = :auto, options = {}, &block
      lang = FileType.fetch filename, :text, true if lang == :auto
      code = File.read filename
      scan code, lang, options, &block
    end
    
    # 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.
    def encode code, lang, format, options = {}
      encoder(format, options).encode code, lang, options
    end
    
    # Encode pre-scanned Tokens.
    # Use this together with CodeRay.scan:
    #
    # require 'coderay'
    #
    # # Highlight a short Ruby code example in a HTML span
    # tokens = CodeRay.scan '1 + 2', :ruby
    # puts CodeRay.encode_tokens(tokens, :span)
    #
    def encode_tokens tokens, format, options = {}
      encoder(format, options).encode_tokens tokens, options
    end
    
    # 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
    def encode_file filename, format, options = {}
      tokens = scan_file filename, :auto, get_scanner_options(options)
      encode_tokens tokens, format, options
    end
    
    # Highlight a string into a HTML <div>.
    #
    # CSS styles use classes, so you have to include a stylesheet
    # in your output.
    #
    # See encode.
    def highlight code, lang, options = { :css => :class }, format = :div
      encode code, lang, format, options
    end
    
    # Highlight a file into a HTML <div>.
    #
    # CSS styles use classes, so you have to include a stylesheet
    # in your output.
    #
    # See encode.
    def highlight_file filename, options = { :css => :class }, format = :div
      encode_file filename, format, options
    end
    
    # 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.
    def encoder format, options = {}
      Encoders[format].new options
    end
    
    # Finds the Scanner class for +lang+ and creates an instance, passing
    # +options+ to it.
    #
    # See Scanner.new.
    def scanner lang, options = {}, &block
      Scanners[lang].new '', options, &block
    end
    
    # Extract the options for the scanner from the +options+ hash.
    #
    # Returns an empty Hash if <tt>:scanner_options</tt> is not set.
    #
    # This is used if a method like CodeRay.encode has to provide options
    # for Encoder _and_ scanner.
    def get_scanner_options options
      options.fetch :scanner_options, {}
    end
    
  end
  
end