haml 2.0.10 → 2.2.0

data/lib/sass/environment.rb

@@ -0,0 +1,79 @@
+module Sass
+  # The lexical environment for SassScript.
+  # This keeps track of variable and mixin definitions.
+  #
+  # A new environment is created for each level of Sass nesting.
+  # This allows variables to be lexically scoped.
+  # The new environment refers to the environment in the upper scope,
+  # so it has access to variables defined in enclosing scopes,
+  # but new variables are defined locally.
+  #
+  # Environment also keeps track of the {Engine} options
+  # so that they can be made available to {Sass::Script::Functions}.
+  class Environment
+    # The enclosing environment,
+    # or nil if this is the global environment.
+    #
+    # @return [Environment]
+    attr_reader :parent
+    attr_writer :options
+
+    # @param parent [Environment] See \{#parent}
+    def initialize(parent = nil)
+      @vars = {}
+      @mixins = {}
+      @parent = parent
+
+      set_var("important", Script::String.new("!important")) unless @parent
+    end
+
+    # The options hash.
+    # See {file:SASS_REFERENCE.md#sass_options the Sass options documentation}.
+    #
+    # @return [Hash<Symbol, Object>]
+    def options
+      @options || (parent && parent.options) || {}
+    end
+
+    class << self
+      private
+
+      # Note: when updating this,
+      # update haml/yard/inherited_hash.rb as well.
+      def inherited_hash(name)
+        class_eval <<RUBY, __FILE__, __LINE__ + 1
+          def #{name}(name)
+            @#{name}s[name] || @parent && @parent.#{name}(name)
+          end
+
+          def set_#{name}(name, value)
+            @#{name}s[name] = value unless try_set_#{name}(name, value)
+          end
+
+          def try_set_#{name}(name, value)
+            if @#{name}s.include?(name)
+              @#{name}s[name] = value
+              true
+            elsif @parent
+              @parent.try_set_#{name}(name, value)
+            else
+              false
+            end
+          end
+          protected :try_set_#{name}
+
+          def set_local_#{name}(name, value)
+            @#{name}s[name] = value
+          end
+RUBY
+      end
+    end
+
+    # variable
+    # Script::Literal
+    inherited_hash :var
+    # mixin
+    # Engine::Mixin
+    inherited_hash :mixin
+  end
+end

data/lib/sass/error.rb

@@ -1,35 +1,57 @@
 module Sass
-  # Sass::SyntaxError encapsulates information about the exception,
-  # such as the line of the Sass template it was raised on
+  # An exception class that keeps track of
+  # the line of the Sass template it was raised on
   # and the Sass file that was being parsed (if applicable).
-  # It also provides a handy way to rescue only exceptions raised
-  # because of a faulty template.
+  #
+  # All Sass errors are raised as {Sass::SyntaxError}s.
   class SyntaxError < StandardError
-    # The line of the Sass template on which the exception was thrown.
+    # The line of the Sass template on which the error occurred.
+    #
+    # @return [Fixnum]
     attr_accessor :sass_line
 
     # The name of the file that was being parsed when the exception was raised.
-    # This will be nil unless Sass is being used as an ActionView plugin.
+    # This could be `nil` if no filename is available.
+    #
+    # @return [String]
     attr_reader :sass_filename
 
-    # Creates a new SyntaxError.
-    # +lineno+ should be the line of the Sass template on which the error occurred.
+    # @param msg [String] The error message
+    # @param lineno [Fixnum] See \{#sass\_line}
     def initialize(msg, lineno = nil)
       @message = msg
       @sass_line = lineno
     end
 
+    # Add information about the filename and line on which the error was raised,
+    # and re-raises the exception.
+    #
+    # @param filename [String] See \{#sass\_filename}
+    # @param line [Fixnum] See \{#sass\_line}
+    # @raise [Sass::SyntaxError] self
+    def add_metadata(filename, line)
+      self.sass_line ||= line
+      add_backtrace_entry(filename) unless sass_filename
+      raise self
+    end
+
     # Adds a properly formatted entry to the exception's backtrace.
-    # +filename+ should be the file in which the error occurred,
-    # if applicable (defaults to "(sass)").
+    #
+    # @param filename [String] The file in which the error occurred,
+    #   if applicable (defaults to "(sass)")
     def add_backtrace_entry(filename) # :nodoc:
       @sass_filename ||= filename
       self.backtrace ||= []
       self.backtrace.unshift "#{@sass_filename || '(sass)'}:#{@sass_line}"
     end
 
-    def to_s # :nodoc:
+    # @return [String] The error message
+    def to_s
       @message
     end
   end
+
+  # The class for Sass errors that are raised due to invalid unit conversions
+  # in SassScript.
+  class UnitConversionError < SyntaxError; end
 end

data/lib/sass/files.rb

@@ -0,0 +1,139 @@
+require 'digest/sha1'
+require 'pathname'
+
+module Sass
+  # This module contains various bits of functionality
+  # related to finding and caching Sass files.
+  module Files
+    extend self
+
+    # Returns the {Sass::Tree} for the given file,
+    # reading it from the Sass cache if possible.
+    #
+    # @param filename [String] The path to the Sass file
+    # @param options [Hash<Symbol, Object>] The options hash.
+    #   Only the {file:SASS_REFERENCE.md#cache-option `:cache_location`} option is used
+    # @raise [Sass::SyntaxError] if there's an error in the document
+    def tree_for(filename, options)
+      options = Sass::Engine::DEFAULT_OPTIONS.merge(options)
+      text = File.read(filename)
+
+      if options[:cache]
+        compiled_filename = sassc_filename(filename, options)
+        sha = Digest::SHA1.hexdigest(text)
+
+        if root = try_to_read_sassc(filename, compiled_filename, sha)
+          root.options = options.merge(:filename => filename)
+          return root
+        end
+      end
+
+      engine = Sass::Engine.new(text, options.merge(:filename => filename))
+
+      begin
+        root = engine.to_tree
+      rescue Sass::SyntaxError => err
+        err.add_backtrace_entry(filename)
+        raise err
+      end
+
+      try_to_write_sassc(root, compiled_filename, sha, options) if options[:cache]
+
+      root
+    end
+
+    # Find the full filename of a Sass or CSS file to import.
+    # This follows Sass's import rules:
+    # if the filename given ends in `".sass"` or `".css"`,
+    # it will try to find that type of file;
+    # otherwise, it will try to find the corresponding Sass file
+    # and fall back on CSS if it's not available.
+    #
+    # Any Sass filename returned will correspond to
+    # an actual Sass file on the filesystem.
+    # CSS filenames, however, may not;
+    # they're expected to be put through directly to the stylesheet
+    # as CSS `@import` statements.
+    #
+    # @param filename [String] The filename to search for
+    # @param load_paths [Array<String>] The set of filesystem paths
+    #   to search for Sass files.
+    # @return [String] The filename of the imported file.
+    #   This is an absolute path if the file is a `".sass"` file.
+    # @raise [Sass::SyntaxError] if `filename` ends in ``".sass"``
+    #   and no corresponding Sass file could be found.
+    def find_file_to_import(filename, load_paths)
+      was_sass = false
+      original_filename = filename
+
+      if filename[-5..-1] == ".sass"
+        filename = filename[0...-5]
+        was_sass = true
+      elsif filename[-4..-1] == ".css"
+        return filename
+      end
+
+      new_filename = find_full_path("#{filename}.sass", load_paths)
+
+      return new_filename if new_filename
+      return filename + '.css' unless was_sass
+      raise SyntaxError.new("File to import not found or unreadable: #{original_filename}.", @line)
+    end
+
+    private
+
+    def sassc_filename(filename, options)
+      File.join(options[:cache_location],
+        Digest::SHA1.hexdigest(File.dirname(File.expand_path(filename))),
+        File.basename(filename) + 'c')
+    end
+
+    def try_to_read_sassc(filename, compiled_filename, sha)
+      return unless File.readable?(compiled_filename)
+
+      File.open(compiled_filename, "rb") do |f|
+        return unless f.readline("\n").strip == Sass::VERSION
+        return unless f.readline("\n").strip == sha
+        return Marshal.load(f.read)
+      end
+    rescue TypeError, ArgumentError => e
+      warn "Warning. Error encountered while reading cache #{compiled_filename}: #{e}"
+    end
+
+    def try_to_write_sassc(root, compiled_filename, sha, options)
+      return unless File.writable?(File.dirname(options[:cache_location]))
+      return if File.exists?(options[:cache_location]) && !File.writable?(options[:cache_location])
+      return if File.exists?(File.dirname(compiled_filename)) && !File.writable?(File.dirname(compiled_filename))
+      return if File.exists?(compiled_filename) && !File.writable?(compiled_filename)
+      FileUtils.mkdir_p(File.dirname(compiled_filename))
+      File.open(compiled_filename, "wb") do |f|
+        f.write(Sass::VERSION)
+        f.write("\n")
+        f.write(sha)
+        f.write("\n")
+        f.write(Marshal.dump(root))
+      end
+    end
+
+    def find_full_path(filename, load_paths)
+      partial_name = File.join(File.dirname(filename), "_#{File.basename(filename)}")
+
+      if Pathname.new(filename).absolute?
+        [partial_name, filename].each do |name|
+          return name if File.readable?(name)
+        end
+        return nil
+      end
+
+      load_paths.each do |path|
+        [partial_name, filename].each do |name|
+          full_path = File.join(path, name)
+          if File.readable?(full_path)
+            return full_path
+          end
+        end
+      end
+      nil
+    end
+  end
+end

data/lib/sass/plugin.rb

@@ -1,114 +1,154 @@
 require 'sass/engine'
 
 module Sass
-  # This module contains methods to aid in using Sass
-  # as a stylesheet-rendering plugin for various systems.
-  # Currently Rails/ActionController and Merb are supported out of the box.
+  # This module handles the compilation of Sass files.
+  # 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.
+  # Currently Rails and Merb are supported out of the box.
   module Plugin
-    class << self
-      @@options = {
-        :template_location  => './public/stylesheets/sass',
-        :css_location       => './public/stylesheets',
-        :always_update      => false,
-        :always_check       => true,
-        :full_exception     => true
-      }
-      @@checked_for_updates = false
-
-      # Whether or not Sass has *ever* checked if the stylesheets need updates
-      # (in this Ruby instance).
-      def checked_for_updates
-        @@checked_for_updates
-      end
-
-      # Gets various options for Sass. See README.rdoc for details.
-      #--
-      # TODO: *DOCUMENT OPTIONS*
-      #++
-      def options
-        @@options
-      end
-
-      # Sets various options for Sass.
-      def options=(value)
-        @@options.merge!(value)
-      end
+    extend self
+
+    @options = {
+      :css_location       => './public/stylesheets',
+      :always_update      => false,
+      :always_check       => true,
+      :full_exception     => true
+    }
+    @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_reader :checked_for_updates
+
+    # An options hash.
+    # See {file:SASS_REFERENCE.md#sass_options the Sass options documentation}.
+    #
+    # @return [Hash<Symbol, Object>]
+    attr_reader :options
+
+    # Sets the options hash.
+    # See {file:SASS_REFERENCE.md#sass_options the Sass options documentation}.
+    #
+    # @param value [Hash<Symbol, Object>] The options hash
+    def options=(value)
+      @options.merge!(value)
+    end
 
-      # Get the options ready to be passed to the Sass::Engine
-      def engine_options(additional_options = {})
-        opts = options.dup.merge(additional_options)
-        opts[:load_paths] = load_paths(opts)
-        opts
-      end
+    # Non-destructively modifies \{#options} so that default values are properly set.
+    #
+    # @param additional_options [Hash<Symbol, Object>] An options hash with which to merge \{#options}
+    # @return [Hash<Symbol, Object>] The modified options hash
+    def engine_options(additional_options = {})
+      opts = options.dup.merge(additional_options)
+      opts[:load_paths] = load_paths(opts)
+      opts
+    end
 
-      # Checks each stylesheet in <tt>options[:css_location]</tt>
-      # to see if it needs updating,
-      # and updates it using the corresponding template
-      # from <tt>options[:templates]</tt>
-      # if it does.
-      def update_stylesheets
-        return if options[:never_update]
+    # Updates out-of-date stylesheets.
+    #
+    # Checks each Sass 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.
+    def update_stylesheets
+      return if options[:never_update]
 
-        @@checked_for_updates = true
-        Dir.glob(File.join(options[:template_location], "**", "*.sass")).entries.each do |file|
+      @checked_for_updates = true
+      template_locations.zip(css_locations).each do |template_location, css_location|
 
+        Dir.glob(File.join(template_location, "**", "*.sass")).each do |file|
           # Get the relative path to the file with no extension
-          name = file.sub(options[:template_location] + "/", "")[0...-5]
-
-          if !forbid_update?(name) && (options[:always_update] || stylesheet_needs_update?(name))
-            css = css_filename(name)
-            File.delete(css) if File.exists?(css)
-
-            filename = template_filename(name)
-            engine = Engine.new(File.read(filename), engine_options(:filename => filename))
-            result = begin
-                       engine.render
-                     rescue Exception => e
-                       exception_string(e)
-                     end
-
-            # Create any directories that might be necessary
-            dirs = [options[:css_location]]
-            name.split("/")[0...-1].each { |dir| dirs << "#{dirs[-1]}/#{dir}" }
-            dirs.each { |dir| Dir.mkdir(dir) unless File.exist?(dir) }
-
-            # Finally, write the file
-            File.open(css, 'w') do |file|
-              file.print(result)
-            end
+          name = file.sub(template_location + "/", "")[0...-5]
+
+          if !forbid_update?(name) && (options[:always_update] || stylesheet_needs_update?(name, template_location, css_location))
+            update_stylesheet(name, template_location, css_location)
           end
         end
       end
+    end
 
-      private
+    private
 
-      def load_paths(opts = options)
-        (opts[:load_paths] || []) + [options[:template_location]]
+    def update_stylesheet(name, template_location, css_location)
+      css = css_filename(name, css_location)
+      File.delete(css) if File.exists?(css)
+
+      filename = template_filename(name, template_location)
+      result = begin
+                 Sass::Files.tree_for(filename, engine_options(:css_filename => css, :filename => filename)).render
+               rescue Exception => e
+                 exception_string(e)
+               end
+
+      # Create any directories that might be necessary
+      mkpath(css_location, name)
+
+      # Finally, write the file
+      File.open(css, 'w') do |file|
+        file.print(result)
+      end
+    end
+    
+    # Create any successive directories required to be able to write a file to: File.join(base,name)
+    def mkpath(base, name)
+      dirs = [base]
+      name.split(File::SEPARATOR)[0...-1].each { |dir| dirs << File.join(dirs[-1],dir) }
+      dirs.each { |dir| Dir.mkdir(dir) unless File.exist?(dir) }
+    end
+
+    def load_paths(opts = options)
+      (opts[:load_paths] || []) + template_locations
+    end
+    
+    def template_locations
+      location = (options[:template_location] || File.join(options[:css_location],'sass'))
+      if location.is_a?(String)
+        [location]
+      else
+        location.to_a.map { |l| l.first }
+      end
+    end
+    
+    def css_locations
+      if options[:template_location] && !options[:template_location].is_a?(String)
+        options[:template_location].to_a.map { |l| l.last }
+      else
+        [options[:css_location]]
       end
+    end
 
-      def exception_string(e)
-        if options[:full_exception]
-          e_string = "#{e.class}: #{e.message}"
+    def exception_string(e)
+      if options[:full_exception]
+        e_string = "#{e.class}: #{e.message}"
 
-          if e.is_a? Sass::SyntaxError
-            e_string << "\non line #{e.sass_line}"
+        if e.is_a? Sass::SyntaxError
+          e_string << "\non line #{e.sass_line}"
 
-            if e.sass_filename
-              e_string << " of #{e.sass_filename}"
+          if e.sass_filename
+            e_string << " of #{e.sass_filename}"
 
-              if File.exists?(e.sass_filename)
-                e_string << "\n\n"
+            if File.exists?(e.sass_filename)
+              e_string << "\n\n"
 
-                min = [e.sass_line - 5, 0].max
+              min = [e.sass_line - 5, 0].max
+              begin
                 File.read(e.sass_filename).rstrip.split("\n")[
                   min .. e.sass_line + 5
                 ].each_with_index do |line, i|
                   e_string << "#{min + i + 1}: #{line}\n"
                 end
+              rescue
+                e_string << "Couldn't read sass file: #{e.sass_filename}"
               end
             end
           end
-          <<END
+        end
+        <<END
 /*
 #{e_string}
 
@@ -119,49 +159,52 @@ body:before {
   font-family: monospace;
   content: "#{e_string.gsub('"', '\"').gsub("\n", '\\A ')}"; }
 END
-          # Fix an emacs syntax-highlighting hiccup: '
-        else
-          "/* Internal stylesheet error */"
-        end
+        # Fix an emacs syntax-highlighting hiccup: '
+      else
+        "/* Internal stylesheet error */"
       end
+    end
 
-      def template_filename(name)
-        "#{options[:template_location]}/#{name}.sass"
-      end
+    def template_filename(name, path)
+      "#{path}/#{name}.sass"
+    end
 
-      def css_filename(name)
-        "#{options[:css_location]}/#{name}.css"
-      end
+    def css_filename(name, path)
+      "#{path}/#{name}.css"
+    end
 
-      def forbid_update?(name)
-        name.sub(/^.*\//, '')[0] == ?_
-      end
+    def forbid_update?(name)
+      name.sub(/^.*\//, '')[0] == ?_
+    end
 
-      def stylesheet_needs_update?(name)
-        if !File.exists?(css_filename(name))
-          return true
-        else
-          css_mtime = File.mtime(css_filename(name))
-          File.mtime(template_filename(name)) > css_mtime ||
-            dependencies(template_filename(name)).any?(&dependency_updated?(css_mtime))
-        end
-      end
+    def stylesheet_needs_update?(name, template_path, css_path)
+      css_file = css_filename(name, css_path)
+      template_file = template_filename(name, template_path)
+      exact_stylesheet_needs_update?(css_file, template_file)
+    end
 
-      def dependency_updated?(css_mtime)
-        lambda do |dep|
-          File.mtime(dep) > css_mtime ||
-            dependencies(dep).any?(&dependency_updated?(css_mtime))
-        end
-      end
+    def exact_stylesheet_needs_update?(css_file, template_file)
+      return true unless File.exists?(css_file)
 
-      def dependencies(filename)
-        File.readlines(filename).grep(/^@import /).map do |line|
-          line[8..-1].split(',').map do |inc|
-            Sass::Engine.find_file_to_import(inc.strip, load_paths)
-          end
-        end.flatten.grep(/\.sass$/)
+      css_mtime = File.mtime(css_file)
+      File.mtime(template_file) > css_mtime ||
+        dependencies(template_file).any?(&dependency_updated?(css_mtime))
+    end
+
+    def dependency_updated?(css_mtime)
+      lambda do |dep|
+        File.mtime(dep) > css_mtime ||
+          dependencies(dep).any?(&dependency_updated?(css_mtime))
       end
     end
+
+    def dependencies(filename)
+      File.readlines(filename).grep(/^@import /).map do |line|
+        line[8..-1].split(',').map do |inc|
+          Sass::Files.find_file_to_import(inc.strip, [File.dirname(filename)] + load_paths)
+        end
+      end.flatten.grep(/\.sass$/)
+    end
   end
 end