annotate vendor/plugins/coderay-0.9.2/lib/coderay/duo.rb @ 863:818ff422eece bug_168

Close obsolete branch bug_168

module CodeRay
  
  # = Duo
  #
  # A Duo is a convenient way to use CodeRay. You just create a Duo,
  # giving it a lang (language of the input code) and a format (desired
  # output format), and call Duo#highlight with the code.
  # 
  # Duo makes it easy to re-use both scanner and encoder for a repetitive
  # task. It also provides a very easy interface syntax:
  # 
  #   require 'coderay'
  #   CodeRay::Duo[:python, :div].highlight 'import this'
  # 
  # Until you want to do uncommon things with CodeRay, I recommend to use
  # this method, since it takes care of everything.
  class Duo

    attr_accessor :lang, :format, :options
    
    # Create a new Duo, holding a lang and a format to highlight code.
    # 
    # simple:
    #   CodeRay::Duo[:ruby, :page].highlight 'bla 42'
    # 
    # streaming:
    #   CodeRay::Duo[:ruby, :page].highlight 'bar 23', :stream => true
    # 
    # with options:
    #   CodeRay::Duo[:ruby, :html, :hint => :debug].highlight '????::??'
    # 
    # alternative syntax without options:
    #   CodeRay::Duo[:ruby => :statistic].encode 'class << self; end'
    # 
    # alternative syntax with options:
    #   CodeRay::Duo[{ :ruby => :statistic }, :do => :something].encode 'abc'
    # 
    # The options are forwarded to scanner and encoder
    # (see CodeRay.get_scanner_options).
    def initialize lang = nil, format = nil, options = {}
      if format == nil and lang.is_a? Hash and lang.size == 1
        @lang = lang.keys.first
        @format = lang[@lang]
      else
        @lang = lang
        @format = format
      end
      @options = options
    end

    class << self
      # To allow calls like Duo[:ruby, :html].highlight.
      alias [] new
    end

    # The scanner of the duo. Only created once.
    def scanner
      @scanner ||= CodeRay.scanner @lang, CodeRay.get_scanner_options(@options)
    end
    
    # The encoder of the duo. Only created once.
    def encoder
      @encoder ||= CodeRay.encoder @format, @options
    end
    
    # Tokenize and highlight the code using +scanner+ and +encoder+.
    #
    # If the :stream option is set, the Duo will go into streaming mode,
    # saving memory for the cost of time.
    def encode code, options = { :stream => false }
      stream = options.delete :stream
      options = @options.merge options
      if stream
        encoder.encode_stream(code, @lang, options)
      else
        scanner.code = code
        encoder.encode_tokens(scanner.tokenize, options)
      end
    end
    alias highlight encode

  end

end