sass 3.2.7 → 3.3.0.rc.1

data/lib/sass/environment.rb

@@ -1,60 +1,20 @@
 require 'set'
 
 module Sass
-  # The lexical environment for SassScript.
-  # This keeps track of variable, mixin, and function 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_reader :options
-    attr_writer :caller
-    attr_writer :content
-
-    # @param options [{Symbol => Object}] The options hash. See
-    #   {file:SASS_REFERENCE.md#sass_options the Sass options documentation}.
-    # @param parent [Environment] See \{#parent}
-    def initialize(parent = nil, options = nil)
-      @parent = parent
-      @options = options || (parent && parent.options) || {}
-    end
-
-    # The environment of the caller of this environment's mixin or function.
-    # @return {Environment?}
-    def caller
-      @caller || (@parent && @parent.caller)
-    end
-
-    # The content passed to this environmnet. This is naturally only set
-    # for mixin body environments with content passed in.
-    # @return {Environment?}
-    def content
-      @content || (@parent && @parent.content)
-    end
-
-    private
-
+  # The abstract base class for lexical environments for SassScript.
+  class BaseEnvironment
     class << self
-      private
-      UNDERSCORE, DASH = '_', '-'
-
       # Note: when updating this,
       # update sass/yard/inherited_hash.rb as well.
-      def inherited_hash(name)
-        class_eval <<RUBY, __FILE__, __LINE__ + 1
+      def inherited_hash_accessor(name)
+        inherited_hash_reader(name)
+        inherited_hash_writer(name)
+      end
+
+      def inherited_hash_reader(name)
+        class_eval <<-RUBY, __FILE__, __LINE__ + 1
           def #{name}(name)
-            _#{name}(name.tr(UNDERSCORE, DASH))
+            _#{name}(name.tr('_', '-'))
           end
 
           def _#{name}(name)
@@ -62,8 +22,17 @@ module Sass
           end
           protected :_#{name}
 
+          def is_#{name}_global?(name)
+            return !@parent if @#{name}s && @#{name}s.has_key?(name)
+            @parent && @parent.is_#{name}_global?(name)
+          end
+        RUBY
+      end
+
+      def inherited_hash_writer(name)
+        class_eval <<-RUBY, __FILE__, __LINE__ + 1
           def set_#{name}(name, value)
-            name = name.tr(UNDERSCORE, DASH)
+            name = name.tr('_', '-')
             @#{name}s[name] = value unless try_set_#{name}(name, value)
           end
 
@@ -82,20 +51,130 @@ module Sass
 
           def set_local_#{name}(name, value)
             @#{name}s ||= {}
-            @#{name}s[name.tr(UNDERSCORE, DASH)] = value
+            @#{name}s[name.tr('_', '-')] = value
           end
-RUBY
+        RUBY
       end
     end
 
+    # The options passed to the Sass Engine.
+    attr_reader :options
+
+    attr_writer :caller
+    attr_writer :content
+    attr_writer :selector
+
     # variable
-    # Script::Literal
-    inherited_hash :var
+    # Script::Value
+    inherited_hash_reader :var
+
     # mixin
     # Sass::Callable
-    inherited_hash :mixin
+    inherited_hash_reader :mixin
+
     # function
     # Sass::Callable
-    inherited_hash :function
+    inherited_hash_reader :function
+
+    # @param options [{Symbol => Object}] The options hash. See
+    #   {file:SASS_REFERENCE.md#sass_options the Sass options documentation}.
+    # @param parent [Environment] See \{#parent}
+    def initialize(parent = nil, options = nil)
+      @parent = parent
+      @options = options || (parent && parent.options) || {}
+      @stack = Sass::Stack.new if @parent.nil?
+    end
+
+    # The environment of the caller of this environment's mixin or function.
+    # @return {Environment?}
+    def caller
+      @caller || (@parent && @parent.caller)
+    end
+
+    # The content passed to this environment. This is naturally only set
+    # for mixin body environments with content passed in.
+    #
+    # @return {[Array<Sass::Tree::Node>, Environment]?} The content nodes and
+    #   the lexical environment of the content block.
+    def content
+      @content || (@parent && @parent.content)
+    end
+
+    # The selector for the current CSS rule, or nil if there is no
+    # current CSS rule.
+    #
+    # @return [Selector::CommaSequence?] The current selector, with any
+    #   nesting fully resolved.
+    def selector
+      @selector || (@caller && @caller.selector) || (@parent && @parent.selector)
+    end
+
+    # The top-level Environment object.
+    #
+    # @return [Environment]
+    def global_env
+      @global_env ||= @parent.nil? ? self : @parent.global_env
+    end
+
+    # The import/mixin stack.
+    #
+    # @return [Sass::Stack]
+    def stack
+      @stack || global_env.stack
+    end
+  end
+
+  # The lexical environment for SassScript.
+  # This keeps track of variable, mixin, and function 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 < BaseEnvironment
+    # The enclosing environment,
+    # or nil if this is the global environment.
+    #
+    # @return [Environment]
+    attr_reader :parent
+
+    # variable
+    # Script::Value
+    inherited_hash_writer :var
+
+    # mixin
+    # Sass::Callable
+    inherited_hash_writer :mixin
+
+    # function
+    # Sass::Callable
+    inherited_hash_writer :function
+  end
+
+  # A read-only wrapper for a lexical environment for SassScript.
+  class ReadOnlyEnvironment < BaseEnvironment
+    # The read-only environment of the caller of this environment's mixin or function.
+    #
+    # @see BaseEnvironment#caller
+    # @return {ReadOnlyEnvironment}
+    def caller
+      return @caller if @caller
+      env = super
+      @caller ||= env.is_a?(ReadOnlyEnvironment) ? env : ReadOnlyEnvironment.new(env, env.options)
+    end
+
+    # The read-only content passed to this environment.
+    #
+    # @see BaseEnvironment#content
+    # @return {ReadOnlyEnvironment}
+    def content
+      return @content if @content
+      env = super
+      @content ||= env.is_a?(ReadOnlyEnvironment) ? env : ReadOnlyEnvironment.new(env, env.options)
+    end
   end
 end

data/lib/sass/error.rb

@@ -138,15 +138,15 @@ module Sass
     # @see #sass_backtrace
     # @return [String]
     def sass_backtrace_str(default_filename = "an unknown file")
-      lines = self.message.split("\n")
+      lines = message.split("\n")
       msg = lines[0] + lines[1..-1].
         map {|l| "\n" + (" " * "Syntax error: ".size) + l}.join
       "Syntax error: #{msg}" +
         Sass::Util.enum_with_index(sass_backtrace).map do |entry, i|
-        "\n        #{i == 0 ? "on" : "from"} line #{entry[:line]}" +
-          " of #{entry[:filename] || default_filename}" +
-          (entry[:mixin] ? ", in `#{entry[:mixin]}'" : "")
-      end.join
+          "\n        #{i == 0 ? "on" : "from"} line #{entry[:line]}" +
+            " of #{entry[:filename] || default_filename}" +
+            (entry[:mixin] ? ", in `#{entry[:mixin]}'" : "")
+        end.join
     end
 
     class << self
@@ -165,9 +165,9 @@ module Sass
 
         <<END
 /*
-#{header}
+#{header.gsub("*/", "*\\/")}
 
-Backtrace:\n#{e.backtrace.join("\n")}
+Backtrace:\n#{e.backtrace.join("\n").gsub("*/", "*\\/")}
 */
 body:before {
   white-space: pre;

data/lib/sass/exec.rb

@@ -17,6 +17,7 @@ module Sass
       #
       # @see #parse
       def parse!
+        # rubocop:disable RescueException
         begin
           parse
         rescue Exception => e
@@ -28,6 +29,7 @@ module Sass
           exit 1
         end
         exit 0
+        # rubocop:enable RescueException
       end
 
       # Parses the command-line arguments and runs the executable.
@@ -58,7 +60,9 @@ module Sass
       def get_line(exception)
         # SyntaxErrors have weird line reporting
         # when there's trailing whitespace
-        return (exception.message.scan(/:(\d+)/).first || ["??"]).first if exception.is_a?(::SyntaxError)
+        if exception.is_a?(::SyntaxError)
+          return (exception.message.scan(/:(\d+)/).first || ["??"]).first
+        end
         (exception.backtrace[0].scan(/:(\d+)/).first || ["??"]).first
       end
 
@@ -70,7 +74,8 @@ module Sass
       #
       # @param opts [OptionParser]
       def set_opts(opts)
-        opts.on('-s', '--stdin', :NONE, 'Read input from standard input instead of an input file') do
+        opts.on('-s', '--stdin', :NONE,
+                'Read input from standard input instead of an input file') do
           @options[:input] = $stdin
         end
 
@@ -95,6 +100,7 @@ module Sass
 
       # Processes the options set by the command-line arguments.
       # In particular, sets `@options[:input]` and `@options[:output]`
+      # (and `@options[:sourcemap]` if one has been specified)
       # to appropriate IO streams.
       #
       # This is meant to be overridden by subclasses
@@ -108,12 +114,17 @@ module Sass
             @options[:filename] = filename
             open_file(filename) || $stdin
           end
-        output ||= open_file(args.shift, 'w') || $stdout
+        @options[:output_filename] = args.shift
+        output ||= @options[:output_filename] || $stdout
+
+        if @options[:sourcemap] && @options[:output_filename]
+          @options[:sourcemap_filename] = Util.sourcemap_name(@options[:output_filename])
+        end
 
         @options[:input], @options[:output] = input, output
       end
 
-      COLORS = { :red => 31, :green => 32, :yellow => 33 }
+      COLORS = {:red => 31, :green => 32, :yellow => 33}
 
       # Prints a status message about performing the given action,
       # colored using the given color (via terminal escapes) if possible.
@@ -128,9 +139,9 @@ module Sass
         STDOUT.flush
       end
 
-      # Same as \{Kernel.puts}, but doesn't print anything if the `--quiet` option is set.
+      # Same as `Kernel.puts`, but doesn't print anything if the `--quiet` option is set.
       #
-      # @param args [Array] Passed on to \{Kernel.puts}
+      # @param args [Array] Passed on to `Kernel.puts`
       def puts(*args)
         return if @options[:for_engine][:quiet]
         Kernel.puts(*args)
@@ -152,7 +163,15 @@ module Sass
         # so we just filter for Windows terms (which don't set TERM)
         # and not-real terminals, which aren't ttys.
         return str if ENV["TERM"].nil? || ENV["TERM"].empty? || !STDOUT.tty?
-        return "\e[#{COLORS[color]}m#{str}\e[0m"
+        "\e[#{COLORS[color]}m#{str}\e[0m"
+      end
+
+      def write_output(text, destination)
+        if destination.is_a?(String)
+          open_file(destination, 'w') {|file| file.write(text)}
+        else
+          destination.write(text)
+        end
       end
 
       private
@@ -160,7 +179,10 @@ module Sass
       def open_file(filename, flag = 'r')
         return if filename.nil?
         flag = 'wb' if @options[:unix_newlines] && flag == 'w'
-        File.open(filename, flag)
+        file = File.open(filename, flag)
+        return file unless block_given?
+        yield file
+        file.close
       end
 
       def handle_load_error(err)
@@ -183,7 +205,7 @@ MESSAGE
       def initialize(args)
         super
         @options[:for_engine] = {
-          :load_paths => ['.'] + (ENV['SASSPATH'] || '').split(File::PATH_SEPARATOR)
+          :load_paths => default_sass_path
         }
         @default_syntax = :sass
       end
@@ -193,6 +215,8 @@ MESSAGE
       # Tells optparse how to parse the arguments.
       #
       # @param opts [OptionParser]
+      # @comment
+      #   rubocop:disable MethodLength
       def set_opts(opts)
         super
 
@@ -243,13 +267,14 @@ END
           @options[:check_syntax] = true
           @options[:output] = StringIO.new
         end
-        opts.on('-t', '--style NAME',
-                'Output style. Can be nested (default), compact, compressed, or expanded.') do |name|
+        style_desc = 'Output style. Can be nested (default), compact, compressed, or expanded.'
+        opts.on('-t', '--style NAME', style_desc) do |name|
           @options[:for_engine][:style] = name.to_sym
         end
         opts.on('--precision NUMBER_OF_DIGITS', Integer,
-                'How many digits of precision to use when outputting decimal numbers. Defaults to 3.') do |precision|
-          ::Sass::Script::Number.precision = precision
+                "How many digits of precision to use when outputting decimal numbers." +
+                "Defaults to #{::Sass::Script::Value::Number.precision}.") do |precision|
+          ::Sass::Script::Value::Number.precision = precision
         end
         opts.on('-q', '--quiet', 'Silence warnings and status messages during compilation.') do
           @options[:for_engine][:quiet] = true
@@ -258,7 +283,7 @@ END
           @options[:compass] = true
         end
         opts.on('-g', '--debug-info',
-                'Emit extra information in the generated CSS that can be used by the FireSass Firebug plugin.') do
+                'Emit output that can be used by the FireSass Firebug plugin.') do
           @options[:for_engine][:debug_info] = true
         end
         opts.on('-l', '--line-numbers', '--line-comments',
@@ -275,19 +300,33 @@ END
         opts.on('-r', '--require LIB', 'Require a Ruby library before running Sass.') do |lib|
           require lib
         end
-        opts.on('--cache-location PATH', 'The path to put cached Sass files. Defaults to .sass-cache.') do |loc|
+        opts.on('--cache-location PATH',
+                'The path to put cached Sass files. Defaults to .sass-cache.') do |loc|
           @options[:for_engine][:cache_location] = loc
         end
         opts.on('-C', '--no-cache', "Don't cache to sassc files.") do
           @options[:for_engine][:cache] = false
         end
+        opts.on('--sourcemap', 'Create sourcemap files next to the generated CSS files.') do
+          @options[:sourcemap] = true
+        end
 
-        unless ::Sass::Util.ruby1_8?
-          opts.on('-E encoding', 'Specify the default encoding for Sass files.') do |encoding|
+        encoding_desc = if ::Sass::Util.ruby1_8?
+                          'Does not work in ruby 1.8.'
+                        else
+                          'Specify the default encoding for Sass files.'
+                        end
+        opts.on('-E encoding', encoding_desc) do |encoding|
+          if ::Sass::Util.ruby1_8?
+            $stderr.puts "Specifying the encoding is not supported in ruby 1.8."
+            exit 1
+          else
             Encoding.default_external = encoding
           end
         end
       end
+      # @comment
+      #   rubocop:enable MethodLength
 
       # Processes the options set by the command-line arguments,
       # and runs the Sass compiler appropriately.
@@ -307,7 +346,7 @@ END
         return watch_or_update if @options[:watch] || @options[:update]
         super
         @options[:for_engine][:filename] = @options[:filename]
-        @options[:for_engine][:css_filename] = @options[:output].path if @options[:output].is_a?(File)
+        @options[:for_engine][:css_filename] = @options[:output] if @options[:output].is_a?(String)
 
         begin
           input = @options[:input]
@@ -322,16 +361,32 @@ END
               # We don't need to do any special handling of @options[:check_syntax] here,
               # because the Sass syntax checking happens alongside evaluation
               # and evaluation doesn't actually evaluate any code anyway.
-              ::Sass::Engine.new(input.read(), @options[:for_engine])
+              ::Sass::Engine.new(input.read, @options[:for_engine])
             end
 
-          input.close() if input.is_a?(File)
+          input.close if input.is_a?(File)
+
+          if @options[:sourcemap]
+            unless @options[:sourcemap_filename]
+              raise "Can't generate a sourcemap for an input without a path."
+            end
 
-          output.write(engine.render)
-          output.close() if output.is_a? File
+            relative_sourcemap_path = Pathname.new(@options[:sourcemap_filename]).
+              relative_path_from(Pathname.new(@options[:output_filename]).dirname)
+            rendered, mapping = engine.render_with_sourcemap(relative_sourcemap_path.to_s)
+            write_output(rendered, output)
+            write_output(mapping.to_json(
+                :css_path => @options[:output_filename],
+                :sourcemap_path => @options[:sourcemap_filename]) + "\n",
+              @options[:sourcemap_filename])
+          else
+            write_output(engine.render, output)
+          end
         rescue ::Sass::SyntaxError => e
           raise e if @options[:trace]
           raise e.sass_backtrace_str("standard input")
+        ensure
+          output.close if output.is_a? File
         end
       end
 
@@ -359,11 +414,14 @@ END
         ::Sass::Repl.new(@options).run
       end
 
+      # @comment
+      #   rubocop:disable MethodLength
       def watch_or_update
         require 'sass/plugin'
         ::Sass::Plugin.options.merge! @options[:for_engine]
         ::Sass::Plugin.options[:unix_newlines] = @options[:unix_newlines]
         ::Sass::Plugin.options[:poll] = @options[:poll]
+        ::Sass::Plugin.options[:sourcemap] = @options[:sourcemap]
 
         if @options[:force]
           raise "The --force flag may only be used with --update." unless @options[:update]
@@ -392,21 +450,25 @@ MSG
 
         dirs, files = @args.map {|name| split_colon_path(name)}.
           partition {|i, _| File.directory? i}
-        files.map! {|from, to| [from, to || from.gsub(/\.[^.]*?$/, '.css')]}
+        files.map! do |from, to|
+          to ||= from.gsub(/\.[^.]*?$/, '.css')
+          sourcemap = Util.sourcemap_name(to) if @options[:sourcemap]
+          [from, to, sourcemap]
+        end
         dirs.map! {|from, to| [from, to || from]}
         ::Sass::Plugin.options[:template_location] = dirs
 
-        ::Sass::Plugin.on_updated_stylesheet do |_, css|
-          if File.exists? css
-            puts_action :overwrite, :yellow, css
-          else
-            puts_action :create, :green, css
+        ::Sass::Plugin.on_updated_stylesheet do |_, css, sourcemap|
+          [css, sourcemap].each do |file|
+            next unless file
+            puts_action :write, :green, file
           end
         end
 
         had_error = false
         ::Sass::Plugin.on_creating_directory {|dirname| puts_action :directory, :green, dirname}
         ::Sass::Plugin.on_deleting_css {|filename| puts_action :delete, :yellow, filename}
+        ::Sass::Plugin.on_deleting_sourcemap {|filename| puts_action :delete, :yellow, filename}
         ::Sass::Plugin.on_compilation_error do |error, _, _|
           if error.is_a?(SystemCallError) && !@options[:stop_on_error]
             had_error = true
@@ -417,7 +479,8 @@ MSG
 
           raise error unless error.is_a?(::Sass::SyntaxError) && !@options[:stop_on_error]
           had_error = true
-          puts_action :error, :red, "#{error.sass_filename} (Line #{error.sass_line}: #{error.message})"
+          puts_action :error, :red,
+            "#{error.sass_filename} (Line #{error.sass_line}: #{error.message})"
           STDOUT.flush
         end
 
@@ -444,6 +507,8 @@ MSG
 
         ::Sass::Plugin.watch(files)
       end
+      # @comment
+      #   rubocop:enable MethodLength
 
       def colon_path?(path)
         !split_colon_path(path)[1].nil?
@@ -466,8 +531,19 @@ MSG
       def probably_dest_dir?(path)
         return false unless path
         return false if colon_path?(path)
-        return ::Sass::Util.glob(File.join(path, "*.s[ca]ss")).empty?
+        ::Sass::Util.glob(File.join(path, "*.s[ca]ss")).empty?
+      end
+
+      def default_sass_path
+        if ENV['SASSPATH']
+          # The select here prevents errors when the environment's
+          # load paths specified do not exist.
+          ENV['SASSPATH'].split(File::PATH_SEPARATOR).select {|d| File.directory?(d)}
+        else
+          [::Sass::Importers::DeprecatedPath.new(".")]
+        end
       end
+
     end
 
     class Scss < Sass
@@ -491,6 +567,8 @@ MSG
       # Tells optparse how to parse the arguments.
       #
       # @param opts [OptionParser]
+      # @comment
+      #   rubocop:disable MethodLength
       def set_opts(opts)
         opts.banner = <<END
 Usage: sass-convert [options] [INPUT] [OUTPUT]
@@ -560,13 +638,16 @@ END
         end
 
         unless ::Sass::Util.ruby1_8?
-          opts.on('-E encoding', 'Specify the default encoding for Sass and CSS files.') do |encoding|
+          opts.on('-E encoding',
+                  'Specify the default encoding for Sass and CSS files.') do |encoding|
             Encoding.default_external = encoding
           end
         end
 
         super
       end
+      # @comment
+      #   rubocop:enable MethodLength
 
       # Processes the options set by the command-line arguments,
       # and runs the CSS compiler appropriately.
@@ -580,7 +661,9 @@ END
 
         super
         input = @options[:input]
-        raise "Error: '#{input.path}' is a directory (did you mean to use --recursive?)" if File.directory?(input)
+        if File.directory?(input)
+          raise "Error: '#{input.path}' is a directory (did you mean to use --recursive?)"
+        end
         output = @options[:output]
         output = input if @options[:in_place]
         process_file(input, output)
@@ -589,20 +672,22 @@ END
       private
 
       def process_directory
-        unless input = @options[:input] = @args.shift
+        unless (input = @options[:input] = @args.shift)
           raise "Error: directory required when using --recursive."
         end
 
         output = @options[:output] = @args.shift
         raise "Error: --from required when using --recursive." unless @options[:from]
         raise "Error: --to required when using --recursive." unless @options[:to]
-        raise "Error: '#{@options[:input]}' is not a directory" unless File.directory?(@options[:input])
-        if @options[:output] && File.exists?(@options[:output]) && !File.directory?(@options[:output])
+        unless File.directory?(@options[:input])
+          raise "Error: '#{@options[:input]}' is not a directory"
+        end
+        if @options[:output] && File.exists?(@options[:output]) &&
+          !File.directory?(@options[:output])
           raise "Error: '#{@options[:output]}' is not a directory"
         end
         @options[:output] ||= @options[:input]
 
-        from = @options[:from]
         if @options[:to] == @options[:from] && !@options[:in_place]
           fmt = @options[:from]
           raise "Error: converting from #{fmt} to #{fmt} without --in-place"
@@ -633,7 +718,6 @@ END
           end
 
           input = open_file(f)
-          output = @options[:in_place] ? input : open_file(output, "w")
           process_file(input, output)
         end
       end
@@ -677,8 +761,8 @@ END
             end
           end
 
-        output = File.open(input.path, 'w') if @options[:in_place]
-        output.write(out)
+        output = input.path if @options[:in_place]
+        write_output(out, output)
       rescue ::Sass::SyntaxError => e
         raise e if @options[:trace]
         file = " of #{e.sass_filename}" if e.sass_filename