cataract 0.3.0 → 0.5.0

data/lib/cataract/stylesheet.rb

@@ -29,6 +29,9 @@ module Cataract
     # @return [Array<MediaQuery>] Array of media query objects
     attr_reader :media_queries
 
+    # @return [Array<ConditionalGroup>] Array of conditional-group objects (@supports/@layer/@container/@scope)
+    attr_reader :conditional_groups
+
     # @return [Hash<Symbol, Array<Integer>>] Cached index mapping media query text to rule IDs
     # Lazily build and return media_index.
     # Only builds the index when first accessed, not eagerly during parse.
@@ -112,6 +115,13 @@ module Cataract
       # Type validation
       raise TypeError, "options must be a Hash, got #{options.class}" unless options.is_a?(Hash)
 
+      # Which backend (Cataract::Backends::Native / ::Pure) produced this
+      # stylesheet - defaults to whichever this process picked as active.
+      # Not part of the public options contract (used internally by
+      # Backends::Native.parse / Backends::Pure.parse), so it's popped off
+      # before @options is built.
+      @backend = options.delete(:backend) || Cataract::Backends.active
+
       # Support :imports as alias for :import (backwards compatibility)
       options[:import] = options.delete(:imports) if options.key?(:imports) && !options.key?(:import)
 
@@ -153,6 +163,8 @@ module Cataract
       @_next_selector_list_id = 0 # Counter for selector list IDs
       @_media_query_lists = {} # Hash: list_id => Array of MediaQuery IDs (for "screen, print" grouping)
       @_next_media_query_list_id = 0 # Counter for media query list IDs
+      @conditional_groups = [] # Array of ConditionalGroup objects (@supports/@layer/@container/@scope)
+      @_next_conditional_group_id = 0 # Counter for ConditionalGroup IDs
       @charset = nil
       @imports = [] # Array of ImportStatement objects
       @_has_nesting = nil # Set by parser (nil or boolean)
@@ -169,6 +181,7 @@ module Cataract
     # @param source [Stylesheet] Source stylesheet being copied
     def initialize_copy(source)
       super
+      @backend = source.backend
       @options = source.options.dup
       @rules = source.rules.dup
       @media_queries = source.media_queries.dup
@@ -179,6 +192,8 @@ module Cataract
       @_next_selector_list_id = source.next_selector_list_id
       @_media_query_lists = source.media_query_lists.transform_values(&:dup)
       @_next_media_query_list_id = source.next_media_query_list_id
+      @conditional_groups = source.conditional_groups.dup
+      @_next_conditional_group_id = source.next_conditional_group_id
       @parser_options = source.parser_options.dup
       clear_memoized_caches
       @_hash = nil # Clear cached hash
@@ -466,7 +481,8 @@ module Cataract
     # @example Filter to multiple media types
     #   sheet.to_s(media: [:screen, :print])  # => "@media screen { ... } @media print { ... }"
     def to_s(media: :all)
-      Cataract.stylesheet_to_s(filter_rules_by_media(media), @charset, @_has_nesting || false, @_selector_lists, @media_queries, @_media_query_lists)
+      @backend.stylesheet_to_s(filter_rules_by_media(media), @charset, @_has_nesting || false, @_selector_lists, @media_queries, @_media_query_lists,
+                               @conditional_groups)
     end
     alias to_css to_s
 
@@ -492,7 +508,8 @@ module Cataract
     #
     # @see #to_s For compact single-line output
     def to_formatted_s(media: :all)
-      Cataract.stylesheet_to_formatted_s(filter_rules_by_media(media), @charset, @_has_nesting || false, @_selector_lists, @media_queries, @_media_query_lists)
+      @backend.stylesheet_to_formatted_s(filter_rules_by_media(media), @charset, @_has_nesting || false, @_selector_lists, @media_queries, @_media_query_lists,
+                                         @conditional_groups)
     end
 
     # Get number of rules
@@ -718,7 +735,7 @@ module Cataract
       parse_options = build_parse_options(effective_base_uri, effective_absolute_paths)
 
       # Parse CSS first (this extracts @import statements into result[:imports])
-      result = Cataract._parse_css(css, parse_options)
+      result = @backend.parse(css, parse_options)
 
       merge_parsed_block!(result, effective_base_uri, effective_base_dir)
 
@@ -761,8 +778,9 @@ module Cataract
     # Compare stylesheets for equality.
     #
     # Two stylesheets are equal if they have the same rules in the same order
-    # and the same media queries. Rule equality uses shorthand-aware comparison.
-    # Order matters because CSS cascade depends on rule order.
+    # and the same media queries and conditional groups. Rule equality uses
+    # shorthand-aware comparison. Order matters because CSS cascade depends
+    # on rule order.
     #
     # Charset is ignored since it's file encoding metadata, not semantic content.
     #
@@ -772,6 +790,7 @@ module Cataract
       return false unless other.is_a?(Stylesheet)
       return false unless rules == other.rules
       return false unless @media_queries == other.media_queries
+      return false unless @conditional_groups == other.conditional_groups
 
       true
     end
@@ -779,11 +798,12 @@ module Cataract
 
     # Generate hash code for this stylesheet.
     #
-    # Hash is based on rules and media_queries to match equality semantics.
+    # Hash is based on rules, media_queries, and conditional_groups to match
+    # equality semantics.
     #
     # @return [Integer] hash code
     def hash
-      @_hash ||= [self.class, rules, @media_queries].hash # rubocop:disable Naming/MemoizedInstanceVariableName
+      @_hash ||= [self.class, rules, @media_queries, @conditional_groups].hash # rubocop:disable Naming/MemoizedInstanceVariableName
     end
 
     # Flatten all rules in this stylesheet according to CSS cascade rules.
@@ -794,7 +814,9 @@ module Cataract
     #
     # @return [Stylesheet] New stylesheet with cascade applied
     def flatten
-      Cataract.flatten(self)
+      result = @backend.flatten(self)
+      result.backend = @backend
+      result
     end
     alias cascade flatten
 
@@ -813,7 +835,7 @@ module Cataract
     #
     # @return [self] Returns self for method chaining
     def flatten!
-      flattened = Cataract.flatten(self)
+      flattened = @backend.flatten(self)
       @rules = flattened.rules
       @media_index = flattened.media_index_cache
       @_has_nesting = flattened.has_nesting
@@ -842,11 +864,13 @@ module Cataract
       list_id_offset = merge_selector_lists!(other.selector_lists, rule_id_offset: offset)
       mq_id_offset = merge_media_queries!(other.media_queries)
       merge_media_query_lists!(other.media_query_lists, mq_id_offset: mq_id_offset)
+      cg_id_offset = merge_conditional_groups!(other.conditional_groups)
 
       # Add rules with updated IDs and cross-references
       other.rules.each do |rule|
         new_rule = rule.dup
-        rebase_rule!(new_rule, rule_id_offset: offset, list_id_offset: list_id_offset, mq_id_offset: mq_id_offset)
+        rebase_rule!(new_rule, rule_id_offset: offset, list_id_offset: list_id_offset, mq_id_offset: mq_id_offset,
+                               cg_id_offset: cg_id_offset)
         @rules << new_rule
       end
 
@@ -930,11 +954,16 @@ module Cataract
     # raw cache these need).
 
     attr_reader :options, :parser_options
+    attr_accessor :backend
 
     def next_media_query_id
       @_next_media_query_id
     end
 
+    def next_conditional_group_id
+      @_next_conditional_group_id
+    end
+
     def next_selector_list_id
       @_next_selector_list_id
     end
@@ -987,6 +1016,28 @@ module Cataract
       mq_id_offset
     end
 
+    # Offset and append ConditionalGroup objects into @conditional_groups,
+    # without mutating the source objects. Unlike merge_media_queries!,
+    # each group's own parent_id (pointing at another ConditionalGroup, for
+    # nesting) must also be rebased by the same offset.
+    #
+    # @param source_groups [Array<ConditionalGroup>, nil]
+    # @return [Integer] id offset applied to each merged ConditionalGroup
+    def merge_conditional_groups!(source_groups)
+      cg_id_offset = @_next_conditional_group_id
+      return cg_id_offset if source_groups.nil? || source_groups.empty?
+
+      source_groups.each do |group|
+        new_group = group.dup
+        new_group.id += cg_id_offset
+        new_group.parent_id += cg_id_offset if new_group.parent_id
+        @conditional_groups << new_group
+      end
+      @_next_conditional_group_id += source_groups.size
+
+      cg_id_offset
+    end
+
     # Offset and merge a selector_lists hash (list_id => [rule_ids]) into
     # @_selector_lists. List ids are always rebased onto the next available
     # id; rule ids are rebased by rule_id_offset (0 when the caller defers
@@ -1045,18 +1096,21 @@ module Cataract
     end
 
     # Rebase a rule/at-rule's own id and its cross-references (Rule's
-    # selector_list_id, and media_query_id on both Rule and AtRule) by the
-    # given offsets, mutating it in place. Callers merging from a live
-    # Stylesheet they don't own (e.g. concat) must dup the rule first.
+    # selector_list_id, and media_query_id/conditional_group_id on both Rule
+    # and AtRule) by the given offsets, mutating it in place. Callers
+    # merging from a live Stylesheet they don't own (e.g. concat) must dup
+    # the rule first.
     #
     # @param rule [Rule, AtRule]
     # @param rule_id_offset [Integer]
     # @param list_id_offset [Integer]
     # @param mq_id_offset [Integer]
+    # @param cg_id_offset [Integer]
     # @return [void]
-    def rebase_rule!(rule, rule_id_offset:, list_id_offset: 0, mq_id_offset: 0)
+    def rebase_rule!(rule, rule_id_offset:, list_id_offset: 0, mq_id_offset: 0, cg_id_offset: 0)
       rule.id += rule_id_offset
       rule.media_query_id += mq_id_offset if rule.media_query_id
+      rule.conditional_group_id += cg_id_offset if rule.conditional_group_id
       return unless rule.is_a?(Rule)
 
       rule.selector_list_id += list_id_offset if rule.selector_list_id
@@ -1080,7 +1134,7 @@ module Cataract
     # rules, media queries, selector/media-query lists, and index, then
     # resolve any @import statements it contained.
     #
-    # @param result [Hash] Return value of Cataract._parse_css
+    # @param result [Hash] Return value of the backend's parse
     # @return [void]
     def merge_parsed_block!(result, effective_base_uri, effective_base_dir)
       offset = @_last_rule_id || 0
@@ -1088,10 +1142,12 @@ module Cataract
       list_id_offset = merge_selector_lists!(result[:_selector_lists], rule_id_offset: offset)
       mq_id_offset = merge_media_queries!(result[:media_queries])
       merge_media_query_lists!(result[:_media_query_lists], mq_id_offset: mq_id_offset)
+      cg_id_offset = merge_conditional_groups!(result[:conditional_groups])
 
       new_rules = result[:rules]
       new_rules.each do |rule|
-        rebase_rule!(rule, rule_id_offset: offset, list_id_offset: list_id_offset, mq_id_offset: mq_id_offset)
+        rebase_rule!(rule, rule_id_offset: offset, list_id_offset: list_id_offset, mq_id_offset: mq_id_offset,
+                           cg_id_offset: cg_id_offset)
         @rules << rule
       end
       @_last_rule_id = offset + new_rules.length
@@ -1263,7 +1319,8 @@ module Cataract
       # Build parse options for imported CSS
       parse_opts = {
         import: opts.merge(imported_urls: imported_urls_copy, depth: depth + 1, base_uri: imported_base_uri),
-        parser: @parser_options.dup # Inherit parent's parser options (including selector_lists)
+        parser: @parser_options.dup, # Inherit parent's parser options (including selector_lists)
+        backend: @backend # Imported stylesheets are produced by the same backend as their parent
       }
 
       # If URL conversion is enabled (base_uri present), enable it for imported files too
@@ -1301,7 +1358,8 @@ module Cataract
     # @return [void]
     def merge_imported_sheet!(imported_sheet, import)
       mq_id_offset = merge_media_queries!(imported_sheet.media_queries)
-      rebase_imported_rules_media_query!(imported_sheet.rules, mq_id_offset, import.media_query_id)
+      cg_id_offset = merge_conditional_groups!(imported_sheet.conditional_groups)
+      rebase_imported_rules!(imported_sheet.rules, mq_id_offset, cg_id_offset, import.media_query_id)
 
       insert_position = import.id
       imported_sheet.rules.each_with_index do |rule, idx|
@@ -1312,15 +1370,16 @@ module Cataract
       merge_media_query_lists!(imported_sheet.media_query_lists, mq_id_offset: mq_id_offset)
     end
 
-    # Rebase every imported rule/at-rule's media_query_id onto this
-    # stylesheet's own @media_queries (now that the imported sheet's own
-    # media queries have been merged in), then, if the @import statement
-    # itself had a media qualifier, combine it with (or assign it to) each
-    # rule's media context.
+    # Rebase every imported rule/at-rule's media_query_id and
+    # conditional_group_id onto this stylesheet's own @media_queries/
+    # @conditional_groups (now that the imported sheet's own copies have
+    # been merged in), then, if the @import statement itself had a media
+    # qualifier, combine it with (or assign it to) each rule's media
+    # context.
     #
     # @return [void]
-    def rebase_imported_rules_media_query!(imported_rules, mq_id_offset, import_media_query_id)
-      imported_rules.each { |rule| rebase_rule!(rule, rule_id_offset: 0, mq_id_offset: mq_id_offset) }
+    def rebase_imported_rules!(imported_rules, mq_id_offset, cg_id_offset, import_media_query_id)
+      imported_rules.each { |rule| rebase_rule!(rule, rule_id_offset: 0, mq_id_offset: mq_id_offset, cg_id_offset: cg_id_offset) }
 
       return unless import_media_query_id
 

data/lib/cataract/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Cataract
-  VERSION = '0.3.0'
+  VERSION = '0.5.0'
 end

data/lib/cataract.rb

@@ -1,34 +1,18 @@
 # frozen_string_literal: true
 
-require_relative 'cataract/version'
-require_relative 'cataract/error'
-require_relative 'cataract/constants'
-
-# Load struct definitions first (before C extension or pure Ruby)
-require_relative 'cataract/declaration'
-require_relative 'cataract/rule'
-require_relative 'cataract/at_rule'
-require_relative 'cataract/media_query'
-require_relative 'cataract/import_statement'
-
-# Load pure Ruby or C extension based on ENV var
-if %w[1 true].include?(ENV.fetch('CATARACT_PURE', nil)) || RUBY_ENGINE == 'jruby'
-  require_relative 'cataract/pure'
-else
-  require_relative 'cataract/native_extension'
-end
-
-# Load supporting Ruby files (used by both implementations)
-require_relative 'cataract/stylesheet_scope'
-require_relative 'cataract/stylesheet'
-require_relative 'cataract/declarations'
-require_relative 'cataract/import_resolver'
-
 # Cataract is a high-performance CSS parser written in C with a Ruby interface.
 #
 # It provides fast CSS parsing, rule querying, cascade merging, and serialization.
 # Designed for performance-critical applications that need to process large amounts of CSS.
 #
+# Pure Ruby and native each live entirely under their own Backends::Pure /
+# Backends::Native namespace (no shared method/constant is ever defined by
+# a backend directly on Cataract or on a shared value type), so both can be
+# required in the same process - e.g. to compare their output directly.
+# Backends.active is the one this process picked by default (below); it's
+# what shared value types (Stylesheet, Declarations, Rule) fall back to
+# when they aren't otherwise told which backend produced them.
+#
 # @example Basic usage
 #   require 'cataract'
 #
@@ -44,6 +28,33 @@ require_relative 'cataract/import_resolver'
 # @see Stylesheet Main class for working with parsed CSS
 # @see Rule Represents individual CSS rules
 module Cataract
+  module Backends
+    class << self
+      attr_accessor :active
+    end
+  end
+end
+
+if %w[1 true].include?(ENV.fetch('CATARACT_PURE', nil)) || RUBY_ENGINE == 'jruby'
+  require_relative 'cataract/pure'
+  Cataract::Backends.active = Cataract::Backends::Pure
+else
+  require_relative 'cataract/native'
+  Cataract::Backends.active = Cataract::Backends::Native
+end
+
+module Cataract
+  # Mirror the active backend's identity constants at the top level.
+  #
+  # Native is a Module (IMPLEMENTATION/COMPILE_FLAGS live on it directly);
+  # Pure is a frozen instance (they live on its class instead), so reach
+  # through .class only when active isn't already a Module itself.
+  backend_const_holder = Backends.active.is_a?(Module) ? Backends.active : Backends.active.class
+  IMPLEMENTATION = backend_const_holder::IMPLEMENTATION
+  COMPILE_FLAGS = backend_const_holder::COMPILE_FLAGS
+  NATIVE_EXTENSION_LOADED = true if defined?(Backends::Native) && Backends.active == Backends::Native
+  PURE_RUBY_LOADED = true if defined?(Backends::Pure) && Backends.active == Backends::Pure
+
   class << self
     # Parse a CSS string into a Stylesheet object.
     #
@@ -75,10 +86,8 @@ module Cataract
     #
     # @see Stylesheet#parse
     # @see Stylesheet.parse
-    unless method_defined?(:parse_css)
-      def parse_css(css, **options)
-        Stylesheet.parse(css, **options)
-      end
+    def parse_css(css, **options)
+      Stylesheet.parse(css, **options)
     end
 
     # Flatten CSS rules according to CSS cascade rules.
@@ -113,9 +122,11 @@ module Cataract
     #
     # @note This is a module-level convenience method. The same functionality is available
     #   as an instance method: `stylesheet.flatten`
-    # @note Implemented in C (see ext/cataract/flatten.c)
     #
     # @see Stylesheet#flatten
-    # Cataract.flatten is defined in C via rb_define_module_function
+    def flatten(stylesheet_or_css)
+      stylesheet_or_css = Stylesheet.parse(stylesheet_or_css) if stylesheet_or_css.is_a?(String)
+      stylesheet_or_css.flatten
+    end
   end
 end

data/lib/tasks/profile.rake

@@ -35,7 +35,7 @@ namespace :profile do
     puts "CSS size: #{css_content.bytesize} bytes"
     puts
 
-    require_relative '../../lib/cataract/pure'
+    require_relative '../../lib/cataract'
     require 'json'
 
     # Use higher sampling rate (interval in microseconds, default is 1000)
@@ -74,6 +74,9 @@ namespace :profile do
       abort('stackprof gem not found. Install with: gem install stackprof')
     end
 
+    # Ensure we're using pure Ruby implementation
+    ENV['CATARACT_PURE'] = '1'
+
     fixture_path = File.expand_path('../../test/fixtures/bootstrap.css', __dir__)
     unless File.exist?(fixture_path)
       abort("Fixture not found: #{fixture_path}")
@@ -94,7 +97,7 @@ namespace :profile do
     puts "CSS size: #{css_content.bytesize} bytes"
     puts
 
-    require_relative '../../lib/cataract/pure'
+    require_relative '../../lib/cataract'
     require 'json'
 
     # Parse once outside profiling to get stylesheet
@@ -162,7 +165,7 @@ namespace :profile do
     puts "CSS size: #{css_content.bytesize} bytes"
     puts
 
-    require_relative '../../lib/cataract/pure'
+    require_relative '../../lib/cataract'
     require 'json'
 
     # Parse once outside profiling to get stylesheet

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cataract
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - James Cook
@@ -29,6 +29,7 @@ files:
 - ".overcommit.yml"
 - ".rubocop.yml"
 - ".rubocop_todo.yml"
+- ".yardopts"
 - BENCHMARKS.md
 - CHANGELOG.md
 - Gemfile
@@ -69,6 +70,7 @@ files:
 - lib/cataract.rb
 - lib/cataract/at_rule.rb
 - lib/cataract/color_conversion.rb
+- lib/cataract/conditional_group.rb
 - lib/cataract/constants.rb
 - lib/cataract/declaration.rb
 - lib/cataract/declarations.rb
@@ -76,10 +78,11 @@ files:
 - lib/cataract/import_resolver.rb
 - lib/cataract/import_statement.rb
 - lib/cataract/media_query.rb
+- lib/cataract/native.rb
 - lib/cataract/pure.rb
 - lib/cataract/pure/byte_constants.rb
+- lib/cataract/pure/declarations.rb
 - lib/cataract/pure/flatten.rb
-- lib/cataract/pure/helpers.rb
 - lib/cataract/pure/parser.rb
 - lib/cataract/pure/serializer.rb
 - lib/cataract/pure/specificity.rb

data/lib/cataract/pure/helpers.rb

@@ -1,35 +0,0 @@
-# frozen_string_literal: true
-
-# Pure Ruby CSS parser - Helper methods
-# NO REGEXP ALLOWED - char-by-char parsing only
-
-module Cataract
-  # Check if a byte is whitespace (space, tab, newline, CR)
-  # @param byte [Integer] Byte value from String#getbyte
-  # @return [Boolean] true if whitespace
-  def self.is_whitespace?(byte)
-    byte == BYTE_SPACE || byte == BYTE_TAB || byte == BYTE_NEWLINE || byte == BYTE_CR
-  end
-
-  # Check if byte is a letter (a-z, A-Z)
-  # @param byte [Integer] Byte value from String#getbyte
-  # @return [Boolean] true if letter
-  def self.letter?(byte)
-    (byte >= BYTE_LOWER_A && byte <= BYTE_LOWER_Z) ||
-    (byte >= BYTE_UPPER_A && byte <= BYTE_UPPER_Z)
-  end
-
-  # Check if byte is a digit (0-9)
-  # @param byte [Integer] Byte value from String#getbyte
-  # @return [Boolean] true if digit
-  def self.digit?(byte)
-    byte >= BYTE_DIGIT_0 && byte <= BYTE_DIGIT_9
-  end
-
-  # 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 self.ident_char?(byte)
-    letter?(byte) || digit?(byte) || byte == BYTE_HYPHEN || byte == BYTE_UNDERSCORE
-  end
-end