sass4 4.0.0

data/lib/sass/selector.rb

@@ -0,0 +1,327 @@
+require 'sass/selector/simple'
+require 'sass/selector/abstract_sequence'
+require 'sass/selector/comma_sequence'
+require 'sass/selector/pseudo'
+require 'sass/selector/sequence'
+require 'sass/selector/simple_sequence'
+
+module Sass
+  # A namespace for nodes in the parse tree for selectors.
+  #
+  # {CommaSequence} is the toplevel selector,
+  # representing a comma-separated sequence of {Sequence}s,
+  # such as `foo bar, baz bang`.
+  # {Sequence} is the next level,
+  # representing {SimpleSequence}s separated by combinators (e.g. descendant or child),
+  # such as `foo bar` or `foo > bar baz`.
+  # {SimpleSequence} is a sequence of selectors that all apply to a single element,
+  # such as `foo.bar[attr=val]`.
+  # Finally, {Simple} is the superclass of the simplest selectors,
+  # such as `.foo` or `#bar`.
+  module Selector
+    # 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.
+    SPECIFICITY_BASE = 1_000
+
+    # A parent-referencing selector (`&` in Sass).
+    # The function of this is to be replaced by the parent selector
+    # in the nested hierarchy.
+    class Parent < Simple
+      # The identifier following the `&`. `nil` indicates no suffix.
+      #
+      # @return [String, nil]
+      attr_reader :suffix
+
+      # @param name [String, nil] See \{#suffix}
+      def initialize(suffix = nil)
+        @suffix = suffix
+      end
+
+      # @see Selector#to_s
+      def to_s(opts = {})
+        "&" + (@suffix || '')
+      end
+
+      # Always raises an exception.
+      #
+      # @raise [Sass::SyntaxError] Parent selectors should be resolved before unification
+      # @see Selector#unify
+      def unify(sels)
+        raise Sass::SyntaxError.new("[BUG] Cannot unify parent selectors.")
+      end
+    end
+
+    # A class selector (e.g. `.foo`).
+    class Class < Simple
+      # The class name.
+      #
+      # @return [String]
+      attr_reader :name
+
+      # @param name [String] The class name
+      def initialize(name)
+        @name = name
+      end
+
+      # @see Selector#to_s
+      def to_s(opts = {})
+        "." + @name
+      end
+
+      # @see AbstractSequence#specificity
+      def specificity
+        SPECIFICITY_BASE
+      end
+    end
+
+    # An id selector (e.g. `#foo`).
+    class Id < Simple
+      # The id name.
+      #
+      # @return [String]
+      attr_reader :name
+
+      # @param name [String] The id name
+      def initialize(name)
+        @name = name
+      end
+
+      def unique?
+        true
+      end
+
+      # @see Selector#to_s
+      def to_s(opts = {})
+        "#" + @name
+      end
+
+      # Returns `nil` if `sels` contains an {Id} selector
+      # with a different name than this one.
+      #
+      # @see Selector#unify
+      def unify(sels)
+        return if sels.any? {|sel2| sel2.is_a?(Id) && name != sel2.name}
+        super
+      end
+
+      # @see AbstractSequence#specificity
+      def specificity
+        SPECIFICITY_BASE**2
+      end
+    end
+
+    # A placeholder selector (e.g. `%foo`).
+    # This exists to be replaced via `@extend`.
+    # Rulesets using this selector will not be printed, but can be extended.
+    # Otherwise, this acts just like a class selector.
+    class Placeholder < Simple
+      # The placeholder name.
+      #
+      # @return [String]
+      attr_reader :name
+
+      # @param name [String] The placeholder name
+      def initialize(name)
+        @name = name
+      end
+
+      # @see Selector#to_s
+      def to_s(opts = {})
+        "%" + @name
+      end
+
+      # @see AbstractSequence#specificity
+      def specificity
+        SPECIFICITY_BASE
+      end
+    end
+
+    # A universal selector (`*` in CSS).
+    class Universal < Simple
+      # The selector namespace. `nil` means the default namespace, `""` means no
+      # namespace, `"*"` means any namespace.
+      #
+      # @return [String, nil]
+      attr_reader :namespace
+
+      # @param namespace [String, nil] See \{#namespace}
+      def initialize(namespace)
+        @namespace = namespace
+      end
+
+      # @see Selector#to_s
+      def to_s(opts = {})
+        @namespace ? "#{@namespace}|*" : "*"
+      end
+
+      # Unification of a universal selector is somewhat complicated,
+      # especially when a namespace is specified.
+      # If there is no namespace specified
+      # or any namespace is specified (namespace `"*"`),
+      # then `sel` is returned without change
+      # (unless it's empty, in which case `"*"` is required).
+      #
+      # If a namespace is specified
+      # but `sel` does not specify a namespace,
+      # then the given namespace is applied to `sel`,
+      # either by adding this {Universal} selector
+      # or applying this namespace to an existing {Element} selector.
+      #
+      # If both this selector *and* `sel` specify namespaces,
+      # those namespaces are unified via {Simple#unify_namespaces}
+      # and the unified namespace is used, if possible.
+      #
+      # @todo There are lots of cases that this documentation specifies;
+      #   make sure we thoroughly test **all of them**.
+      # @todo Keep track of whether a default namespace has been declared
+      #   and handle namespace-unspecified selectors accordingly.
+      # @todo If any branch of a CommaSequence ends up being just `"*"`,
+      #   then all other branches should be eliminated
+      #
+      # @see Selector#unify
+      def unify(sels)
+        name =
+          case sels.first
+          when Universal; :universal
+          when Element; sels.first.name
+          else
+            return [self] + sels unless namespace.nil? || namespace == '*'
+            return sels unless sels.empty?
+            return [self]
+          end
+
+        ns, accept = unify_namespaces(namespace, sels.first.namespace)
+        return unless accept
+        [name == :universal ? Universal.new(ns) : Element.new(name, ns)] + sels[1..-1]
+      end
+
+      # @see AbstractSequence#specificity
+      def specificity
+        0
+      end
+    end
+
+    # An element selector (e.g. `h1`).
+    class Element < Simple
+      # The element name.
+      #
+      # @return [String]
+      attr_reader :name
+
+      # The selector namespace. `nil` means the default namespace, `""` means no
+      # namespace, `"*"` means any namespace.
+      #
+      # @return [String, nil]
+      attr_reader :namespace
+
+      # @param name [String] The element name
+      # @param namespace [String, nil] See \{#namespace}
+      def initialize(name, namespace)
+        @name = name
+        @namespace = namespace
+      end
+
+      # @see Selector#to_s
+      def to_s(opts = {})
+        @namespace ? "#{@namespace}|#{@name}" : @name
+      end
+
+      # Unification of an element selector is somewhat complicated,
+      # especially when a namespace is specified.
+      # First, if `sel` contains another {Element} with a different \{#name},
+      # then the selectors can't be unified and `nil` is returned.
+      #
+      # Otherwise, if `sel` doesn't specify a namespace,
+      # or it specifies any namespace (via `"*"`),
+      # then it's returned with this element selector
+      # (e.g. `.foo` becomes `a.foo` or `svg|a.foo`).
+      # Similarly, if this selector doesn't specify a namespace,
+      # the namespace from `sel` is used.
+      #
+      # If both this selector *and* `sel` specify namespaces,
+      # those namespaces are unified via {Simple#unify_namespaces}
+      # and the unified namespace is used, if possible.
+      #
+      # @todo There are lots of cases that this documentation specifies;
+      #   make sure we thoroughly test **all of them**.
+      # @todo Keep track of whether a default namespace has been declared
+      #   and handle namespace-unspecified selectors accordingly.
+      #
+      # @see Selector#unify
+      def unify(sels)
+        case sels.first
+        when Universal;
+        when Element; return unless name == sels.first.name
+        else return [self] + sels
+        end
+
+        ns, accept = unify_namespaces(namespace, sels.first.namespace)
+        return unless accept
+        [Element.new(name, ns)] + sels[1..-1]
+      end
+
+      # @see AbstractSequence#specificity
+      def specificity
+        1
+      end
+    end
+
+    # An attribute selector (e.g. `[href^="http://"]`).
+    class Attribute < Simple
+      # The attribute name.
+      #
+      # @return [Array<String, Sass::Script::Tree::Node>]
+      attr_reader :name
+
+      # The attribute namespace. `nil` means the default namespace, `""` means
+      # no namespace, `"*"` means any namespace.
+      #
+      # @return [String, nil]
+      attr_reader :namespace
+
+      # The matching operator, e.g. `"="` or `"^="`.
+      #
+      # @return [String]
+      attr_reader :operator
+
+      # The right-hand side of the operator.
+      #
+      # @return [String]
+      attr_reader :value
+
+      # Flags for the attribute selector (e.g. `i`).
+      #
+      # @return [String]
+      attr_reader :flags
+
+      # @param name [String] The attribute name
+      # @param namespace [String, nil] See \{#namespace}
+      # @param operator [String] The matching operator, e.g. `"="` or `"^="`
+      # @param value [String] See \{#value}
+      # @param flags [String] See \{#flags}
+      def initialize(name, namespace, operator, value, flags)
+        @name = name
+        @namespace = namespace
+        @operator = operator
+        @value = value
+        @flags = flags
+      end
+
+      # @see Selector#to_s
+      def to_s(opts = {})
+        res = "["
+        res << @namespace << "|" if @namespace
+        res << @name
+        res << @operator << @value if @value
+        res << " " << @flags if @flags
+        res << "]"
+      end
+
+      # @see AbstractSequence#specificity
+      def specificity
+        SPECIFICITY_BASE
+      end
+    end
+  end
+end

data/lib/sass/shared.rb

@@ -0,0 +1,76 @@
+module Sass
+  # This module contains functionality that's shared between Haml and Sass.
+  module Shared
+    extend self
+
+    # Scans through a string looking for the interoplation-opening `#{`
+    # and, when it's found, yields the scanner to the calling code
+    # so it can handle it properly.
+    #
+    # The scanner will have any backslashes immediately in front of the `#{`
+    # as the second capture group (`scan[2]`),
+    # and the text prior to that as the first (`scan[1]`).
+    #
+    # @yieldparam scan [StringScanner] The scanner scanning through the string
+    # @return [String] The text remaining in the scanner after all `#{`s have been processed
+    def handle_interpolation(str)
+      scan = Sass::Util::MultibyteStringScanner.new(str)
+      yield scan while scan.scan(/(.*?)(\\*)\#\{/m)
+      scan.rest
+    end
+
+    # Moves a scanner through a balanced pair of characters.
+    # For example:
+    #
+    #     Foo (Bar (Baz bang) bop) (Bang (bop bip))
+    #     ^                       ^
+    #     from                    to
+    #
+    # @param scanner [StringScanner] The string scanner to move
+    # @param start [Character] The character opening the balanced pair.
+    #   A `Fixnum` in 1.8, a `String` in 1.9
+    # @param finish [Character] The character closing the balanced pair.
+    #   A `Fixnum` in 1.8, a `String` in 1.9
+    # @param count [Integer] The number of opening characters matched
+    #   before calling this method
+    # @return [(String, String)] The string matched within the balanced pair
+    #   and the rest of the string.
+    #   `["Foo (Bar (Baz bang) bop)", " (Bang (bop bip))"]` in the example above.
+    def balance(scanner, start, finish, count = 0)
+      str = ''
+      scanner = Sass::Util::MultibyteStringScanner.new(scanner) unless scanner.is_a? StringScanner
+      regexp = Regexp.new("(.*?)[\\#{start.chr}\\#{finish.chr}]", Regexp::MULTILINE)
+      while scanner.scan(regexp)
+        str << scanner.matched
+        count += 1 if scanner.matched[-1] == start
+        count -= 1 if scanner.matched[-1] == finish
+        return [str, scanner.rest] if count == 0
+      end
+    end
+
+    # Formats a string for use in error messages about indentation.
+    #
+    # @param indentation [String] The string used for indentation
+    # @param was [Boolean] Whether or not to add `"was"` or `"were"`
+    #   (depending on how many characters were in `indentation`)
+    # @return [String] The name of the indentation (e.g. `"12 spaces"`, `"1 tab"`)
+    def human_indentation(indentation, was = false)
+      if !indentation.include?(?\t)
+        noun = 'space'
+      elsif !indentation.include?(?\s)
+        noun = 'tab'
+      else
+        return indentation.inspect + (was ? ' was' : '')
+      end
+
+      singular = indentation.length == 1
+      if was
+        was = singular ? ' was' : ' were'
+      else
+        was = ''
+      end
+
+      "#{indentation.length} #{noun}#{'s' unless singular}#{was}"
+    end
+  end
+end

data/lib/sass/source/map.rb

@@ -0,0 +1,209 @@
+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 [Integer] 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 [Integer] 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.
+    #
+    # 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.
+    # @option options :type [Symbol]
+    #   `:auto` (default),  `:file`, or `:inline`.
+    # @return [String] The JSON string.
+    # @raise [ArgumentError] If neither `:css_uri` nor `:css_path` and
+    #   `:sourcemap_path` are specified.
+    def to_json(options)
+      css_uri, css_path, sourcemap_path =
+        options[:css_uri], options[:css_path], options[:sourcemap_path]
+      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 &&= Sass::Util.pathname(File.absolute_path(css_path))
+      sourcemap_path &&= Sass::Util.pathname(File.absolute_path(sourcemap_path))
+      css_uri ||= Sass::Util.file_uri_from_path(
+        Sass::Util.relative_path_from(css_path, sourcemap_path.dirname))
+
+      result = "{\n"
+      write_json_field(result, "version", 3, true)
+
+      source_uri_to_id = {}
+      id_to_source_uri = {}
+      id_to_contents = {} if options[:type] == :inline
+      next_source_id = 0
+      line_data = []
+      segment_data_for_line = []
+
+      # 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
+
+        next unless importer
+
+        if options[:type] == :inline
+          source_uri = file
+        else
+          sourcemap_dir = sourcemap_path && sourcemap_path.dirname.to_s
+          sourcemap_dir = nil if options[:type] == :file
+          source_uri = importer.public_url(file, sourcemap_dir)
+          next unless source_uri
+        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
+
+          if options[:type] == :inline
+            id_to_contents[current_source_id] =
+              importer.find(file, {}).instance_variable_get('@template')
+          end
+        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)
+
+      if options[:type] == :inline
+        write_json_field(result, "sourcesContent",
+          (0...next_source_id).map {|id| id_to_contents[id]})
+      end
+
+      write_json_field(result, "names", [])
+      write_json_field(result, "file", css_uri)
+
+      result << "\n}"
+      result
+    end
+
+    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 [Integer]
+    attr_accessor :line
+
+    # The one-based offset in the line of the document associated with the
+    # position.
+    #
+    # @return [Integer]
+    attr_accessor :offset
+
+    # @param line [Integer] The source line
+    # @param offset [Integer] 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