Module: Sass::Script::Value::Helpers

Included in:
Functions::EvaluationContext
Defined in:
lib/sass/script/value/helpers.rb

Overview

Provides helper functions for creating sass values from within ruby methods.

Since:

  • 3.3.0

Instance Method Summary collapse

Instance Method Details

#bool(value) ⇒ Sass::Script::Value::Bool

Construct a Sass Boolean.

Parameters:

  • value (Object) —

    A ruby object that will be tested for truthiness.

Returns:

Since:

  • 3.3.0



9
10
11
 
# File 'lib/sass/script/value/helpers.rb', line 9

def bool(value)
  Bool.new(value)
end

#calc?(literal) ⇒ Boolean

Returns true when the literal is a string containing a calc().

Use #special_number? in preference to this.

Parameters:

Returns:

  • (Boolean) —

    Boolean

Since:

  • 3.3.0



249
250
251
 
# File 'lib/sass/script/value/helpers.rb', line 249

def calc?(literal)
  literal.is_a?(Sass::Script::Value::String) && literal.value =~ /calc\(/
end

#format_color_function(function_name, list) ⇒ Sass::Script::Value::String

Formats a CSS Color Level 4 function call with proper slash separator handling. Used for functions like rgb(), hsl() that support space-separated and slash-separated syntax.

Parameters:

Returns:

Since:

  • 3.3.0



139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
 
# File 'lib/sass/script/value/helpers.rb', line 139

def format_color_function(function_name, list)
  # Check if this is a space-separated list with a slash-separated alpha component
  if list.is_a?(Sass::Script::Value::List) && 
     list.separator == :space && 
     list.value.length == 2
    
    rgb_or_hsl = list.value[0]
    alpha_part = list.value[1]
    
    # Check if alpha part is a slash-separated list
    if alpha_part.is_a?(Sass::Script::Value::List) && 
       alpha_part.separator == :slash && 
       alpha_part.value.length == 1
      
      # Format: rgb(255 128 0 / 0.5)
      rgb_str = if rgb_or_hsl.is_a?(Sass::Script::Value::List)
                  rgb_or_hsl.value.map(&:to_s).join(' ')
                else
                  rgb_or_hsl.to_s
                end
      
      alpha_str = alpha_part.value[0].to_s
      
      return unquoted_string("#{function_name}(#{rgb_str} / #{alpha_str})")
    end
  end
  
  # Default formatting
  unquoted_string("#{function_name}(#{list})")
end

#hex_color(value, alpha = nil) ⇒ Sass::Script::Value::Color

Construct a Sass Color from a hex color string.

Parameters:

  • value (::String) —

    A string representing a hex color. The leading hash ("#") is optional.

  • alpha (::Number) (defaults to: nil) —

    The alpha channel. A number between 0 and 1.

Returns:

Since:

  • 3.3.0



19
20
21
 
# File 'lib/sass/script/value/helpers.rb', line 19

def hex_color(value, alpha = nil)
  Color.from_hex(value, alpha)
end

#hsl_color(hue, saturation, lightness, alpha = nil) ⇒ Sass::Script::Value::Color

Construct a Sass Color from hsl values.

Parameters:

  • hue (::Number) —

    The hue of the color in degrees. A non-negative number, usually less than 360.

  • saturation (::Number) —

    The saturation of the color. Must be between 0 and 100 inclusive.

  • lightness (::Number) —

    The lightness of the color. Must be between 0 and 100 inclusive.

  • alpha (::Number) (defaults to: nil) —

    The alpha channel. A number between 0 and 1.

Returns:

Since:

  • 3.3.0



34
35
36
37
38
 
# File 'lib/sass/script/value/helpers.rb', line 34

def hsl_color(hue, saturation, lightness, alpha = nil)
  attrs = {:hue => hue, :saturation => saturation, :lightness => lightness}
  attrs[:alpha] = alpha if alpha
  Color.new(attrs)
end

#list(*elements, separator: , bracketed: false) ⇒ Sass::Script::Value::List #list(array, separator: , bracketed: false) ⇒ Sass::Script::Value::List

Overloads:

  • #list(*elements, separator: , bracketed: false) ⇒ Sass::Script::Value::List

    Create a space-separated list from the arguments given.

    Parameters:

    • elements (Array<Sass::Script::Value::Base>) —

      Each argument will be a list element.

    • separator (Symbol) (defaults to: ) —

      Either :space or :comma.

    • bracketed (Boolean) (defaults to: false) —

      Whether the list uses square brackets.

    Returns:

  • #list(array, separator: , bracketed: false) ⇒ Sass::Script::Value::List

    Create a space-separated list from the array given.

    Parameters:

    • array (Array<Sass::Script::Value::Base>) —

      A ruby array of Sass values to make into a list.

    • separator (Symbol) (defaults to: ) —

      Either :space or :comma.

    • bracketed (Boolean) (defaults to: false) —

      Whether the list uses square brackets.

    Returns:

Since:

  • 3.3.0



83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
 
# File 'lib/sass/script/value/helpers.rb', line 83

def list(*elements, separator: nil, bracketed: false)
  # Support passing separator as the last value in elements for
  # backwards-compatibility.
  if separator.nil?
    if elements.last.is_a?(Symbol)
      separator = elements.pop
    else
      raise ArgumentError.new("A separator of :space or :comma must be specified.")
    end
  end

  if elements.size == 1 && elements.first.is_a?(Array)
    elements = elements.first
  end
  Sass::Script::Value::List.new(elements, separator: separator, bracketed: bracketed)
end

#map(hash) ⇒ Sass::Script::Value::Map

Construct a Sass map.

Parameters:

Returns:

Since:

  • 3.3.0



105
106
107
 
# File 'lib/sass/script/value/helpers.rb', line 105

def map(hash)
  Map.new(hash)
end

#null ⇒ Sass::Script::Value::Null

Create a sass null value.

Returns:

Since:

  • 3.3.0



112
113
114
 
# File 'lib/sass/script/value/helpers.rb', line 112

def null
  Sass::Script::Value::Null.new
end

#number(number, unit_string = nil) ⇒ Sass::Script::Value::Number

Construct a Sass Number from a ruby number.

Parameters:

  • number (::Number) —

    A numeric value.

  • unit_string (::String) (defaults to: nil) —

    A unit string of the form numeral_unit1 * numeral_unit2 ... / denominator_unit1 * denominator_unit2 ... this is the same format that is returned by the unit_str method

Returns:

See Also:

Since:

  • 3.3.0



65
66
67
 
# File 'lib/sass/script/value/helpers.rb', line 65

def number(number, unit_string = nil)
  Number.new(number, *parse_unit_string(unit_string))
end

#parse_complex_selector(value, name = nil, allow_parent_ref = false) ⇒ Sass::Selector::Sequence

Parses a user-provided complex selector.

A complex selector can contain combinators but cannot contain commas.

Parameters:

  • value (Sass::Script::Value::String, Sass::Script::Value::List) —

    The selector to parse. This can be either a string or a list of strings.

  • name (Symbol, nil) (defaults to: nil) —

    If provided, the name of the selector argument. This is used for error reporting.

  • allow_parent_ref (Boolean) (defaults to: false) —

    Whether the parsed selector should allow parent references.

Returns:

Raises:

  • (ArgumentError)

Since:

  • 3.3.0



207
208
209
210
211
212
213
214
 
# File 'lib/sass/script/value/helpers.rb', line 207

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

#parse_compound_selector(value, name = nil, allow_parent_ref = false) ⇒ Sass::Selector::SimpleSequence

Parses a user-provided compound selector.

A compound selector cannot contain combinators or commas.

Parameters:

  • value (Sass::Script::Value::String) —

    The selector to parse.

  • name (Symbol, nil) (defaults to: nil) —

    If provided, the name of the selector argument. This is used for error reporting.

  • allow_parent_ref (Boolean) (defaults to: false) —

    Whether the parsed selector should allow parent references.

Returns:

Raises:

  • (ArgumentError)

Since:

  • 3.3.0



228
229
230
231
232
233
234
235
236
237
238
239
240
241
 
# File 'lib/sass/script/value/helpers.rb', line 228

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

#parse_selector(value, name = nil, allow_parent_ref = false) ⇒ Sass::Selector::CommaSequence

Parses a user-provided selector.

Parameters:

  • 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 &.

  • name (Symbol, nil) (defaults to: nil) —

    If provided, the name of the selector argument. This is used for error reporting.

  • allow_parent_ref (Boolean) (defaults to: false) —

    Whether the parsed selector should allow parent references.

Returns:

Since:

  • 3.3.0



182
183
184
185
186
187
188
189
190
191
 
# File 'lib/sass/script/value/helpers.rb', line 182

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

#quoted_string(str) ⇒ Sass::Script::Value::String

Create a quoted string.

Parameters:

  • str (::String) —

    A ruby string.

Returns:

Since:

  • 3.3.0



120
121
122
 
# File 'lib/sass/script/value/helpers.rb', line 120

def quoted_string(str)
  Sass::Script::String.new(str, :string)
end

#rgb_color(red, green, blue, alpha = nil) ⇒ Sass::Script::Value::Color

Construct a Sass Color from rgb values.

Parameters:

  • red (::Number) —

    The red component. Must be between 0 and 255 inclusive.

  • green (::Number) —

    The green component. Must be between 0 and 255 inclusive.

  • blue (::Number) —

    The blue component. Must be between 0 and 255 inclusive.

  • alpha (::Number) (defaults to: nil) —

    The alpha channel. A number between 0 and 1.

Returns:

Since:

  • 3.3.0



48
49
50
51
52
 
# File 'lib/sass/script/value/helpers.rb', line 48

def rgb_color(red, green, blue, alpha = nil)
  attrs = {:red => red, :green => green, :blue => blue}
  attrs[:alpha] = alpha if alpha
  Color.new(attrs)
end

#special_number?(literal) ⇒ Boolean

Returns whether the literal is a special CSS value that may evaluate to a number, such as calc(), var(), env(), attr(), clamp(), min(), or max().

These functions are part of CSS Color Level 4 spec and should be passed through to CSS without evaluation.

Parameters:

Returns:

  • (Boolean) —

    Boolean

Since:

  • 3.3.0



269
270
271
272
273
274
 
# File 'lib/sass/script/value/helpers.rb', line 269

def special_number?(literal)
  return false unless literal.is_a?(Sass::Script::Value::String)
  # Check for CSS special functions that can evaluate to numbers
  # According to CSS Color Level 4 and CSS Values Level 4 specs
  literal.value =~ /(calc|var|env|attr|clamp|min|max)\s*\(/i
end

#unquoted_string(str) ⇒ Sass::Script::Value::String Also known as: identifier

Create an unquoted string.

Parameters:

  • str (::String) —

    A ruby string.

Returns:

Since:

  • 3.3.0



128
129
130
 
# File 'lib/sass/script/value/helpers.rb', line 128

def unquoted_string(str)
  Sass::Script::String.new(str, :identifier)
end

#var?(literal) ⇒ Boolean

Returns true when the literal is a string containing a var().

Parameters:

Returns:

  • (Boolean) —

    Boolean

Since:

  • 3.3.0



257
258
259
 
# File 'lib/sass/script/value/helpers.rb', line 257

def var?(literal)
  literal.is_a?(Sass::Script::Value::String) && literal.value =~ /var\(/
end