p_css 0.1.0

data/lib/css/selectors/parser.rb

@@ -0,0 +1,395 @@
+module CSS
+  module Selectors
+    # Parser for CSS Selectors Level 4. Covers compound and complex
+    # selectors, the four standard combinators (descendant, child, next-
+    # sibling, subsequent-sibling), pseudo-classes / pseudo-elements
+    # (with recursive parsing of `:not/:is/:where/:has` and AnB parsing of
+    # `:nth-*`), attribute selectors with case-insensitive `i` / `s` flags,
+    # and the `&` nesting selector.
+    #
+    # Out of scope (intermediate plan): namespace prefixes, the column
+    # combinator `||`, and forgiving vs strict selector list distinctions.
+    class Parser
+      include CSS::TokenCursor
+
+      # `:has()` is intentionally excluded — it takes a *relative* selector
+      # list (each item may start with a combinator) which would require
+      # extending the ComplexSelector AST. Falls back to opaque component
+      # values for now.
+      SELECTOR_LIST_PSEUDOS = %w[is where not matches].freeze
+      ANB_PSEUDOS           = %w[nth-child nth-last-child nth-of-type nth-last-of-type].freeze
+
+      ATTR_MATCHERS = {
+        '~' => :includes,
+        '|' => :dash,
+        '^' => :prefix,
+        '$' => :suffix,
+        '*' => :substring
+      }.freeze
+
+      class << self
+        def parse_selector_list(input)
+          new(tokens_from(input)).parse_selector_list_complete
+        end
+
+        def parse_selector(input)
+          new(tokens_from(input)).parse_selector_complete
+        end
+
+        private
+
+        def tokens_from(input)
+          return Tokenizer.new(input).tokenize if input.is_a?(String)
+
+          flatten_tokens(input.to_a)
+        end
+
+        # Selectors are normally parsed straight from a token stream, but a
+        # caller may pass a `prelude` from the main parser, which contains
+        # `Function` and `SimpleBlock` AST nodes in place of the raw paren
+        # / bracket tokens. Flatten those back into a token sequence the
+        # selector parser can step through.
+        def flatten_tokens(items)
+          out = []
+
+          items.each {|it|
+            case it
+            when Token
+              out << it
+            when Nodes::SimpleBlock
+              out << Token.new(BRACKET_TYPE_FOR_OPEN.fetch(it.open))
+              out.concat(flatten_tokens(it.value))
+              out << Token.new(BRACKET_CLOSE_TYPE_FOR_OPEN.fetch(it.open))
+            when Nodes::Function
+              out << Token.new(:function, it.name)
+              out.concat(flatten_tokens(it.value))
+              out << Token.new(:rparen)
+            else
+              raise ArgumentError, "cannot feed #{it.class} into selector parser"
+            end
+          }
+
+          out
+        end
+      end
+
+      BRACKET_TYPE_FOR_OPEN       = BRACKET_OPEN_CHAR.invert.freeze
+      BRACKET_CLOSE_TYPE_FOR_OPEN = BRACKET_OPEN_CHAR.to_h {|type, ch| [ch, BRACKET_CLOSE_TYPE.fetch(type)] }.freeze
+
+      def initialize(tokens)
+        init_cursor(tokens)
+      end
+
+      def parse_selector_list_complete
+        list = parse_selector_list
+
+        skip_whitespace
+
+        parse_error!("trailing tokens after selector list: #{peek.type}") unless peek.type == :eof
+
+        list
+      end
+
+      def parse_selector_complete
+        skip_whitespace
+
+        cs = parse_complex_selector
+
+        skip_whitespace
+
+        parse_error!("trailing tokens after selector: #{peek.type}") unless peek.type == :eof
+
+        cs
+      end
+
+      # A comma-separated list of complex selectors, terminated by EOF or
+      # `)` (for use inside functional pseudos like `:is(...)`).
+      def parse_selector_list
+        skip_whitespace
+
+        parse_error!('empty selector list') if list_terminator?(peek)
+
+        selectors = [parse_complex_selector]
+
+        loop do
+          skip_whitespace
+          break unless peek.type == :comma
+
+          consume
+          skip_whitespace
+          selectors << parse_complex_selector
+        end
+
+        SelectorList.new(selectors:)
+      end
+
+      def parse_complex_selector
+        skip_whitespace
+
+        compounds   = [parse_compound_selector]
+        combinators = []
+
+        loop do
+          combo = try_consume_combinator
+          break if combo.nil?
+
+          compounds   << parse_compound_selector
+          combinators << combo
+        end
+
+        ComplexSelector.new(compounds:, combinators:)
+      end
+
+      private
+
+      def consume_whitespace_returning_bool
+        consumed = false
+
+        while peek.type == :whitespace
+          consume
+          consumed = true
+        end
+
+        consumed
+      end
+
+      def list_terminator?(t)
+        t.type == :eof || t.type == :rparen
+      end
+
+      def try_consume_combinator
+        saved  = @pos
+        had_ws = consume_whitespace_returning_bool
+
+        t = peek
+
+        if t.type == :delim && (combo = combinator_for_delim(t.value))
+          consume
+          skip_whitespace
+          return combo
+        end
+
+        if had_ws && compound_selector_ahead?(t)
+          return :descendant
+        end
+
+        @pos = saved
+        nil
+      end
+
+      def combinator_for_delim(value)
+        case value
+        when '>' then :child
+        when '+' then :next_sibling
+        when '~' then :subsequent_sibling
+        end
+      end
+
+      def compound_selector_ahead?(t)
+        case t.type
+        when :ident, :hash, :lbracket, :colon
+          true
+        when :delim
+          %w[* . &].include?(t.value)
+        else
+          false
+        end
+      end
+
+      def parse_compound_selector
+        components = []
+
+        if (head = try_consume_type_or_universal)
+          components << head
+        end
+
+        loop do
+          sub = try_consume_subclass_or_pseudo
+          break if sub.nil?
+
+          components << sub
+        end
+
+        parse_error!('expected a compound selector') if components.empty?
+
+        CompoundSelector.new(components:)
+      end
+
+      def try_consume_type_or_universal
+        case peek.type
+        when :ident
+          TypeSelector.new(name: consume.value)
+        when :delim
+          case peek.value
+          when '*' then consume; UniversalSelector.new
+          when '&' then consume; NestingSelector.new
+          end
+        end
+      end
+
+      def try_consume_subclass_or_pseudo
+        case peek.type
+        when :hash
+          parse_id_selector
+        when :lbracket
+          parse_attribute_selector
+        when :colon
+          parse_pseudo
+        when :delim
+          case peek.value
+          when '.' then parse_class_selector
+          when '&' then consume; NestingSelector.new
+          end
+        end
+      end
+
+      def parse_id_selector
+        t = consume
+
+        parse_error!('id hash must be a valid identifier') unless t.flag == :id
+
+        IdSelector.new(name: t.value)
+      end
+
+      def parse_class_selector
+        consume # the '.'
+
+        parse_error!("expected ident after '.', got #{peek.type}") unless peek.type == :ident
+
+        ClassSelector.new(name: consume.value)
+      end
+
+      def parse_attribute_selector
+        consume # [
+        skip_whitespace
+
+        parse_error!('expected attribute name') unless peek.type == :ident
+
+        name = consume.value
+
+        skip_whitespace
+
+        matcher, value = parse_attr_matcher_and_value
+        case_flag      = parse_attr_case_flag
+
+        skip_whitespace
+
+        parse_error!("expected ']', got #{peek.type}") unless peek.type == :rbracket
+
+        consume
+
+        AttributeSelector.new(name:, matcher:, value:, case_flag:)
+      end
+
+      def parse_attr_matcher_and_value
+        return [nil, nil] if peek.type == :rbracket
+
+        matcher =
+          if peek.type == :delim && peek.value == '='
+            consume
+            :exact
+          elsif peek.type == :delim && (sym = ATTR_MATCHERS[peek.value])
+            consume
+            unless peek.type == :delim && peek.value == '='
+              parse_error!("expected '=' to complete attribute matcher")
+            end
+            consume
+            sym
+          else
+            parse_error!("invalid attribute matcher: #{peek.type}")
+          end
+
+        skip_whitespace
+
+        unless peek.type == :ident || peek.type == :string
+          parse_error!("expected attribute value, got #{peek.type}")
+        end
+
+        [matcher, consume.value]
+      end
+
+      def parse_attr_case_flag
+        skip_whitespace
+
+        return nil unless peek.type == :ident
+
+        v = peek.value.downcase
+        return nil unless v == 'i' || v == 's'
+
+        consume
+        v.to_sym
+      end
+
+      def parse_pseudo
+        consume # first colon
+
+        if peek.type == :colon
+          consume
+          parse_pseudo_body(element: true)
+        else
+          parse_pseudo_body(element: false)
+        end
+      end
+
+      def parse_pseudo_body(element:)
+        case peek.type
+        when :ident
+          name = consume.value
+          build_pseudo(element:, name:, argument: nil)
+        when :function
+          name = consume.value
+          arg  = parse_pseudo_argument(name)
+
+          parse_error!("expected ')' to close :#{name}") unless peek.type == :rparen
+
+          consume
+          build_pseudo(element:, name:, argument: arg)
+        else
+          parse_error!("expected pseudo-#{element ? 'element' : 'class'} name, got #{peek.type}")
+        end
+      end
+
+      def build_pseudo(element:, name:, argument:)
+        element ? PseudoElement.new(name:, argument:) : PseudoClass.new(name:, argument:)
+      end
+
+      def parse_pseudo_argument(name)
+        n = name.downcase
+
+        if SELECTOR_LIST_PSEUDOS.include?(n)
+          parse_selector_list
+        elsif ANB_PSEUDOS.include?(n)
+          AnBParser.parse(collect_argument_tokens)
+        else
+          collect_argument_tokens
+        end
+      end
+
+      # Collects all tokens up to the closing `)` of the current functional
+      # context, balancing nested parens / functions.
+      def collect_argument_tokens
+        inner = []
+        depth = 0
+
+        loop do
+          case peek.type
+          when :eof
+            parse_error!('unexpected EOF in pseudo argument')
+          when :function, :lparen
+            depth += 1
+            inner << consume
+          when :rparen
+            break if depth.zero?
+
+            depth -= 1
+            inner << consume
+          else
+            inner << consume
+          end
+        end
+
+        inner
+      end
+    end
+  end
+end

data/lib/css/selectors/serializer.rb

@@ -0,0 +1,102 @@
+module CSS
+  module Selectors
+    module Serializer
+      extend self
+
+      COMBINATOR_GLUE = {
+        descendant:          ' ',
+        child:               ' > ',
+        next_sibling:        ' + ',
+        subsequent_sibling:  ' ~ '
+      }.freeze
+
+      ATTR_OPS = {
+        exact:     '=',
+        includes:  '~=',
+        dash:      '|=',
+        prefix:    '^=',
+        suffix:    '$=',
+        substring: '*='
+      }.freeze
+
+      def serialize(node)
+        case node
+        when SelectorList      then node.selectors.map { serialize(it) }.join(', ')
+        when ComplexSelector   then serialize_complex(node)
+        when CompoundSelector  then node.components.map { serialize(it) }.join
+        when TypeSelector      then Escape.ident(node.name)
+        when UniversalSelector then '*'
+        when NestingSelector   then '&'
+        when IdSelector        then "##{Escape.ident(node.name)}"
+        when ClassSelector     then ".#{Escape.ident(node.name)}"
+        when AttributeSelector then serialize_attribute(node)
+        when PseudoClass       then serialize_pseudo(node, '')
+        when PseudoElement     then serialize_pseudo(node, ':')
+        when AnB               then serialize_anb(node)
+        else
+          raise ArgumentError, "cannot serialize selector node #{node.class}"
+        end
+      end
+
+      private
+
+      def serialize_complex(cs)
+        out = +serialize(cs.compounds[0])
+
+        cs.combinators.each_with_index {|combo, i|
+          out << COMBINATOR_GLUE.fetch(combo) << serialize(cs.compounds[i + 1])
+        }
+
+        out
+      end
+
+      def serialize_attribute(attr)
+        out = +"[#{Escape.ident(attr.name)}"
+
+        if attr.matcher
+          out << ATTR_OPS.fetch(attr.matcher) << Escape.string(attr.value.to_s)
+          out << " #{attr.case_flag}" if attr.case_flag
+        end
+
+        out << ']'
+      end
+
+      def serialize_pseudo(node, extra_colon)
+        head = ":#{extra_colon}#{Escape.ident(node.name)}"
+
+        return head if node.argument.nil?
+
+        "#{head}(#{serialize_argument(node.argument)})"
+      end
+
+      def serialize_argument(arg)
+        case arg
+        when SelectorList then serialize(arg)
+        when AnB          then serialize_anb(arg)
+        when Array        then CSS::Serializer.serialize(arg)
+        else
+          raise ArgumentError, "unknown pseudo argument #{arg.class}"
+        end
+      end
+
+      def serialize_anb(anb)
+        return 'even' if anb.step == 2 && anb.offset.zero?
+        return 'odd'  if anb.step == 2 && anb.offset == 1
+
+        return anb.offset.to_s if anb.step.zero?
+
+        step_str =
+          case anb.step
+          when 1  then 'n'
+          when -1 then '-n'
+          else        "#{anb.step}n"
+          end
+
+        return step_str if anb.offset.zero?
+
+        sign = anb.offset.positive? ? '+' : '-'
+        "#{step_str}#{sign}#{anb.offset.abs}"
+      end
+    end
+  end
+end

data/lib/css/selectors/specificity.rb

@@ -0,0 +1,81 @@
+module CSS
+  module Selectors
+    # Selectors §16 specificity tuple `(a, b, c)`.
+    #   a = id selectors
+    #   b = class / attribute / pseudo-class selectors
+    #   c = type / pseudo-element selectors
+    Specificity = Data.define(:a, :b, :c) do
+      include Comparable
+
+      # Avoids the per-call allocation of two 3-element arrays — this
+      # comparison runs many times in the cascade-sort hot path.
+      def <=>(other)
+        return nil unless other.is_a?(Specificity)
+
+        d = a - other.a
+        return d unless d.zero?
+
+        d = b - other.b
+        return d unless d.zero?
+
+        c - other.c
+      end
+
+      def +(other)
+        Specificity.new(a: a + other.a, b: b + other.b, c: c + other.c)
+      end
+
+      def to_s = "#{a},#{b},#{c}"
+    end
+
+    Specificity::ZERO = Specificity.new(a: 0, b: 0, c: 0).freeze
+
+    # Computes specificity for any selector AST node.
+    #
+    # Note on the nesting selector (`&`): without parent context its
+    # specificity is conservatively reported as zero. Callers wanting
+    # accurate cascade behavior should run `CSS.desugar(stylesheet)` first
+    # so `&` is replaced by the parent's compounds.
+    module SpecificityCalculator
+      extend self
+
+      def calculate(node)
+        case node
+        when SelectorList     then node.selectors.map { calculate(it) }.max || Specificity::ZERO
+        when ComplexSelector  then sum(node.compounds)
+        when CompoundSelector then sum(node.components)
+        when IdSelector       then Specificity.new(a: 1, b: 0, c: 0)
+        when ClassSelector,
+             AttributeSelector then Specificity.new(a: 0, b: 1, c: 0)
+        when TypeSelector     then Specificity.new(a: 0, b: 0, c: 1)
+        when PseudoElement    then Specificity.new(a: 0, b: 0, c: 1)
+        when PseudoClass      then specificity_of_pseudo_class(node)
+        when UniversalSelector,
+             NestingSelector  then Specificity::ZERO
+        else                       Specificity::ZERO
+        end
+      end
+
+      private
+
+      def sum(items)
+        items.map { calculate(it) }.reduce(Specificity::ZERO, :+)
+      end
+
+      def specificity_of_pseudo_class(node)
+        case node.name.downcase
+        when 'where'
+          Specificity::ZERO
+        when 'is', 'not', 'has', 'matches'
+          if node.argument.is_a?(SelectorList)
+            calculate(node.argument)
+          else
+            Specificity.new(a: 0, b: 1, c: 0)
+          end
+        else
+          Specificity.new(a: 0, b: 1, c: 0)
+        end
+      end
+    end
+  end
+end

data/lib/css/selectors.rb

@@ -0,0 +1,11 @@
+require_relative 'selectors/nodes'
+require_relative 'selectors/anb_parser'
+require_relative 'selectors/parser'
+require_relative 'selectors/serializer'
+require_relative 'selectors/specificity'
+require_relative 'selectors/matcher'
+
+module CSS
+  module Selectors
+  end
+end