cataract 0.1.0

data/lib/cataract/rule.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module Cataract
+  # Represents a CSS rule with a selector and declarations.
+  #
+  # Rule is a C struct defined as: `Struct.new(:id, :selector, :declarations, :specificity)`
+  #
+  # 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)
+  #
+  # Media query information is stored separately in Stylesheet's media_index.
+  #
+  # @example 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
+  #
+  # @attr [Integer] id The rule's position in the stylesheet (0-indexed)
+  # @attr [String] selector The CSS selector (e.g., "body", ".class", "#id")
+  # @attr [Array<Declaration>] declarations Array of CSS property declarations
+  # @attr [Integer, nil] specificity CSS specificity value (calculated lazily)
+  class Rule
+    # Silence warning about method redefinition. We redefine below to lazily calculate
+    # specificity
+    undef_method :specificity if method_defined?(:specificity)
+
+    # 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
+    #
+    # @return [Integer] CSS specificity value
+    #
+    # @example Get specificity
+    #   rule = Cataract.parse_css("#header .nav a").rules.first
+    #   rule.specificity #=> 111 (1 ID + 1 class + 1 element)
+    def specificity
+      return self[:specificity] unless self[:specificity].nil?
+
+      # Calculate and cache
+      calculated = Cataract.calculate_specificity(selector)
+      self[:specificity] = calculated
+      calculated
+    end
+
+    # Check if this is a selector-based rule (vs an at-rule like @keyframes).
+    #
+    # @return [Boolean] Always returns true for Rule objects
+    def selector?
+      true
+    end
+
+    # Check if this is an at-rule.
+    #
+    # @return [Boolean] Always returns false for Rule objects
+    def at_rule?
+      false
+    end
+
+    # Check if this is a specific at-rule type.
+    #
+    # @param _type [Symbol] At-rule type (e.g., :keyframes, :font_face)
+    # @return [Boolean] Always returns false for Rule objects
+    def at_rule_type?(_type)
+      false
+    end
+
+    # Check if this rule has a declaration with the specified property and optional value.
+    #
+    # @param property [String] CSS property name to match
+    # @param value [String, nil] Optional value to match
+    # @return [Boolean] true if rule has matching declaration
+    #
+    # @example Check for color property
+    #   rule.has_property?('color') #=> true
+    #
+    # @example Check for specific property value
+    #   rule.has_property?('color', 'red') #=> true
+    def has_property?(property, value = nil)
+      declarations.any? do |decl|
+        property_matches = decl.property == property
+        value_matches = value.nil? || decl.value == value
+        property_matches && value_matches
+      end
+    end
+
+    # Check if this rule has any !important declarations, optionally for a specific property.
+    #
+    # @param property [String, nil] Optional property name to match
+    # @return [Boolean] true if rule has matching !important declaration
+    #
+    # @example Check for any !important
+    #   rule.has_important? #=> true
+    #
+    # @example Check for color !important
+    #   rule.has_important?('color') #=> true
+    def has_important?(property = nil)
+      if property
+        declarations.any? { |d| d.property == property && d.important }
+      else
+        declarations.any?(&:important)
+      end
+    end
+
+    # Compare rules by their attributes rather than object identity.
+    #
+    # Two rules are equal if they have the same id, selector, declarations, and specificity.
+    #
+    # @param other [Object] Object to compare with
+    # @return [Boolean] true if rules have same attributes
+    def ==(other)
+      return false unless other.is_a?(Rule)
+
+      id == other.id &&
+        selector == other.selector &&
+        declarations == other.declarations &&
+        specificity == other.specificity
+    end
+    alias eql? ==
+  end
+end