aliddle-sass 1.0

data/lib/sass/plugin/configuration.rb

@@ -0,0 +1,123 @@
+# We keep configuration in its own self-contained file
+# so that we can load it independently in Rails 3,
+# where the full plugin stuff is lazy-loaded.
+
+module Sass
+  module Plugin
+    module Configuration
+
+      # Returns the default options for a {Sass::Plugin::Compiler}.
+      #
+      # @return [{Symbol => Object}]
+      def default_options
+        @default_options ||= {
+          :css_location       => './public/stylesheets',
+          :always_update      => false,
+          :always_check       => true,
+          :full_exception     => true,
+          :cache_location     => ".sass-cache"
+        }.freeze
+      end
+
+      # Resets the options and {Sass::Callbacks::InstanceMethods#clear_callbacks! clears all callbacks}.
+      def reset!
+        @options = nil
+        clear_callbacks!
+      end
+
+      # An options hash.
+      # See {file:SASS_REFERENCE.md#sass_options the Sass options documentation}.
+      #
+      # @return [{Symbol => Object}]
+      def options
+        @options ||= default_options.dup
+      end
+
+      # Sets the options hash.
+      # See {file:SASS_REFERENCE.md#sass_options the Sass options documentation}.
+      # See {Sass::Plugin::Configuration#reset!}
+      # @deprecated Instead, modify the options hash in-place.
+      # @param value [{Symbol => Object}] The options hash
+      def options=(value)
+        Sass::Util.sass_warn("Setting Sass::Plugin.options is deprecated " +
+                             "and will be removed in a future release.")
+        options.merge!(value)
+      end
+
+      # Adds a new template-location/css-location mapping.
+      # This means that Sass/SCSS files in `template_location`
+      # will be compiled to CSS files in `css_location`.
+      #
+      # This is preferred over manually manipulating the {file:SASS_REFERENCE.md#template_location-option `:template_location` option}
+      # since the option can be in multiple formats.
+      #
+      # Note that this method will change `options[:template_location]`
+      # to be in the Array format.
+      # This means that even if `options[:template_location]`
+      # had previously been a Hash or a String,
+      # it will now be an Array.
+      #
+      # @param template_location [String] The location where Sass/SCSS files will be.
+      # @param css_location [String] The location where compiled CSS files will go.
+      def add_template_location(template_location, css_location = options[:css_location])
+        normalize_template_location!
+        template_location_array << [template_location, css_location]
+      end
+
+      # Removes a template-location/css-location mapping.
+      # This means that Sass/SCSS files in `template_location`
+      # will no longer be compiled to CSS files in `css_location`.
+      #
+      # This is preferred over manually manipulating the {file:SASS_REFERENCE.md#template_location-option `:template_location` option}
+      # since the option can be in multiple formats.
+      #
+      # Note that this method will change `options[:template_location]`
+      # to be in the Array format.
+      # This means that even if `options[:template_location]`
+      # had previously been a Hash or a String,
+      # it will now be an Array.
+      #
+      # @param template_location [String]
+      #   The location where Sass/SCSS files were,
+      #   which is now going to be ignored.
+      # @param css_location [String]
+      #   The location where compiled CSS files went, but will no longer go.
+      # @return [Boolean]
+      #   Non-`nil` if the given mapping already existed and was removed,
+      #   or `nil` if nothing was changed.
+      def remove_template_location(template_location, css_location = options[:css_location])
+        normalize_template_location!
+        template_location_array.delete([template_location, css_location])
+      end
+
+      # Returns the template locations configured for Sass
+      # as an array of `[template_location, css_location]` pairs.
+      # See the {file:SASS_REFERENCE.md#template_location-option `:template_location` option}
+      # for details.
+      #
+      # @return [Array<(String, String)>]
+      #   An array of `[template_location, css_location]` pairs.
+      def template_location_array
+        old_template_location = options[:template_location]
+        normalize_template_location!
+        options[:template_location]
+      ensure
+        options[:template_location] = old_template_location
+      end
+
+      private
+
+      def normalize_template_location!
+        return if options[:template_location].is_a?(Array)
+        options[:template_location] =
+          case options[:template_location]
+          when nil
+            options[:css_location] ?
+              [[File.join(options[:css_location], 'sass'), options[:css_location]]] : []
+          when String; [[options[:template_location], options[:css_location]]]
+          else; options[:template_location].to_a
+          end
+      end
+    end
+  end
+end

data/lib/sass/plugin/generic.rb

@@ -0,0 +1,15 @@
+# The reason some options are declared here rather than in sass/plugin/configuration.rb
+# is that otherwise they'd clobber the Rails-specific options.
+# Since Rails' options are lazy-loaded in Rails 3,
+# they're reverse-merged with the default options
+# so that user configuration is preserved.
+# This means that defaults that differ from Rails'
+# must be declared here.
+
+unless defined?(Sass::GENERIC_LOADED)
+  Sass::GENERIC_LOADED = true
+
+  Sass::Plugin.options.merge!(:css_location   => './public/stylesheets',
+                              :always_update  => false,
+                              :always_check   => true)
+end

data/lib/sass/plugin/merb.rb

@@ -0,0 +1,48 @@
+unless defined?(Sass::MERB_LOADED)
+  Sass::MERB_LOADED = true
+
+  module Sass::Plugin::Configuration
+    # Different default options in a m envirionment.
+    def default_options
+      @default_options ||= begin
+        version = Merb::VERSION.split('.').map { |n| n.to_i }
+        if version[0] <= 0 && version[1] < 5
+          root = MERB_ROOT
+          env  = MERB_ENV
+        else
+          root = Merb.root.to_s
+          env  = Merb.environment
+        end
+
+        {
+          :always_update      => false,
+          :template_location => root + '/public/stylesheets/sass',
+          :css_location      => root + '/public/stylesheets',
+          :cache_location    => root + '/tmp/sass-cache',
+          :always_check      => env != "production",
+          :quiet             => env != "production",
+          :full_exception    => env != "production"
+        }.freeze
+      end
+    end
+  end
+
+  config = Merb::Plugins.config[:sass] || Merb::Plugins.config["sass"] || {}
+
+  if defined? config.symbolize_keys!
+    config.symbolize_keys!
+  end
+
+  Sass::Plugin.options.merge!(config)
+
+  require 'sass/plugin/rack'
+  class Sass::Plugin::MerbBootLoader < Merb::BootLoader
+    after Merb::BootLoader::RackUpApplication
+
+    def self.run
+      # Apparently there's no better way than this to add Sass
+      # to Merb's Rack stack.
+      Merb::Config[:app] = Sass::Plugin::Rack.new(Merb::Config[:app])
+    end
+  end
+end

data/lib/sass/plugin/rack.rb

@@ -0,0 +1,60 @@
+module Sass
+  module Plugin
+    # Rack middleware for compiling Sass code.
+    #
+    # ## Activate
+    #
+    #     require 'sass/plugin/rack'
+    #     use Sass::Plugin::Rack
+    #
+    # ## Customize
+    #
+    #     Sass::Plugin.options.merge(
+    #       :cache_location => './tmp/sass-cache',
+    #       :never_update => environment != :production,
+    #       :full_exception => environment != :production)
+    #
+    # {file:SASS_REFERENCE.md#options See the Reference for more options}.
+    #
+    # ## Use
+    #
+    # Put your Sass files in `public/stylesheets/sass`.
+    # Your CSS will be generated in `public/stylesheets`,
+    # and regenerated every request if necessary.
+    # The locations and frequency {file:SASS_REFERENCE.md#options can be customized}.
+    # That's all there is to it!
+    class Rack
+      # The delay, in seconds, between update checks.
+      # Useful when many resources are requested for a single page.
+      # `nil` means no delay at all.
+      #
+      # @return [Float]
+      attr_accessor :dwell
+
+      # Initialize the middleware.
+      #
+      # @param app [#call] The Rack application
+      # @param dwell [Float] See \{#dwell}
+      def initialize(app, dwell = 1.0)
+        @app = app
+        @dwell = dwell
+        @check_after = Time.now.to_f
+      end
+
+      # Process a request, checking the Sass stylesheets for changes
+      # and updating them if necessary.
+      #
+      # @param env The Rack request environment
+      # @return [(#to_i, {String => String}, Object)] The Rack response
+      def call(env)
+        if @dwell.nil? || Time.now.to_f > @check_after
+          Sass::Plugin.check_for_updates
+          @check_after = Time.now.to_f + @dwell if @dwell
+        end
+        @app.call(env)
+      end
+    end
+  end
+end
+
+require 'sass/plugin'

data/lib/sass/plugin/rails.rb

@@ -0,0 +1,47 @@
+unless defined?(Sass::RAILS_LOADED)
+  Sass::RAILS_LOADED = true
+
+  module Sass::Plugin::Configuration
+    # Different default options in a rails envirionment.
+    def default_options
+      return @default_options if @default_options
+      opts = {
+        :quiet             => Sass::Util.rails_env != "production",
+        :full_exception    => Sass::Util.rails_env != "production",
+        :cache_location    => Sass::Util.rails_root + '/tmp/sass-cache'
+      }
+
+      opts.merge!(
+        :always_update     => false,
+        :template_location => Sass::Util.rails_root + '/public/stylesheets/sass',
+        :css_location      => Sass::Util.rails_root + '/public/stylesheets',
+        :always_check      => Sass::Util.rails_env == "development")
+
+      @default_options = opts.freeze
+    end
+  end
+
+  Sass::Plugin.options.reverse_merge!(Sass::Plugin.default_options)
+
+  # Rails 3.1 loads and handles Sass all on its own
+  if defined?(ActionController::Metal)
+    # 3.1 > Rails >= 3.0
+    require 'sass/plugin/rack'
+    Rails.configuration.middleware.use(Sass::Plugin::Rack)
+  elsif defined?(ActionController::Dispatcher) &&
+      defined?(ActionController::Dispatcher.middleware)
+    # Rails >= 2.3
+    require 'sass/plugin/rack'
+    ActionController::Dispatcher.middleware.use(Sass::Plugin::Rack)
+  else
+    module ActionController
+      class Base
+        alias_method :sass_old_process, :process
+        def process(*args)
+          Sass::Plugin.check_for_updates
+          sass_old_process(*args)
+        end
+      end
+    end
+  end
+end

data/lib/sass/plugin/staleness_checker.rb

@@ -0,0 +1,183 @@
+module Sass
+  module Plugin
+    # The class handles `.s[ca]ss` file staleness checks via their mtime timestamps.
+    #
+    # To speed things up two level of caches are employed:
+    #
+    # * A class-level dependency cache which stores @import paths for each file.
+    #   This is a long-lived cache that is reused by every StalenessChecker instance.
+    # * Three short-lived instance-level caches, one for file mtimes,
+    #   one for whether a file is stale during this particular run.
+    #   and one for the parse tree for a file.
+    #   These are only used by a single StalenessChecker instance.
+    #
+    # Usage:
+    #
+    # * For a one-off staleness check of a single `.s[ca]ss` file,
+    #   the class-level {stylesheet_needs_update?} method
+    #   should be used.
+    # * For a series of staleness checks (e.g. checking all files for staleness)
+    #   a StalenessChecker instance should be created,
+    #   and the instance-level \{#stylesheet\_needs\_update?} method should be used.
+    #   the caches should make the whole process significantly faster.
+    #   *WARNING*: It is important not to retain the instance for too long,
+    #   as its instance-level caches are never explicitly expired.
+    class StalenessChecker
+      @dependencies_cache = {}
+
+      class << self
+        # TODO: attach this to a compiler instance.
+        # @private
+        attr_accessor :dependencies_cache
+      end
+
+      # Creates a new StalenessChecker
+      # for checking the staleness of several stylesheets at once.
+      #
+      # @param options [{Symbol => Object}]
+      #   See {file:SASS_REFERENCE.md#sass_options the Sass options documentation}.
+      def initialize(options)
+        @dependencies = self.class.dependencies_cache
+
+        # URIs that are being actively checked for staleness. Protects against
+        # import loops.
+        @actively_checking = Set.new
+
+        # Entries in the following instance-level caches are never explicitly expired.
+        # Instead they are supposed to automaticaly go out of scope when a series of staleness checks
+        # (this instance of StalenessChecker was created for) is finished.
+        @mtimes, @dependencies_stale, @parse_trees = {}, {}, {}
+        @options = Sass::Engine.normalize_options(options)
+      end
+
+      # Returns whether or not a given CSS file is out of date
+      # and needs to be regenerated.
+      #
+      # @param css_file [String] The location of the CSS file to check.
+      # @param template_file [String] The location of the Sass or SCSS template
+      #   that is compiled to `css_file`.
+      # @return [Boolean] Whether the stylesheet needs to be updated.
+      def stylesheet_needs_update?(css_file, template_file, importer = nil)
+        template_file = File.expand_path(template_file)
+        begin
+          css_mtime = File.mtime(css_file)
+        rescue Errno::ENOENT
+          return true
+        end
+        stylesheet_modified_since?(template_file, css_mtime, importer)
+      end
+
+      # Returns whether a Sass or SCSS stylesheet has been modified since a given time.
+      #
+      # @param template_file [String] The location of the Sass or SCSS template.
+      # @param mtime [Fixnum] The modification time to check against.
+      # @param importer [Sass::Importers::Base] The importer used to locate the stylesheet.
+      #   Defaults to the filesystem importer.
+      # @return [Boolean] Whether the stylesheet has been modified.
+      def stylesheet_modified_since?(template_file, mtime, importer = nil)
+        importer ||= @options[:filesystem_importer].new(".")
+        dependency_updated?(mtime).call(template_file, importer)
+      end
+
+      # Returns whether or not a given CSS file is out of date
+      # and needs to be regenerated.
+      #
+      # The distinction between this method and the instance-level \{#stylesheet\_needs\_update?}
+      # is that the instance method preserves mtime and stale-dependency caches,
+      # so it's better to use when checking multiple stylesheets at once.
+      #
+      # @param css_file [String] The location of the CSS file to check.
+      # @param template_file [String] The location of the Sass or SCSS template
+      #   that is compiled to `css_file`.
+      # @return [Boolean] Whether the stylesheet needs to be updated.
+      def self.stylesheet_needs_update?(css_file, template_file, importer = nil)
+        new(Plugin.engine_options).stylesheet_needs_update?(css_file, template_file, importer)
+      end
+
+      # Returns whether a Sass or SCSS stylesheet has been modified since a given time.
+      #
+      # The distinction between this method and the instance-level \{#stylesheet\_modified\_since?}
+      # is that the instance method preserves mtime and stale-dependency caches,
+      # so it's better to use when checking multiple stylesheets at once.
+      #
+      # @param template_file [String] The location of the Sass or SCSS template.
+      # @param mtime [Fixnum] The modification time to check against.
+      # @param importer [Sass::Importers::Base] The importer used to locate the stylesheet.
+      #   Defaults to the filesystem importer.
+      # @return [Boolean] Whether the stylesheet has been modified.
+      def self.stylesheet_modified_since?(template_file, mtime, importer = nil)
+        new(Plugin.engine_options).stylesheet_modified_since?(template_file, mtime, importer)
+      end
+
+      private
+
+      def dependencies_stale?(uri, importer, css_mtime)
+        timestamps = @dependencies_stale[[uri, importer]] ||= {}
+        timestamps.each_pair do |checked_css_mtime, is_stale|
+          if checked_css_mtime <= css_mtime && !is_stale
+            return false
+          elsif checked_css_mtime > css_mtime && is_stale
+            return true
+          end
+        end
+        timestamps[css_mtime] = dependencies(uri, importer).any?(&dependency_updated?(css_mtime))
+      rescue Sass::SyntaxError
+        # If there's an error finding dependencies, default to recompiling.
+        true
+      end
+
+      def mtime(uri, importer)
+        @mtimes[[uri, importer]] ||=
+          begin
+            mtime = importer.mtime(uri, @options)
+            if mtime.nil?
+              @dependencies.delete([uri, importer])
+              nil
+            else
+              mtime
+            end
+          end
+      end
+
+      def dependencies(uri, importer)
+        stored_mtime, dependencies = Sass::Util.destructure(@dependencies[[uri, importer]])
+
+        if !stored_mtime || stored_mtime < mtime(uri, importer)
+          dependencies = compute_dependencies(uri, importer)
+          @dependencies[[uri, importer]] = [mtime(uri, importer), dependencies]
+        end
+
+        dependencies
+      end
+
+      def dependency_updated?(css_mtime)
+        Proc.new do |uri, importer|
+          next true if @actively_checking.include?(uri)
+          begin
+            @actively_checking << uri
+            sass_mtime = mtime(uri, importer)
+            !sass_mtime ||
+              sass_mtime > css_mtime ||
+              dependencies_stale?(uri, importer, css_mtime)
+          ensure
+            @actively_checking.delete uri
+          end
+        end
+      end
+
+      def compute_dependencies(uri, importer)
+        tree(uri, importer).grep(Tree::ImportNode) do |n|
+          next if n.css_import?
+          file = n.imported_file
+          key = [file.options[:filename], file.options[:importer]]
+          @parse_trees[key] = file.to_tree
+          key
+        end.compact
+      end
+
+      def tree(uri, importer)
+        @parse_trees[[uri, importer]] ||= importer.find(uri, @options).to_tree
+      end
+    end
+  end
+end