Class: Cataract::Rule

Inherits:
Struct
  • Object
show all
Defined in:
lib/cataract/rule.rb,
lib/cataract/rule.rb

Overview

Rules are created by the parser and stored in Stylesheet objects. Each rule contains:

  • An ID (position in the stylesheet)
  • A CSS selector string
  • An array of Declaration structs
  • A specificity value (calculated lazily)
  • Parent rule ID for nested rules (nil if top-level)
  • Nesting style (0=implicit, 1=explicit, nil=not nested)

Media query information is stored separately in Stylesheet's media_index.

Examples:

Access rule properties

sheet = Cataract.parse_css("body { color: red; font-size: 14px; }")
rule = sheet.rules.first
rule.selector #=> "body"
rule.specificity #=> 1
rule.declarations.length #=> 2

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#conditional_group_id ⇒ Integer?

ID of the ConditionalGroup (@supports/@layer/@container/@scope) this rule belongs to (nil if not in one)

Returns:

  • (Integer, nil) —

    the current value of conditional_group_id



30
31
32
 
# File 'lib/cataract/rule.rb', line 30

def conditional_group_id
  @conditional_group_id
end

#declarations ⇒ Array<Declaration>

Array of CSS property declarations

Returns:

  • (Array<Declaration>) —

    the current value of declarations



30
31
32
 
# File 'lib/cataract/rule.rb', line 30

def declarations
  @declarations
end

#id ⇒ Integer

The rule's position in the stylesheet (0-indexed)

Returns:

  • (Integer) —

    the current value of id



30
31
32
 
# File 'lib/cataract/rule.rb', line 30

def id
  @id
end

#media_query_id ⇒ Integer?

ID of the MediaQuery this rule belongs to (nil if not in media query)

Returns:

  • (Integer, nil) —

    the current value of media_query_id



30
31
32
 
# File 'lib/cataract/rule.rb', line 30

def media_query_id
  @media_query_id
end

#nesting_style ⇒ Integer?

0=implicit, 1=explicit, nil=not nested

Returns:

  • (Integer, nil) —

    the current value of nesting_style



30
31
32
 
# File 'lib/cataract/rule.rb', line 30

def nesting_style
  @nesting_style
end

#parent_rule_id ⇒ Integer?

Parent rule ID for nested rules

Returns:

  • (Integer, nil) —

    the current value of parent_rule_id



30
31
32
 
# File 'lib/cataract/rule.rb', line 30

def parent_rule_id
  @parent_rule_id
end

#selector ⇒ String

The CSS selector (e.g., "body", ".class", "#id")

Returns:

  • (String) —

    the current value of selector



30
31
32
 
# File 'lib/cataract/rule.rb', line 30

def selector
  @selector
end

#selector_list_id ⇒ Integer?

ID linking rules from same selector list (e.g., "h1, h2")

Returns:

  • (Integer, nil) —

    the current value of selector_list_id



30
31
32
 
# File 'lib/cataract/rule.rb', line 30

def selector_list_id
  @selector_list_id
end

#specificity ⇒ Integer

Get the CSS specificity value for this rule's selector.

Specificity is calculated lazily on first access and then cached. The calculation follows the CSS specification:

  • Inline styles: not applicable to parsed stylesheets
  • IDs: count of #id selectors
  • Classes/attributes/pseudo-classes: count of .class, [attr], :pseudo
  • Elements/pseudo-elements: count of element, ::pseudo

Examples:

Get specificity

rule = Cataract.parse_css("#header .nav a").rules.first
rule.specificity #=> 111 (1 ID + 1 class + 1 element)

Returns:

  • (Integer) —

    CSS specificity value



30
31
32
 
# File 'lib/cataract/rule.rb', line 30

def specificity
  @specificity
end

Class Method Details

.make(id:, selector:, declarations:, specificity: nil, parent_rule_id: nil, nesting_style: nil, selector_list_id: nil, media_query_id: nil, conditional_group_id: nil) ⇒ Rule

Factory method for creating Rules with keyword arguments (for tests/readability). C code and hot paths should use positional arguments directly via Rule.new.

Examples:

Create a rule with keyword arguments

Rule.make(
  id: 0,
  selector: '.foo',
  declarations: [Declaration.new('color', 'red', false)],
  specificity: 10,
  parent_rule_id: nil,
  nesting_style: nil,
  selector_list_id: nil,
  media_query_id: nil,
  conditional_group_id: nil
)

Parameters:

  • id (Integer) —

    The rule's position in the stylesheet

  • selector (String) —

    CSS selector

  • declarations (Array<Declaration>) —

    Array of declarations

  • specificity (Integer, nil) (defaults to: nil) —

    Specificity value (nil to calculate lazily)

  • parent_rule_id (Integer, nil) (defaults to: nil) —

    Parent rule ID for nested rules

  • nesting_style (Integer, nil) (defaults to: nil) —

    Nesting style (0=implicit, 1=explicit, nil=not nested)

  • selector_list_id (Integer, nil) (defaults to: nil) —

    Selector list ID for grouping

  • media_query_id (Integer, nil) (defaults to: nil) —

    MediaQuery ID for rules in media queries

  • conditional_group_id (Integer, nil) (defaults to: nil) —

    ConditionalGroup ID for rules in @supports/@layer/@container/@scope

Returns:

  • (Rule) —

    New rule instance



69
70
71
 
# File 'lib/cataract/rule.rb', line 69

def self.make(id:, selector:, declarations:, specificity: nil, parent_rule_id: nil, nesting_style: nil, selector_list_id: nil, media_query_id: nil, conditional_group_id: nil)
  new(id, selector, declarations, specificity, parent_rule_id, nesting_style, selector_list_id, media_query_id, conditional_group_id)
end

Instance Method Details

#==(other) ⇒ Boolean Also known as: eql?

Compare rules for logical equality based on CSS semantics.

Two rules are equal if they have the same selector and declarations. Shorthand properties are expanded before comparison, so margin: 10px equals margin-top: 10px; margin-right: 10px; ...

Internal implementation details (id, specificity) are not considered since they don't affect the CSS semantics.

Can also compare against a CSS string, which is parsed and compared.

Parameters:

  • other (Object) —

    Object to compare with (Rule or String)

Returns:

  • (Boolean) —

    true if rules have same selector and declarations



183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
 
# File 'lib/cataract/rule.rb', line 183

def ==(other)
  case other
  when Rule
    return false unless selector == other.selector

    expanded_declarations == other.expanded_declarations
  when String
    # Parse CSS string and compare to first rule
    parsed = Cataract.parse_css(other)
    return false unless parsed.rules.size == 1

    self == parsed.rules.first
  else
    false
  end
end

#at_rule? ⇒ Boolean

Check if this is an at-rule.

Returns:

  • (Boolean) —

    Always returns false for Rule objects



113
114
115
 
# File 'lib/cataract/rule.rb', line 113

def at_rule?
  false
end

#at_rule_type?(_type) ⇒ Boolean

Check if this is a specific at-rule type.

Parameters:

  • _type (Symbol) —

    At-rule type (e.g., :keyframes, :font_face)

Returns:

  • (Boolean) —

    Always returns false for Rule objects



121
122
123
 
# File 'lib/cataract/rule.rb', line 121

def at_rule_type?(_type)
  false
end

#has_important?(property = nil) ⇒ Boolean

Check if this rule has any !important declarations, optionally for a specific property.

Examples:

Check for any !important

rule.has_important? #=> true

Check for color !important

rule.has_important?('color') #=> true

Parameters:

  • property (String, nil) (defaults to: nil) —

    Optional property name to match

Returns:

  • (Boolean) —

    true if rule has matching !important declaration



162
163
164
165
166
167
168
 
# File 'lib/cataract/rule.rb', line 162

def has_important?(property = nil)
  if property
    declarations.any? { |d| d.property == property && d.important }
  else
    declarations.any?(&:important)
  end
end

#has_property?(property, value = nil, prefix_match: false) ⇒ Boolean

Check if this rule has a declaration with the specified property and optional value.

Examples:

Check for color property

rule.has_property?('color') #=> true

Check for specific property value

rule.has_property?('color', 'red') #=> true

Check for any margin-related property

rule.has_property?('margin', prefix_match: true) #=> true if has margin, margin-top, etc.

Parameters:

  • property (String) —

    CSS property name to match

  • value (String, nil) (defaults to: nil) —

    Optional value to match

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

    Whether to match by prefix (default: false)

Returns:

  • (Boolean) —

    true if rule has matching declaration



140
141
142
143
144
145
146
147
148
149
150
 
# File 'lib/cataract/rule.rb', line 140

def has_property?(property, value = nil, prefix_match: false)
  declarations.any? do |decl|
    property_matches = if prefix_match
                         decl.property.start_with?(property)
                       else
                         decl.property == property
                       end
    value_matches = value.nil? || decl.value == value
    property_matches && value_matches
  end
end

#hash ⇒ Integer

Generate hash code for this rule.

Hash is based on selector and expanded declarations to match the equality semantics. This allows rules to be used as Hash keys or in Sets correctly.

rubocop:disable Naming/MemoizedInstanceVariableName

Returns:

  • (Integer) —

    hash code



209
210
211
 
# File 'lib/cataract/rule.rb', line 209

def hash
  @_hash ||= [self.class, selector, expanded_declarations].hash
end

#selector? ⇒ Boolean

Check if this is a selector-based rule (vs an at-rule like @keyframes).

Returns:

  • (Boolean) —

    Always returns true for Rule objects



106
107
108
 
# File 'lib/cataract/rule.rb', line 106

def selector?
  true
end