sass 3.2.19 → 3.4.25

data/lib/sass/script/value/helpers.rb

@@ -0,0 +1,272 @@
+module Sass::Script::Value
+  # Provides helper functions for creating sass values from within ruby methods.
+  # @since `3.3.0`
+  # @comment
+  #   rubocop:disable ModuleLength
+  module Helpers
+    # Construct a Sass Boolean.
+    #
+    # @param value [Object] A ruby object that will be tested for truthiness.
+    # @return [Sass::Script::Value::Bool] whether the ruby value is truthy.
+    def bool(value)
+      Bool.new(value)
+    end
+
+    # Construct a Sass Color from a hex color string.
+    #
+    # @param value [::String] A string representing a hex color.
+    #   The leading hash ("#") is optional.
+    # @param alpha [::Number] The alpha channel. A number between 0 and 1.
+    # @return [Sass::Script::Value::Color] the color object
+    def hex_color(value, alpha = nil)
+      Color.from_hex(value, alpha)
+    end
+
+    # Construct a Sass Color from hsl values.
+    #
+    # @param hue [::Number] The hue of the color in degrees.
+    #   A non-negative number, usually less than 360.
+    # @param saturation [::Number] The saturation of the color.
+    #   Must be between 0 and 100 inclusive.
+    # @param lightness [::Number] The lightness of the color.
+    #   Must be between 0 and 100 inclusive.
+    # @param alpha [::Number] The alpha channel. A number between 0 and 1.
+    #
+    # @return [Sass::Script::Value::Color] the color object
+    def hsl_color(hue, saturation, lightness, alpha = nil)
+      attrs = {:hue => hue, :saturation => saturation, :lightness => lightness}
+      attrs[:alpha] = alpha if alpha
+      Color.new(attrs)
+    end
+
+    # Construct a Sass Color from rgb values.
+    #
+    # @param red [::Number] The red component. Must be between 0 and 255 inclusive.
+    # @param green [::Number] The green component. Must be between 0 and 255 inclusive.
+    # @param blue [::Number] The blue component. Must be between 0 and 255 inclusive.
+    # @param alpha [::Number] The alpha channel. A number between 0 and 1.
+    #
+    # @return [Sass::Script::Value::Color] the color object
+    def rgb_color(red, green, blue, alpha = nil)
+      attrs = {:red => red, :green => green, :blue => blue}
+      attrs[:alpha] = alpha if alpha
+      Color.new(attrs)
+    end
+
+    # Construct a Sass Number from a ruby number.
+    #
+    # @param number [::Number] A numeric value.
+    # @param unit_string [::String] A unit string of the form
+    #   `numeral_unit1 * numeral_unit2 ... / denominator_unit1 * denominator_unit2 ...`
+    #   this is the same format that is returned by
+    #   {Sass::Script::Value::Number#unit_str the `unit_str` method}
+    #
+    # @see Sass::Script::Value::Number#unit_str
+    #
+    # @return [Sass::Script::Value::Number] The sass number representing the given ruby number.
+    def number(number, unit_string = nil)
+      Number.new(number, *parse_unit_string(unit_string))
+    end
+
+    # @overload list(*elements, separator)
+    #   Create a space-separated list from the arguments given.
+    #   @param elements [Array<Sass::Script::Value::Base>] Each argument will be a list element.
+    #   @param separator [Symbol] Either :space or :comma.
+    #   @return [Sass::Script::Value::List] The space separated list.
+    #
+    # @overload list(array, separator)
+    #   Create a space-separated list from the array given.
+    #   @param array [Array<Sass::Script::Value::Base>] A ruby array of Sass values
+    #     to make into a list.
+    #   @return [Sass::Script::Value::List] The space separated list.
+    def list(*elements)
+      unless elements.last.is_a?(Symbol)
+        raise ArgumentError.new("A list type of :space or :comma must be specified.")
+      end
+      separator = elements.pop
+      if elements.size == 1 && elements.first.is_a?(Array)
+        elements = elements.first
+      end
+      Sass::Script::Value::List.new(elements, separator)
+    end
+
+    # Construct a Sass map.
+    #
+    # @param hash [Hash<Sass::Script::Value::Base,
+    #   Sass::Script::Value::Base>] A Ruby map to convert to a Sass map.
+    # @return [Sass::Script::Value::Map] The map.
+    def map(hash)
+      Map.new(hash)
+    end
+
+    # Create a sass null value.
+    #
+    # @return [Sass::Script::Value::Null]
+    def null
+      Sass::Script::Value::Null.new
+    end
+
+    # Create a quoted string.
+    #
+    # @param str [::String] A ruby string.
+    # @return [Sass::Script::Value::String] A quoted string.
+    def quoted_string(str)
+      Sass::Script::String.new(str, :string)
+    end
+
+    # Create an unquoted string.
+    #
+    # @param str [::String] A ruby string.
+    # @return [Sass::Script::Value::String] An unquoted string.
+    def unquoted_string(str)
+      Sass::Script::String.new(str, :identifier)
+    end
+    alias_method :identifier, :unquoted_string
+
+    # Parses a user-provided selector.
+    #
+    # @param value [Sass::Script::Value::String, Sass::Script::Value::List]
+    #   The selector to parse. This can be either a string, a list of
+    #   strings, or a list of lists of strings as returned by `&`.
+    # @param name [Symbol, nil]
+    #   If provided, the name of the selector argument. This is used
+    #   for error reporting.
+    # @param allow_parent_ref [Boolean]
+    #   Whether the parsed selector should allow parent references.
+    # @return [Sass::Selector::CommaSequence] The parsed selector.
+    # @throw [ArgumentError] if the parse failed for any reason.
+    def parse_selector(value, name = nil, allow_parent_ref = false)
+      str = normalize_selector(value, name)
+      begin
+        Sass::SCSS::StaticParser.new(str, nil, nil, 1, 1, allow_parent_ref).parse_selector
+      rescue Sass::SyntaxError => e
+        err = "#{value.inspect} is not a valid selector: #{e}"
+        err = "$#{name.to_s.tr('_', '-')}: #{err}" if name
+        raise ArgumentError.new(err)
+      end
+    end
+
+    # Parses a user-provided complex selector.
+    #
+    # A complex selector can contain combinators but cannot contain commas.
+    #
+    # @param value [Sass::Script::Value::String, Sass::Script::Value::List]
+    #   The selector to parse. This can be either a string or a list of
+    #   strings.
+    # @param name [Symbol, nil]
+    #   If provided, the name of the selector argument. This is used
+    #   for error reporting.
+    # @param allow_parent_ref [Boolean]
+    #   Whether the parsed selector should allow parent references.
+    # @return [Sass::Selector::Sequence] The parsed selector.
+    # @throw [ArgumentError] if the parse failed for any reason.
+    def parse_complex_selector(value, name = nil, allow_parent_ref = false)
+      selector = parse_selector(value, name, allow_parent_ref)
+      return seq if selector.members.length == 1
+
+      err = "#{value.inspect} is not a complex selector"
+      err = "$#{name.to_s.tr('_', '-')}: #{err}" if name
+      raise ArgumentError.new(err)
+    end
+
+    # Parses a user-provided compound selector.
+    #
+    # A compound selector cannot contain combinators or commas.
+    #
+    # @param value [Sass::Script::Value::String] The selector to parse.
+    # @param name [Symbol, nil]
+    #   If provided, the name of the selector argument. This is used
+    #   for error reporting.
+    # @param allow_parent_ref [Boolean]
+    #   Whether the parsed selector should allow parent references.
+    # @return [Sass::Selector::SimpleSequence] The parsed selector.
+    # @throw [ArgumentError] if the parse failed for any reason.
+    def parse_compound_selector(value, name = nil, allow_parent_ref = false)
+      assert_type value, :String, name
+      selector = parse_selector(value, name, allow_parent_ref)
+      seq = selector.members.first
+      sseq = seq.members.first
+      if selector.members.length == 1 && seq.members.length == 1 &&
+          sseq.is_a?(Sass::Selector::SimpleSequence)
+        return sseq
+      end
+
+      err = "#{value.inspect} is not a compound selector"
+      err = "$#{name.to_s.tr('_', '-')}: #{err}" if name
+      raise ArgumentError.new(err)
+    end
+
+    # Returns true when the literal is a string containing a calc()
+    #
+    # @param literal [Sass::Script::Value::Base] The value to check
+    # @return boolean
+    def calc?(literal)
+      literal.is_a?(Sass::Script::Value::String) && literal.value =~ /calc\(/
+    end
+
+    private
+
+    # Converts a user-provided selector into string form or throws an
+    # ArgumentError if it's in an invalid format.
+    def normalize_selector(value, name)
+      if (str = selector_to_str(value))
+        return str
+      end
+
+      err = "#{value.inspect} is not a valid selector: it must be a string,\n" +
+        "a list of strings, or a list of lists of strings"
+      err = "$#{name.to_s.tr('_', '-')}: #{err}" if name
+      raise ArgumentError.new(err)
+    end
+
+    # Converts a user-provided selector into string form or returns
+    # `nil` if it's in an invalid format.
+    def selector_to_str(value)
+      return value.value if value.is_a?(Sass::Script::String)
+      return unless value.is_a?(Sass::Script::List)
+
+      if value.separator == :comma
+        return value.to_a.map do |complex|
+          next complex.value if complex.is_a?(Sass::Script::String)
+          return unless complex.is_a?(Sass::Script::List) && complex.separator == :space
+          return unless (str = selector_to_str(complex))
+          str
+        end.join(', ')
+      end
+
+      value.to_a.map do |compound|
+        return unless compound.is_a?(Sass::Script::String)
+        compound.value
+      end.join(' ')
+    end
+
+    # @private
+    VALID_UNIT = /#{Sass::SCSS::RX::NMSTART}#{Sass::SCSS::RX::NMCHAR}|%*/
+
+    # @example
+    #   parse_unit_string("em*px/in*%") # => [["em", "px], ["in", "%"]]
+    #
+    # @param unit_string [String] A string adhering to the output of a number with complex
+    #   units. E.g. "em*px/in*%"
+    # @return [Array<Array<String>>] A list of numerator units and a list of denominator units.
+    def parse_unit_string(unit_string)
+      denominator_units = numerator_units = Sass::Script::Value::Number::NO_UNITS
+      return numerator_units, denominator_units unless unit_string && unit_string.length > 0
+      num_over_denominator = unit_string.split(%r{ */ *})
+      unless (1..2).include?(num_over_denominator.size)
+        raise ArgumentError.new("Malformed unit string: #{unit_string}")
+      end
+      numerator_units = num_over_denominator[0].split(/ *\* */)
+      denominator_units = (num_over_denominator[1] || "").split(/ *\* */)
+      [[numerator_units, "numerator"], [denominator_units, "denominator"]].each do |units, name|
+        if unit_string =~ %r{/} && units.size == 0
+          raise ArgumentError.new("Malformed unit string: #{unit_string}")
+        end
+        if units.any? {|unit| unit !~ VALID_UNIT}
+          raise ArgumentError.new("Malformed #{name} in unit string: #{unit_string}")
+        end
+      end
+      [numerator_units, denominator_units]
+    end
+  end
+end

data/lib/sass/script/value/list.rb

@@ -0,0 +1,113 @@
+module Sass::Script::Value
+  # A SassScript object representing a CSS list.
+  # This includes both comma-separated lists and space-separated lists.
+  class List < Base
+    # The Ruby array containing the contents of the list.
+    #
+    # @return [Array<Value>]
+    attr_reader :value
+    alias_method :to_a, :value
+
+    # The operator separating the values of the list.
+    # Either `:comma` or `:space`.
+    #
+    # @return [Symbol]
+    attr_reader :separator
+
+    # Creates a new list.
+    #
+    # @param value [Array<Value>] See \{#value}
+    # @param separator [Symbol] See \{#separator}
+    def initialize(value, separator)
+      super(value)
+      @separator = separator
+    end
+
+    # @see Value#options=
+    def options=(options)
+      super
+      value.each {|v| v.options = options}
+    end
+
+    # @see Value#eq
+    def eq(other)
+      Sass::Script::Value::Bool.new(
+        other.is_a?(List) && value == other.value &&
+        separator == other.separator)
+    end
+
+    def hash
+      @hash ||= [value, separator].hash
+    end
+
+    # @see Value#to_s
+    def to_s(opts = {})
+      raise Sass::SyntaxError.new("() isn't a valid CSS value.") if value.empty?
+      value.
+        reject {|e| e.is_a?(Null) || e.is_a?(List) && e.value.empty?}.
+        map {|e| e.to_s(opts)}.join(sep_str)
+    end
+
+    # @see Value#to_sass
+    def to_sass(opts = {})
+      return "()" if value.empty?
+      members = value.map do |v|
+        if element_needs_parens?(v)
+          "(#{v.to_sass(opts)})"
+        else
+          v.to_sass(opts)
+        end
+      end
+      return "(#{members.first},)" if members.length == 1 && separator == :comma
+      members.join(sep_str(nil))
+    end
+
+    # @see Value#to_h
+    def to_h
+      return Sass::Util.ordered_hash if value.empty?
+      super
+    end
+
+    # @see Value#inspect
+    def inspect
+      "(#{value.map {|e| e.inspect}.join(sep_str(nil))})"
+    end
+
+    # Asserts an index is within the list.
+    #
+    # @private
+    #
+    # @param list [Sass::Script::Value::List] The list for which the index should be checked.
+    # @param n [Sass::Script::Value::Number] The index being checked.
+    def self.assert_valid_index(list, n)
+      if !n.int? || n.to_i == 0
+        raise ArgumentError.new("List index #{n} must be a non-zero integer")
+      elsif list.to_a.size == 0
+        raise ArgumentError.new("List index is #{n} but list has no items")
+      elsif n.to_i.abs > (size = list.to_a.size)
+        raise ArgumentError.new(
+          "List index is #{n} but list is only #{size} item#{'s' if size != 1} long")
+      end
+    end
+
+    private
+
+    def element_needs_parens?(element)
+      if element.is_a?(List)
+        return false if element.value.empty?
+        precedence = Sass::Script::Parser.precedence_of(separator)
+        return Sass::Script::Parser.precedence_of(element.separator) <= precedence
+      end
+
+      return false unless separator == :space
+      return false unless element.is_a?(Sass::Script::Tree::UnaryOperation)
+      element.operator == :minus || element.operator == :plus
+    end
+
+    def sep_str(opts = options)
+      return ' ' if separator == :space
+      return ',' if opts && opts[:style] == :compressed
+      ', '
+    end
+  end
+end

data/lib/sass/script/value/map.rb

@@ -0,0 +1,70 @@
+module Sass::Script::Value
+  # A SassScript object representing a map from keys to values. Both keys and
+  # values can be any SassScript object.
+  class Map < Base
+    # The Ruby hash containing the contents of this map.
+    #
+    # @return [Hash<Node, Node>]
+    attr_reader :value
+    alias_method :to_h, :value
+
+    # Creates a new map.
+    #
+    # @param hash [Hash<Node, Node>]
+    def initialize(hash)
+      super(Sass::Util.ordered_hash(hash))
+    end
+
+    # @see Value#options=
+    def options=(options)
+      super
+      value.each do |k, v|
+        k.options = options
+        v.options = options
+      end
+    end
+
+    # @see Value#separator
+    def separator
+      :comma unless value.empty?
+    end
+
+    # @see Value#to_a
+    def to_a
+      value.map do |k, v|
+        list = List.new([k, v], :space)
+        list.options = options
+        list
+      end
+    end
+
+    # @see Value#eq
+    def eq(other)
+      Bool.new(other.is_a?(Map) && value == other.value)
+    end
+
+    def hash
+      @hash ||= value.hash
+    end
+
+    # @see Value#to_s
+    def to_s(opts = {})
+      raise Sass::SyntaxError.new("#{inspect} isn't a valid CSS value.")
+    end
+
+    def to_sass(opts = {})
+      return "()" if value.empty?
+
+      to_sass = lambda do |value|
+        if value.is_a?(List) && value.separator == :comma
+          "(#{value.to_sass(opts)})"
+        else
+          value.to_sass(opts)
+        end
+      end
+
+      "(#{value.map {|(k, v)| "#{to_sass[k]}: #{to_sass[v]}"}.join(', ')})"
+    end
+    alias_method :inspect, :to_sass
+  end
+end

data/lib/sass/script/{null.rb → value/null.rb}

@@ -1,11 +1,18 @@
-require 'sass/script/literal'
-
-module Sass::Script
+module Sass::Script::Value
   # A SassScript object representing a null value.
-  class Null < Literal
-    # Creates a new null literal.
-    def initialize
-      super nil
+  class Null < Base
+    # The null value in SassScript.
+    #
+    # This is assigned before new is overridden below so that we use the default implementation.
+    NULL = new(nil)
+
+    # We override object creation so that users of the core API
+    # will not need to know that null is a specific constant.
+    #
+    # @private
+    # @return [Null] the {NULL} constant.
+    def self.new
+      NULL
     end
 
     # @return [Boolean] `false` (the Ruby boolean value)