xass 0.1.0

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,199 @@
+require 'thread'
+
+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 = {}
+      @dependency_cache_mutex = Mutex.new
+
+      class << self
+        # TODO: attach this to a compiler instance.
+        # @private
+        attr_accessor :dependencies_cache
+        attr_reader :dependency_cache_mutex
+      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)
+        # 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?
+              with_dependency_cache {|cache| cache.delete([uri, importer])}
+              nil
+            else
+              mtime
+            end
+          end
+      end
+
+      def dependencies(uri, importer)
+        stored_mtime, dependencies =
+          with_dependency_cache {|cache| Sass::Util.destructure(cache[[uri, importer]])}
+
+        if !stored_mtime || stored_mtime < mtime(uri, importer)
+          dependencies = compute_dependencies(uri, importer)
+          with_dependency_cache do |cache|
+            cache[[uri, importer]] = [mtime(uri, importer), dependencies]
+          end
+        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
+
+      # Get access to the global dependency cache in a threadsafe manner.
+      # Inside the block, no other thread can access the dependency cache.
+      #
+      # @yieldparam cache [Hash] The hash that is the global dependency cache
+      # @return The value returned by the block to which this method yields
+      def with_dependency_cache
+        StalenessChecker.dependency_cache_mutex.synchronize do
+          yield StalenessChecker.dependencies_cache
+        end
+      end
+    end
+  end
+end

data/lib/sass/plugin.rb

@@ -0,0 +1,133 @@
+require 'fileutils'
+
+require 'sass'
+require 'sass/plugin/compiler'
+
+module Sass
+  # This module provides a single interface to the compilation of Sass/SCSS files
+  # for an application. It provides global options and checks whether CSS files
+  # need to be updated.
+  #
+  # This module is used as the primary interface with Sass
+  # when it's used as a plugin for various frameworks.
+  # All Rack-enabled frameworks are supported out of the box.
+  # The plugin is {file:SASS_REFERENCE.md#rails_merb_plugin automatically activated for Rails and Merb}.
+  # Other frameworks must enable it explicitly; see {Sass::Plugin::Rack}.
+  #
+  # This module has a large set of callbacks available
+  # to allow users to run code (such as logging) when certain things happen.
+  # All callback methods are of the form `on_#{name}`,
+  # and they all take a block that's called when the given action occurs.
+  #
+  # Note that this class proxies almost all methods to its {Sass::Plugin::Compiler} instance.
+  # See \{#compiler}.
+  #
+  # @example Using a callback
+  #   Sass::Plugin.on_updating_stylesheet do |template, css|
+  #     puts "Compiling #{template} to #{css}"
+  #   end
+  #   Sass::Plugin.update_stylesheets
+  #     #=> Compiling app/sass/screen.scss to public/stylesheets/screen.css
+  #     #=> Compiling app/sass/print.scss to public/stylesheets/print.css
+  #     #=> Compiling app/sass/ie.scss to public/stylesheets/ie.css
+  # @see Sass::Plugin::Compiler
+  module Plugin
+    include Sass::Util
+    extend self
+
+    @checked_for_updates = false
+
+    # Whether or not Sass has **ever** checked if the stylesheets need to be updated
+    # (in this Ruby instance).
+    #
+    # @return [Boolean]
+    attr_accessor :checked_for_updates
+
+    # Same as \{#update\_stylesheets}, but respects \{#checked\_for\_updates}
+    # and the {file:SASS_REFERENCE.md#always_update-option `:always_update`}
+    # and {file:SASS_REFERENCE.md#always_check-option `:always_check`} options.
+    #
+    # @see #update_stylesheets
+    def check_for_updates
+      return unless !Sass::Plugin.checked_for_updates ||
+          Sass::Plugin.options[:always_update] || Sass::Plugin.options[:always_check]
+      update_stylesheets
+    end
+
+    # Returns the singleton compiler instance.
+    # This compiler has been pre-configured according
+    # to the plugin configuration.
+    #
+    # @return [Sass::Plugin::Compiler]
+    def compiler
+      @compiler ||= Compiler.new
+    end
+
+    # Updates out-of-date stylesheets.
+    #
+    # Checks each Sass/SCSS file in {file:SASS_REFERENCE.md#template_location-option `:template_location`}
+    # to see if it's been modified more recently than the corresponding CSS file
+    # in {file:SASS_REFERENCE.md#css_location-option `:css_location`}.
+    # If it has, it updates the CSS file.
+    #
+    # @param individual_files [Array<(String, String)>]
+    #   A list of files to check for updates
+    #   **in addition to those specified by the
+    #   {file:SASS_REFERENCE.md#template_location-option `:template_location` option}.**
+    #   The first string in each pair is the location of the Sass/SCSS file,
+    #   the second is the location of the CSS file that it should be compiled to.
+    def update_stylesheets(individual_files = [])
+      return if options[:never_update]
+      compiler.update_stylesheets(individual_files)
+    end
+
+    # Updates all stylesheets, even those that aren't out-of-date.
+    # Ignores the cache.
+    #
+    # @param individual_files [Array<(String, String)>]
+    #   A list of files to check for updates
+    #   **in addition to those specified by the
+    #   {file:SASS_REFERENCE.md#template_location-option `:template_location` option}.**
+    #   The first string in each pair is the location of the Sass/SCSS file,
+    #   the second is the location of the CSS file that it should be compiled to.
+    # @see #update_stylesheets
+    def force_update_stylesheets(individual_files = [])
+      Compiler.new(options.dup.merge(
+          :never_update => false,
+          :always_update => true,
+          :cache => false)).update_stylesheets(individual_files)
+    end
+
+    # All other method invocations are proxied to the \{#compiler}.
+    #
+    # @see #compiler
+    # @see Sass::Plugin::Compiler
+    def method_missing(method, *args, &block)
+      if compiler.respond_to?(method)
+        compiler.send(method, *args, &block)
+      else
+        super
+      end
+    end
+
+    # For parity with method_missing
+    def respond_to?(method)
+      super || compiler.respond_to?(method)
+    end
+
+    # There's a small speedup by not using method missing for frequently delegated methods.
+    def options
+      compiler.options
+    end
+
+  end
+end
+
+# On Rails 3+ the rails plugin is loaded at the right time in railtie.rb
+if defined?(ActionController) && !Sass::Util.ap_geq_3?
+  require 'sass/plugin/rails'
+elsif defined?(Merb::Plugins)
+  require 'sass/plugin/merb'
+else
+  require 'sass/plugin/generic'
+end

data/lib/sass/railtie.rb

@@ -0,0 +1,10 @@
+# Rails 3.0.0.beta.2+, < 3.1
+if defined?(ActiveSupport) && Sass::Util.has?(:public_method, ActiveSupport, :on_load) &&
+    !Sass::Util.ap_geq?('3.1.0.beta')
+  require 'sass/plugin/configuration'
+  ActiveSupport.on_load(:before_configuration) do
+    require 'sass'
+    require 'sass/plugin'
+    require 'sass/plugin/rails'
+  end
+end

data/lib/sass/repl.rb

@@ -0,0 +1,57 @@
+require 'readline'
+
+module Sass
+  # Runs a SassScript read-eval-print loop.
+  # It presents a prompt on the terminal,
+  # reads in SassScript expressions,
+  # evaluates them,
+  # and prints the result.
+  class Repl
+    # @param options [{Symbol => Object}] An options hash.
+    def initialize(options = {})
+      @options = options
+    end
+
+    # Starts the read-eval-print loop.
+    def run
+      environment = Environment.new
+      @line = 0
+      loop do
+        @line += 1
+        unless text = Readline.readline('>> ')
+          puts
+          return
+        end
+
+        Readline::HISTORY << text
+        parse_input(environment, text)
+      end
+    end
+
+    private
+
+    def parse_input(environment, text)
+      case text
+      when Script::MATCH
+        name = $1
+        guarded = !!$3
+        val = Script::Parser.parse($2, @line, text.size - ($3 || '').size - $2.size)
+
+        unless guarded && environment.var(name)
+          environment.set_var(name, val.perform(environment))
+        end
+
+        p environment.var(name)
+      else
+        p Script::Parser.parse(text, @line, 0).perform(environment)
+      end
+    rescue Sass::SyntaxError => e
+      puts "SyntaxError: #{e.message}"
+      if @options[:trace]
+        e.backtrace.each do |e|
+          puts "\tfrom #{e}"
+        end
+      end
+    end
+  end
+end

data/lib/sass/root.rb

@@ -0,0 +1,7 @@
+module Sass
+  # The root directory of the Sass source tree.
+  # This may be overridden by the package manager
+  # if the lib directory is separated from the main source tree.
+  # @api public
+  ROOT_DIR = File.expand_path(File.join(__FILE__, "../../.."))
+end

data/lib/sass/script/arg_list.rb

@@ -0,0 +1,52 @@
+module Sass::Script
+  # A SassScript object representing a variable argument list. This works just
+  # like a normal list, but can also contain keyword arguments.
+  #
+  # The keyword arguments attached to this list are unused except when this is
+  # passed as a glob argument to a function or mixin.
+  class ArgList < List
+    # Whether \{#keywords} has been accessed. If so, we assume that all keywords
+    # were valid for the function that created this ArgList.
+    #
+    # @return [Boolean]
+    attr_accessor :keywords_accessed
+
+    # Creates a new argument list.
+    #
+    # @param value [Array<Literal>] See \{List#value}.
+    # @param keywords [Hash<String, Literal>] See \{#keywords}
+    # @param separator [String] See \{List#separator}.
+    def initialize(value, keywords, separator)
+      super(value, separator)
+      @keywords = keywords
+    end
+
+    # The keyword arguments attached to this list.
+    #
+    # @return [Hash<String, Literal>]
+    def keywords
+      @keywords_accessed = true
+      @keywords
+    end
+
+    # @see Node#children
+    def children
+      super + @keywords.values
+    end
+
+    # @see Node#deep_copy
+    def deep_copy
+      node = super
+      node.instance_variable_set('@keywords',
+        Sass::Util.map_hash(@keywords) {|k, v| [k, v.deep_copy]})
+      node
+    end
+
+    protected
+
+    # @see Node#_perform
+    def _perform(environment)
+      self
+    end
+  end
+end

data/lib/sass/script/bool.rb

@@ -0,0 +1,18 @@
+require 'sass/script/literal'
+
+module Sass::Script
+  # A SassScript object representing a boolean (true or false) value.
+  class Bool < Literal
+    # The Ruby value of the boolean.
+    #
+    # @return [Boolean]
+    attr_reader :value
+    alias_method :to_bool, :value
+
+    # @return [String] "true" or "false"
+    def to_s(opts = {})
+      @value.to_s
+    end
+    alias_method :to_sass, :to_s
+  end
+end