coderay 1.0.0 → 1.0.0.598.pre

data/lib/coderay/helpers/gzip_simple.rb

@@ -0,0 +1,123 @@
+# =GZip Simple
+#
+# A simplified interface to the gzip library +zlib+ (from the Ruby Standard Library.)
+#
+# Author: murphy (mail to murphy rubychan de)
+#
+# Version: 0.2 (2005.may.28)
+#
+# ==Documentation
+#
+# See +GZip+ module and the +String+ extensions.
+#
+module GZip
+
+  require 'zlib'
+
+  # The default zipping level. 7 zips good and fast.
+  DEFAULT_GZIP_LEVEL = 7
+
+  # Unzips the given string +s+.
+  #
+  # Example:
+  #   require 'gzip_simple'
+  #   print GZip.gunzip(File.read('adresses.gz'))
+  def GZip.gunzip s
+    Zlib::Inflate.inflate s
+  end
+
+  # Zips the given string +s+.
+  #
+  # Example:
+  #   require 'gzip_simple'
+  #   File.open('adresses.gz', 'w') do |file
+  #     file.write GZip.gzip('Mum: 0123 456 789', 9)
+  #   end
+  #
+  # If you provide a +level+, you can control how strong
+  # the string is compressed:
+  # - 0: no compression, only convert to gzip format
+  # - 1: compress fast
+  # - 7: compress more, but still fast (default)
+  # - 8: compress more, slower
+  # - 9: compress best, very slow
+  def GZip.gzip s, level = DEFAULT_GZIP_LEVEL
+    Zlib::Deflate.new(level).deflate s, Zlib::FINISH
+  end
+end
+
+
+# String extensions to use the GZip module.
+#
+# The methods gzip and gunzip provide an even more simple
+# interface to the ZLib:
+#
+#   # create a big string
+#   x = 'a' * 1000
+#   
+#   # zip it
+#   x_gz = x.gzip
+#   
+#   # test the result
+#   puts 'Zipped %d bytes to %d bytes.' % [x.size, x_gz.size]
+#   #-> Zipped 1000 bytes to 19 bytes.
+#   
+#   # unzipping works
+#   p x_gz.gunzip == x  #-> true
+class String
+  # Returns the string, unzipped.
+  # See GZip.gunzip
+  def gunzip
+    GZip.gunzip self
+  end
+  # Replaces the string with its unzipped value.
+  # See GZip.gunzip
+  def gunzip!
+    replace gunzip
+  end
+
+  # Returns the string, zipped.
+  # +level+ is the gzip compression level, see GZip.gzip.
+  def gzip level = GZip::DEFAULT_GZIP_LEVEL
+    GZip.gzip self, level
+  end
+  # Replaces the string with its zipped value.
+  # See GZip.gzip.
+  def gzip!(*args)
+    replace gzip(*args)
+  end
+end
+
+if $0 == __FILE__
+  eval DATA.read, nil, $0, __LINE__+4
+end
+
+__END__
+#CODE
+
+# Testing / Benchmark
+x = 'a' * 1000
+x_gz = x.gzip
+puts 'Zipped %d bytes to %d bytes.' % [x.size, x_gz.size]  #-> Zipped 1000 bytes to 19 bytes.
+p x_gz.gunzip == x  #-> true
+
+require 'benchmark'
+
+INFO = 'packed to %0.3f%%'  # :nodoc:
+
+x = Array.new(100000) { rand(255).chr + 'aaaaaaaaa' + rand(255).chr }.join
+Benchmark.bm(10) do |bm|
+  for level in 0..9
+    bm.report "zip #{level}" do
+      $x = x.gzip level
+    end
+    puts INFO % [100.0 * $x.size / x.size]
+  end
+  bm.report 'zip' do
+    $x = x.gzip
+  end
+  puts INFO % [100.0 * $x.size / x.size]
+  bm.report 'unzip' do
+    $x.gunzip
+  end
+end

data/lib/coderay/helpers/plugin.rb

@@ -1,284 +1,350 @@
 module CodeRay
   
-  # = PluginHost
-  #
-  # A simple subclass/subfolder plugin system.
+# = PluginHost
+#
+# A simple subclass plugin system.
+#
+#  Example:
+#    class Generators < PluginHost
+#      plugin_path 'app/generators'
+#    end
+#    
+#    class Generator
+#      extend Plugin
+#      PLUGIN_HOST = Generators
+#    end
+#    
+#    class FancyGenerator < Generator
+#      register_for :fancy
+#    end
+#
+#    Generators[:fancy]  #-> FancyGenerator
+#    # or
+#    CodeRay.require_plugin 'Generators/fancy'
+module PluginHost
+
+  # Raised if Encoders::[] fails because:
+  # * a file could not be found
+  # * the requested Encoder is not registered
+  PluginNotFound = Class.new Exception
+  HostNotFound = Class.new Exception
+
+  PLUGIN_HOSTS = []
+  PLUGIN_HOSTS_BY_ID = {}  # dummy hash
+
+  # Loads all plugins using list and load.
+  def load_all
+    for plugin in list
+      load plugin
+    end
+  end
+
+  # Returns the Plugin for +id+.
   #
   # Example:
-  #  class Generators
-  #    extend PluginHost
-  #    plugin_path 'app/generators'
-  #  end
-  #  
-  #  class Generator
-  #    extend Plugin
-  #    PLUGIN_HOST = Generators
-  #  end
-  #  
-  #  class FancyGenerator < Generator
-  #    register_for :fancy
-  #  end
-  #  
-  #  Generators[:fancy]  #-> FancyGenerator
-  #  # or
-  #  CodeRay.require_plugin 'Generators/fancy'
-  #  # or
-  #  Generators::Fancy
-  module PluginHost
-    
-    # Raised if Encoders::[] fails because:
-    # * a file could not be found
-    # * the requested Plugin is not registered
-    PluginNotFound = Class.new LoadError
-    HostNotFound = Class.new LoadError
-    
-    PLUGIN_HOSTS = []
-    PLUGIN_HOSTS_BY_ID = {}  # dummy hash
-    
-    # Loads all plugins using list and load.
-    def load_all
-      for plugin in list
-        load plugin
-      end
-    end
-    
-    # Returns the Plugin for +id+.
-    #
-    # Example:
-    #  yaml_plugin = MyPluginHost[:yaml]
-    def [] id, *args, &blk
-      plugin = validate_id(id)
-      begin
-        plugin = plugin_hash.[] plugin, *args, &blk
-      end while plugin.is_a? Symbol
-      plugin
-    end
-    
-    alias load []
-    
-    # Tries to +load+ the missing plugin by translating +const+ to the
-    # underscore form (eg. LinesOfCode becomes lines_of_code).
-    def const_missing const
-      id = const.to_s.
-        gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
-        gsub(/([a-z\d])([A-Z])/,'\1_\2').
-        downcase
-      load id
+  #  yaml_plugin = MyPluginHost[:yaml]
+  def [] id, *args, &blk
+    plugin = validate_id(id)
+    begin
+      plugin = plugin_hash.[] plugin, *args, &blk
+    end while plugin.is_a? Symbol
+    plugin
+  end
+
+  # Alias for +[]+.
+  alias load []
+
+  def require_helper plugin_id, helper_name
+    path = path_to File.join(plugin_id, helper_name)
+    require path
+  end
+
+  class << self
+
+    # Adds the module/class to the PLUGIN_HOSTS list.
+    def extended mod
+      PLUGIN_HOSTS << mod
     end
-    
-    class << self
-      
-      # Adds the module/class to the PLUGIN_HOSTS list.
-      def extended mod
-        PLUGIN_HOSTS << mod
-      end
-      
+
+    # Warns you that you should not #include this module.
+    def included mod
+      warn "#{name} should not be included. Use extend."
     end
-    
-    # The path where the plugins can be found.
-    def plugin_path *args
-      unless args.empty?
-        @plugin_path = File.expand_path File.join(*args)
+
+    # Find the PluginHost for host_id.
+    def host_by_id host_id
+      unless PLUGIN_HOSTS_BY_ID.default_proc
+        ph = Hash.new do |h, a_host_id|
+          for host in PLUGIN_HOSTS
+            h[host.host_id] = host
+          end
+          h.fetch a_host_id, nil
+        end
+        PLUGIN_HOSTS_BY_ID.replace ph
       end
-      @plugin_path ||= ''
+      PLUGIN_HOSTS_BY_ID[host_id]
     end
-    
-    # Map a plugin_id to another.
-    #
-    # Usage: Put this in a file plugin_path/_map.rb.
-    #
-    #  class MyColorHost < PluginHost
-    #    map :navy => :dark_blue,
-    #      :maroon => :brown,
-    #      :luna => :moon
-    #  end
-    def map hash
-      for from, to in hash
-        from = validate_id from
-        to = validate_id to
-        plugin_hash[from] = to unless plugin_hash.has_key? from
-      end
+
+  end
+
+  # The path where the plugins can be found.
+  def plugin_path *args
+    unless args.empty?
+      @plugin_path = File.expand_path File.join(*args)
+      load_map
     end
-    
-    # Define the default plugin to use when no plugin is found
-    # for a given id, or return the default plugin.
-    #
-    # See also map.
-    #
-    #  class MyColorHost < PluginHost
-    #    map :navy => :dark_blue
-    #    default :gray
-    #  end
-    #  
-    #  MyColorHost.default  # loads and returns the Gray plugin
-    def default id = nil
-      if id
-        id = validate_id id
-        raise "The default plugin can't be named \"default\"." if id == :default
-        plugin_hash[:default] = id
-      else
-        load :default
-      end
+    @plugin_path
+  end
+
+  # The host's ID.
+  #
+  # If PLUGIN_HOST_ID is not set, it is simply the class name.
+  def host_id
+    if self.const_defined? :PLUGIN_HOST_ID
+      self::PLUGIN_HOST_ID
+    else
+      name
     end
-    
-    # Every plugin must register itself for +id+ by calling register_for,
-    # which calls this method.
-    #
-    # See Plugin#register_for.
-    def register plugin, id
-      plugin_hash[validate_id(id)] = plugin
+  end
+
+  # Map a plugin_id to another.
+  #
+  # Usage: Put this in a file plugin_path/_map.rb.
+  #
+  #  class MyColorHost < PluginHost
+  #    map :navy => :dark_blue,
+  #      :maroon => :brown,
+  #      :luna => :moon
+  #  end
+  def map hash
+    for from, to in hash
+      from = validate_id from
+      to = validate_id to
+      plugin_hash[from] = to unless plugin_hash.has_key? from
     end
-    
-    # A Hash of plugion_id => Plugin pairs.
-    def plugin_hash
-      @plugin_hash ||= make_plugin_hash
+  end
+
+  # Define the default plugin to use when no plugin is found
+  # for a given id.
+  #
+  # See also map.
+  #
+  #  class MyColorHost < PluginHost
+  #    map :navy => :dark_blue
+  #    default :gray
+  #  end
+  def default id = nil
+    if id
+      id = validate_id id
+      plugin_hash[nil] = id
+    else
+      plugin_hash[nil]
     end
-    
-    # Returns an array of all .rb files in the plugin path.
-    #
-    # The extension .rb is not included.
-    def list
-      Dir[path_to('*')].select do |file|
-        File.basename(file)[/^(?!_)\w+\.rb$/]
-      end.map do |file|
-        File.basename(file, '.rb').to_sym
+  end
+
+  # Every plugin must register itself for one or more
+  # +ids+ by calling register_for, which calls this method.
+  #
+  # See Plugin#register_for.
+  def register plugin, *ids
+    for id in ids
+      unless id.is_a? Symbol
+        raise ArgumentError,
+          "id must be a Symbol, but it was a #{id.class}"
       end
+      plugin_hash[validate_id(id)] = plugin
     end
-    
-    # Returns an array of all Plugins.
-    # 
-    # Note: This loads all plugins using load_all.
-    def all_plugins
-      load_all
-      plugin_hash.values.grep(Class)
+  end
+
+  # A Hash of plugion_id => Plugin pairs.
+  def plugin_hash
+    @plugin_hash ||= create_plugin_hash
+  end
+
+  # Returns an array of all .rb files in the plugin path.
+  #
+  # The extension .rb is not included.
+  def list
+    Dir[path_to('*')].select do |file|
+      File.basename(file)[/^(?!_)\w+\.rb$/]
+    end.map do |file|
+      File.basename file, '.rb'
     end
-    
-    # Loads the map file (see map).
-    #
-    # This is done automatically when plugin_path is called.
-    def load_plugin_map
-      mapfile = path_to '_map'
-      @plugin_map_loaded = true
-      if File.exist? mapfile
-        require mapfile
-        true
-      else
-        false
-      end
+  end
+
+  # Makes a map of all loaded plugins.
+  def inspect
+    map = plugin_hash.dup
+    map.each do |id, plugin|
+      map[id] = plugin.to_s[/(?>\w+)$/]
     end
-    
-  protected
-    
-    # Return a plugin hash that automatically loads plugins.
-    def make_plugin_hash
-      @plugin_map_loaded ||= false
+    "#{name}[#{host_id}]#{map.inspect}"
+  end
+
+protected
+  # Created a new plugin list and stores it to @plugin_hash.
+  def create_plugin_hash
+    @plugin_hash =
       Hash.new do |h, plugin_id|
         id = validate_id(plugin_id)
         path = path_to id
         begin
-          raise LoadError, "#{path} not found" unless File.exist? path
           require path
         rescue LoadError => boom
-          if @plugin_map_loaded
-            if h.has_key?(:default)
-              warn '%p could not load plugin %p; falling back to %p' % [self, id, h[:default]]
-              h[:default]
-            else
-              raise PluginNotFound, '%p could not load plugin %p: %s' % [self, id, boom]
-            end
+          if h.has_key? nil  # default plugin
+            h[id] = h[nil]
           else
-            load_plugin_map
-            h[plugin_id]
+            raise PluginNotFound, 'Could not load plugin %p: %s' % [id, boom]
           end
         else
           # Plugin should have registered by now
-          if h.has_key? id
-            h[id]
-          else
-            raise PluginNotFound, "No #{self.name} plugin for #{id.inspect} found in #{path}."
+          unless h.has_key? id
+            raise PluginNotFound,
+              "No #{self.name} plugin for #{id.inspect} found in #{path}."
           end
         end
+        h[id]
       end
+  end
+
+  # Loads the map file (see map).
+  #
+  # This is done automatically when plugin_path is called.
+  def load_map
+    mapfile = path_to '_map'
+    if File.exist? mapfile
+      require mapfile
+    elsif $VERBOSE
+      warn 'no _map.rb found for %s' % name
     end
-    
-    # Returns the expected path to the plugin file for the given id.
-    def path_to plugin_id
-      File.join plugin_path, "#{plugin_id}.rb"
-    end
-    
-    # Converts +id+ to a Symbol if it is a String,
-    # or returns +id+ if it already is a Symbol.
-    #
-    # Raises +ArgumentError+ for all other objects, or if the
-    # given String includes non-alphanumeric characters (\W).
-    def validate_id id
-      if id.is_a? Symbol or id.nil?
-        id
-      elsif id.is_a? String
-        if id[/\w+/] == id
-          id.downcase.to_sym
-        else
-          raise ArgumentError, "Invalid id given: #{id}"
-        end
+  end
+
+  # Returns the Plugin for +id+.
+  # Use it like Hash#fetch.
+  #
+  # Example:
+  #  yaml_plugin = MyPluginHost[:yaml, :default]
+  def fetch id, *args, &blk
+    plugin_hash.fetch validate_id(id), *args, &blk
+  end
+
+  # Returns the expected path to the plugin file for the given id.
+  def path_to plugin_id
+    File.join plugin_path, "#{plugin_id}.rb"
+  end
+
+  # Converts +id+ to a Symbol if it is a String,
+  # or returns +id+ if it already is a Symbol.
+  #
+  # Raises +ArgumentError+ for all other objects, or if the
+  # given String includes non-alphanumeric characters (\W).
+  def validate_id id
+    if id.is_a? Symbol or id.nil?
+      id
+    elsif id.is_a? String
+      if id[/\w+/] == id
+        id.downcase.to_sym
       else
-        raise ArgumentError, "String or Symbol expected, but #{id.class} given."
+        raise ArgumentError, "Invalid id: '#{id}' given."
       end
+    else
+      raise ArgumentError,
+        "String or Symbol expected, but #{id.class} given."
     end
-    
+  end
+
+end
+
+
+# = Plugin
+#
+#  Plugins have to include this module.
+#
+#  IMPORTANT: use extend for this module.
+#
+#  Example: see PluginHost.
+module Plugin
+
+  def included mod
+    warn "#{name} should not be included. Use extend."
+  end
+
+  # Register this class for the given langs.
+  # Example:
+  #   class MyPlugin < PluginHost::BaseClass
+  #     register_for :my_id
+  #     ...
+  #   end
+  #
+  # See PluginHost.register.
+  def register_for *ids
+    @plugin_id = ids.first
+    plugin_host.register self, *ids
   end
   
-  
-  # = Plugin
+  # Returns the title of the plugin, or sets it to the
+  # optional argument +title+.
+  def title title = nil
+    if title
+      @title = title.to_s
+    else
+      @title ||= name[/([^:]+)$/, 1]
+    end
+  end
+
+  # The host for this Plugin class.
+  def plugin_host host = nil
+    if host and not host.is_a? PluginHost
+      raise ArgumentError,
+        "PluginHost expected, but #{host.class} given."
+    end
+    self.const_set :PLUGIN_HOST, host if host
+    self::PLUGIN_HOST
+  end
+
+  # Require some helper files.
   #
-  #  Plugins have to include this module.
+  # Example:
   #
-  #  IMPORTANT: Use extend for this module.
+  #  class MyPlugin < PluginHost::BaseClass
+  #     register_for :my_id
+  #     helper :my_helper
   #
-  #  See CodeRay::PluginHost for examples.
-  module Plugin
-    
-    attr_reader :plugin_id
-    
-    # Register this class for the given +id+.
-    # 
-    # Example:
-    #   class MyPlugin < PluginHost::BaseClass
-    #     register_for :my_id
-    #     ...
-    #   end
-    #
-    # See PluginHost.register.
-    def register_for id
-      @plugin_id = id
-      plugin_host.register self, id
-    end
-    
-    # Returns the title of the plugin, or sets it to the
-    # optional argument +title+.
-    def title title = nil
-      if title
-        @title = title.to_s
+  # The above example loads the file myplugin/my_helper.rb relative to the
+  # file in which MyPlugin was defined.
+  # 
+  # You can also load a helper from a different plugin:
+  # 
+  #  helper 'other_plugin/helper_name'
+  def helper *helpers
+    for helper in helpers
+      if helper.is_a?(String) && helper[/\//]
+        self::PLUGIN_HOST.require_helper $`, $'
       else
-        @title ||= name[/([^:]+)$/, 1]
-      end
-    end
-    
-    # The PluginHost for this Plugin class.
-    def plugin_host host = nil
-      if host.is_a? PluginHost
-        const_set :PLUGIN_HOST, host
-      end
-      self::PLUGIN_HOST
-    end
-    
-    def aliases
-      plugin_host.load_plugin_map
-      plugin_host.plugin_hash.inject [] do |aliases, (key, _)|
-        aliases << key if plugin_host[key] == self
-        aliases
+        self::PLUGIN_HOST.require_helper plugin_id.to_s, helper.to_s
       end
     end
-    
   end
-  
+
+  # Returns the pulgin id used by the engine.
+  def plugin_id
+    @plugin_id || name[/\w+$/].downcase
+  end
+
+end
+
+# Convenience method for plugin loading.
+# The syntax used is:
+#
+#  CodeRay.require_plugin '<Host ID>/<Plugin ID>'
+#
+# Returns the loaded plugin.
+def self.require_plugin path
+  host_id, plugin_id = path.split '/', 2
+  host = PluginHost.host_by_id(host_id)
+  raise PluginHost::HostNotFound,
+    "No host for #{host_id.inspect} found." unless host
+  host.load plugin_id
 end
+
+end