sass 3.2.7 → 3.3.0.rc.1

data/lib/sass/selector.rb

@@ -21,8 +21,6 @@ module Sass
     # The base used for calculating selector specificity. The spec says this
     # should be "sufficiently high"; it's extremely unlikely that any single
     # selector sequence will contain 1,000 simple selectors.
-    #
-    # @type [Fixnum]
     SPECIFICITY_BASE = 1_000
 
     # A parent-referencing selector (`&` in Sass).
@@ -47,10 +45,10 @@ module Sass
     class Class < Simple
       # The class name.
       #
-      # @return [Array<String, Sass::Script::Node>]
+      # @return [Array<String, Sass::Script::Tree::Node>]
       attr_reader :name
 
-      # @param name [Array<String, Sass::Script::Node>] The class name
+      # @param name [Array<String, Sass::Script::Tree::Node>] The class name
       def initialize(name)
         @name = name
       end
@@ -70,10 +68,10 @@ module Sass
     class Id < Simple
       # The id name.
       #
-      # @return [Array<String, Sass::Script::Node>]
+      # @return [Array<String, Sass::Script::Tree::Node>]
       attr_reader :name
 
-      # @param name [Array<String, Sass::Script::Node>] The id name
+      # @param name [Array<String, Sass::Script::Tree::Node>] The id name
       def initialize(name)
         @name = name
       end
@@ -88,7 +86,7 @@ module Sass
       #
       # @see Selector#unify
       def unify(sels)
-        return if sels.any? {|sel2| sel2.is_a?(Id) && self.name != sel2.name}
+        return if sels.any? {|sel2| sel2.is_a?(Id) && name != sel2.name}
         super
       end
 
@@ -105,10 +103,10 @@ module Sass
     class Placeholder < Simple
       # The placeholder name.
       #
-      # @return [Array<String, Sass::Script::Node>]
+      # @return [Array<String, Sass::Script::Tree::Node>]
       attr_reader :name
 
-      # @param name [Array<String, Sass::Script::Node>] The placeholder name
+      # @param name [Array<String, Sass::Script::Tree::Node>] The placeholder name
       def initialize(name)
         @name = name
       end
@@ -120,7 +118,7 @@ module Sass
 
       # @see AbstractSequence#specificity
       def specificity
-        0
+        SPECIFICITY_BASE
       end
     end
 
@@ -131,10 +129,10 @@ module Sass
       # `[""]` means no namespace,
       # `["*"]` means any namespace.
       #
-      # @return [Array<String, Sass::Script::Node>, nil]
+      # @return [Array<String, Sass::Script::Tree::Node>, nil]
       attr_reader :namespace
 
-      # @param namespace [Array<String, Sass::Script::Node>, nil] See \{#namespace}
+      # @param namespace [Array<String, Sass::Script::Tree::Node>, nil] See \{#namespace}
       def initialize(namespace)
         @namespace = namespace
       end
@@ -195,7 +193,7 @@ module Sass
     class Element < Simple
       # The element name.
       #
-      # @return [Array<String, Sass::Script::Node>]
+      # @return [Array<String, Sass::Script::Tree::Node>]
       attr_reader :name
 
       # The selector namespace.
@@ -203,11 +201,11 @@ module Sass
       # `[""]` means no namespace,
       # `["*"]` means any namespace.
       #
-      # @return [Array<String, Sass::Script::Node>, nil]
+      # @return [Array<String, Sass::Script::Tree::Node>, nil]
       attr_reader :namespace
 
-      # @param name [Array<String, Sass::Script::Node>] The element name
-      # @param namespace [Array<String, Sass::Script::Node>, nil] See \{#namespace}
+      # @param name [Array<String, Sass::Script::Tree::Node>] The element name
+      # @param namespace [Array<String, Sass::Script::Tree::Node>, nil] See \{#namespace}
       def initialize(name, namespace)
         @name = name
         @namespace = namespace
@@ -262,10 +260,10 @@ module Sass
     class Interpolation < Simple
       # The script to run.
       #
-      # @return [Sass::Script::Node]
+      # @return [Sass::Script::Tree::Node]
       attr_reader :script
 
-      # @param script [Sass::Script::Node] The script to run
+      # @param script [Sass::Script::Tree::Node] The script to run
       def initialize(script)
         @script = script
       end
@@ -288,7 +286,7 @@ module Sass
     class Attribute < Simple
       # The attribute name.
       #
-      # @return [Array<String, Sass::Script::Node>]
+      # @return [Array<String, Sass::Script::Tree::Node>]
       attr_reader :name
 
       # The attribute namespace.
@@ -296,7 +294,7 @@ module Sass
       # `[""]` means no namespace,
       # `["*"]` means any namespace.
       #
-      # @return [Array<String, Sass::Script::Node>, nil]
+      # @return [Array<String, Sass::Script::Tree::Node>, nil]
       attr_reader :namespace
 
       # The matching operator, e.g. `"="` or `"^="`.
@@ -306,20 +304,23 @@ module Sass
 
       # The right-hand side of the operator.
       #
-      # @return [Array<String, Sass::Script::Node>]
+      # @return [Array<String, Sass::Script::Tree::Node>]
       attr_reader :value
 
       # Flags for the attribute selector (e.g. `i`).
       #
-      # @return [Array<String, Sass::Script::Node>]
+      # @return [Array<String, Sass::Script::Tree::Node>]
       attr_reader :flags
 
-      # @param name [Array<String, Sass::Script::Node>] The attribute name
-      # @param namespace [Array<String, Sass::Script::Node>, nil] See \{#namespace}
+      # @param name [Array<String, Sass::Script::Tree::Node>] The attribute name
+      # @param namespace [Array<String, Sass::Script::Tree::Node>, nil] See \{#namespace}
       # @param operator [String] The matching operator, e.g. `"="` or `"^="`
-      # @param value [Array<String, Sass::Script::Node>] See \{#value}
-      # @param value [Array<String, Sass::Script::Node>] See \{#flags}
+      # @param value [Array<String, Sass::Script::Tree::Node>] See \{#value}
+      # @param flags [Array<String, Sass::Script::Tree::Node>] See \{#flags}
+      # @comment
+      #   rubocop:disable ParameterLists
       def initialize(name, namespace, operator, value, flags)
+        # rubocop:enable ParameterLists
         @name = name
         @namespace = namespace
         @operator = operator
@@ -346,23 +347,23 @@ module Sass
     # A pseudoclass (e.g. `:visited`) or pseudoelement (e.g. `::first-line`) selector.
     # It can have arguments (e.g. `:nth-child(2n+1)`).
     class Pseudo < Simple
-      # The type of the selector.
-      # `:class` if this is a pseudoclass selector,
-      # `:element` if it's a pseudoelement.
+      # Some psuedo-class-syntax selectors are actually considered
+      # pseudo-elements and must be treated differently. This is a list of such
+      # selectors
       #
-      # @return [Symbol]
-      attr_reader :type
+      # @return [Array<String>]
+      ACTUALLY_ELEMENTS = %w[after before first-line first-letter]
 
-      # Some psuedo-class-syntax selectors (`:after` and `:before)
-      # are actually considered pseudo-elements
-      # and must be at the end of the selector to function properly.
+      # Like \{#type}, but returns the type of selector this looks like, rather
+      # than the type it is semantically. This only differs from type for
+      # selectors in \{ACTUALLY\_ELEMENTS}.
       #
-      # @return [Array<String>]
-      FINAL_SELECTORS = %w[after before]
+      # @return [Symbol]
+      attr_reader :syntactic_type
 
       # The name of the selector.
       #
-      # @return [Array<String, Sass::Script::Node>]
+      # @return [Array<String, Sass::Script::Tree::Node>]
       attr_reader :name
 
       # The argument to the selector,
@@ -372,26 +373,30 @@ module Sass
       # Note that this should not include SassScript nodes
       # after resolution has taken place.
       #
-      # @return [Array<String, Sass::Script::Node>, nil]
+      # @return [Array<String, Sass::Script::Tree::Node>, nil]
       attr_reader :arg
 
       # @param type [Symbol] See \{#type}
-      # @param name [Array<String, Sass::Script::Node>] The name of the selector
-      # @param arg [nil, Array<String, Sass::Script::Node>] The argument to the selector,
+      # @param name [Array<String, Sass::Script::Tree::Node>] The name of the selector
+      # @param arg [nil, Array<String, Sass::Script::Tree::Node>] The argument to the selector,
       #   or nil if no argument was given
       def initialize(type, name, arg)
-        @type = type
+        @syntactic_type = type
         @name = name
         @arg = arg
       end
 
-      def final?
-        type == :class && FINAL_SELECTORS.include?(name.first)
+      # The type of the selector. `:class` if this is a pseudoclass selector,
+      # `:element` if it's a pseudoelement.
+      #
+      # @return [Symbol]
+      def type
+        ACTUALLY_ELEMENTS.include?(name.first) ? :element : syntactic_type
       end
 
       # @see Selector#to_a
       def to_a
-        res = [@type == :class ? ":" : "::"] + @name
+        res = [syntactic_type == :class ? ":" : "::"] + @name
         (res << "(").concat(Sass::Util.strip_string_array(@arg)) << ")" if @arg
         res
       end
@@ -403,9 +408,8 @@ module Sass
       def unify(sels)
         return if type == :element && sels.any? do |sel|
           sel.is_a?(Pseudo) && sel.type == :element &&
-            (sel.name != self.name || sel.arg != self.arg)
+            (sel.name != name || sel.arg != arg)
         end
-        return sels + [self] if final?
         super
       end
 
@@ -428,8 +432,8 @@ module Sass
       # @return [Selector::Sequence]
       attr_reader :selector
 
-      # @param [String] The name of the pseudoclass
-      # @param [Selector::CommaSequence] The selector argument
+      # @param name [String] The name of the pseudoclass
+      # @param selector [Selector::CommaSequence] The selector argument
       def initialize(name, selector)
         @name = name
         @selector = selector

data/lib/sass/source/map.rb

@@ -0,0 +1,211 @@
+require 'pathname'
+
+module Sass::Source
+  class Map
+    # A mapping from one source range to another. Indicates that `input` was
+    # compiled to `output`.
+    #
+    # @!attribute input
+    #   @return [Sass::Source::Range] The source range in the input document.
+    #
+    # @!attribute output
+    #   @return [Sass::Source::Range] The source range in the output document.
+    class Mapping < Struct.new(:input, :output)
+      # @return [String] A string representation of the mapping.
+      def inspect
+        "#{input.inspect} => #{output.inspect}"
+      end
+    end
+
+    # The mapping data ordered by the location in the target.
+    #
+    # @return [Array<Mapping>]
+    attr_reader :data
+
+    def initialize
+      @data = []
+    end
+
+    # Adds a new mapping from one source range to another. Multiple invocations
+    # of this method should have each `output` range come after all previous ranges.
+    #
+    # @param input [Sass::Source::Range]
+    #   The source range in the input document.
+    # @param output [Sass::Source::Range]
+    #   The source range in the output document.
+    def add(input, output)
+      @data.push(Mapping.new(input, output))
+    end
+
+    # Shifts all output source ranges forward one or more lines.
+    #
+    # @param delta [Fixnum] The number of lines to shift the ranges forward.
+    def shift_output_lines(delta)
+      return if delta == 0
+      @data.each do |m|
+        m.output.start_pos.line += delta
+        m.output.end_pos.line += delta
+      end
+    end
+
+    # Shifts any output source ranges that lie on the first line forward one or
+    # more characters on that line.
+    #
+    # @param delta [Fixnum] The number of characters to shift the ranges
+    #   forward.
+    def shift_output_offsets(delta)
+      return if delta == 0
+      @data.each do |m|
+        break if m.output.start_pos.line > 1
+        m.output.start_pos.offset += delta
+        m.output.end_pos.offset += delta if m.output.end_pos.line > 1
+      end
+    end
+
+    # Returns the standard JSON representation of the source map.
+    #
+    # If the `:css_uri` option isn't specified, the `:css_path` and
+    # `:sourcemap_path` options must both be specified. Any options may also be
+    # specified alongside the `:css_uri` option. If `:css_uri` isn't specified,
+    # it will be inferred from `:css_path` and `:sourcemap_path` using the
+    # assumption that the local file system has the same layout as the server.
+    #
+    # If any source stylesheets use the default filesystem importer, sourcemap
+    # generation will fail unless the `:sourcemap_path` option is specified.
+    # The layout of the local file system is assumed to be the same as the
+    # layout of the server for the purposes of linking to source stylesheets
+    # that use the filesystem importer.
+    #
+    # Regardless of which options are passed to this method, source stylesheets
+    # that are imported using a non-default importer will only be linked to in
+    # the source map if their importers implement
+    # \{Sass::Importers::Base#public\_url\}.
+    #
+    # @option options :css_uri [String]
+    #   The publicly-visible URI of the CSS output file.
+    # @option options :css_path [String]
+    #   The local path of the CSS output file.
+    # @option options :sourcemap_path [String]
+    #   The (eventual) local path of the sourcemap file.
+    # @return [String] The JSON string.
+    # @raise [ArgumentError] If neither `:css_uri` nor `:css_path` and
+    #   `:sourcemap_path` are specified.
+    # @comment
+    #   rubocop:disable MethodLength
+    def to_json(options)
+      css_uri, css_path, sourcemap_path =
+        [:css_uri, :css_path, :sourcemap_path].map {|o| options[o]}
+      unless css_uri || (css_path && sourcemap_path)
+        raise ArgumentError.new("Sass::Source::Map#to_json requires either " +
+          "the :css_uri option or both the :css_path and :soucemap_path options.")
+      end
+      css_path &&= Pathname.pwd.join(Pathname.new(css_path)).cleanpath
+      sourcemap_path &&= Pathname.pwd.join(Pathname.new(sourcemap_path)).cleanpath
+      css_uri ||= css_path.relative_path_from(sourcemap_path.dirname).to_s
+
+      result = "{\n"
+      write_json_field(result, "version", "3", true)
+
+      source_uri_to_id = {}
+      id_to_source_uri = {}
+      next_source_id = 0
+      line_data = []
+      segment_data_for_line = []
+      no_public_url = Set.new
+
+      # These track data necessary for the delta coding.
+      previous_target_line = nil
+      previous_target_offset = 1
+      previous_source_line = 1
+      previous_source_offset = 1
+      previous_source_id = 0
+
+      @data.each do |m|
+        file, importer = m.input.file, m.input.importer
+        unless (source_uri = importer && importer.public_url(file))
+          if importer.is_a?(Sass::Importers::Filesystem) && sourcemap_path
+            file_path = Pathname.new(importer.root).join(file)
+            source_uri = file_path.relative_path_from(sourcemap_path.dirname).to_s
+          elsif no_public_url.include?(file)
+            next
+          else
+            no_public_url << file
+            Sass::Util.sass_warn <<WARNING
+WARNING: Couldn't determine public URL for "#{file}" while generating sourcemap.
+  Without a public URL, there's nothing for the source map to link to.
+  Custom importers should define the #public_url method.
+WARNING
+            next
+          end
+        end
+
+        current_source_id = source_uri_to_id[source_uri]
+        unless current_source_id
+          current_source_id = next_source_id
+          next_source_id += 1
+
+          source_uri_to_id[source_uri] = current_source_id
+          id_to_source_uri[current_source_id] = source_uri
+        end
+
+        [
+          [m.input.start_pos, m.output.start_pos],
+          [m.input.end_pos, m.output.end_pos]
+        ].each do |source_pos, target_pos|
+          if previous_target_line != target_pos.line
+            line_data.push(segment_data_for_line.join(",")) unless segment_data_for_line.empty?
+            (target_pos.line - 1 - (previous_target_line || 0)).times {line_data.push("")}
+            previous_target_line = target_pos.line
+            previous_target_offset = 1
+            segment_data_for_line = []
+          end
+
+          # `segment` is a data chunk for a single position mapping.
+          segment = ""
+
+          # Field 1: zero-based starting offset.
+          segment << Sass::Util.encode_vlq(target_pos.offset - previous_target_offset)
+          previous_target_offset = target_pos.offset
+
+          # Field 2: zero-based index into the "sources" list.
+          segment << Sass::Util.encode_vlq(current_source_id - previous_source_id)
+          previous_source_id = current_source_id
+
+          # Field 3: zero-based starting line in the original source.
+          segment << Sass::Util.encode_vlq(source_pos.line - previous_source_line)
+          previous_source_line = source_pos.line
+
+          # Field 4: zero-based starting offset in the original source.
+          segment << Sass::Util.encode_vlq(source_pos.offset - previous_source_offset)
+          previous_source_offset = source_pos.offset
+
+          segment_data_for_line.push(segment)
+
+          previous_target_line = target_pos.line
+        end
+      end
+      line_data.push(segment_data_for_line.join(","))
+      write_json_field(result, "mappings", line_data.join(";"))
+
+      source_names = []
+      (0...next_source_id).each {|id| source_names.push(id_to_source_uri[id].to_s)}
+      write_json_field(result, "sources", source_names)
+      write_json_field(result, "file", css_uri)
+
+      result << "\n}"
+      result
+    end
+    # @comment
+    #   rubocop:enable MethodLength
+
+    private
+
+    def write_json_field(out, name, value, is_first = false)
+      out << (is_first ? "" : ",\n") <<
+        "\"" <<
+        Sass::Util.json_escape_string(name) <<
+        "\": " <<
+        Sass::Util.json_value_of(value)
+    end
+  end
+end

data/lib/sass/source/position.rb

@@ -0,0 +1,39 @@
+module Sass::Source
+  class Position
+    # The one-based line of the document associated with the position.
+    #
+    # @return [Fixnum]
+    attr_accessor :line
+
+    # The one-based offset in the line of the document associated with the
+    # position.
+    #
+    # @return [Fixnum]
+    attr_accessor :offset
+
+    # @param line [Fixnum] The source line
+    # @param offset [Fixnum] The source offset
+    def initialize(line, offset)
+      @line = line
+      @offset = offset
+    end
+
+    # @return [String] A string representation of the source position.
+    def inspect
+      "#{line.inspect}:#{offset.inspect}"
+    end
+
+    # @param str [String] The string to move through.
+    # @return [Position] The source position after proceeding forward through
+    #   `str`.
+    def after(str)
+      newlines = str.count("\n")
+      Position.new(line + newlines,
+        if newlines == 0
+          offset + str.length
+        else
+          str.length - str.rindex("\n") - 1
+        end)
+    end
+  end
+end

data/lib/sass/source/range.rb

@@ -0,0 +1,41 @@
+module Sass::Source
+  class Range
+    # The starting position of the range in the document (inclusive).
+    #
+    # @return [Sass::Source::Position]
+    attr_accessor :start_pos
+
+    # The ending position of the range in the document (exclusive).
+    #
+    # @return [Sass::Source::Position]
+    attr_accessor :end_pos
+
+    # The file in which this source range appears. This can be nil if the file
+    # is unknown or not yet generated.
+    #
+    # @return [String]
+    attr_accessor :file
+
+    # The importer that imported the file in which this source range appears.
+    # This is nil for target ranges.
+    #
+    # @return [Sass::Importers::Base]
+    attr_accessor :importer
+
+    # @param start_pos [Sass::Source::Position] See \{#start_pos}
+    # @param end_pos [Sass::Source::Position] See \{#end_pos}
+    # @param file [String] See \{#file}
+    # @param importer [Sass::Importers::Base] See \{#importer}
+    def initialize(start_pos, end_pos, file, importer = nil)
+      @start_pos = start_pos
+      @end_pos = end_pos
+      @file = file
+      @importer = importer
+    end
+
+    # @return [String] A string representation of the source range.
+    def inspect
+      "(#{start_pos.inspect} to #{end_pos.inspect}#{" in #{@file}" if @file})"
+    end
+  end
+end

data/lib/sass/stack.rb

@@ -0,0 +1,120 @@
+module Sass
+  # A class representing the stack when compiling a Sass file.
+  class Stack
+    # TODO: use this to generate stack information for Sass::SyntaxErrors.
+
+    # A single stack frame.
+    class Frame
+      # The filename of the file in which this stack frame was created.
+      #
+      # @return [String]
+      attr_reader :filename
+
+      # The line number on which this stack frame was created.
+      #
+      # @return [String]
+      attr_reader :line
+
+      # The type of this stack frame. This can be `:import`, `:mixin`, or
+      # `:base`.
+      #
+      # `:base` indicates that this is the bottom-most frame, meaning that it
+      # represents a single line of code rather than a nested context. The stack
+      # will only ever have one base frame, and it will always be the most
+      # deeply-nested frame.
+      #
+      # @return [Symbol?]
+      attr_reader :type
+
+      # The name of the stack frame. For mixin frames, this is the mixin name;
+      # otherwise, it's `nil`.
+      #
+      # @return [String?]
+      attr_reader :name
+
+      def initialize(filename, line, type, name = nil)
+        @filename = filename
+        @line = line
+        @type = type
+        @name = name
+      end
+
+      # Whether this frame represents an import.
+      #
+      # @return [Boolean]
+      def is_import?
+        type == :import
+      end
+
+      # Whether this frame represents a mixin.
+      #
+      # @return [Boolean]
+      def is_mixin?
+        type == :mixin
+      end
+
+      # Whether this is the base frame.
+      #
+      # @return [Boolean]
+      def is_base?
+        type == :base
+      end
+    end
+
+    # The stack frames. The last frame is the most deeply-nested.
+    #
+    # @return [Array<Frame>]
+    attr_reader :frames
+
+    def initialize
+      @frames = []
+    end
+
+    # Pushes a base frame onto the stack.
+    #
+    # @param filename [String] See \{Frame#filename}.
+    # @param line [String] See \{Frame#line}.
+    # @yield [] A block in which the new frame is on the stack.
+    def with_base(filename, line)
+      with_frame(filename, line, :base) {yield}
+    end
+
+    # Pushes an import frame onto the stack.
+    #
+    # @param filename [String] See \{Frame#filename}.
+    # @param line [String] See \{Frame#line}.
+    # @yield [] A block in which the new frame is on the stack.
+    def with_import(filename, line)
+      with_frame(filename, line, :import) {yield}
+    end
+
+    # Pushes a mixin frame onto the stack.
+    #
+    # @param filename [String] See \{Frame#filename}.
+    # @param line [String] See \{Frame#line}.
+    # @param name [String] See \{Frame#name}.
+    # @yield [] A block in which the new frame is on the stack.
+    def with_mixin(filename, line, name)
+      with_frame(filename, line, :mixin, name) {yield}
+    end
+
+    def to_s
+      Sass::Util.enum_with_index(Sass::Util.enum_cons(frames.reverse + [nil], 2)).
+          map do |(frame, caller), i|
+        "#{i == 0 ? "on" : "from"} line #{frame.line}" +
+          " of #{frame.filename || "an unknown file"}" +
+          (caller && caller.name ? ", in `#{caller.name}'" : "")
+      end.join("\n")
+    end
+
+    private
+
+    def with_frame(filename, line, type, name = nil)
+      @frames.pop if @frames.last && @frames.last.type == :base
+      @frames.push(Frame.new(filename, line, type, name))
+      yield
+    ensure
+      @frames.pop unless type == :base && @frames.last && @frames.last.type != :base
+    end
+  end
+end