haml-edge 2.3.100 → 2.3.148

data/lib/sass/plugin.rb

@@ -1,4 +1,8 @@
+require 'fileutils'
+require 'rbconfig'
+
 require 'sass'
+require 'sass/callbacks'
 
 module Sass
   # This module handles the compilation of Sass files.
@@ -10,8 +14,23 @@ module Sass
   # 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.
+  #
+  # @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.sass to public/stylesheets/screen.css
+  #   #=> Compiling app/sass/print.sass to public/stylesheets/print.css
+  #   #=> Compiling app/sass/ie.sass to public/stylesheets/ie.css
   module Plugin
     include Haml::Util
+    include Sass::Callbacks
     extend self
 
     @options = {
@@ -22,6 +41,114 @@ module Sass
     }
     @checked_for_updates = false
 
+    # Register a callback to be run before stylesheets are mass-updated.
+    # This is run whenever \{#update\_stylesheets} is called,
+    # unless the \{file:SASS_REFERENCE.md#never_update-option `:never_update` option}
+    # is enabled.
+    #
+    # @yield [individual_files]
+    # @yieldparam individual_files [<(String, String)>]
+    #   Individual files to be updated, in addition to the directories
+    #   specified in the options.
+    #   The first element of each pair is the source file,
+    #   the second is the target CSS file.
+    define_callback :updating_stylesheets
+
+    # Register a callback to be run before a single stylesheet is updated.
+    # The callback is only run if the stylesheet is guaranteed to be updated;
+    # if the CSS file is fresh, this won't be run.
+    #
+    # Even if the \{file:SASS_REFERENCE.md#full_exception-option `:full_exception` option}
+    # is enabled, this callback won't be run
+    # when an exception CSS file is being written.
+    # To run an action for those files, use \{#on\_compilation\_error}.
+    #
+    # @yield [template, css]
+    # @yieldparam template [String]
+    #   The location of the Sass file being updated.
+    # @yieldparam css [String]
+    #   The location of the CSS file being generated.
+    define_callback :updating_stylesheet
+
+    # Register a callback to be run when Sass decides not to update a stylesheet.
+    # In particular, the callback is run when Sass finds that
+    # the template file and none of its dependencies
+    # have been modified since the last compilation.
+    #
+    # Note that this is **not** run when the
+    # \{file:SASS_REFERENCE.md#never-update_option `:never_update` option} is set,
+    # nor when Sass decides not to compile a partial.
+    #
+    # @yield [template, css]
+    # @yieldparam template [String]
+    #   The location of the Sass file not being updated.
+    # @yieldparam css [String]
+    #   The location of the CSS file not being generated.
+    define_callback :not_updating_stylesheet
+
+    # Register a callback to be run when there's an error
+    # compiling a Sass file.
+    # This could include not only errors in the Sass document,
+    # but also errors accessing the file at all.
+    #
+    # @yield [error, template, css]
+    # @yieldparam error [Exception] The exception that was raised.
+    # @yieldparam template [String]
+    #   The location of the Sass file being updated.
+    # @yieldparam css [String]
+    #   The location of the CSS file being generated.
+    define_callback :compilation_error
+
+    # Register a callback to be run when Sass creates a directory
+    # into which to put CSS files.
+    #
+    # Note that even if multiple levels of directories need to be created,
+    # the callback may only be run once.
+    # For example, if "foo/" exists and "foo/bar/baz/" needs to be created,
+    # this may only be run for "foo/bar/baz/".
+    # This is not a guarantee, however;
+    # it may also be run for "foo/bar/".
+    #
+    # @yield [dirname]
+    # @yieldparam dirname [String]
+    #   The location of the directory that was created.
+    define_callback :creating_directory
+
+    # Register a callback to be run when Sass detects
+    # that a template has been modified.
+    # This is only run when using \{#watch}.
+    #
+    # @yield [template]
+    # @yieldparam template [String]
+    #   The location of the template that was modified.
+    define_callback :template_modified
+
+    # Register a callback to be run when Sass detects
+    # that a new template has been created.
+    # This is only run when using \{#watch}.
+    #
+    # @yield [template]
+    # @yieldparam template [String]
+    #   The location of the template that was created.
+    define_callback :template_created
+
+    # Register a callback to be run when Sass detects
+    # that a template has been deleted.
+    # This is only run when using \{#watch}.
+    #
+    # @yield [template]
+    # @yieldparam template [String]
+    #   The location of the template that was deleted.
+    define_callback :template_deleted
+
+    # Register a callback to be run when Sass deletes a CSS file.
+    # This happens when the corresponding Sass file has been deleted.
+    #
+    # @yield [filename]
+    # @yieldparam filename [String]
+    #   The location of the CSS file that was deleted.
+    define_callback :deleting_css
+
     # Whether or not Sass has **ever** checked if the stylesheets need to be updated
     # (in this Ruby instance).
     #
@@ -67,58 +194,163 @@ module Sass
     #
     # 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`}.
+    # in {file:SASS_REFERENCE.md#css_location-option `:css_location`}.
     # If it has, it updates the CSS file.
-    def update_stylesheets
+    #
+    # @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 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]
 
+      run_updating_stylesheets individual_files
+
+      individual_files.each {|t, c| update_stylesheet(t, c)}
+
       @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(template_location + "/", "")[0...-5]
+          name = file.sub(template_location.sub(/\/*$/, '/'), "")[0...-5]
+
+          next if forbid_update?(name)
 
-          if !forbid_update?(name) && (options[:always_update] || stylesheet_needs_update?(name, template_location, css_location))
-            update_stylesheet(name, template_location, css_location)
+          filename = template_filename(name, template_location)
+          css = css_filename(name, css_location)
+          if options[:always_update] || stylesheet_needs_update?(name, template_location, css_location)
+            update_stylesheet filename, css
+          else
+            run_not_updating_stylesheet filename, css
           end
         end
       end
     end
 
-    private
+    # Watches the template directory (or directories)
+    # and updates the CSS files whenever the related Sass files change.
+    # `watch` never returns.
+    #
+    # Whenever a change is detected to a Sass file in
+    # {file:SASS_REFERENCE.md#template_location-option `:template_location`},
+    # the corresponding CSS file in {file:SASS_REFERENCE.md#css_location-option `:css_location`}
+    # will be recompiled.
+    # The CSS files of any Sass files that import the changed file will also be recompiled.
+    #
+    # Before the watching starts in earnest, `watch` calls \{#update\_stylesheets}.
+    #
+    # Note that `watch` uses the [FSSM](http://github.com/ttilley/fssm) library
+    # to monitor the filesystem for changes.
+    # FSSM isn't loaded until `watch` is run.
+    # The version of FSSM distributed with Sass is loaded by default,
+    # but if another version has already been loaded that will be used instead.
+    #
+    # @param individual_files [Array<(String, String)>]
+    #   A list of files to watch 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 file,
+    #   the second is the location of the CSS file that it should be compiled to.
+    def watch(individual_files = [])
+      update_stylesheets(individual_files)
 
-    def update_stylesheet(name, template_location, css_location)
-      css = css_filename(name, css_location)
-      File.delete(css) if File.exists?(css)
+      begin
+        require 'fssm'
+      rescue LoadError => e
+        e.message << "\n" <<
+          if File.exists?(scope(".git"))
+            'Run "git submodule update --init" to get the recommended version.'
+          else
+            'Run "gem install fssm" to get it.'
+          end
+        raise e
+      end
 
-      filename = template_filename(name, template_location)
-      result = begin
-                 Sass::Files.tree_for(filename, engine_options(:css_filename => css, :filename => filename)).render
-               rescue Exception => e
-                 Sass::SyntaxError.exception_to_css(e, options)
-               end
+      # TODO: Keep better track of what depends on what
+      # so we don't have to run a global update every time anything changes.
+      FSSM.monitor do |mon|
+        template_locations.zip(css_locations).each do |template_location, css_location|
+          mon.path template_location do |path|
+            path.glob '**/*.sass'
 
-      # Create any directories that might be necessary
-      mkpath(css_location, name)
+            path.update do |base, relative|
+              run_template_modified File.join(base, relative)
+              update_stylesheets(individual_files)
+            end
 
-      # Finally, write the file
-      File.open(css, 'w') do |file|
-        file.print(result)
+            path.create do |base, relative|
+              run_template_created File.join(base, relative)
+              update_stylesheets(individual_files)
+            end
+
+            path.delete do |base, relative|
+              run_template_deleted File.join(base, relative)
+              css = File.join(css_location, relative.gsub(/\.sass$/, '.css'))
+              try_delete_css css
+              update_stylesheets(individual_files)
+            end
+          end
+        end
+
+        individual_files.each do |template, css|
+          mon.file template do |path|
+            path.update do
+              run_template_modified template
+              update_stylesheets(individual_files)
+            end
+
+            path.create do
+              run_template_created template
+              update_stylesheets(individual_files)
+            end
+
+            path.delete do
+              run_template_deleted template
+              try_delete_css css
+              update_stylesheets(individual_files)
+            end
+          end
+        end
+      end
+    end
+
+    private
+
+    def update_stylesheet(filename, css)
+      dir = File.dirname(css)
+      unless File.exists?(dir)
+        run_creating_directory dir
+        FileUtils.mkdir_p dir
+      end
+
+      begin
+        result = Sass::Files.tree_for(filename, engine_options(:css_filename => css, :filename => filename)).render
+      rescue Exception => e
+        run_compilation_error e, filename, css
+        result = Sass::SyntaxError.exception_to_css(e, options)
+      else
+        run_updating_stylesheet filename, css
       end
+
+      # Finally, write the file
+      flag = 'w'
+      flag = 'wb' if RbConfig::CONFIG['host_os'] =~ /mswin|windows/i && options[:unix_newlines]
+      File.open(css, flag) {|file| file.print(result)}
     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) }
+
+    def try_delete_css(css)
+      return unless File.exists?(css)
+      run_deleting_css css
+      File.delete css
     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)
@@ -127,7 +359,7 @@ module Sass
         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 }

data/lib/sass/script/color.rb

@@ -2,10 +2,24 @@ require 'sass/script/literal'
 
 module Sass::Script
   # A SassScript object representing a CSS color.
+  #
+  # A color may be represented internally as RGBA, HSLA, or both.
+  # It's originally represented as whatever its input is;
+  # if it's created with RGB values, it's represented as RGBA,
+  # and if it's created with HSL values, it's represented as HSLA.
+  # Once a property is accessed that requires the other representation --
+  # for example, \{#red} for an HSL color --
+  # that component is calculated and cached.
+  #
+  # The alpha channel of a color is independent of its RGB or HSL representation.
+  # It's always stored, as 1 if nothing else is specified.
+  # If only the alpha channel is modified using \{#with},
+  # the cached RGB and HSL values are retained.
   class Color < Literal
     class << self; include Haml::Util; end
 
     # A hash from color names to `[red, green, blue]` value arrays.
+    # @private
     HTML4_COLORS = map_vals({
         'black'   => 0x000000,
         'silver'  => 0xc0c0c0,
@@ -25,52 +39,139 @@ module Sass::Script
         'aqua'    => 0x00ffff
       }) {|color| (0..2).map {|n| color >> (n << 3) & 0xff}.reverse}
     # A hash from `[red, green, blue]` value arrays to color names.
+    # @private
     HTML4_COLORS_REVERSE = map_hash(HTML4_COLORS) {|k, v| [v, k]}
 
-    # Constructs an RGB or RGBA color object.
-    # The RGB values must be between 0 and 255,
-    # and the alpha value is generally expected to be between 0 and 1.
-    # However, the alpha value can be greater than 1
-    # in order to allow it to be used for color multiplication.
-    #
-    # @param rgba [Array<Numeric>] A three-element array of the red, green, blue,
-    #   and optionally alpha values (respectively) of the color
-    # @raise [Sass::SyntaxError] if any color value isn't between 0 and 255,
-    #   or the alpha value is negative
-    def initialize(rgba)
-      @red, @green, @blue = rgba[0...3].map {|c| c.to_i}
-      @alpha = rgba[3] ? rgba[3].to_f : 1
+    # Constructs an RGB or HSL color object,
+    # optionally with an alpha channel.
+    # 
+    # The RGB values must be between 0 and 255.
+    # The saturation and lightness values must be between 0 and 100.
+    # The alpha value must be between 0 and 1.
+    #
+    # @raise [Sass::SyntaxError] if any color value isn't in the specified range
+    #
+    # @overload initialize(attrs)
+    #   The attributes are specified as a hash.
+    #   This hash must contain either `:hue`, `:saturation`, and `:value` keys,
+    #   or `:red`, `:green`, and `:blue` keys.
+    #   It cannot contain both HSL and RGB keys.
+    #   It may also optionally contain an `:alpha` key.
+    #
+    #   @param attrs [{Symbol => Numeric}] A hash of color attributes to values
+    #   @raise [ArgumentError] if not enough attributes are specified,
+    #     or both RGB and HSL attributes are specified
+    #
+    # @overload initialize(rgba)
+    #   The attributes are specified as an array.
+    #   This overload only supports RGB or RGBA colors.
+    #
+    #   @param rgba [Array<Numeric>] A three- or four-element array
+    #     of the red, green, blue, and optionally alpha values (respectively)
+    #     of the color
+    #   @raise [ArgumentError] if not enough attributes are specified
+    def initialize(attrs, allow_both_rgb_and_hsl = false)
       super(nil)
 
-      unless rgb.all? {|c| (0..255).include?(c)}
-        raise Sass::SyntaxError.new("Color values must be between 0 and 255")
+      if attrs.is_a?(Array)
+        unless (3..4).include?(attrs.size)
+          raise ArgumentError.new("Color.new(array) expects a three- or four-element array")
+        end
+
+        red, green, blue = attrs[0...3].map {|c| c.to_i}
+        @attrs = {:red => red, :green => green, :blue => blue}
+        @attrs[:alpha] = attrs[3] ? attrs[3].to_f : 1
+      else
+        attrs = attrs.reject {|k, v| v.nil?}
+        hsl = [:hue, :saturation, :lightness] & attrs.keys
+        rgb = [:red, :green, :blue] & attrs.keys
+        if !allow_both_rgb_and_hsl && !hsl.empty? && !rgb.empty?
+          raise ArgumentError.new("Color.new(hash) may not have both HSL and RGB keys specified")
+        elsif hsl.empty? && rgb.empty?
+          raise ArgumentError.new("Color.new(hash) must have either HSL or RGB keys specified")
+        elsif !hsl.empty? && hsl.size != 3
+          raise ArgumentError.new("Color.new(hash) must have all three HSL values specified")
+        elsif !rgb.empty? && rgb.size != 3
+          raise ArgumentError.new("Color.new(hash) must have all three RGB values specified")
+        end
+
+        @attrs = attrs
+        @attrs[:hue] %= 360 if @attrs[:hue]
+        @attrs[:alpha] ||= 1
+      end
+
+      [:red, :green, :blue].each do |k|
+        next if @attrs[k].nil?
+        @attrs[k] = @attrs[k].to_i
+        next if (0..255).include?(@attrs[k])
+        raise Sass::SyntaxError.new("#{k.to_s.capitalize} value must be between 0 and 255")
+      end
+
+      [:saturation, :lightness].each do |k|
+        next if @attrs[k].nil? || (0..100).include?(@attrs[k])
+        raise Sass::SyntaxError.new("#{k.to_s.capitalize} must be between 0 and 100")
       end
 
-      unless (0..1).include?(alpha)
-        raise Sass::SyntaxError.new("Color opacity value must between 0 and 1")
+      unless (0..1).include?(@attrs[:alpha])
+        raise Sass::SyntaxError.new("Alpha channel must between 0 and 1")
       end
     end
 
     # The red component of the color.
     #
     # @return [Fixnum]
-    attr_reader :red
+    def red
+      hsl_to_rgb!
+      @attrs[:red]
+    end
 
     # The green component of the color.
     #
     # @return [Fixnum]
-    attr_reader :green
+    def green
+      hsl_to_rgb!
+      @attrs[:green]
+    end
 
     # The blue component of the color.
     #
     # @return [Fixnum]
-    attr_reader :blue
+    def blue
+      hsl_to_rgb!
+      @attrs[:blue]
+    end
+
+    # The hue component of the color.
+    #
+    # @return [Numeric]
+    def hue
+      rgb_to_hsl!
+      @attrs[:hue]
+    end
+
+    # The saturation component of the color.
+    #
+    # @return [Numeric]
+    def saturation
+      rgb_to_hsl!
+      @attrs[:saturation]
+    end
+
+    # The lightness component of the color.
+    #
+    # @return [Numeric]
+    def lightness
+      rgb_to_hsl!
+      @attrs[:lightness]
+    end
 
     # The alpha channel (opacity) of the color.
     # This is 1 unless otherwise defined.
     #
     # @return [Fixnum]
-    attr_reader :alpha
+    def alpha
+      @attrs[:alpha]
+    end
 
     # Returns whether this color object is translucent;
     # that is, whether the alpha channel is non-1.
@@ -80,13 +181,13 @@ module Sass::Script
       alpha < 1
     end
 
-    # @deprecated This will be removed in version 2.6.
+    # @deprecated This will be removed in version 3.2.
     # @see #rgb
     def value
       warn <<END
 DEPRECATION WARNING:
 The Sass::Script::Color #value attribute is deprecated and will be
-removed in version 2.6. Use the #rgb attribute instead.
+removed in version 3.2. Use the #rgb attribute instead.
 END
       rgb
     end
@@ -99,6 +200,14 @@ END
       [red, green, blue].freeze
     end
 
+    # Returns the hue, saturation, and lightness components of the color.
+    #
+    # @return [Array<Fixnum>] A frozen three-element array of the
+    #   hue, saturation, and lightness values (respectively) of the color
+    def hsl
+      [hue, saturation, lightness].freeze
+    end
+
     # The SassScript `==` operation.
     # **Note that this returns a {Sass::Script::Bool} object,
     # not a Ruby boolean**.
@@ -112,6 +221,7 @@ END
     end
 
     # Returns a copy of this color with one or more channels changed.
+    # RGB or HSL colors may be changed, but not both at once.
     #
     # For example:
     #
@@ -119,19 +229,36 @@ END
     #       #=> rgb(10, 40, 30)
     #     Color.new([126, 126, 126]).with(:red => 0, :green => 255)
     #       #=> rgb(0, 255, 126)
+    #     Color.new([255, 0, 127]).with(:saturation => 60)
+    #       #=> rgb(204, 51, 127)
     #     Color.new([1, 2, 3]).with(:alpha => 0.4)
     #       #=> rgba(1, 2, 3, 0.4)
     #
     # @param attrs [{Symbol => Numeric}]
-    #   A map of channel names (`:red`, `:green`, `:blue`, or `:alpha`) to values
+    #   A map of channel names (`:red`, `:green`, `:blue`,
+    #   `:hue`, `:saturation`, `:lightness`, or `:alpha`) to values
     # @return [Color] The new Color object
+    # @raise [ArgumentError] if both RGB and HSL keys are specified
     def with(attrs)
-      Color.new([
-          attrs[:red] || red,
-          attrs[:green] || green,
-          attrs[:blue] || blue,
-          attrs[:alpha] || alpha,
-        ])
+      attrs = attrs.reject {|k, v| v.nil?}
+      hsl = !([:hue, :saturation, :lightness] & attrs.keys).empty?
+      rgb = !([:red, :green, :blue] & attrs.keys).empty?
+      if hsl && rgb
+        raise ArgumentError.new("Color#with may not have both HSL and RGB keys specified")
+      end
+
+      if hsl
+        [:hue, :saturation, :lightness].each {|k| attrs[k] ||= send(k)}
+      elsif rgb
+        [:red, :green, :blue].each {|k| attrs[k] ||= send(k)}
+      else
+        # If we're just changing the alpha channel,
+        # keep all the HSL/RGB stuff we've calculated
+        attrs = @attrs.merge(attrs)
+      end
+      attrs[:alpha] ||= alpha
+
+      Color.new(attrs, :allow_both_rgb_and_hsl)
     end
 
     # The SassScript `+` operation.
@@ -299,5 +426,64 @@ END
 
       with(:red => result[0], :green => result[1], :blue => result[2])
     end
+
+    def hsl_to_rgb!
+      return if @attrs[:red] && @attrs[:blue] && @attrs[:green]
+
+      h = @attrs[:hue] / 360.0
+      s = @attrs[:saturation] / 100.0
+      l = @attrs[:lightness] / 100.0
+
+      # Algorithm from the CSS3 spec: http://www.w3.org/TR/css3-color/#hsl-color.
+      m2 = l <= 0.5 ? l * (s + 1) : l + s - l * s
+      m1 = l * 2 - m2
+      @attrs[:red], @attrs[:green], @attrs[:blue] = [
+        hue_to_rgb(m1, m2, h + 1.0/3),
+        hue_to_rgb(m1, m2, h),
+        hue_to_rgb(m1, m2, h - 1.0/3)
+      ].map {|c| (c * 0xff).round}
+    end
+
+    def hue_to_rgb(m1, m2, h)
+      h += 1 if h < 0
+      h -= 1 if h > 1
+      return m1 + (m2 - m1) * h * 6 if h * 6 < 1
+      return m2 if h * 2 < 1
+      return m1 + (m2 - m1) * (2.0/3 - h) * 6 if h * 3 < 2
+      return m1
+    end
+
+    def rgb_to_hsl!
+      return if @attrs[:hue] && @attrs[:saturation] && @attrs[:lightness]
+      r, g, b = [:red, :green, :blue].map {|k| @attrs[k] / 255.0}
+
+      # Algorithm from http://en.wikipedia.org/wiki/HSL_and_HSV#Conversion_from_RGB_to_HSL_or_HSV
+      max = [r, g, b].max
+      min = [r, g, b].min
+      d = max - min
+
+      h =
+        case max
+        when min; 0
+        when r; 60 * (g-b)/d
+        when g; 60 * (b-r)/d + 120
+        when b; 60 * (r-g)/d + 240
+        end
+
+      l = (max + min)/2.0
+
+      s =
+        if max == min
+          0
+        elsif l < 0.5
+          d/(2*l)
+        else
+          d/(2 - 2*l)
+        end
+
+      @attrs[:hue] = h % 360
+      @attrs[:saturation] = s * 100
+      @attrs[:lightness] = l * 100
+    end
   end
 end