cataract 0.3.0 → 0.4.0

data/lib/cataract/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Cataract
-  VERSION = '0.3.0'
+  VERSION = '0.4.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.4.0
 platform: ruby
 authors:
 - James Cook
@@ -76,10 +76,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