sass 3.1.0 → 3.3.0

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.
@@ -125,11 +136,12 @@ module Sass
       def puts_action(name, color, arg)
         return if @options[:for_engine][:quiet]
         printf color(color, "%11s %s\n"), name, arg
+        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)
@@ -151,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
@@ -159,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)
@@ -182,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
@@ -192,6 +215,8 @@ MESSAGE
       # Tells optparse how to parse the arguments.
       #
       # @param opts [OptionParser]
+      # @comment
+      #   rubocop:disable MethodLength
       def set_opts(opts)
         super
 
@@ -229,15 +254,28 @@ END
                                    'Only meaningful for --watch and --update.') do
           @options[:stop_on_error] = true
         end
+        opts.on('--poll', 'Check for file changes manually, rather than relying on the OS.',
+                          'Only meaningful for --watch.') do
+          @options[:poll] = true
+        end
+        opts.on('-f', '--force', 'Recompile all Sass files, even if the CSS file is newer.',
+                                 'Only meaningful for --update.') do
+          @options[:force] = true
+        end
         opts.on('-c', '--check', "Just check syntax, don't evaluate.") do
           require 'stringio'
           @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 #{::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
         end
@@ -245,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',
@@ -262,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', '--default-encoding 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.
@@ -294,6 +346,8 @@ END
         return watch_or_update if @options[:watch] || @options[:update]
         super
         @options[:for_engine][:filename] = @options[:filename]
+        @options[:for_engine][:css_filename] = @options[:output] if @options[:output].is_a?(String)
+        @options[:for_engine][:sourcemap_filename] = @options[:sourcemap_filename]
 
         begin
           input = @options[:input]
@@ -308,16 +362,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 = ::Sass::Util.pathname(@options[:sourcemap_filename]).
+              relative_path_from(::Sass::Util.pathname(@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
 
@@ -345,10 +415,19 @@ 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]
+          ::Sass::Plugin.options[:always_update] = true
+        end
 
         raise <<MSG if @args.empty?
 What files should I watch? Did you mean something like:
@@ -372,25 +451,38 @@ 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_updating_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
+            puts_action :error, :red, error.message
+            STDOUT.flush
+            next
+          end
+
           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
 
         if @options[:update]
@@ -401,12 +493,23 @@ MSG
 
         puts ">>> Sass is watching for changes. Press Ctrl-C to stop."
 
-        ::Sass::Plugin.on_template_modified {|template| puts ">>> Change detected to: #{template}"}
-        ::Sass::Plugin.on_template_created {|template| puts ">>> New template detected: #{template}"}
-        ::Sass::Plugin.on_template_deleted {|template| puts ">>> Deleted template detected: #{template}"}
+        ::Sass::Plugin.on_template_modified do |template|
+          puts ">>> Change detected to: #{template}"
+          STDOUT.flush
+        end
+        ::Sass::Plugin.on_template_created do |template|
+          puts ">>> New template detected: #{template}"
+          STDOUT.flush
+        end
+        ::Sass::Plugin.on_template_deleted do |template|
+          puts ">>> Deleted template detected: #{template}"
+          STDOUT.flush
+        end
 
         ::Sass::Plugin.watch(files)
       end
+      # @comment
+      #   rubocop:enable MethodLength
 
       def colon_path?(path)
         !split_colon_path(path)[1].nil?
@@ -429,7 +532,17 @@ MSG
       def probably_dest_dir?(path)
         return false unless path
         return false if colon_path?(path)
-        return Dir.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['SASS_PATH']
+          # The select here prevents errors when the environment's
+          # load paths specified do not exist.
+          ENV['SASS_PATH'].split(File::PATH_SEPARATOR).select {|d| File.directory?(d)}
+        else
+          [::Sass::Importers::DeprecatedPath.new(".")]
+        end
       end
     end
 
@@ -454,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]
@@ -467,14 +582,14 @@ Options:
 END
 
         opts.on('-F', '--from FORMAT',
-          'The format to convert from. Can be css, scss, sass, less.',
+          'The format to convert from. Can be css, scss, sass.',
           'By default, this is inferred from the input filename.',
           'If there is none, defaults to css.') do |name|
           @options[:from] = name.downcase.to_sym
-          unless [:css, :scss, :sass, :less].include?(@options[:from])
+          raise "sass-convert no longer supports LessCSS." if @options[:from] == :less
+          unless [:css, :scss, :sass].include?(@options[:from])
             raise "Unknown format for sass-convert --from: #{name}"
           end
-          try_less_note if @options[:from] == :less
         end
 
         opts.on('-T', '--to FORMAT',
@@ -502,6 +617,17 @@ END
           @options[:for_tree][:dasherize] = true
         end
 
+        opts.on('--indent NUM',
+          'How many spaces to use for each level of indentation. Defaults to 2.',
+          '"t" means use hard tabs.') do |indent|
+
+          if indent == 't'
+            @options[:for_tree][:indent] = "\t"
+          else
+            @options[:for_tree][:indent] = " " * indent.to_i
+          end
+        end
+
         opts.on('--old', 'Output the old-style ":prop val" property syntax.',
                          'Only meaningful when generating Sass.') do
           @options[:for_tree][:old] = true
@@ -512,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.
@@ -532,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)
@@ -541,27 +672,29 @@ 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"
         end
 
         ext = @options[:from]
-        Dir.glob("#{@options[:input]}/**/*.#{ext}") do |f|
+        ::Sass::Util.glob("#{@options[:input]}/**/*.#{ext}") do |f|
           output =
             if @options[:in_place]
               f
@@ -585,7 +718,6 @@ END
           end
 
           input = open_file(f)
-          output = @options[:in_place] ? input : open_file(output, "w")
           process_file(input, output)
         end
       end
@@ -596,7 +728,7 @@ END
             case input.path
             when /\.scss$/; :scss
             when /\.sass$/; :sass
-            when /\.less$/; :less
+            when /\.less$/; raise "sass-convert no longer supports LessCSS."
             when /\.css$/; :css
             end
         elsif @options[:in_place]
@@ -620,11 +752,6 @@ END
             if @options[:from] == :css
               require 'sass/css'
               ::Sass::CSS.new(input.read, @options[:for_tree]).render(@options[:to])
-            elsif @options[:from] == :less
-              require 'sass/less'
-              try_less_note
-              input = input.read if input.is_a?(IO) && !input.is_a?(File) # Less is dumb
-              Less::Engine.new(input).to_tree.to_sass_tree.send("to_#{@options[:to]}", @options[:for_tree])
             else
               if input.is_a?(File)
                 ::Sass::Engine.for_file(input.path, @options[:for_engine])
@@ -634,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
@@ -643,17 +770,6 @@ END
       rescue LoadError => err
         handle_load_error(err)
       end
-
-      @@less_note_printed = false
-      def try_less_note
-        return if @@less_note_printed
-        @@less_note_printed = true
-        warn <<NOTE
-* NOTE: Sass and Less are different languages, and they work differently.
-* I'll do my best to translate, but some features -- especially mixins --
-* should be checked by hand.
-NOTE
-      end
     end
   end
 end

data/lib/sass/features.rb

@@ -0,0 +1,40 @@
+require 'set'
+module Sass
+  # Provides `Sass.has_feature?` which allows for simple feature detection
+  # by providing a feature name.
+  module Features
+    # This is the set of features that can be detected.
+    KNOWN_FEATURES = Set[*%w{
+    }]
+
+    # Check if a feature exists by name. This is used to implement
+    # the Sass function `feature-exists($feature)`
+    #
+    # @param feature_name [String] The case sensitive name of the feature to
+    #   check if it exists in this version of Sass.
+    # @return [Boolean] whether the feature of that name exists.
+    def has_feature?(feature_name)
+      KNOWN_FEATURES.include?(feature_name)
+    end
+
+    # Add a feature to Sass. Plugins can use this to easily expose their
+    # availability to end users. Plugins must prefix their feature
+    # names with a dash to distinguish them from official features.
+    #
+    # @example
+    #   Sass.add_feature("-import-globbing")
+    #   Sass.add_feature("-math-cos")
+    #
+    #
+    # @param feature_name [String] The case sensitive name of the feature to
+    #   to add to Sass. Must begin with a dash.
+    def add_feature(feature_name)
+      unless feature_name[0] == ?-
+        raise ArgumentError.new("Plugin feature names must begin with a dash")
+      end
+      KNOWN_FEATURES << feature_name
+    end
+  end
+
+  extend Features
+end

data/lib/sass/importers/base.rb

@@ -15,13 +15,9 @@ module Sass
     # They should also implement the \{#find\_relative} method.
     #
     # Importers should be serializable via `Marshal.dump`.
-    # In addition to the standard `_dump` and `_load` methods,
-    # importers can define `_before_dump`, `_after_dump`, `_around_dump`,
-    # and `_after_load` methods as per {Sass::Util#dump} and {Sass::Util#load}.
     #
     # @abstract
     class Base
-
       # Find a Sass file relative to another file.
       # Importers without a notion of "relative paths"
       # should just return nil here.
@@ -72,7 +68,8 @@ module Sass
       # If no such files exist, it should return nil.
       #
       # The {Sass::Engine} to be returned should be passed `options`,
-      # with a few modifications. `:filename` and `:syntax` should be set appropriately,
+      # with a few modifications. `:syntax` should be set appropriately,
+      # `:filename` should be set to `uri`,
       # and `:importer` should be set to this importer.
       #
       # @param uri [String] The URI to import.
@@ -121,6 +118,29 @@ module Sass
         Sass::Util.abstract(self)
       end
 
+      # Get the publicly-visible URL for an imported file. This URL is used by
+      # source maps to link to the source stylesheet. This may return `nil` to
+      # indicate that no public URL is available; however, this will cause
+      # sourcemap generation to fail if any CSS is generated from files imported
+      # from this importer.
+      #
+      # @param uri [String] A URI known to be valid for this importer.
+      # @param sourcemap_directory [String, NilClass] The absolute path to a
+      #   directory on disk where the sourcemap will be saved. If uri refers to
+      #   a file on disk that's accessible relative to sourcemap_directory, this
+      #   may return a relative URL. This may be `nil` if the sourcemap's
+      #   eventual location is unknown.
+      # @return [String?] The publicly-visible URL for this file, or `nil`
+      #   indicating that no publicly-visible URL exists.
+      def public_url(uri, sourcemap_directory = nil)
+        return if @public_url_warning_issued
+        @public_url_warning_issued = true
+        Sass::Util.sass_warn <<WARNING
+WARNING: #{self.class.name} should define the #public_url method.
+WARNING
+        nil
+      end
+
       # A string representation of the importer.
       # Should be overridden by subclasses.
       #
@@ -131,8 +151,27 @@ module Sass
       def to_s
         Sass::Util.abstract(self)
       end
+
+      # If the importer is based on files on the local filesystem
+      # this method should return folders which should be watched
+      # for changes.
+      #
+      # @return [Array<String>] List of absolute paths of directories to watch
+      def directories_to_watch
+        []
+      end
+
+      # If this importer is based on files on the local filesystem This method
+      # should return true if the file, when changed, should trigger a
+      # recompile.
+      #
+      # It is acceptable for non-sass files to be watched and trigger a recompile.
+      #
+      # @param filename [String] The absolute filename for a file that has changed.
+      # @return [Boolean] When the file changed should cause a recompile.
+      def watched_file?(filename)
+        false
+      end
     end
   end
 end
-
-