sass4 4.0.0

data/lib/sass/environment.rb

@@ -0,0 +1,236 @@
+require 'set'
+
+module Sass
+  # The abstract base class for lexical environments for SassScript.
+  class BaseEnvironment
+    class << self
+      # Note: when updating this,
+      # update sass/yard/inherited_hash.rb as well.
+      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('_', '-'))
+          end
+
+          def _#{name}(name)
+            (@#{name}s && @#{name}s[name]) || @parent && @parent._#{name}(name)
+          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('_', '-')
+            @#{name}s[name] = value unless try_set_#{name}(name, value)
+          end
+
+          def try_set_#{name}(name, value)
+            @#{name}s ||= {}
+            if @#{name}s.include?(name)
+              @#{name}s[name] = value
+              true
+            elsif @parent && !@parent.global?
+              @parent.try_set_#{name}(name, value)
+            else
+              false
+            end
+          end
+          protected :try_set_#{name}
+
+          def set_local_#{name}(name, value)
+            @#{name}s ||= {}
+            @#{name}s[name.tr('_', '-')] = value
+          end
+
+          def set_global_#{name}(name, value)
+            global_env.set_#{name}(name, value)
+          end
+        RUBY
+      end
+    end
+
+    # The options passed to the Sass Engine.
+    attr_reader :options
+
+    attr_writer :caller
+    attr_writer :content
+    attr_writer :selector
+
+    # variable
+    # Script::Value
+    inherited_hash_reader :var
+
+    # mixin
+    # Sass::Callable
+    inherited_hash_reader :mixin
+
+    # function
+    # Sass::Callable
+    inherited_hash_reader :function
+
+    # @param options [{Symbol => Object}] The options hash. See
+    #   {file:SASS_REFERENCE.md#Options the Sass options documentation}.
+    # @param parent [Environment] See \{#parent}
+    def initialize(parent = nil, options = nil)
+      @parent = parent
+      @options = options || (parent && parent.options) || {}
+      @stack = @parent.nil? ? Sass::Stack.new : nil
+      @caller = nil
+      @content = nil
+      @filename = nil
+      @functions = nil
+      @mixins = nil
+      @selector = nil
+      @vars = nil
+    end
+
+    # Returns whether this is the global environment.
+    #
+    # @return [Boolean]
+    def global?
+      @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 ||= global? ? 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
+    def initialize(parent = nil, options = nil)
+      super
+      @content_cached = nil
+    end
+    # 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 content passed to this environment. If the content's environment isn't already
+    # read-only, it's made read-only.
+    #
+    # @see BaseEnvironment#content
+    #
+    # @return {[Array<Sass::Tree::Node>, ReadOnlyEnvironment]?} The content nodes and
+    #   the lexical environment of the content block.
+    #   Returns `nil` when there is no content in this environment.
+    def content
+      # Return the cached content from a previous invocation if any
+      return @content if @content_cached
+      # get the content with a read-write environment from the superclass
+      read_write_content = super
+      if read_write_content
+        tree, env = read_write_content
+        # make the content's environment read-only
+        if env && !env.is_a?(ReadOnlyEnvironment)
+          env = ReadOnlyEnvironment.new(env, env.options)
+        end
+        @content_cached = true
+        @content = [tree, env]
+      else
+        @content_cached = true
+        @content = nil
+      end
+    end
+  end
+
+  # An environment that can write to in-scope global variables, but doesn't
+  # create new variables in the global scope. Useful for top-level control
+  # directives.
+  class SemiGlobalEnvironment < Environment
+    def try_set_var(name, value)
+      @vars ||= {}
+      if @vars.include?(name)
+        @vars[name] = value
+        true
+      elsif @parent
+        @parent.try_set_var(name, value)
+      else
+        false
+      end
+    end
+  end
+end

data/lib/sass/error.rb

@@ -0,0 +1,198 @@
+module Sass
+  # 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).
+  #
+  # All Sass errors are raised as {Sass::SyntaxError}s.
+  #
+  # When dealing with SyntaxErrors,
+  # it's important to provide filename and line number information.
+  # This will be used in various error reports to users, including backtraces;
+  # see \{#sass\_backtrace} for details.
+  #
+  # Some of this information is usually provided as part of the constructor.
+  # New backtrace entries can be added with \{#add\_backtrace},
+  # which is called when an exception is raised between files (e.g. with `@import`).
+  #
+  # Often, a chunk of code will all have similar backtrace information -
+  # the same filename or even line.
+  # It may also be useful to have a default line number set.
+  # In those situations, the default values can be used
+  # by omitting the information on the original exception,
+  # and then calling \{#modify\_backtrace} in a wrapper `rescue`.
+  # When doing this, be sure that all exceptions ultimately end up
+  # with the information filled in.
+  class SyntaxError < StandardError
+    # The backtrace of the error within Sass files.
+    # This is an array of hashes containing information for a single entry.
+    # The hashes have the following keys:
+    #
+    # `:filename`
+    # : The name of the file in which the exception was raised,
+    #   or `nil` if no filename is available.
+    #
+    # `:mixin`
+    # : The name of the mixin in which the exception was raised,
+    #   or `nil` if it wasn't raised in a mixin.
+    #
+    # `:line`
+    # : The line of the file on which the error occurred. Never nil.
+    #
+    # This information is also included in standard backtrace format
+    # in the output of \{#backtrace}.
+    #
+    # @return [Aray<{Symbol => Object>}]
+    attr_accessor :sass_backtrace
+
+    # The text of the template where this error was raised.
+    #
+    # @return [String]
+    attr_accessor :sass_template
+
+    # @param msg [String] The error message
+    # @param attrs [{Symbol => Object}] The information in the backtrace entry.
+    #   See \{#sass\_backtrace}
+    def initialize(msg, attrs = {})
+      @message = msg
+      @sass_backtrace = []
+      add_backtrace(attrs)
+    end
+
+    # The name of the file in which the exception was raised.
+    # This could be `nil` if no filename is available.
+    #
+    # @return [String, nil]
+    def sass_filename
+      sass_backtrace.first[:filename]
+    end
+
+    # The name of the mixin in which the error occurred.
+    # This could be `nil` if the error occurred outside a mixin.
+    #
+    # @return [String]
+    def sass_mixin
+      sass_backtrace.first[:mixin]
+    end
+
+    # The line of the Sass template on which the error occurred.
+    #
+    # @return [Integer]
+    def sass_line
+      sass_backtrace.first[:line]
+    end
+
+    # Adds an entry to the exception's Sass backtrace.
+    #
+    # @param attrs [{Symbol => Object}] The information in the backtrace entry.
+    #   See \{#sass\_backtrace}
+    def add_backtrace(attrs)
+      sass_backtrace << attrs.reject {|_k, v| v.nil?}
+    end
+
+    # Modify the top Sass backtrace entries
+    # (that is, the most deeply nested ones)
+    # to have the given attributes.
+    #
+    # Specifically, this goes through the backtrace entries
+    # from most deeply nested to least,
+    # setting the given attributes for each entry.
+    # If an entry already has one of the given attributes set,
+    # the pre-existing attribute takes precedence
+    # and is not used for less deeply-nested entries
+    # (even if they don't have that attribute set).
+    #
+    # @param attrs [{Symbol => Object}] The information to add to the backtrace entry.
+    #   See \{#sass\_backtrace}
+    def modify_backtrace(attrs)
+      attrs = attrs.reject {|_k, v| v.nil?}
+      # Move backwards through the backtrace
+      (0...sass_backtrace.size).to_a.reverse_each do |i|
+        entry = sass_backtrace[i]
+        sass_backtrace[i] = attrs.merge(entry)
+        attrs.reject! {|k, _v| entry.include?(k)}
+        break if attrs.empty?
+      end
+    end
+
+    # @return [String] The error message
+    def to_s
+      @message
+    end
+
+    # Returns the standard exception backtrace,
+    # including the Sass backtrace.
+    #
+    # @return [Array<String>]
+    def backtrace
+      return nil if super.nil?
+      return super if sass_backtrace.all? {|h| h.empty?}
+      sass_backtrace.map do |h|
+        "#{h[:filename] || '(sass)'}:#{h[:line]}" +
+          (h[:mixin] ? ":in `#{h[:mixin]}'" : "")
+      end + super
+    end
+
+    # Returns a string representation of the Sass backtrace.
+    #
+    # @param default_filename [String] The filename to use for unknown files
+    # @see #sass_backtrace
+    # @return [String]
+    def sass_backtrace_str(default_filename = "an unknown file")
+      lines = message.split("\n")
+      msg = lines[0] + lines[1..-1].
+        map {|l| "\n" + (" " * "Error: ".size) + l}.join
+      "Error: #{msg}" +
+        sass_backtrace.each_with_index.map do |entry, i|
+          "\n        #{i == 0 ? 'on' : 'from'} line #{entry[:line]}" +
+            " of #{entry[:filename] || default_filename}" +
+            (entry[:mixin] ? ", in `#{entry[:mixin]}'" : "")
+        end.join
+    end
+
+    class << self
+      # Returns an error report for an exception in CSS format.
+      #
+      # @param e [Exception]
+      # @param line_offset [Integer] The number of the first line of the Sass template.
+      # @return [String] The error report
+      # @raise [Exception] `e`, if the
+      #   {file:SASS_REFERENCE.md#full_exception-option `:full_exception`} option
+      #   is set to false.
+      def exception_to_css(e, line_offset = 1)
+        header = header_string(e, line_offset)
+
+        <<END
+/*
+#{header.gsub('*/', '*\\/')}
+
+Backtrace:\n#{e.backtrace.join("\n").gsub('*/', '*\\/')}
+*/
+body:before {
+  white-space: pre;
+  font-family: monospace;
+  content: "#{header.gsub('"', '\"').gsub("\n", '\\A ')}"; }
+END
+      end
+
+      private
+
+      def header_string(e, line_offset)
+        unless e.is_a?(Sass::SyntaxError) && e.sass_line && e.sass_template
+          return "#{e.class}: #{e.message}"
+        end
+
+        line_num = e.sass_line + 1 - line_offset
+        min = [line_num - 6, 0].max
+        section = e.sass_template.rstrip.split("\n")[min...line_num + 5]
+        return e.sass_backtrace_str if section.nil? || section.empty?
+
+        e.sass_backtrace_str + "\n\n" + section.each_with_index.
+          map {|line, i| "#{line_offset + min + i}: #{line}"}.join("\n")
+      end
+    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/exec/base.rb

@@ -0,0 +1,188 @@
+require 'optparse'
+
+module Sass::Exec
+  # The abstract base class for Sass executables.
+  class Base
+    # @param args [Array<String>] The command-line arguments
+    def initialize(args)
+      @args = args
+      @options = {}
+    end
+
+    # Parses the command-line arguments and runs the executable.
+    # Calls `Kernel#exit` at the end, so it never returns.
+    #
+    # @see #parse
+    def parse!
+      begin
+        parse
+      rescue Exception => e
+        # Exit code 65 indicates invalid data per
+        # http://www.freebsd.org/cgi/man.cgi?query=sysexits. Setting it via
+        # at_exit is a bit of a hack, but it allows us to rethrow when --trace
+        # is active and get both the built-in exception formatting and the
+        # correct exit code.
+        at_exit {exit Sass::Util.windows? ? 13 : 65} if e.is_a?(Sass::SyntaxError)
+
+        raise e if @options[:trace] || e.is_a?(SystemExit)
+
+        if e.is_a?(Sass::SyntaxError)
+          $stderr.puts e.sass_backtrace_str("standard input")
+        else
+          $stderr.print "#{e.class}: " unless e.class == RuntimeError
+          $stderr.puts e.message.to_s
+        end
+        $stderr.puts "  Use --trace for backtrace."
+
+        exit 1
+      end
+      exit 0
+    end
+
+    # Parses the command-line arguments and runs the executable.
+    # This does not handle exceptions or exit the program.
+    #
+    # @see #parse!
+    def parse
+      @opts = OptionParser.new(&method(:set_opts))
+      @opts.parse!(@args)
+
+      process_result
+
+      @options
+    end
+
+    # @return [String] A description of the executable
+    def to_s
+      @opts.to_s
+    end
+
+    protected
+
+    # Finds the line of the source template
+    # on which an exception was raised.
+    #
+    # @param exception [Exception] The exception
+    # @return [String] The line number
+    def get_line(exception)
+      # SyntaxErrors have weird line reporting
+      # when there's trailing whitespace
+      if exception.is_a?(::SyntaxError)
+        return (exception.message.scan(/:(\d+)/).first || ["??"]).first
+      end
+      (exception.backtrace[0].scan(/:(\d+)/).first || ["??"]).first
+    end
+
+    # Tells optparse how to parse the arguments
+    # available for all executables.
+    #
+    # This is meant to be overridden by subclasses
+    # so they can add their own options.
+    #
+    # @param opts [OptionParser]
+    def set_opts(opts)
+      Sass::Util.abstract(this)
+    end
+
+    # Set an option for specifying `Encoding.default_external`.
+    #
+    # @param opts [OptionParser]
+    def encoding_option(opts)
+      encoding_desc = 'Specify the default encoding for input files.'
+      opts.on('-E', '--default-encoding ENCODING', encoding_desc) do |encoding|
+        Encoding.default_external = encoding
+      end
+    end
+
+    # Processes the options set by the command-line arguments. In particular,
+    # sets `@options[:input]` and `@options[:output]` to appropriate IO streams.
+    #
+    # This is meant to be overridden by subclasses
+    # so they can run their respective programs.
+    def process_result
+      input, output = @options[:input], @options[:output]
+      args = @args.dup
+      input ||=
+        begin
+          filename = args.shift
+          @options[:filename] = filename
+          open_file(filename) || $stdin
+        end
+      @options[:output_filename] = args.shift
+      output ||= @options[:output_filename] || $stdout
+      @options[:input], @options[:output] = input, output
+    end
+
+    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.
+    #
+    # @param name [#to_s] A short name for the action being performed.
+    #   Shouldn't be longer than 11 characters.
+    # @param color [Symbol] The name of the color to use for this action.
+    #   Can be `:red`, `:green`, or `:yellow`.
+    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.
+    #
+    # @param args [Array] Passed on to `Kernel.puts`
+    def puts(*args)
+      return if @options[:for_engine][:quiet]
+      Kernel.puts(*args)
+    end
+
+    # Wraps the given string in terminal escapes
+    # causing it to have the given color.
+    # If terminal escapes aren't supported on this platform,
+    # just returns the string instead.
+    #
+    # @param color [Symbol] The name of the color to use.
+    #   Can be `:red`, `:green`, or `:yellow`.
+    # @param str [String] The string to wrap in the given color.
+    # @return [String] The wrapped string.
+    def color(color, str)
+      raise "[BUG] Unrecognized color #{color}" unless COLORS[color]
+
+      # Almost any real Unix terminal will support color,
+      # 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?
+      "\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
+
+    def open_file(filename, flag = 'r')
+      return if filename.nil?
+      flag = 'wb' if @options[:unix_newlines] && flag == 'w'
+      file = File.open(filename, flag)
+      return file unless block_given?
+      yield file
+      file.close
+    end
+
+    def handle_load_error(err)
+      dep = err.message[/^no such file to load -- (.*)/, 1]
+      raise err if @options[:trace] || dep.nil? || dep.empty?
+      $stderr.puts <<MESSAGE
+Required dependency #{dep} not found!
+    Run "gem install #{dep}" to get it.
+  Use --trace for backtrace.
+MESSAGE
+      exit 1
+    end
+  end
+end