crush 0.2.0 → 0.3.0

data/.travis.yml

@@ -0,0 +1,4 @@
+rvm:
+  - 1.8.7
+  - 1.9.2
+  

data/README.md

@@ -1,80 +1,116 @@
 Crush
 =====
 
-Crush is a generic interface, like Tilt, for the various compression engines in Ruby.
-It is useful for asset libraries that support multiple javascript and stylesheet compression engines.
+Crush is a set of Tilt templates for the various JavaScript and CSS compression libraries in Ruby.
+
+See here for more information about Tilt templates: [http://github.com/rtomayko/tilt](https://github.com/rtomayko/tilt)
+
+Well, they're not really templates. They're more like engines or processors. But, anyway, they fit
+in very well with Tilt, because each one likes to do things a little differently. Tilt + Crush cures
+the headache by providing a generic API to use any of the engines you need.
 
 Basic Usage
 -----------
 
+Step 1, Install:
+
+```
+gem install crush
+```
+
+Step 2, Compress:
+
 ```ruby
-require "uglifier"
 require "crush"
-Crush.new("application.js").compress
+Crush.register
+Tilt.new("application.js").render
+# => compressed JavaScript...
 ```
 
-This would automatically compress the data found in the `application.js` file using Uglifier.
-Crush favors engines whose libraries have already been loaded.
+Tilt Mappings
+-------------
 
-If you have multiple compression libraries loaded, and you want to control which one to use,
-you can initialize the engine directly.
+If you look closely at the above example, you had to call `Crush.register` before you could
+use any of the engines. That's because, by default, Crush does not automatically register
+its templates with Tilt. But, fear not, it's insanely easy to register them.
 
 ```ruby
-require "uglifier"
-require "jsmin"
 require "crush"
-Crush::Uglifier.new("application.js").compress
+Crush.register
+# or you can use this shortcut to do the same thing:
+require "crush/all"
 ```
 
-Or you could use `Crush.prefer` to tell Crush which engine you'd like to use.
+If you only want to use the JavaScript templates:
 
 ```ruby
-require "uglifier"
-require "jsmin"
 require "crush"
-Crush.prefer(Crush::Uglifier) # or Crush.prefer(:uglifier)
-Crush.new("application.js").compress
+Crush.register_js
+# or just:
+require "crush/js"
 ```
 
-API
----
-
-There a few different ways to compress some data. The API, for the most part, follows the Tilt
-API. So this is the standard way of compressing (reading the data from the file):
+CSS engines only:
 
 ```ruby
-Crush.new("file.js", :mangle => true).compress
+require "crush"
+Crush.register_css
+# or, because I love shortcuts so much:
+require "crush/css"
 ```
 
-You can also pass the data using a block, like Tilt.
+And finally, it's not hard to register only the ones you need, manually:
 
 ```ruby
-Crush.new(:uglifier, :mangle => true) { "some data to compress" }.compress
+require "crush"
+Tilt.register Crush::Uglifier, "js"
+Tilt.register Crush::Rainpress, "css"
 ```
 
-_Note how I declared which engine to use by its name (as a Symbol)._
+Generic API
+-----------
+
+The included templates are actually subclasses of `Crush::Engine`, which adds a few
+methods somewhat common to compression libraries.
+
+`Crush::Engine.compress` takes the given string and immediately compresses it. It is also
+aliased as `compile`.
+
+```ruby
+Crush::CSSMin.compress "body { color: red; }"
+# => "body{color:red;}"
+
+# Using Tilt's interface:
+Tilt[:css].compress "body { color: red; }"
+# => "body{color:red;}"
+```
 
-I've also included a way to pass data that is more consistent with the other compression engines:
+`Crush::Engine`s do not require data from a file or block like `Tilt::Template`s. They can
+be initialized and given data through the `Crush::Engine#compress` instance method, which
+is also aliased as `compile`.
 
 ```ruby
-Crush.new(:uglifier, :mangle => true).compress("some data to compress")
+engine = Crush::CSSMin.new
+# Does not through an ArgumentError like a Tilt::Template
+engine.compress "body { color: red; }"
+# => "body{color:red;}"
 ```
 
-Engines
--------
+Included Engines
+----------------
 
 Support fo these compression engines are included:
 
-    ENGINES                    FILE EXTENSIONS    NAME       REQUIRED LIBRARIES
-    -------------------------- ------------------ ---------- ------------------
-    JSMin                      .js,  .min.js      jsmin      jsmin
-    Packr                      .js,  .pack.js     packr      packr
-    YUI::JavaScriptCompressor  .js,  .yui.js      yui_js     yui/compressor
-    Closure::Compiler          .js,  .closure.js  closure    closure-compiler
-    Uglifier                   .js,  .ugly.js     uglifier   uglifier
-    CSSMin                     .css, .min.css     cssmin     cssmin
-    Rainpress                  .css, .rain.css    rainpress  rainpress
-    YUI::CssCompressor         .css, .yui.css     yui_css    yui/compressor    
+    ENGINES                    EXTENSIONS  REQUIRED LIBRARIES
+    -------------------------- ----------- -----------------------
+    JSMin                      .js         jsmin
+    Packr                      .js         packr
+    YUI::JavaScriptCompressor  .js         yui/compressor
+    Closure::Compiler          .js         closure-compiler
+    Uglifier                   .js         uglifier
+    CSSMin                     .css        cssmin
+    Rainpress                  .css        rainpress
+    YUI::CssCompressor         .css        yui/compressor    
 
 Copyright
 ---------

data/crush.gemspec

@@ -5,15 +5,18 @@ require "crush/version"
 Gem::Specification.new do |s|
   s.name        = "crush"
   s.version     = Crush::VERSION
-  s.authors     = %w(Pete Browne)
+  s.authors     = [ "Pete Browne" ]
   s.email       = "me@petebrowne.com"
   s.homepage    = "http://github.com/petebrowne/crush"
-  s.summary     = "A generic interface to multiple Ruby compression engines."
-  s.description = "Crush is a generic interface, like Tilt, for the various compression engines in Ruby."
+  s.summary     = "Tilt templates for various JavaScript and CSS compression libraries."
+  s.description = "Crush is a set of Tilt templates for the various JavaScript and CSS compression libraries in Ruby."
 
   s.rubyforge_project = "crush"
+
+  s.add_dependency "tilt", "~> 1.3"
   
-  s.add_development_dependency "rspec", "~> 2.6.0"
+  s.add_development_dependency "rspec", "~> 2.6"
+  s.add_development_dependency "rake"
   s.add_development_dependency "jsmin"
   s.add_development_dependency "packr"
   s.add_development_dependency "uglifier"

data/lib/crush.rb

@@ -1,4 +1,9 @@
+require "tilt"
+require "crush/version"
+
 module Crush
+  extend self
+  
   autoload :Closure,   "crush/closure"
   autoload :CSSMin,    "crush/cssmin"
   autoload :Engine,    "crush/engine"
@@ -8,101 +13,42 @@ module Crush
   autoload :Uglifier,  "crush/uglifier"
   autoload :YUI,       "crush/yui"
   
-  class EngineNotFound < StandardError; end
-  
-  @preferred_engines = {}
-  @engine_mappings   = Hash.new { |h, k| h[k] = [] }
-  
-  # Hash of registered compression engines.
-  def self.mappings
-    @engine_mappings
-  end
-  
-  # Ensures the extension doesn't include the "."
-  def self.normalize(ext)
-    ext.to_s.downcase.sub /^\./, ""
-  end
-  
-  # Registers a compression engine for the given file extension(s).
-  def self.register(engine, *extensions)
-    extensions.each do |ext|
-      ext = normalize(ext)
-      mappings[ext].unshift(engine).uniq!
-    end
-  end
-  
-  # Returns true when an engine exists for the given file extension.
-  def self.registered?(ext)
-    ext = normalize(ext)
-    mappings.key?(ext) && !mappings[ext].empty?
-  end
-  
-  # Make the given compression engine preferred. Which means,
-  # it will reordered the beginning of its mapping.
-  def self.prefer(engine_or_name, *extensions)
-    engine = find_by_name(engine_or_name) unless engine_or_name.is_a?(Class)
-    
-    if extensions.empty?
-      mappings.each do |ext, engines|
-        @preferred_engines[ext] = engine if engines.include?(engine)
-      end
-    else
-      register(engine, *extensions)
-      extensions.each do |ext|
-        ext = normalize(ext)
-        @preferred_engines[ext] = engine
-      end
-    end
-  end
-  
-  # Looks for a compression engine. When given a Symbol, it will look for an engine
-  # by name. When given a String, it will look for a compression engine by filename
-  # or file extension.
-  def self.[](path_or_name)
-    path_or_name.is_a?(Symbol) ? find_by_name(path_or_name) : find_by_path(path_or_name)
-  end
-  
-  # Create a new compression engine. The first argument is used to determine
-  # which engine to use. This can be either an engine name (as a Symbol) or a path
-  # to a file (as a String). If a path is given, the engine is initialized with
-  # a reference to that path.
-  def self.new(path_or_name, options = {}, &block)
-    if engine = self[path_or_name]
-      path = path_or_name.is_a?(Symbol) ? nil : path_or_name
-      engine.new(path, options, &block)
-    else
-      raise EngineNotFound.new("No compression engine registered for '#{path}'")
-    end
-  end
-  
-  # Look for a compression engine with the given engine name.
-  # Return nil when no engine is found.
-  def self.find_by_name(engine_name)
-    mappings.values.flatten.detect { |engine| engine.engine_name == engine_name.to_s }
-  end
-  
-  # Look for a compression engine for the given filename or file
-  # extension. Return nil when no engine is found.
-  def self.find_by_path(path)
-    pattern = File.basename(path.to_s).downcase
-    until pattern.empty? || registered?(pattern)
-      pattern.sub! /^[^.]*\.?/, ""
-    end
-    pattern = normalize(pattern)
-    
-    preferred_engine = @preferred_engines[pattern]
-    return preferred_engine unless preferred_engine.nil?
-    
-    mappings[pattern].detect(&:engine_initialized?) || mappings[pattern].first
-  end
-  
-  register Crush::JSMin,                     "js",  "min.js"
-  register Crush::Packr,                     "js",  "pack.js"
-  register Crush::YUI::JavaScriptCompressor, "js",  "yui.js"
-  register Crush::Closure::Compiler,         "js",  "closure.js"
-  register Crush::Uglifier,                  "js",  "ugly.js"
-  
-  register Crush::CSSMin,                    "css", "min.css"
-  register Crush::Rainpress,                 "css", "rain.css"
-  register Crush::YUI::CssCompressor,        "css", "yui.css"
+  # Registers all of the JavaScripts engines
+  # with Tilt in the following order of importance:
+  #
+  # 1. Crush::Uglifer
+  # 2. Crush::Closure::Compiler
+  # 3. Crush::YUI::JavaScriptCompressor
+  # 4. Crush::Packr
+  # 5. Crush::JSMin
+  def register_js
+    Tilt.register JSMin,                     "js"
+    Tilt.register Packr,                     "js"
+    Tilt.register YUI::JavaScriptCompressor, "js"
+    Tilt.register Closure::Compiler,         "js"
+    Tilt.register Uglifier,                  "js"
+  end
+  
+  # Registers all of the CSS engines
+  # with Tilt in the following order of importance:
+  #
+  # 3. Crush::CSSMin
+  # 4. Crush::Rainpress
+  # 5. Crush::YUI::CssCompressor
+  def register_css
+    Tilt.register CSSMin,             "css"
+    Tilt.register Rainpress,          "css"
+    Tilt.register YUI::CssCompressor, "css"
+  end
+  
+  # Registers all of the included engines
+  # with Tilt.
+  #
+  # (see #register_js)
+  # (see #register_css)
+  def register
+    register_js
+    register_css
+  end
+  alias :register_all :register
 end

data/lib/crush/all.rb

@@ -0,0 +1,3 @@
+require "crush"
+
+Crush.register

data/lib/crush/closure.rb

@@ -1,12 +1,16 @@
+require "crush/engine"
+
 module Crush
   module Closure
+    # Engine implementation of Google's Closure Compiler,
+    # using the closure-compiler gem. See:
+    #
+    # https://rubygems.org/gems/closure-compiler
     class Compiler < Crush::Engine
-      def self.engine_name
-        "closure"
-      end
+      self.default_mime_type = "application/javascript"
       
       def self.engine_initialized?
-        !!(defined? ::Closure) && !!(defined? ::Closure::Compiler)
+        !!(defined? ::Closure && defined? ::Closure::Compiler)
       end
     
       def initialize_engine
@@ -15,10 +19,11 @@ module Crush
     
       def prepare
         @engine = ::Closure::Compiler.new(options)
+        @output = nil
       end
     
-      def evaluate
-        @engine.compile(data)
+      def evaluate(scope, locals, &block)
+        @output ||= @engine.compile(data)
       end
     end
   end

data/lib/crush/css.rb

@@ -0,0 +1,3 @@
+require "crush"
+
+Crush.register_css

data/lib/crush/cssmin.rb

@@ -1,8 +1,12 @@
+require "crush/engine"
+
 module Crush
+  # Engine implementation of the CSS minification
+  # library, CSSMin. See:
+  #
+  # https://rubygems.org/gems/cssmin
   class CSSMin < Engine
-    def self.engine_name
-      "cssmin"
-    end
+    self.default_mime_type = "text/css"
       
     def self.engine_initialized?
       !!(defined? ::CSSMin)
@@ -12,8 +16,12 @@ module Crush
       require_template_library "cssmin"
     end
     
-    def evaluate
-      ::CSSMin.minify(data)
+    def prepare
+      @output = nil
+    end
+    
+    def evaluate(scope, locals, &block)
+      @output ||= ::CSSMin.minify(data)
     end
   end
 end

data/lib/crush/engine.rb

@@ -1,100 +1,64 @@
+require "tilt/template"
+
 module Crush
-  class Engine
-    # The name of the file to be compressed
-    attr_reader :file
-    
-    # A Hash of compression engine specific options. This is passed directly
-    # to the underlying engine and is not used by the generic interface.
-    attr_reader :options
-    
-    # The data to cmopress; loaded from a file or given directly.
-    attr_reader :data
-    
-    # Used to determine if this class's initialize_engine method has
-    # been called yet.
-    @engine_initialized = false
+  # Crush::Engine is an abstract class like Tilt::Template,
+  # which adds methods common to compression library APIs.
+  class Engine < Tilt::Template
     class << self
-      attr_accessor :engine_initialized
-      alias :engine_initialized? :engine_initialized
-      
-      # Returns a lowercase, underscored name for the engine.
-      def engine_name
-        engine_name = name.to_s.dup
-        engine_name.sub!  /^.*::/ , ""
-        engine_name.gsub! /([A-Z]+)([A-Z][a-z])/, '\1_\2'
-        engine_name.gsub! /([a-z\d])([A-Z])/, '\1_\2'
-        engine_name.tr!   "-", "_"
-        engine_name.downcase!
-        engine_name
+      # Convenience method of initializing an
+      # engine and immediately compressing the given
+      # data.
+      #
+      # @param [String] data The data to compress.
+      # @param [Hash] options Options to pass to the 
+      #   underlying compressor.
+      # @return [String] the compressed data.
+      def compress(data, options = {})
+        self.new(options).compress(data)
       end
+      alias :compile :compress
     end
     
-    # Create a new engine with the file and options specified. By
-    # default, the data to compress is read from the file. When a block is given,
-    # it should read data and return as a String.
+    # Override Tilt::Template#initialize so that it
+    # does not require a file or block. This is done
+    # so that Crush::Engines can follow the usual
+    # compressor API convention of having an instance
+    # method, #compress, which accepts the data to
+    # compress as an argument.
     #
-    # All arguments are optional.
-    def initialize(file = nil, options = nil)
-      if file.respond_to?(:to_hash)
-        @options = file.to_hash
-      else
-        @file    = file
-        @options = options || {}
-      end
-      
-      unless self.class.engine_initialized?
-        initialize_engine
-        self.class.engine_initialized = true
+    # (see Tilt::Template#initialize)
+    def initialize(file = nil, *args, &block)
+      unless block_given? or args[0].respond_to?(:to_str)
+        block = Proc.new {}
       end
-      
-      @data = if block_given?
-        yield
-      elsif @file
-        File.respond_to?(:binread) ? File.binread(@file) : File.read(@file)
-      end
-      
-      prepare
+      super file, *args, &block
+    end
+    
+    # Compresses the given data.
+    #
+    # @param [String] data The data to compress.
+    # @return [String] the compressed data.
+    def compress(data = nil)
+      @data = data.to_s unless data.nil?
+      render
     end
+    alias :compile :compress
     
-    # Compresses the data. Data can be read through the file or the block
-    # given at initialization, or through passing it here directly.
-    def render(data = nil)
-      @data = data unless data.nil?
-      evaluate
+    # Override Tilt::Template#render to check for
+    # data and raise an error if there isn't any.
+    #
+    # (see Tilt::Template#render)
+    def render(*args)
+      raise ArgumentError, "data must be set before rendering" if @data.nil?
+      super
     end
-    alias :compress :render
-    alias :compile :render
     
     protected
     
-      # Called once and only once for each template subclass the first time
-      # the engine class is initialized. This should be used to require the
-      # underlying engine library and perform any initial setup.
-      def initialize_engine
-        
-      end
-      
-      # Do whatever preparation is necessary to setup the underlying compression
-      # engine. Called immediately after template data is loaded. Instance
-      # variables set in this method are available when #compress is called.
-      def prepare
-        
-      end
-      
-      # Called when it's time to compress. Return the compressed data
-      # from this method.
-      def evaluate
-        
-      end
-      
-      # Like Kernel::require but issues a warning urging a manual require when
-      # running under a threaded environment.
-      def require_template_library(name)
-        if Thread.list.size > 1
-          warn "WARN: crush autoloading '#{name}' in a non thread-safe way; " +
-               "explicit require '#{name}' suggested."
-        end
-        require name
-      end
+    # Crush::Engines are usually very, very simple.
+    # There's no need for them to be required to
+    # implement #prepare.
+    def prepare
+    end
   end
 end