sprockets 1.0.2 → 2.0.0

data/lib/sprockets/engines.rb

@@ -0,0 +1,98 @@
+require 'sprockets/eco_template'
+require 'sprockets/ejs_template'
+require 'sprockets/jst_processor'
+require 'sprockets/utils'
+require 'tilt'
+
+module Sprockets
+  # `Engines` provides a global and `Environment` instance registry.
+  #
+  # An engine is a type of processor that is bound to an filename
+  # extension. `application.js.coffee` indicates that the
+  # `CoffeeScriptTemplate` engine will be ran on the file.
+  #
+  # Extensions can be stacked and will be evaulated from right to
+  # left. `application.js.coffee.erb` will first run `ERBTemplate`
+  # then `CoffeeScriptTemplate`.
+  #
+  # All `Engine`s must follow the `Tilt::Template` interface. It is
+  # recommended to subclass `Tilt::Template`.
+  #
+  # Its recommended that you register engine changes on your local
+  # `Environment` instance.
+  #
+  #     environment.register_engine '.foo', FooProcessor
+  #
+  # The global registry is exposed for plugins to register themselves.
+  #
+  #     Sprockets.register_engine '.sass', SassTemplate
+  #
+  module Engines
+    # Returns an `Array` of `Engine`s registered on the
+    # `Environment`. If an `ext` argument is supplied, the `Engine`
+    # register under that extension will be returned.
+    #
+    #     environment.engines
+    #     # => [CoffeeScriptTemplate, SassTemplate, ...]
+    #
+    #     environment.engines('.coffee')
+    #     # => CoffeeScriptTemplate
+    #
+    def engines(ext = nil)
+      if ext
+        ext = Sprockets::Utils.normalize_extension(ext)
+        @engines[ext]
+      else
+        @engines.dup
+      end
+    end
+
+    # Returns an `Array` of engine extension `String`s.
+    #
+    #     environment.engine_extensions
+    #     # => ['.coffee', '.sass', ...]
+    def engine_extensions
+      @engines.keys
+    end
+
+    # Registers a new Engine `klass` for `ext`. If the `ext` already
+    # has an engine registered, it will be overridden.
+    #
+    #     environment.register_engine '.coffee', CoffeeScriptTemplate
+    #
+    def register_engine(ext, klass)
+      ext = Sprockets::Utils.normalize_extension(ext)
+      @engines[ext] = klass
+    end
+
+    private
+      def deep_copy_hash(hash)
+        initial = Hash.new { |h, k| h[k] = [] }
+        hash.inject(initial) { |h, (k, a)| h[k] = a.dup; h }
+      end
+  end
+
+  # Extend Sprockets module to provide global registry
+  extend Engines
+  @engines = {}
+
+  # Cherry pick the default Tilt engines that make sense for
+  # Sprockets. We don't need ones that only generate html like HAML.
+
+  # Mmm, CoffeeScript
+  register_engine '.coffee', Tilt::CoffeeScriptTemplate
+
+  # JST engines
+  register_engine '.jst',    JstProcessor
+  register_engine '.eco',    EcoTemplate
+  register_engine '.ejs',    EjsTemplate
+
+  # CSS engines
+  register_engine '.less',   Tilt::LessTemplate
+  register_engine '.sass',   Tilt::SassTemplate
+  register_engine '.scss',   Tilt::ScssTemplate
+
+  # Other
+  register_engine '.erb',    Tilt::ERBTemplate
+  register_engine '.str',    Tilt::StringTemplate
+end

data/lib/sprockets/environment.rb

@@ -1,52 +1,93 @@
+require 'sprockets/base'
+require 'sprockets/charset_normalizer'
+require 'sprockets/context'
+require 'sprockets/directive_processor'
+require 'sprockets/index'
+require 'sprockets/safety_colons'
+
+require 'hike'
+require 'logger'
+require 'pathname'
+require 'tilt'
+
 module Sprockets
-  class Environment
-    attr_reader :root, :load_path
-    
-    def initialize(root, load_path = [])
-      @load_path = [@root = Pathname.new(self, root)]
-
-      load_path.reverse_each do |location|
-        register_load_location(location)
+  class Environment < Base
+    # `Environment` should initialized with your application's root
+    # directory. This should be the same as your Rails or Rack root.
+    #
+    #     env = Environment.new(Rails.root)
+    #
+    def initialize(root = ".")
+      @trail = Hike::Trail.new(root)
+
+      self.logger = Logger.new($stderr)
+      self.logger.level = Logger::FATAL
+
+      # Create a safe `Context` subclass to mutate
+      @context_class = Class.new(Context)
+
+      # Set MD5 as the default digest
+      require 'digest/md5'
+      @digest_class = ::Digest::MD5
+      @version = ''
+
+      @mime_types        = {}
+      @engines           = Sprockets.engines
+      @preprocessors     = Hash.new { |h, k| h[k] = [] }
+      @postprocessors    = Hash.new { |h, k| h[k] = [] }
+      @bundle_processors = Hash.new { |h, k| h[k] = [] }
+
+      @engines.each do |ext, klass|
+        add_engine_to_trail(ext, klass)
       end
-    end
-    
-    def pathname_from(location)
-      Pathname.new(self, absolute_location_from(location))
-    end
 
-    def register_load_location(location)
-      pathname = pathname_from(location)
-      load_path.delete(pathname)
-      load_path.unshift(pathname)
-      location
+      register_mime_type 'text/css', '.css'
+      register_mime_type 'application/javascript', '.js'
+
+      register_preprocessor 'text/css', DirectiveProcessor
+      register_preprocessor 'application/javascript', DirectiveProcessor
+
+      register_postprocessor 'application/javascript', SafetyColons
+      register_bundle_processor 'text/css', CharsetNormalizer
+
+      expire_index!
+
+      yield self if block_given?
     end
-    
-    def find(location)
-      if Sprockets.absolute?(location) && File.exists?(location)
-        pathname_from(location)
-      else
-        find_all(location).first
-      end
+
+    # Returns a cached version of the environment.
+    #
+    # All its file system calls are cached which makes `index` much
+    # faster. This behavior is ideal in production since the file
+    # system only changes between deploys.
+    def index
+      Index.new(self)
     end
-    
-    def constants(reload = false)
-      @constants = nil if reload
-      @constants ||= find_all("constants.yml").inject({}) do |constants, pathname|
-        contents = YAML.load(pathname.contents) rescue nil
-        contents = {} unless contents.is_a?(Hash)
-        constants.merge(contents)
+
+    # Cache `find_asset` calls
+    def find_asset(path, options = {})
+      # Ensure inmemory cached assets are still fresh on every lookup
+      if (asset = @assets[path.to_s]) && asset.fresh?
+        asset
+      elsif asset = super
+        @assets[path.to_s] = @assets[asset.pathname.to_s] = asset
+        asset
       end
     end
-    
+
     protected
-      def absolute_location_from(location)
-        location = location.to_s
-        location = File.join(root.absolute_location, location) unless Sprockets.absolute?(location)
-        File.expand_path(location)
+      # Cache asset building in persisted cache.
+      def build_asset(path, pathname, options)
+        # Persisted cache
+        cache_asset(pathname.to_s) do
+          super
+        end
       end
-      
-      def find_all(location)
-        load_path.map { |pathname| pathname.find(location) }.compact
+
+      def expire_index!
+        # Clear digest to be recomputed
+        @digest = nil
+        @assets = {}
       end
   end
 end

data/lib/sprockets/errors.rb

@@ -0,0 +1,17 @@
+# Define some basic Sprockets error classes
+module Sprockets
+  class Error           < StandardError; end
+  class ArgumentError           < Error; end
+  class CircularDependencyError < Error; end
+  class ContentTypeMismatch     < Error; end
+  class EncodingError           < Error; end
+  class FileNotFound            < Error; end
+
+  module EngineError
+    attr_accessor :sprockets_annotation
+
+    def message
+      [super, sprockets_annotation].compact.join("\n")
+    end
+  end
+end

data/lib/sprockets/index.rb

@@ -0,0 +1,79 @@
+require 'sprockets/base'
+
+module Sprockets
+  # `Index` is a special cached version of `Environment`.
+  #
+  # The expection is that all of its file system methods are cached
+  # for the instances lifetime. This makes `Index` much faster. This
+  # behavior is ideal in production environments where the file system
+  # is immutable.
+  #
+  # `Index` should not be initialized directly. Instead use
+  # `Environment#index`.
+  class Index < Base
+    def initialize(environment)
+      # Copy environment attributes
+      @logger            = environment.logger
+      @context_class     = environment.context_class
+      @cache             = environment.cache
+      @trail             = environment.trail.index
+      @digest            = environment.digest
+      @digest_class      = environment.digest_class
+      @version           = environment.version
+      @mime_types        = environment.mime_types
+      @engines           = environment.engines
+      @preprocessors     = environment.preprocessors
+      @postprocessors    = environment.postprocessors
+      @bundle_processors = environment.bundle_processors
+
+      # Initialize caches
+      @assets  = {}
+      @digests = {}
+    end
+
+    # No-op return self as index
+    def index
+      self
+    end
+
+    # Cache calls to `file_digest`
+    def file_digest(pathname, data = nil)
+      memoize(@digests, pathname.to_s) { super }
+    end
+
+    # Cache `find_asset` calls
+    def find_asset(path, options = {})
+      if asset = @assets[path.to_s]
+        asset
+      elsif asset = super
+        # Cache at logical path and expanded path
+        @assets[path.to_s] = @assets[asset.pathname.to_s] = asset
+        asset
+      end
+    end
+
+    protected
+      # Index is immutable, any methods that try to clear the cache
+      # should bomb.
+      def expire_index!
+        raise TypeError, "can't modify immutable index"
+      end
+
+      # Cache asset building in memory and in persisted cache.
+      def build_asset(path, pathname, options)
+        # Memory cache
+        memoize(@assets, pathname.to_s) do
+          # Persisted cache
+          cache_asset(pathname.to_s) do
+            super
+          end
+        end
+      end
+
+    private
+      # Simple memoize helper that stores `nil` values
+      def memoize(hash, key)
+        hash.key?(key) ? hash[key] : hash[key] = yield
+      end
+  end
+end

data/lib/sprockets/jst_processor.rb

@@ -0,0 +1,26 @@
+require 'tilt'
+
+module Sprockets
+  class JstProcessor < Tilt::Template
+    def self.default_mime_type
+      'application/javascript'
+    end
+
+    def prepare
+    end
+
+    def evaluate(scope, locals, &block)
+      <<-JST
+(function() {
+  this.JST || (this.JST = {});
+  this.JST[#{scope.logical_path.inspect}] = #{indent(data)};
+}).call(this);
+      JST
+    end
+
+    private
+      def indent(string)
+        string.gsub(/$(.)/m, "\\1  ").strip
+      end
+  end
+end

data/lib/sprockets/mime.rb

@@ -0,0 +1,38 @@
+require 'rack/mime'
+
+module Sprockets
+  module Mime
+    # Returns a `Hash` of registered mime types registered on the
+    # environment and those part of `Rack::Mime`.
+    #
+    # If an `ext` is given, it will lookup the mime type for that extension.
+    def mime_types(ext = nil)
+      if ext.nil?
+        Rack::Mime::MIME_TYPES.merge(@mime_types)
+      else
+        ext = Sprockets::Utils.normalize_extension(ext)
+        @mime_types[ext] || Rack::Mime::MIME_TYPES[ext]
+      end
+    end
+
+    if {}.respond_to?(:key)
+      def extension_for_mime_type(type)
+        mime_types.key(type)
+      end
+    else
+      def extension_for_mime_type(type)
+        mime_types.index(type)
+      end
+    end
+
+    # Register a new mime type.
+    def register_mime_type(mime_type, ext)
+      ext = Sprockets::Utils.normalize_extension(ext)
+      @mime_types[ext] = mime_type
+    end
+  end
+
+  # Extend Sprockets module to provide global registry
+  extend Mime
+  @mime_types = {}
+end

data/lib/sprockets/processing.rb

@@ -0,0 +1,280 @@
+require 'sprockets/engines'
+require 'sprockets/mime'
+require 'sprockets/processor'
+require 'sprockets/utils'
+
+module Sprockets
+  # `Processing` is an internal mixin whose public methods are exposed on
+  # the `Environment` and `Index` classes.
+  module Processing
+    include Engines, Mime
+
+    # Register a new mime type.
+    def register_mime_type(mime_type, ext)
+      # Overrides the global behavior to expire the index
+      expire_index!
+      @trail.append_extension(ext)
+      super
+    end
+
+    # Returns an `Array` of format extension `String`s.
+    #
+    #     format_extensions
+    #     # => ['.js', '.css']
+    #
+    def format_extensions
+      @trail.extensions - @engines.keys
+    end
+
+    # Registers a new Engine `klass` for `ext`.
+    def register_engine(ext, klass)
+      # Overrides the global behavior to expire the index
+      expire_index!
+      add_engine_to_trail(ext, klass)
+      super
+    end
+
+    # Deprecated alias for `preprocessors`.
+    def processors(*args)
+      preprocessors(*args)
+    end
+
+    # Returns an `Array` of `Processor` classes. If a `mime_type`
+    # argument is supplied, the processors registered under that
+    # extension will be returned.
+    #
+    # Preprocessors are ran before Postprocessors and Engine
+    # processors.
+    #
+    # All `Processor`s must follow the `Tilt::Template` interface. It is
+    # recommended to subclass `Tilt::Template`.
+    def preprocessors(mime_type = nil)
+      if mime_type
+        @preprocessors[mime_type].dup
+      else
+        deep_copy_hash(@preprocessors)
+      end
+    end
+
+    # Returns an `Array` of `Processor` classes. If a `mime_type`
+    # argument is supplied, the processors registered under that
+    # extension will be returned.
+    #
+    # Postprocessors are ran after Postprocessors and Engine processors.
+    #
+    # All `Processor`s must follow the `Tilt::Template` interface. It is
+    # recommended to subclass `Tilt::Template`.
+    def postprocessors(mime_type = nil)
+      if mime_type
+        @postprocessors[mime_type].dup
+      else
+        deep_copy_hash(@postprocessors)
+      end
+    end
+
+    # Deprecated alias for `register_preprocessor`.
+    def register_processor(*args, &block)
+      register_preprocessor(*args, &block)
+    end
+
+    # Registers a new Preprocessor `klass` for `mime_type`.
+    #
+    #     register_preprocessor 'text/css', Sprockets::DirectiveProcessor
+    #
+    # A block can be passed for to create a shorthand processor.
+    #
+    #     register_preprocessor :my_processor do |context, data|
+    #       data.gsub(...)
+    #     end
+    #
+    def register_preprocessor(mime_type, klass, &block)
+      expire_index!
+
+      if block_given?
+        name  = klass.to_s
+        klass = Class.new(Processor) do
+          @name      = name
+          @processor = block
+        end
+      end
+
+      @preprocessors[mime_type].push(klass)
+    end
+
+    # Registers a new Postprocessor `klass` for `mime_type`.
+    #
+    #     register_postprocessor 'text/css', Sprockets::CharsetNormalizer
+    #
+    # A block can be passed for to create a shorthand processor.
+    #
+    #     register_postprocessor :my_processor do |context, data|
+    #       data.gsub(...)
+    #     end
+    #
+    def register_postprocessor(mime_type, klass, &block)
+      expire_index!
+
+      if block_given?
+        name  = klass.to_s
+        klass = Class.new(Processor) do
+          @name      = name
+          @processor = block
+        end
+      end
+
+      @postprocessors[mime_type].push(klass)
+    end
+
+    # Deprecated alias for `unregister_preprocessor`.
+    def unregister_processor(*args)
+      unregister_preprocessor(*args)
+    end
+
+    # Remove Preprocessor `klass` for `mime_type`.
+    #
+    #     unregister_preprocessor 'text/css', Sprockets::DirectiveProcessor
+    #
+    def unregister_preprocessor(mime_type, klass)
+      expire_index!
+
+      if klass.is_a?(String) || klass.is_a?(Symbol)
+        klass = @preprocessors[mime_type].detect { |cls|
+          cls.respond_to?(:name) &&
+            cls.name == "Sprockets::Processor (#{klass})"
+        }
+      end
+
+      @preprocessors[mime_type].delete(klass)
+    end
+
+    # Remove Postprocessor `klass` for `mime_type`.
+    #
+    #     unregister_postprocessor 'text/css', Sprockets::DirectiveProcessor
+    #
+    def unregister_postprocessor(mime_type, klass)
+      expire_index!
+
+      if klass.is_a?(String) || klass.is_a?(Symbol)
+        klass = @postprocessors[mime_type].detect { |cls|
+          cls.respond_to?(:name) &&
+            cls.name == "Sprockets::Processor (#{klass})"
+        }
+      end
+
+      @postprocessors[mime_type].delete(klass)
+    end
+
+    # Returns an `Array` of `Processor` classes. If a `mime_type`
+    # argument is supplied, the processors registered under that
+    # extension will be returned.
+    #
+    # Bundle Processors are ran on concatenated assets rather than
+    # individual files.
+    #
+    # All `Processor`s must follow the `Tilt::Template` interface. It is
+    # recommended to subclass `Tilt::Template`.
+    def bundle_processors(mime_type = nil)
+      if mime_type
+        @bundle_processors[mime_type].dup
+      else
+        deep_copy_hash(@bundle_processors)
+      end
+    end
+
+    # Registers a new Bundle Processor `klass` for `mime_type`.
+    #
+    #     register_bundle_processor  'text/css', Sprockets::CharsetNormalizer
+    #
+    # A block can be passed for to create a shorthand processor.
+    #
+    #     register_bundle_processor :my_processor do |context, data|
+    #       data.gsub(...)
+    #     end
+    #
+    def register_bundle_processor(mime_type, klass, &block)
+      expire_index!
+
+      if block_given?
+        name  = klass.to_s
+        klass = Class.new(Processor) do
+          @name      = name
+          @processor = block
+        end
+      end
+
+      @bundle_processors[mime_type].push(klass)
+    end
+
+    # Remove Bundle Processor `klass` for `mime_type`.
+    #
+    #     unregister_bundle_processor 'text/css', Sprockets::CharsetNormalizer
+    #
+    def unregister_bundle_processor(mime_type, klass)
+      expire_index!
+
+      if klass.is_a?(String) || klass.is_a?(Symbol)
+        klass = @bundle_processors[mime_type].detect { |cls|
+          cls.respond_to?(:name) &&
+            cls.name == "Sprockets::Processor (#{klass})"
+        }
+      end
+
+      @bundle_processors[mime_type].delete(klass)
+    end
+
+    # Return CSS compressor or nil if none is set
+    def css_compressor
+      bundle_processors('text/css').detect { |klass|
+        klass.respond_to?(:name) &&
+          klass.name == 'Sprockets::Processor (css_compressor)'
+      }
+    end
+
+    # Assign a compressor to run on `text/css` assets.
+    #
+    # The compressor object must respond to `compress` or `compile`.
+    def css_compressor=(compressor)
+      expire_index!
+
+      unregister_bundle_processor 'text/css', :css_compressor
+      return unless compressor
+
+      register_bundle_processor 'text/css', :css_compressor do |context, data|
+        compressor.compress(data)
+      end
+    end
+
+    # Return JS compressor or nil if none is set
+    def js_compressor
+      bundle_processors('application/javascript').detect { |klass|
+        klass.respond_to?(:name) &&
+          klass.name == 'Sprockets::Processor (js_compressor)'
+      }
+    end
+
+    # Assign a compressor to run on `application/javascript` assets.
+    #
+    # The compressor object must respond to `compress` or `compile`.
+    def js_compressor=(compressor)
+      expire_index!
+
+      unregister_bundle_processor 'application/javascript', :js_compressor
+      return unless compressor
+
+      register_bundle_processor 'application/javascript', :js_compressor do |context, data|
+        compressor.compress(data)
+      end
+    end
+
+    private
+      def add_engine_to_trail(ext, klass)
+        @trail.append_extension(ext.to_s)
+
+        if klass.respond_to?(:default_mime_type) && klass.default_mime_type
+          if format_ext = extension_for_mime_type(klass.default_mime_type)
+            @trail.alias_extension(ext.to_s, format_ext)
+          end
+        end
+      end
+  end
+end