p_css 0.1.0

data/lib/css/nesting.rb

@@ -0,0 +1,229 @@
+module CSS
+  # Desugars CSS Nesting Module Level 1 — replaces `&` with the parent
+  # selector and lifts every nested rule out of its parent. The result is
+  # a flat Stylesheet whose rules contain only declarations and at-rules.
+  #
+  # The substitution favors readable output over conservative correctness
+  # padding: `:is(parent)` wrapping is only emitted when the parent has
+  # multiple selectors, or when a non-lone `&` is mixed into a compound and
+  # the parent has combinators. In simple cases the parent is inlined
+  # directly (`& .x` with parent `.a` → `.a .x`, not `:is(.a) .x`).
+  module Nesting
+    extend self
+
+    def desugar(stylesheet)
+      Nodes::Stylesheet.new(rules: stylesheet.rules.flat_map { desugar_top_level(it) })
+    end
+
+    private
+
+    def desugar_top_level(rule)
+      case rule
+      when Nodes::QualifiedRule
+        desugar_qualified_rule(rule, parent_list: nil)
+      when Nodes::AtRule
+        [desugar_at_rule(rule, parent_list: nil)]
+      else
+        [rule]
+      end
+    end
+
+    # Returns an Array of rules. The first emitted rule (when there are
+    # declarations) carries the parent's own declarations under the
+    # effective selector; subsequent rules are the nested ones recursively
+    # desugared.
+    def desugar_qualified_rule(rule, parent_list:)
+      own       = Selectors::Parser.parse_selector_list(rule.prelude)
+      effective = parent_list ? substitute_nesting(own, parent_list) : own
+
+      decls, rules = partition_block_items(rule.block.items, parent_list: effective)
+
+      output = []
+      output << build_rule_with(effective, decls) unless decls.empty?
+      output.concat(rules)
+      output
+    end
+
+    # Desugars a top-level (or nested) at-rule, recursing into its block
+    # if any.
+    def desugar_at_rule(rule, parent_list:)
+      return rule unless rule.block
+
+      new_items = desugar_at_rule_block_items(rule.block.items, parent_list:)
+
+      Nodes::AtRule.new(
+        name:    rule.name,
+        prelude: rule.prelude,
+        block:   Nodes::Block.new(items: new_items)
+      )
+    end
+
+    # Inside an at-rule's block (e.g. `@media`), declarations need to be
+    # wrapped in a synthesized rule using the parent selector if there is
+    # one (the at-rule itself doesn't carry a selector).
+    def desugar_at_rule_block_items(items, parent_list:)
+      decls, rules = partition_block_items(items, parent_list:)
+
+      output = []
+
+      unless decls.empty?
+        if parent_list
+          output << build_rule_with(parent_list, decls)
+        else
+          output.concat(decls)
+        end
+      end
+
+      output.concat(rules)
+      output
+    end
+
+    # Splits items into (declarations, nested rules). Nested qualified
+    # rules and at-rules are recursively desugared.
+    def partition_block_items(items, parent_list:)
+      decls = []
+      rules = []
+
+      items.each {|item|
+        case item
+        when Nodes::Declaration
+          decls << item
+        when Nodes::QualifiedRule
+          rules.concat(desugar_qualified_rule(item, parent_list:))
+        when Nodes::AtRule
+          rules << desugar_at_rule(item, parent_list:)
+        else
+          decls << item
+        end
+      }
+
+      [decls, rules]
+    end
+
+    def build_rule_with(selector_list, items)
+      Nodes::QualifiedRule.new(
+        prelude: Parser.parse_component_values(Selectors::Serializer.serialize(selector_list)),
+        block:   Nodes::Block.new(items:)
+      )
+    end
+
+    # Substitution
+    # ----------------------------------------------------------------
+
+    def substitute_nesting(own_list, parent_list)
+      Selectors::SelectorList.new(
+        selectors: own_list.selectors.map {|sel|
+          substitute_complex(ensure_nesting(sel), parent_list)
+        }
+      )
+    end
+
+    # Per CSS Nesting §3.1, a selector that doesn't reference `&` has it
+    # implicitly prepended with the descendant combinator. `.b` becomes
+    # `& .b`.
+    def ensure_nesting(complex_selector)
+      return complex_selector if contains_nesting?(complex_selector)
+
+      Selectors::ComplexSelector.new(
+        compounds:   [
+          Selectors::CompoundSelector.new(components: [Selectors::NestingSelector.new]),
+          *complex_selector.compounds
+        ],
+        combinators: [:descendant, *complex_selector.combinators]
+      )
+    end
+
+    def contains_nesting?(complex_selector)
+      complex_selector.compounds.any? {|c|
+        c.components.any? { it.is_a?(Selectors::NestingSelector) }
+      }
+    end
+
+    def substitute_complex(own_complex, parent_list)
+      if parent_list.selectors.size > 1
+        substitute_with_is(own_complex, parent_list)
+      else
+        parent = parent_list.selectors.first
+
+        if parent.compounds.size > 1
+          substitute_inline_compounds(own_complex, parent, parent_list)
+        else
+          substitute_inline_components(own_complex, parent.compounds.first)
+        end
+      end
+    end
+
+    # Multi-selector parent: every `&` becomes `:is(parent_list)`, regardless
+    # of the surrounding compound shape.
+    def substitute_with_is(own_complex, parent_list)
+      replacement = Selectors::PseudoClass.new(name: 'is', argument: parent_list)
+
+      Selectors::ComplexSelector.new(
+        compounds:   own_complex.compounds.map { swap_components_in_compound(it, replacement) },
+        combinators: own_complex.combinators
+      )
+    end
+
+    # Single complex parent with multiple compounds: a lone `&` compound is
+    # spliced in by the parent's compound chain (carrying combinators);
+    # mixed compounds use `:is()` wrapping.
+    def substitute_inline_compounds(own_complex, parent_complex, parent_list)
+      replacement   = Selectors::PseudoClass.new(name: 'is', argument: parent_list)
+      new_compounds = []
+      new_combos    = []
+      pair_combos   = [nil, *own_complex.combinators]
+
+      own_complex.compounds.each_with_index {|compound, i|
+        incoming = pair_combos[i]
+
+        if lone_nesting?(compound)
+          parent_complex.compounds.each_with_index {|pc, j|
+            new_compounds << pc
+
+            if j.zero?
+              new_combos << incoming unless incoming.nil?
+            else
+              new_combos << parent_complex.combinators[j - 1]
+            end
+          }
+        else
+          new_compounds << swap_components_in_compound(compound, replacement)
+          new_combos << incoming unless incoming.nil?
+        end
+      }
+
+      Selectors::ComplexSelector.new(compounds: new_compounds, combinators: new_combos)
+    end
+
+    # Single compound parent: components are spliced in place of `&`,
+    # producing a clean compound (`&.x` with parent `.a` → `.a.x`).
+    def substitute_inline_components(own_complex, parent_compound)
+      Selectors::ComplexSelector.new(
+        compounds:   own_complex.compounds.map {|compound|
+          if lone_nesting?(compound)
+            Selectors::CompoundSelector.new(components: parent_compound.components.dup)
+          else
+            Selectors::CompoundSelector.new(
+              components: compound.components.flat_map {|x|
+                x.is_a?(Selectors::NestingSelector) ? parent_compound.components : [x]
+              }
+            )
+          end
+        },
+        combinators: own_complex.combinators
+      )
+    end
+
+    def swap_components_in_compound(compound, replacement)
+      Selectors::CompoundSelector.new(
+        components: compound.components.map {|x|
+          x.is_a?(Selectors::NestingSelector) ? replacement : x
+        }
+      )
+    end
+
+    def lone_nesting?(compound)
+      compound.components.size == 1 && compound.components.first.is_a?(Selectors::NestingSelector)
+    end
+  end
+end

data/lib/css/nodes.rb

@@ -0,0 +1,42 @@
+module CSS
+  module Nodes
+    # A complete stylesheet: a list of top-level rules.
+    Stylesheet = Data.define(:rules)
+
+    # An at-rule, e.g. `@media (min-width: 600px) { ... }` or `@charset "UTF-8";`.
+    # `prelude` is an array of component values, `block` is a Block or nil.
+    AtRule = Data.define(:name, :prelude, :block)
+
+    # A qualified rule, i.e. a style rule. `prelude` is the selector list as
+    # raw component values, `block` is the body.
+    QualifiedRule = Data.define(:prelude, :block)
+
+    # The body of a qualified rule or at-rule. Contains a list of declarations,
+    # nested qualified rules, and nested at-rules in source order.
+    Block = Data.define(:items)
+
+    # `name: value [!important]`.
+    Declaration = Data.define(:name, :value, :important)
+
+    # A function reference like `rgb(255, 0, 0)`. `value` is an array of
+    # component values.
+    Function = Data.define(:name, :value)
+
+    # A `( ... )`, `[ ... ]`, or `{ ... }` block as a component value.
+    # `open` is one of `(`, `[`, `{`. `value` is an array of component values.
+    SimpleBlock = Data.define(:open, :value) do
+      def braced?      = open == '{'
+      def bracketed?   = open == '['
+      def parenthesized? = open == '('
+    end
+
+    # An inclusive code-point range, e.g. `U+0-7F`. Result of CSS.parse_urange.
+    UnicodeRange = Data.define(:first, :last) do
+      def cover?(cp) = (first..last).cover?(cp)
+
+      def to_s
+        first == last ? format('U+%X', first) : format('U+%X-%X', first, last)
+      end
+    end
+  end
+end

data/lib/css/parser.rb

@@ -0,0 +1,430 @@
+module CSS
+  # Parser based on CSS Syntax Module Level 4 §5, with the nesting extensions
+  # described in CSS Nesting Module Level 1 / Syntax 4.
+  # https://drafts.csswg.org/css-syntax/
+  class Parser
+    include Nodes
+
+    # Shared sentinel returned past the end of the token stream. It has no
+    # position, which is why ParseError messages at EOF show no `line:col:`
+    # prefix.
+    EOF_TOKEN = Token.new(:eof).freeze
+
+    class << self
+      def parse_stylesheet(input, **opts)             = build(input, **opts).parse_stylesheet
+      def parse_rule(input, **opts)                   = build(input, **opts).parse_rule
+      def parse_declaration(input, **opts)            = build(input, **opts).parse_declaration
+      def parse_block_contents(input, **opts)         = build(input, **opts).parse_block_contents
+      def parse_component_value(input, **opts)        = build(input, **opts).parse_component_value
+      def parse_component_values(input, **opts)       = build(input, **opts).parse_component_values
+      def parse_comma_separated_values(input, **opts) = build(input, **opts).parse_comma_separated_values
+
+      private
+
+      def build(input, **opts)
+        tokens = input.is_a?(String) ? Tokenizer.new(input, **opts).tokenize : input.to_a
+        new(tokens)
+      end
+    end
+
+    def initialize(tokens)
+      @tokens = tokens
+      @pos    = 0
+    end
+
+    # §5.3.3.
+    def parse_stylesheet
+      Stylesheet.new(rules: consume_rule_list(top_level: true))
+    end
+
+    # §5.3.4.
+    def parse_rule
+      skip_whitespace
+
+      parse_error!('expected a rule, got end of input') if peek.type == :eof
+
+      rule = if peek.type == :at_keyword
+               consume_at_rule(nested: false)
+             else
+               consume_qualified_rule(nested: false)
+             end
+
+      parse_error!('invalid rule') if rule.nil?
+
+      skip_whitespace
+
+      parse_error!("unexpected token after rule: #{peek.type}") unless peek.type == :eof
+
+      rule
+    end
+
+    # §5.3.5. Per spec, trailing tokens after the declaration are ignored.
+    def parse_declaration
+      skip_whitespace
+
+      parse_error!('expected a declaration') unless peek.type == :ident
+
+      decl = try_consume_declaration
+
+      parse_error!('invalid declaration') unless decl
+
+      decl
+    end
+
+    # §5.4.4. Used for parsing the contents of a `style="..."` attribute,
+    # `@page` blocks, and similar contexts where there is no enclosing `{}`.
+    def parse_block_contents
+      Block.new(items: collect_block_items(stop_at_close_brace: false))
+    end
+
+    # §5.3.7.
+    def parse_component_value
+      skip_whitespace
+
+      parse_error!('expected a component value') if peek.type == :eof
+
+      cv = consume_component_value
+
+      skip_whitespace
+
+      parse_error!("unexpected token after component value: #{peek.type}") unless peek.type == :eof
+
+      cv
+    end
+
+    # §5.3.8.
+    def parse_component_values
+      values = []
+      values << consume_component_value until peek.type == :eof
+      values
+    end
+
+    # §5.3.9. Empty input produces `[[]]`; a trailing comma produces a
+    # trailing empty group.
+    def parse_comma_separated_values
+      groups  = []
+      current = []
+
+      loop do
+        case peek.type
+        when :eof
+          groups << current
+          return groups
+        when :comma
+          consume
+          groups << current
+          current = []
+        else
+          current << consume_component_value
+        end
+      end
+    end
+
+    private
+
+    def parse_error!(message)
+      raise ParseError.new(message, position: peek.position)
+    end
+
+    def peek(offset = 0)
+      @tokens[@pos + offset] || EOF_TOKEN
+    end
+
+    def consume
+      tok = @tokens[@pos] || EOF_TOKEN
+      @pos += 1
+      tok
+    end
+
+    def reconsume
+      @pos -= 1
+    end
+
+    # Skips whitespace and (when comments are preserved) comment tokens.
+    def skip_whitespace
+      consume while peek.trivia?
+    end
+
+    # CDO/CDC tokens are dropped at the top level (legacy HTML wrapping);
+    # inside a block they are treated as the start of a qualified rule.
+    # Comment tokens are passed through into the rules list when present.
+    def consume_rule_list(top_level:)
+      rules = []
+
+      loop do
+        t = peek
+
+        case t.type
+        when :eof
+          return rules
+        when :whitespace, :semicolon
+          consume
+        when :comment
+          rules << consume
+        when :cdo, :cdc
+          if top_level
+            consume
+          else
+            rule = consume_qualified_rule(nested: !top_level)
+            rules << rule if rule
+          end
+        when :at_keyword
+          rule = consume_at_rule(nested: !top_level)
+          rules << rule if rule
+        else
+          rule = consume_qualified_rule(nested: !top_level)
+          rules << rule if rule
+        end
+      end
+    end
+
+    def consume_at_rule(nested:)
+      name    = consume.value
+      prelude = []
+      block   = nil
+
+      loop do
+        t = peek
+
+        case t.type
+        when :semicolon, :eof
+          consume if t.type == :semicolon
+          break
+        when :rbrace
+          break if nested
+
+          prelude << consume
+        when :lbrace
+          consume
+          block = consume_braced_block
+          break
+        else
+          prelude << consume_component_value
+        end
+      end
+
+      strip_whitespace!(prelude)
+      AtRule.new(name:, prelude:, block:)
+    end
+
+    def consume_qualified_rule(nested:)
+      saved   = @pos
+      prelude = []
+
+      loop do
+        t = peek
+
+        case t.type
+        when :eof
+          @pos = saved
+          return nil
+        when :rbrace
+          if nested
+            @pos = saved
+            return nil
+          end
+
+          prelude << consume
+        when :semicolon
+          if nested
+            consume
+            return nil
+          end
+
+          prelude << consume
+        when :lbrace
+          consume
+          block = consume_braced_block
+          strip_whitespace!(prelude)
+          return QualifiedRule.new(prelude:, block:)
+        else
+          prelude << consume_component_value
+        end
+      end
+    end
+
+    # Assumes the opening `{` has already been consumed; consumes through
+    # the matching `}`.
+    def consume_braced_block
+      Block.new(items: collect_block_items(stop_at_close_brace: true))
+    end
+
+    # Shared loop for both `{}`-terminated blocks (inside a rule) and
+    # EOF-terminated block contents (style attribute, `@page`, etc.).
+    # Comment tokens are passed through into the items list when present.
+    def collect_block_items(stop_at_close_brace:)
+      items = []
+
+      loop do
+        t = peek
+
+        case t.type
+        when :eof
+          return items
+        when :rbrace
+          consume
+          return items if stop_at_close_brace
+          # Stray `}` outside any block: parse error per spec; skip.
+          next
+        when :whitespace, :semicolon
+          consume
+        when :comment
+          items << consume
+        when :at_keyword
+          rule = consume_at_rule(nested: true)
+          items << rule if rule
+        else
+          decl = try_consume_declaration
+          if decl
+            items << decl
+          else
+            rule = consume_qualified_rule(nested: true)
+            items << rule if rule
+          end
+        end
+      end
+    end
+
+    # In nested context a token sequence like `a:hover { ... }` looks like
+    # the start of a declaration (`<ident> : ...`). We detect such cases by
+    # noticing a `{}` simple block in the value and rolling back so the
+    # caller can re-parse it as a nested qualified rule.
+    def try_consume_declaration
+      saved = @pos
+
+      return nil unless peek.type == :ident
+
+      name = consume.value
+
+      skip_whitespace
+
+      unless peek.type == :colon
+        @pos = saved
+        return nil
+      end
+
+      consume
+
+      value = []
+
+      loop do
+        t = peek
+
+        case t.type
+        when :semicolon
+          consume
+          break
+        when :eof, :rbrace
+          break
+        else
+          value << consume_component_value
+        end
+      end
+
+      if value.any? { it.is_a?(SimpleBlock) && it.braced? }
+        @pos = saved
+        return nil
+      end
+
+      important = extract_important!(value)
+      strip_whitespace!(value)
+
+      Declaration.new(name:, value:, important:)
+    end
+
+    def consume_component_value
+      t = peek
+
+      case t.type
+      when :lbrace, :lbracket, :lparen
+        consume_simple_block
+      when :function
+        consume_function
+      else
+        consume
+      end
+    end
+
+    def consume_simple_block
+      open_type = consume.type
+      open_char = BRACKET_OPEN_CHAR.fetch(open_type)
+      end_type  = BRACKET_CLOSE_TYPE.fetch(open_type)
+      values    = []
+
+      loop do
+        t = peek
+
+        case t.type
+        when :eof
+          break
+        when end_type
+          consume
+          break
+        else
+          values << consume_component_value
+        end
+      end
+
+      SimpleBlock.new(open: open_char, value: values)
+    end
+
+    def consume_function
+      name   = consume.value
+      values = []
+
+      loop do
+        t = peek
+
+        case t.type
+        when :eof
+          break
+        when :rparen
+          consume
+          break
+        else
+          values << consume_component_value
+        end
+      end
+
+      Function.new(name:, value: values)
+    end
+
+    # Strips only whitespace tokens — comments, when present, are preserved
+    # as significant content of preludes/values.
+    def strip_whitespace!(value)
+      value.shift while whitespace_item?(value.first)
+      value.pop   while whitespace_item?(value.last)
+    end
+
+    def whitespace_item?(item)
+      item.is_a?(Token) && item.whitespace?
+    end
+
+    # Strips a trailing `! important` from `value` and returns whether it
+    # was present.
+    def extract_important!(value)
+      i = value.length - 1
+      i -= 1 while i >= 0 && trivia_item?(value[i])
+
+      return false unless i >= 1
+
+      ident = value[i]
+
+      return false unless ident.is_a?(Token) && ident.type == :ident && ident.value.casecmp('important').zero?
+
+      j = i - 1
+      j -= 1 while j >= 0 && trivia_item?(value[j])
+
+      bang = value[j]
+
+      return false unless bang.is_a?(Token) && bang.type == :delim && bang.value == '!'
+
+      value.slice!(j..)
+      true
+    end
+
+    def trivia_item?(item)
+      item.is_a?(Token) && item.trivia?
+    end
+  end
+end