cataract 0.2.5 → 0.4.0

data/lib/cataract/pure/specificity.rb

@@ -4,203 +4,180 @@
 # NO REGEXP ALLOWED - char-by-char parsing only
 
 module Cataract
-  # Calculate CSS specificity for a selector
-  #
-  # @param selector [String] CSS selector
-  # @return [Integer] Specificity value
-  #
-  # Specificity calculation (per CSS spec):
-  # - Count IDs (#id) - each worth 100
-  # - Count classes/attributes/pseudo-classes (.class, [attr], :pseudo) - each worth 10
-  # - Count elements/pseudo-elements (div, ::before) - each worth 1
-  def self.calculate_specificity(selector)
-    return 0 if selector.nil? || selector.empty?
-
-    # Counters for specificity components
-    id_count = 0
-    class_count = 0
-    attr_count = 0
-    pseudo_class_count = 0
-    pseudo_element_count = 0
-    element_count = 0
-
-    i = 0
-    len = selector.length
-
-    pseudo_element_kwords = %w[before after first-line first-letter selection]
-
-    while i < len
-      byte = selector.getbyte(i)
-
-      # Skip whitespace and combinators
-      if byte == BYTE_SPACE || byte == BYTE_TAB || byte == BYTE_NEWLINE || byte == BYTE_CR ||
-         byte == BYTE_GT || byte == BYTE_PLUS || byte == BYTE_TILDE || byte == BYTE_COMMA
-        i += 1
-        next
+  module Backends
+    class PureImpl
+      # Legacy CSS2 pseudo-elements written with a single colon (e.g. :before)
+      # that must still be counted as pseudo-elements, not pseudo-classes.
+      PSEUDO_ELEMENT_KEYWORDS = %w[before after first-line first-letter selection].freeze
+
+      # Check if byte is a letter (a-z, A-Z)
+      # @param byte [Integer] Byte value from String#getbyte
+      # @return [Boolean] true if letter
+      def letter?(byte)
+        (byte >= BYTE_LOWER_A && byte <= BYTE_LOWER_Z) ||
+          (byte >= BYTE_UPPER_A && byte <= BYTE_UPPER_Z)
       end
+      private :letter?
 
-      # ID selector: #id
-      if byte == BYTE_HASH
-        id_count += 1
-        i += 1
-        # Skip the identifier
-        while i < len && ident_char?(selector.getbyte(i))
-          i += 1
+      # Check if byte is alphanumeric, hyphen, or underscore (CSS identifier char)
+      # @param byte [Integer] Byte value from String#getbyte
+      # @return [Boolean] true if valid identifier character
+      def ident_char?(byte)
+        letter?(byte) || (byte >= BYTE_DIGIT_0 && byte <= BYTE_DIGIT_9) || byte == BYTE_HYPHEN || byte == BYTE_UNDERSCORE
+      end
+      private :ident_char?
+
+      # Calculate CSS specificity for a selector
+      #
+      # @param selector [String] CSS selector
+      # @return [Integer] Specificity value
+      #
+      # Specificity calculation (per CSS spec):
+      # - Count IDs (#id) - each worth 100
+      # - Count classes/attributes/pseudo-classes (.class, [attr], :pseudo) - each worth 10
+      # - Count elements/pseudo-elements (div, ::before) - each worth 1
+      def calculate_specificity(selector)
+        return 0 if selector.nil? || selector.empty?
+
+        # Counters for specificity components
+        id_count = 0
+        class_count = 0
+        attr_count = 0
+        pseudo_class_count = 0
+        pseudo_element_count = 0
+        element_count = 0
+
+        i = 0
+        len = selector.length
+
+        while i < len
+          byte = selector.getbyte(i)
+
+          if byte == BYTE_HASH
+            id_count += 1
+            i = skip_identifier(selector, i + 1, len)
+          elsif byte == BYTE_DOT
+            class_count += 1
+            i = skip_identifier(selector, i + 1, len)
+          elsif byte == BYTE_LBRACKET
+            attr_count += 1
+            i = skip_attribute_selector(selector, i, len)
+          elsif byte == BYTE_COLON
+            i, is_not, not_content, counts_as_element = parse_pseudo(selector, i, len)
+            if not_content
+              # :not() doesn't count itself, but its content does
+              not_specificity = calculate_specificity(not_content)
+              id_count += not_specificity / 100
+              class_count += (not_specificity % 100) / 10
+              element_count += not_specificity % 10
+            elsif !is_not
+              if counts_as_element
+                pseudo_element_count += 1
+              else
+                pseudo_class_count += 1
+              end
+            end
+          elsif letter?(byte)
+            element_count += 1
+            i = skip_identifier(selector, i + 1, len)
+          else
+            # Whitespace, combinators, and the universal selector (*) all have
+            # zero specificity - just skip a single byte.
+            i += 1
+          end
         end
-        next
+
+        # Calculate specificity using W3C formula
+        (id_count * 100) +
+          ((class_count + attr_count + pseudo_class_count) * 10) +
+          ((element_count + pseudo_element_count) * 1)
       end
 
-      # Class selector: .class
-      if byte == BYTE_DOT
-        class_count += 1
-        i += 1
-        # Skip the identifier
-        while i < len && ident_char?(selector.getbyte(i))
-          i += 1
-        end
-        next
+      # Advances past an identifier (used after #id, .class, element names, and
+      # pseudo names), returning the index of the first non-identifier byte.
+      def skip_identifier(selector, pos, len)
+        pos += 1 while pos < len && ident_char?(selector.getbyte(pos))
+        pos
       end
+      private :skip_identifier
 
-      # Attribute selector: [attr]
-      if byte == BYTE_LBRACKET
-        attr_count += 1
-        i += 1
-        # Skip to closing bracket
-        bracket_depth = 1
-        while i < len && bracket_depth > 0
-          b = selector.getbyte(i)
-          if b == BYTE_LBRACKET
-            bracket_depth += 1
-          elsif b == BYTE_RBRACKET
-            bracket_depth -= 1
-          end
-          i += 1
+      # Advances past a bracketed [attr] selector, honoring nested brackets,
+      # returning the index just after the matching closing bracket.
+      def skip_attribute_selector(selector, pos, len)
+        skip_balanced(selector, pos + 1, len, BYTE_LBRACKET, BYTE_RBRACKET)
+      end
+      private :skip_attribute_selector
+
+      # Advances past a balanced open/close byte pair (already past the opening
+      # byte, with depth 1), returning the index just after the matching close.
+      def skip_balanced(selector, pos, len, open_byte, close_byte)
+        depth = 1
+        while pos < len && depth > 0
+          b = selector.getbyte(pos)
+          depth += 1 if b == open_byte
+          depth -= 1 if b == close_byte
+          pos += 1
         end
-        next
+        pos
       end
-
-      # Pseudo-element (::) or pseudo-class (:)
-      if byte == BYTE_COLON
-        i += 1
+      private :skip_balanced
+
+      # Advances past a balanced open/close byte pair (already past the opening
+      # byte, with depth 1), returning the index OF the matching close byte
+      # (rather than past it), so the caller can capture the content in between.
+      def find_balanced_close(selector, pos, len, open_byte, close_byte)
+        depth = 1
+        while pos < len && depth > 0
+          b = selector.getbyte(pos)
+          depth += 1 if b == open_byte
+          depth -= 1 if b == close_byte
+          pos += 1 if depth > 0
+        end
+        pos
+      end
+      private :find_balanced_close
+
+      # Parses a :pseudo-class, ::pseudo-element, or :not(...) token starting at
+      # the colon byte. Returns [new_pos, is_not, not_content, counts_as_element]:
+      # - new_pos: index just after the fully-consumed token (incl. any (...) args)
+      # - is_not: whether this token is :not (which never counts itself)
+      # - not_content: the non-empty content of :not(...), or nil otherwise
+      # - counts_as_element: whether this token counts toward pseudo-elements
+      #   (::foo, or a legacy single-colon pseudo-element like :before) rather
+      #   than pseudo-classes
+      def parse_pseudo(selector, pos, len)
+        pos += 1
         is_pseudo_element = false
-
-        # Check for double colon (::)
-        if i < len && selector.getbyte(i) == BYTE_COLON
+        if pos < len && selector.getbyte(pos) == BYTE_COLON
           is_pseudo_element = true
-          i += 1
-        end
-
-        # Extract pseudo name
-        pseudo_start = i
-        while i < len && ident_char?(selector.getbyte(i))
-          i += 1
+          pos += 1
         end
-        pseudo_name = selector[pseudo_start...i]
 
-        # Check for legacy pseudo-elements (single colon but should be double)
-        is_legacy_pseudo_element = false
-        if !is_pseudo_element && !pseudo_name.empty?
-          is_legacy_pseudo_element = pseudo_element_kwords.include?(pseudo_name)
-        end
+        pseudo_start = pos
+        pos = skip_identifier(selector, pos, len)
+        pseudo_name = selector[pseudo_start...pos]
 
-        # Check for :not() - it doesn't count itself, but its content does
+        is_legacy_pseudo_element = !is_pseudo_element && !pseudo_name.empty? &&
+                                   PSEUDO_ELEMENT_KEYWORDS.include?(pseudo_name)
         is_not = (pseudo_name == 'not')
+        not_content = nil
 
-        # Skip function arguments if present
-        if i < len && selector.getbyte(i) == BYTE_LPAREN
-          i += 1
-          paren_depth = 1
-
-          # If it's :not(), calculate specificity of the content
+        if pos < len && selector.getbyte(pos) == BYTE_LPAREN
+          pos += 1
           if is_not
-            not_content_start = i
-
-            # Find closing paren
-            while i < len && paren_depth > 0
-              b = selector.getbyte(i)
-              if b == BYTE_LPAREN
-                paren_depth += 1
-              elsif b == BYTE_RPAREN
-                paren_depth -= 1
-              end
-              i += 1 if paren_depth > 0
-            end
-
-            not_content = selector[not_content_start...i]
-
-            # Recursively calculate specificity of :not() content
-            unless not_content.empty?
-              not_specificity = calculate_specificity(not_content)
-
-              # Add :not() content's specificity to our counts
-              additional_a = not_specificity / 100
-              additional_b = (not_specificity % 100) / 10
-              additional_c = not_specificity % 10
-
-              id_count += additional_a
-              class_count += additional_b
-              element_count += additional_c
-            end
-
-            i += 1 # Skip closing paren
-          else
-            # Skip other function arguments
-            while i < len && paren_depth > 0
-              b = selector.getbyte(i)
-              if b == BYTE_LPAREN
-                paren_depth += 1
-              elsif b == BYTE_RPAREN
-                paren_depth -= 1
-              end
-              i += 1
-            end
-
-            # Count the pseudo-class/element
-            if is_pseudo_element || is_legacy_pseudo_element
-              pseudo_element_count += 1
-            else
-              pseudo_class_count += 1
-            end
-          end
-        else
-          # No function arguments - count the pseudo-class/element
-          if is_not
-            # :not without parens is invalid, but don't count it
-          elsif is_pseudo_element || is_legacy_pseudo_element
-            pseudo_element_count += 1
+            content_start = pos
+            pos = find_balanced_close(selector, pos, len, BYTE_LPAREN, BYTE_RPAREN)
+            content = selector[content_start...pos]
+            not_content = content unless content.empty?
+            pos += 1 # Skip closing paren
           else
-            pseudo_class_count += 1
+            pos = skip_balanced(selector, pos, len, BYTE_LPAREN, BYTE_RPAREN)
           end
         end
-        next
-      end
-
-      # Universal selector: *
-      if byte == BYTE_ASTERISK
-        # Universal selector has specificity 0, don't count
-        i += 1
-        next
-      end
 
-      # Type selector (element name): div, span, etc.
-      if letter?(byte)
-        element_count += 1
-        # Skip the identifier
-        while i < len && ident_char?(selector.getbyte(i))
-          i += 1
-        end
-        next
+        [pos, is_not, not_content, is_pseudo_element || is_legacy_pseudo_element]
       end
-
-      # Unknown character, skip it
-      i += 1
+      private :parse_pseudo
     end
-
-    # Calculate specificity using W3C formula
-    specificity = (id_count * 100) +
-                  ((class_count + attr_count + pseudo_class_count) * 10) +
-                  ((element_count + pseudo_element_count) * 1)
-
-    specificity
   end
 end

data/lib/cataract/pure.rb

@@ -7,23 +7,24 @@
 # NO REGEXP ALLOWED - consume chars one at a time like the C version.
 # ==================================================================
 #
-# Load this instead of the C extension with:
-#   require 'cataract/pure'
+# Load this instead of the C extension by setting CATARACT_PURE before
+# requiring 'cataract' (not by requiring this file directly - lib/cataract.rb
+# is what sets up Cataract::Backends.active and the top-level identity
+# constants like IMPLEMENTATION; this file alone does not):
+#   ENV['CATARACT_PURE'] = '1'
+#   require 'cataract'
 #
 # Or run tests with:
 #   CATARACT_PURE=1 rake test
-
-# Check if C extension is already loaded
-if defined?(Cataract::NATIVE_EXTENSION_LOADED)
-  raise LoadError, 'Cataract C extension is already loaded. Cannot load pure Ruby version.'
-end
-
-# Define base module and error classes first
-module Cataract
-  class Error < StandardError; end
-  class DepthError < Error; end
-  class SizeError < Error; end
-end
+#
+# Everything backend-specific here lives under Cataract::Backends::Pure -
+# nothing is defined directly on Cataract itself, so this file can be loaded
+# in the same process as the native backend without either clobbering the
+# other. The one exception is Stylesheet#convert_colors! below: color
+# conversion has no pure-Ruby implementation at all, so the stub simply
+# raises - native's real implementation (ext/cataract_color, loaded
+# separately and only opt-in) defines its own convert_colors! and is
+# unaffected by this file being loaded or not.
 
 require_relative 'error'
 
@@ -31,7 +32,7 @@ require_relative 'version'
 require_relative 'constants'
 
 # Load struct definitions and supporting files
-# (These are also loaded by lib/cataract.rb, but we need them here for direct require)
+# (These are also loaded by lib/cataract/native.rb, but we need them here for direct require)
 require_relative 'declaration'
 require_relative 'rule'
 require_relative 'at_rule'
@@ -42,115 +43,79 @@ require_relative 'stylesheet'
 require_relative 'declarations'
 require_relative 'import_resolver'
 
-# Add to_s method to Declarations class for pure Ruby mode
-module Cataract
-  class Declarations
-    # Serialize declarations to CSS string
-    def to_s
-      result = String.new
-      @values.each_with_index do |decl, i|
-        result << decl.property
-        result << ': '
-        result << decl.value
-        result << ' !important' if decl.important
-        result << ';'
-        result << ' ' if i < @values.length - 1 # Add space after semicolon except for last
-      end
-      result
-    end
-  end
-end
-
 # Load pure Ruby implementation modules
 require_relative 'pure/byte_constants'
-require_relative 'pure/helpers'
 require_relative 'pure/specificity'
 require_relative 'pure/serializer'
 require_relative 'pure/parser'
 require_relative 'pure/flatten'
+require_relative 'pure/declarations'
 
 module Cataract
-  # Flag to indicate pure Ruby version is loaded
-  PURE_RUBY_LOADED = true
-
-  # Implementation type constant
-  IMPLEMENTATION = :ruby
-
-  # Compile flags (mimic C version)
-  COMPILE_FLAGS = {
-    debug: false,
-    str_buf_optimization: false,
-    pure_ruby: true
-  }.freeze
-
-  # Parse CSS string and return hash with rules, media_index, charset, etc.
-  #
-  # @api private
-  # @param css_string [String] CSS to parse
-  # @param parser_options [Hash] Parser configuration options
-  # @option parser_options [Boolean] :selector_lists (true) Track selector lists
-  # @return [Hash] {
-  #   rules: Array<Rule>,           # Flat array of Rule/AtRule structs
-  #   _media_index: Hash,           # Symbol => Array of rule IDs
-  #   charset: String|nil,          # @charset value if present
-  #   _has_nesting: Boolean         # Whether any nested rules exist
-  # }
-  def self._parse_css(css_string, parser_options = {})
-    parser = Parser.new(css_string, parser_options: parser_options)
-    parser.parse
-  end
-
-  # NOTE: Copied from cataract.rb
-  # Need to untangle this eventually
-  def self.parse_css(css, **options)
-    Stylesheet.parse(css, **options)
-  end
-
-  # Flatten stylesheet rules according to CSS cascade rules
-  #
-  # @param stylesheet [Stylesheet] Stylesheet to flatten
-  # @return [Stylesheet] New stylesheet with flattened rules
-  def self.flatten(stylesheet)
-    Flatten.flatten(stylesheet, mutate: false)
-  end
-
-  # Flatten stylesheet rules in-place (mutates receiver)
-  #
-  # @param stylesheet [Stylesheet] Stylesheet to flatten
-  # @return [Stylesheet] Same stylesheet (mutated)
-  def self.flatten!(stylesheet)
-    Flatten.flatten(stylesheet, mutate: true)
-  end
+  module Backends
+    class PureImpl
+      # Flag to indicate the pure Ruby backend is loaded
+      PURE_RUBY_LOADED = true
+
+      # Implementation type constant
+      IMPLEMENTATION = :ruby
+
+      # Compile flags (mimic C version)
+      COMPILE_FLAGS = {
+        debug: false,
+        str_buf_optimization: false,
+        pure_ruby: true
+      }.freeze
+
+      # Parse CSS string and return hash with rules, media_index, charset, etc.
+      # Called by Stylesheet#add_block - not meant for direct use.
+      #
+      # @param css_string [String] CSS to parse
+      # @param parser_options [Hash] Parser configuration options
+      # @option parser_options [Boolean] :selector_lists (true) Track selector lists
+      # @return [Hash] {
+      #   rules: Array<Rule>,           # Flat array of Rule/AtRule structs
+      #   _media_index: Hash,           # Symbol => Array of rule IDs
+      #   charset: String|nil,          # @charset value if present
+      #   _has_nesting: Boolean         # Whether any nested rules exist
+      # }
+      def parse(css_string, parser_options = {})
+        parser = Parser.new(css_string, parser_options: parser_options)
+        parser.parse
+      end
 
-  # Deprecated: Use flatten instead
-  def self.merge(stylesheet)
-    warn 'Cataract.merge is deprecated, use Cataract.flatten instead', uplevel: 1
-    flatten(stylesheet)
-  end
+      # Flatten stylesheet rules according to CSS cascade rules
+      #
+      # @param stylesheet [Stylesheet] Stylesheet to flatten
+      # @return [Stylesheet] New stylesheet with flattened rules
+      def flatten(stylesheet)
+        Flatten.flatten(stylesheet, mutate: false)
+      end
 
-  # Deprecated: Use flatten! instead
-  def self.merge!(stylesheet)
-    warn 'Cataract.merge! is deprecated, use Cataract.flatten! instead', uplevel: 1
-    flatten!(stylesheet)
-  end
+      # Expand a single shorthand declaration into longhand declarations.
+      # Called by Rule#expanded_declarations - not meant for direct use.
+      #
+      # @param decl [Declaration] Declaration to expand
+      # @return [Array<Declaration>] Array of expanded longhand declarations
+      def expand_shorthand(decl)
+        Flatten.expand_shorthand(decl)
+      end
+    end
 
-  # Expand a single shorthand declaration into longhand declarations.
-  # Underscore prefix indicates semi-private API - use with caution.
-  #
-  # @param decl [Declaration] Declaration to expand
-  # @return [Array<Declaration>] Array of expanded longhand declarations
-  # @api private
-  def self.expand_shorthand(decl)
-    Flatten.expand_shorthand(decl)
+    # The active-facing constant is a single frozen instance, not the class
+    # itself - none of PureImpl's methods touch instance state, so one shared
+    # instance is exactly as safe as the bare module this replaces, while
+    # giving its methods genuine instance-level `private` instead of
+    # `private_class_method`.
+    Pure = PureImpl.new.freeze
   end
 
-  # Add stub method to Stylesheet for pure Ruby implementation
   class Stylesheet
-    # Color conversion is only available in the native C extension
+    # Color conversion has no pure-Ruby implementation.
     #
-    # @raise [NotImplementedError] Always raises - color conversion requires C extension
+    # @raise [NotImplementedError] Always raises - not implemented for pure Ruby
     def convert_colors!(*_args)
-      raise NotImplementedError, 'convert_colors! is only available in the native C extension'
+      raise NotImplementedError, 'convert_colors! is not yet implemented in Cataract'
     end
   end
 end

data/lib/cataract/rule.rb

@@ -87,8 +87,11 @@ module Cataract
     def specificity
       return self[:specificity] unless self[:specificity].nil?
 
-      # Calculate and cache
-      calculated = Cataract.calculate_specificity(selector)
+      # Calculate and cache. Specificity is a pure function of the selector
+      # string, identical across backends by design, so this always goes
+      # through the process's active backend regardless of which backend
+      # actually produced this Rule.
+      calculated = Cataract::Backends.active.calculate_specificity(selector)
       self[:specificity] = calculated
       calculated
     end
@@ -215,7 +218,7 @@ module Cataract
     # rubocop:disable Naming/MemoizedInstanceVariableName
     def expanded_declarations
       @_expanded_declarations ||= begin
-        expanded = declarations.flat_map { |decl| Cataract.expand_shorthand(decl) }
+        expanded = declarations.flat_map { |decl| Cataract::Backends.active.expand_shorthand(decl) }
         expanded.sort_by! { |d| [d.property, d.value, d.important ? 1 : 0] }
         expanded
       end