cataract 0.3.0 → 0.4.0

data/lib/cataract/native.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+# Native (C extension) backend for Cataract.
+#
+# Load this instead of the pure Ruby version by NOT 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):
+#   require 'cataract'
+
+require_relative 'error'
+require_relative 'version'
+require_relative 'constants'
+
+# Load struct definitions first (before the C extension) - the extension's
+# Init function looks these up and raises if they're missing.
+require_relative 'declaration'
+require_relative 'rule'
+require_relative 'at_rule'
+require_relative 'media_query'
+require_relative 'import_statement'
+
+require_relative 'native_extension'
+
+# Load supporting Ruby files (used by both implementations)
+require_relative 'stylesheet_scope'
+require_relative 'stylesheet'
+require_relative 'declarations'
+require_relative 'import_resolver'

data/lib/cataract/pure/byte_constants.rb

@@ -4,80 +4,84 @@
 # Using getbyte() instead of String#[] to avoid allocating millions of string objects
 
 module Cataract
-  # Whitespace bytes
-  BYTE_SPACE     = 32  # ' '
-  BYTE_TAB       = 9   # '\t'
-  BYTE_NEWLINE   = 10  # '\n'
-  BYTE_CR        = 13  # '\r'
+  module Backends
+    class PureImpl
+      # Whitespace bytes
+      BYTE_SPACE     = 32  # ' '
+      BYTE_TAB       = 9   # '\t'
+      BYTE_NEWLINE   = 10  # '\n'
+      BYTE_CR        = 13  # '\r'
 
-  # CSS structural characters
-  BYTE_AT        = 64  # '@'
-  BYTE_LBRACE    = 123 # '{'
-  BYTE_RBRACE    = 125 # '}'
-  BYTE_LPAREN    = 40  # '('
-  BYTE_RPAREN    = 41  # ')'
-  BYTE_LBRACKET  = 91  # '['
-  BYTE_RBRACKET  = 93  # ']'
-  BYTE_SEMICOLON = 59  # ';'
-  BYTE_COLON     = 58  # ':'
-  BYTE_COMMA     = 44  # ','
+      # CSS structural characters
+      BYTE_AT        = 64  # '@'
+      BYTE_LBRACE    = 123 # '{'
+      BYTE_RBRACE    = 125 # '}'
+      BYTE_LPAREN    = 40  # '('
+      BYTE_RPAREN    = 41  # ')'
+      BYTE_LBRACKET  = 91  # '['
+      BYTE_RBRACKET  = 93  # ']'
+      BYTE_SEMICOLON = 59  # ';'
+      BYTE_COLON     = 58  # ':'
+      BYTE_COMMA     = 44  # ','
 
-  # Comment characters
-  BYTE_SLASH     = 47  # '/'
-  BYTE_STAR      = 42  # '*'
+      # Comment characters
+      BYTE_SLASH     = 47  # '/'
+      BYTE_STAR      = 42  # '*'
 
-  # Quote characters
-  BYTE_SQUOTE    = 39  # "'"
-  BYTE_DQUOTE    = 34  # '"'
+      # Quote characters
+      BYTE_SQUOTE    = 39  # "'"
+      BYTE_DQUOTE    = 34  # '"'
 
-  # Selector characters
-  BYTE_HASH      = 35  # '#'
-  BYTE_DOT       = 46  # '.'
-  BYTE_GT        = 62  # '>'
-  BYTE_PLUS      = 43  # '+'
-  BYTE_TILDE     = 126 # '~'
-  BYTE_ASTERISK  = 42  # '*'
-  BYTE_AMPERSAND = 38  # '&'
+      # Selector characters
+      BYTE_HASH      = 35  # '#'
+      BYTE_DOT       = 46  # '.'
+      BYTE_GT        = 62  # '>'
+      BYTE_PLUS      = 43  # '+'
+      BYTE_TILDE     = 126 # '~'
+      BYTE_ASTERISK  = 42  # '*'
+      BYTE_AMPERSAND = 38  # '&'
 
-  # Other
-  BYTE_HYPHEN     = 45 # '-'
-  BYTE_UNDERSCORE = 95 # '_'
-  BYTE_BACKSLASH  = 92 # '\\'
-  BYTE_BANG       = 33 # '!'
-  BYTE_PERCENT    = 37 # '%'
-  BYTE_EQUALS     = 61 # '='
-  BYTE_CARET      = 94 # '^'
-  BYTE_DOLLAR     = 36 # '$'
-  BYTE_PIPE       = 124 # '|'
+      # Other
+      BYTE_HYPHEN     = 45 # '-'
+      BYTE_UNDERSCORE = 95 # '_'
+      BYTE_BACKSLASH  = 92 # '\\'
+      BYTE_BANG       = 33 # '!'
+      BYTE_PERCENT    = 37 # '%'
+      BYTE_EQUALS     = 61 # '='
+      BYTE_CARET      = 94 # '^'
+      BYTE_DOLLAR     = 36 # '$'
+      BYTE_PIPE       = 124 # '|'
 
-  # Specific lowercase letters (for keyword matching)
-  BYTE_LOWER_U    = 117 # 'u'
-  BYTE_LOWER_R    = 114 # 'r'
-  BYTE_LOWER_L    = 108 # 'l'
-  BYTE_LOWER_D    = 100 # 'd'
-  BYTE_LOWER_T    = 116 # 't'
-  BYTE_LOWER_N    = 110 # 'n'
+      # Specific lowercase letters (for keyword matching)
+      BYTE_LOWER_U    = 117 # 'u'
+      BYTE_LOWER_R    = 114 # 'r'
+      BYTE_LOWER_L    = 108 # 'l'
+      BYTE_LOWER_D    = 100 # 'd'
+      BYTE_LOWER_T    = 116 # 't'
+      BYTE_LOWER_N    = 110 # 'n'
 
-  # Specific uppercase letters (for case-insensitive matching)
-  BYTE_UPPER_U    = 85  # 'U'
-  BYTE_UPPER_R    = 82  # 'R'
-  BYTE_UPPER_L    = 76  # 'L'
-  BYTE_UPPER_D    = 68  # 'D'
-  BYTE_UPPER_T    = 84  # 'T'
-  BYTE_UPPER_N    = 78  # 'N'
+      # Specific uppercase letters (for case-insensitive matching)
+      BYTE_UPPER_U    = 85  # 'U'
+      BYTE_UPPER_R    = 82  # 'R'
+      BYTE_UPPER_L    = 76  # 'L'
+      BYTE_UPPER_D    = 68  # 'D'
+      BYTE_UPPER_T    = 84  # 'T'
+      BYTE_UPPER_N    = 78  # 'N'
 
-  # Letter ranges (a-z, A-Z)
-  BYTE_LOWER_A   = 97  # 'a'
-  BYTE_LOWER_Z   = 122 # 'z'
-  BYTE_UPPER_A   = 65  # 'A'
-  BYTE_UPPER_Z   = 90  # 'Z'
-  BYTE_CASE_DIFF = 32  # Difference between lowercase and uppercase ('a' - 'A')
+      # Letter ranges (a-z, A-Z)
+      BYTE_LOWER_A   = 97  # 'a'
+      BYTE_LOWER_Z   = 122 # 'z'
+      BYTE_UPPER_A   = 65  # 'A'
+      BYTE_UPPER_Z   = 90  # 'Z'
+      BYTE_CASE_DIFF = 32  # Difference between lowercase and uppercase ('a' - 'A')
 
-  # Digit range (0-9)
-  BYTE_DIGIT_0   = 48  # '0'
-  BYTE_DIGIT_9   = 57  # '9'
+      # Digit range (0-9)
+      BYTE_DIGIT_0   = 48  # '0'
+      BYTE_DIGIT_9   = 57  # '9'
 
-  # Nesting styles (for CSS nesting support)
-  NESTING_STYLE_IMPLICIT = 0  # Implicit nesting: .parent { .child { ... } } => .parent .child
-  NESTING_STYLE_EXPLICIT = 1  # Explicit nesting: .parent { &:hover { ... } } => .parent:hover
+      # Nesting styles (for CSS nesting support)
+      NESTING_STYLE_IMPLICIT = 0  # Implicit nesting: .parent { .child { ... } } => .parent .child
+      NESTING_STYLE_EXPLICIT = 1  # Explicit nesting: .parent { &:hover { ... } } => .parent:hover
+    end
+  end
 end

data/lib/cataract/pure/declarations.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+# Pure Ruby CSS parser - standalone declaration-list string parsing
+# NO REGEXP ALLOWED - char-by-char parsing only
+#
+# Backs Declarations.new(some_string), NOT the main parser's declaration
+# handling - the two intentionally disagree in a few ways:
+#   - Custom properties (--foo) are downcased here too (the main parser
+#     preserves their case, since they're case-sensitive per spec)
+#   - No relative-URL conversion (there's no base_uri to convert against)
+#   - A missing colon stops parsing entirely, rather than recovering at the
+#     next semicolon like the main parser does
+# Mirrors ext/cataract/cataract.c's new_parse_declarations_string exactly,
+# byte for byte, since both backends must agree here.
+
+module Cataract
+  module Backends
+    class PureImpl
+      # Parse a standalone CSS declaration-list string ("color: red; margin: 10px")
+      # into an array of Declaration structs.
+      #
+      # @param str [String] CSS declarations, optionally wrapped in { ... }
+      # @return [Array<Declaration>] Parsed declarations
+      def parse_declarations(str)
+        fin = str.bytesize
+        pos = 0
+
+        # Strip outer braces and whitespace (css_parser compatibility)
+        pos += 1 while pos < fin && (decl_whitespace?(str.getbyte(pos)) || str.getbyte(pos) == BYTE_LBRACE)
+        fin -= 1 while fin > pos && (decl_whitespace?(str.getbyte(fin - 1)) || str.getbyte(fin - 1) == BYTE_RBRACE)
+
+        declarations = []
+
+        while pos < fin
+          pos += 1 while pos < fin && (decl_whitespace?(str.getbyte(pos)) || str.getbyte(pos) == BYTE_SEMICOLON)
+          break if pos >= fin
+
+          span = scan_one_declaration(str, pos, fin)
+          break unless span # No colon found - stop parsing entirely
+
+          pos = span[:next_pos]
+          next unless span[:val_end] > span[:val_start] # Skip if value is empty
+
+          property = str.byteslice(span[:prop_start], span[:prop_end] - span[:prop_start])
+                        .force_encoding(Encoding::US_ASCII).downcase
+          value = str.byteslice(span[:val_start], span[:val_end] - span[:val_start]).force_encoding(Encoding::UTF_8)
+
+          declarations << Declaration.new(property, value, span[:important])
+        end
+
+        declarations
+      end
+
+      # Scans one "prop: value" declaration starting at pos, stopping at fin
+      # (never reads past it). On success, returns a span hash and next_pos is
+      # the position just past the terminating ';' (or fin/'}' if there wasn't
+      # one). On failure - no ':' found - returns nil, leaving the caller to
+      # decide how to recover (this parser stops entirely).
+      #
+      # The value scan tracks paren depth, so a ';' inside url(...) or rgba(...)
+      # doesn't end the value early, and always stops at an unguarded '}'.
+      def scan_one_declaration(str, pos, fin)
+        prop_start = pos
+        pos += 1 while pos < fin && str.getbyte(pos) != BYTE_COLON
+        return nil if pos >= fin
+
+        prop_end = pos
+        prop_end -= 1 while prop_end > prop_start && decl_whitespace?(str.getbyte(prop_end - 1))
+        prop_start += 1 while prop_start < prop_end && decl_whitespace?(str.getbyte(prop_start))
+
+        pos += 1 # Skip ':'
+        pos += 1 while pos < fin && decl_whitespace?(str.getbyte(pos))
+
+        val_start = pos
+        paren_depth = 0
+        while pos < fin && str.getbyte(pos) != BYTE_RBRACE
+          byte = str.getbyte(pos)
+          if byte == BYTE_LPAREN
+            paren_depth += 1
+          elsif byte == BYTE_RPAREN
+            paren_depth -= 1
+          elsif byte == BYTE_SEMICOLON && paren_depth == 0
+            break
+          end
+          pos += 1
+        end
+        val_end = pos
+        val_end -= 1 while val_end > val_start && decl_whitespace?(str.getbyte(val_end - 1))
+
+        important, val_end = extract_important(str, val_start, val_end)
+        val_end -= 1 while val_end > val_start && decl_whitespace?(str.getbyte(val_end - 1))
+
+        pos += 1 if pos < fin && str.getbyte(pos) == BYTE_SEMICOLON
+
+        { prop_start: prop_start, prop_end: prop_end, val_start: val_start, val_end: val_end,
+          important: important, next_pos: pos }
+      end
+      private :scan_one_declaration
+
+      # Detects and strips a trailing '!important' marker from [val_start, val_end).
+      # Assumes trailing whitespace has already been trimmed once. Zero or more
+      # whitespace tokens are allowed between '!' and 'important' per the CSS2.1
+      # grammar. Returns [important?, new_val_end].
+      def extract_important(str, val_start, val_end)
+        check = val_end
+        return [false, val_end] if check - val_start < 10 # strlen("!important") == 10
+
+        check -= 1 while check > val_start && decl_whitespace?(str.getbyte(check - 1))
+        return [false, val_end] if check - val_start < 9 || str.byteslice(check - 9, 9) != 'important'
+
+        check -= 9
+        check -= 1 while check > val_start && decl_whitespace?(str.getbyte(check - 1))
+        return [false, val_end] if check <= val_start || str.getbyte(check - 1) != BYTE_BANG
+
+        [true, check - 1]
+      end
+      private :extract_important
+
+      def decl_whitespace?(byte)
+        byte == BYTE_SPACE || byte == BYTE_TAB || byte == BYTE_NEWLINE || byte == BYTE_CR
+      end
+      private :decl_whitespace?
+    end
+  end
+end