markbridge 0.1.0

data/lib/markbridge/parsers/bbcode/handler_registry.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module Parsers
+    module BBCode
+      # Registry of BBCode tag handlers
+      class HandlerRegistry
+        attr_writer :closing_strategy
+
+        def initialize(closing_strategy: nil)
+          @handlers = {}
+          @normalized_tag_cache = {}
+          @element_handlers = {}
+          @auto_closeable_elements = Set.new
+          @closing_strategy = closing_strategy
+        end
+
+        # Register a handler for one or more tag names and associate it with an element class
+        # @param tag_names [String, Array<String>] tag name(s) to register
+        # @param handler [BaseHandler] the handler instance
+        def register(tag_names, handler)
+          element_class = handler.element_class
+          Array(tag_names).each do |tag_name|
+            normalized = tag_name.to_s.downcase
+            @handlers[normalized] = handler
+            @normalized_tag_cache[tag_name.to_s] = normalized
+          end
+          @element_handlers[element_class] = handler
+          @auto_closeable_elements << element_class if handler.auto_closeable?
+          self
+        end
+
+        # Get handler for a tag name
+        # @param tag_name [String]
+        # @return [BaseHandler, nil]
+        def [](tag_name)
+          tag_str = tag_name.to_s
+          normalized = @normalized_tag_cache[tag_str] || tag_str.downcase
+          @handlers[normalized]
+        end
+
+        # Get handler for an element instance
+        # @param element [Element]
+        # @return [BaseHandler, nil]
+        def handler_for_element(element)
+          @element_handlers[element.class]
+        end
+
+        # Check if an element class is auto-closeable
+        # @param element_class [Class]
+        # @return [Boolean]
+        def auto_closeable?(element_class)
+          @auto_closeable_elements.include?(element_class)
+        end
+
+        # Close an element using the closing strategy
+        # @param token [TagEndToken]
+        # @param context [ParserState]
+        # @param tokens [PeekableEnumerator, nil]
+        def close_element(token:, context:, tokens: nil)
+          @closing_strategy&.handle_close(token:, context:, registry: self, tokens:)
+        end
+
+        # Create the default handler registry with common BBCode tags
+        # @param closing_strategy [Object, nil] optional closing strategy to apply, defaults to Reordering strategy
+        # @return [HandlerRegistry]
+        def self.default(closing_strategy: nil)
+          # Create registry - we'll set closing strategy after registering handlers
+          registry = new
+
+          # Simple formatting handlers (auto-closeable)
+          registry.register(
+            %w[b bold strong],
+            Handlers::SimpleHandler.new(AST::Bold, auto_closeable: true),
+          )
+          registry.register(
+            %w[i italic em],
+            Handlers::SimpleHandler.new(AST::Italic, auto_closeable: true),
+          )
+          registry.register(
+            %w[s strike del],
+            Handlers::SimpleHandler.new(AST::Strikethrough, auto_closeable: true),
+          )
+          registry.register(
+            %w[u underline],
+            Handlers::SimpleHandler.new(AST::Underline, auto_closeable: true),
+          )
+          registry.register(
+            "sup",
+            Handlers::SimpleHandler.new(AST::Superscript, auto_closeable: true),
+          )
+          registry.register(
+            "sub",
+            Handlers::SimpleHandler.new(AST::Subscript, auto_closeable: true),
+          )
+
+          # Code handlers (raw content)
+          registry.register(%w[code pre tt], Handlers::RawHandler.new(AST::Code))
+
+          # Image handler
+          registry.register("img", Handlers::ImageHandler.new)
+
+          # Attachment handler
+          registry.register(%w[attach attachment], Handlers::AttachmentHandler.new)
+
+          # URL handler
+          registry.register(%w[url link iurl], Handlers::UrlHandler.new)
+
+          # Email handler
+          registry.register("email", Handlers::EmailHandler.new)
+
+          # Quote handler
+          registry.register("quote", Handlers::QuoteHandler.new)
+
+          # Spoiler handler
+          registry.register(%w[spoiler hide], Handlers::SpoilerHandler.new)
+
+          # Color handler
+          registry.register("color", Handlers::ColorHandler.new)
+
+          # Size handler
+          registry.register("size", Handlers::SizeHandler.new)
+
+          # Alignment handlers (single instance - reads alignment from tag name)
+          registry.register(%w[center left right justify], Handlers::AlignHandler.new)
+
+          # Self-closing handlers
+          registry.register("br", Handlers::SelfClosingHandler.new(AST::LineBreak))
+          registry.register("hr", Handlers::SelfClosingHandler.new(AST::HorizontalRule))
+
+          # List handlers
+          registry.register(%w[list ul ol ulist olist], Handlers::ListHandler.new)
+          registry.register(%w[* li .], Handlers::ListItemHandler.new)
+
+          # Set the closing strategy
+          registry.closing_strategy = closing_strategy || default_closing_strategy(registry)
+
+          registry
+        end
+
+        # Build a registry from the default configuration with optional customization
+        # @yield [HandlerRegistry] the registry to customize
+        # @return [HandlerRegistry]
+        def self.build_from_default
+          registry = default
+          yield(registry) if block_given?
+          registry
+        end
+
+        # Create the default closing strategy for a registry
+        # @param registry [HandlerRegistry] the registry to create a strategy for
+        # @return [ClosingStrategies::Reordering]
+        def self.default_closing_strategy(registry)
+          reconciler = ClosingStrategies::TagReconciler.new(registry:)
+          ClosingStrategies::Reordering.new(reconciler)
+        end
+      end
+    end
+  end
+end

data/lib/markbridge/parsers/bbcode/handlers/align_handler.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module Parsers
+    module BBCode
+      module Handlers
+        # Handler for ALIGN tags (center, left, right, justify)
+        # Creates a generic Align element with the appropriate alignment
+        class AlignHandler < BaseHandler
+          def initialize(alignment = nil)
+            @alignment = alignment
+            @element_class = AST::Align
+          end
+
+          def on_open(token:, context:, registry:, tokens: nil)
+            alignment = @alignment || token.tag.downcase
+            element = AST::Align.new(alignment:)
+            context.push(element, token:)
+          end
+
+          attr_reader :element_class
+        end
+      end
+    end
+  end
+end

data/lib/markbridge/parsers/bbcode/handlers/attachment_handler.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module Parsers
+    module BBCode
+      module Handlers
+        # Handler for ATTACH/ATTACHMENT tags across platforms (phpBB, vBulletin, XenForo, SMF mods).
+        #
+        # Examples:
+        # - [attachment=0]image.jpg[/attachment]         # phpBB (index + filename)
+        # - [ATTACH=CONFIG]1234[/ATTACH]                # vBulletin (id)
+        # - [ATTACH type="full" alt="diagram"]5678[/ATTACH] # XenForo (id + alt)
+        # - [attach id=2 msg=9876]                      # SMF-style self-contained attributes
+        class AttachmentHandler < BaseHandler
+          def initialize(collector: RawContentCollector.new)
+            @collector = collector
+            @element_class = AST::Attachment
+          end
+
+          def on_open(token:, context:, registry:, tokens: nil)
+            content = collect_content(token:, tokens:)
+            attachment = build_attachment(token:, content:)
+
+            context.add_child(attachment)
+          end
+
+          # Closing tags are consumed during collection; if one leaks through, treat as text.
+          def on_close(token:, context:, registry:, tokens: nil)
+            context.add_child(AST::Text.new(token.source))
+          end
+
+          private
+
+          def collect_content(token:, tokens:)
+            return unless tokens
+            return unless closing_tag_ahead?(token.tag, tokens)
+
+            @collector.collect(token.tag, tokens).content
+          end
+
+          def closing_tag_ahead?(tag, tokens)
+            tokens.peek_ahead(100).any? { |token| token.is_a?(TagEndToken) && token.tag == tag }
+          end
+
+          def build_attachment(token:, content:)
+            attrs = normalize_attrs(token.attrs)
+            option = attrs[:option]
+            body = presence(content&.strip)
+
+            id = preferred_id(attrs)
+            index = preferred_index(attrs)
+            filename = attrs[:filename]
+            alt = attrs[:alt]
+
+            index ||= option if option && numeric?(option)
+            id, filename = apply_body_content(body:, id:, index:, filename:)
+
+            AST::Attachment.new(id:, index:, filename:, alt:)
+          end
+
+          def normalize_attrs(attrs)
+            attrs.transform_values { |value| presence(value) }
+          end
+
+          def apply_body_content(body:, id:, index:, filename:)
+            return id, filename unless body
+
+            if id.nil?
+              return body, filename if index.nil?
+              return body, filename if numeric?(body)
+            end
+
+            filename ||= body
+
+            [id, filename]
+          end
+
+          def preferred_id(attrs)
+            presence(attrs[:msg]) || presence(attrs[:id])
+          end
+
+          def preferred_index(attrs)
+            explicit_index = presence(attrs[:index])
+            smf_index = presence(attrs[:id]) if attrs[:msg]
+
+            explicit_index || smf_index
+          end
+
+          def presence(value)
+            return if value.nil?
+            return value unless value.is_a?(String)
+
+            stripped = value.strip
+            stripped unless stripped.empty?
+          end
+
+          def numeric?(value)
+            value.is_a?(String) && value.match?(/\A\d+\z/)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/markbridge/parsers/bbcode/handlers/base_handler.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module Parsers
+    module BBCode
+      module Handlers
+        class BaseHandler
+          # Default opening behavior: create element and push to context
+          # Subclasses should override this method
+          # @param token [TagStartToken]
+          # @param context [ParserState]
+          # @param registry [HandlerRegistry]
+          # @param tokens [Enumerator, nil]
+          # @return [void]
+          def on_open(token:, context:, registry:, tokens: nil)
+            # Default: do nothing, subclasses override
+          end
+
+          # Default closing behavior: pop matching element from stack
+          # Subclasses can override or call super for custom behavior
+          # @param token [TagEndToken]
+          # @param context [ParserState]
+          # @param registry [HandlerRegistry]
+          # @param tokens [PeekableEnumerator, nil]
+          # @return [void]
+          def on_close(token:, context:, registry:, tokens: nil)
+            registry.close_element(token:, context:, tokens:)
+          end
+
+          # Whether elements created by this handler can be auto-closed
+          # @return [Boolean]
+          def auto_closeable?
+            false
+          end
+
+          # The element class created by this handler
+          # Subclasses must expose this via attr_reader :element_class
+          # @return [Class]
+          attr_reader :element_class
+        end
+      end
+    end
+  end
+end

data/lib/markbridge/parsers/bbcode/handlers/code_handler.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module Parsers
+    module BBCode
+      module Handlers
+        # Handler for [code]...[/code] tags
+        #
+        # Preserves content as-is without parsing nested BBCode
+        # Inherits from RawHandler using AST::Code element
+        #
+        # Example:
+        # [code=python]
+        # def hello_world():
+        #   print("Hello, world!")
+        # [/code]
+        class CodeHandler < RawHandler
+          def initialize
+            super(AST::Code)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/markbridge/parsers/bbcode/handlers/color_handler.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module Parsers
+    module BBCode
+      module Handlers
+        # Handler for COLOR tags
+        # Supports:
+        # - [color=red]text[/color]
+        # - [color=#FF0000]text[/color]
+        class ColorHandler < BaseHandler
+          def initialize
+            @element_class = AST::Color
+          end
+
+          def on_open(token:, context:, registry:, tokens: nil)
+            color = token.attrs[:color] || token.attrs[:option]
+            element = AST::Color.new(color:)
+            context.push(element, token:)
+          end
+
+          def auto_closeable?
+            true
+          end
+
+          attr_reader :element_class
+        end
+      end
+    end
+  end
+end

data/lib/markbridge/parsers/bbcode/handlers/email_handler.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module Parsers
+    module BBCode
+      module Handlers
+        # Handler for EMAIL tags
+        # Similar to UrlHandler but for email addresses
+        class EmailHandler < BaseHandler
+          def initialize
+            @element_class = AST::Email
+          end
+
+          def on_open(token:, context:, registry:, tokens: nil)
+            address = token.attrs[:email] || token.attrs[:address] || token.attrs[:option]
+            element = AST::Email.new(address:)
+            context.push(element, token:)
+          end
+
+          attr_reader :element_class
+        end
+      end
+    end
+  end
+end

data/lib/markbridge/parsers/bbcode/handlers/image_handler.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module Parsers
+    module BBCode
+      module Handlers
+        # Handler for IMG tags
+        # Supports:
+        # - [img]url[/img]
+        # - [img=100x100]url[/img]
+        # - [img width=100]url[/img]
+        # - [img width=100 height=50]url[/img]
+        class ImageHandler < RawHandler
+          def initialize
+            super(AST::Image)
+          end
+
+          private
+
+          def create_element(token:, content:)
+            # Extract dimensions from attributes or option
+            width = sanitize_dimension(token.attrs[:width])
+            height = sanitize_dimension(token.attrs[:height])
+
+            # Parse option for WIDTHxHEIGHT format (e.g., [img=100x200])
+            if token.attrs[:option]&.match?(/^\d+x\d+$/i)
+              dimensions = token.attrs[:option].split("x", 2)
+              width = sanitize_dimension(dimensions[0])
+              height = sanitize_dimension(dimensions[1])
+            elsif token.attrs[:option]&.match?(/^\d+$/)
+              # Just a number means width
+              width = sanitize_dimension(token.attrs[:option])
+            end
+
+            # Content is the URL
+            AST::Image.new(src: content, width:, height:)
+          end
+
+          # Convert dimension to positive integer or nil
+          # Handles string input from BBCode attributes
+          def sanitize_dimension(value)
+            return nil if value.nil?
+
+            dim = value.to_i
+            dim.positive? ? dim : nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/markbridge/parsers/bbcode/handlers/list_handler.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module Parsers
+    module BBCode
+      module Handlers
+        # Handler for list tags (list, ul, ol, etc.)
+        class ListHandler < BaseHandler
+          def initialize
+            @element_class = AST::List
+          end
+
+          def on_open(token:, context:, registry:, tokens: nil)
+            # Check if ordered: explicit ol/olist tag, or type=1, or option=1
+            ordered =
+              %w[ol olist].include?(token.tag) || token.attrs[:type] == "1" ||
+                token.attrs[:option] == "1"
+
+            element = AST::List.new(ordered:)
+            context.push(element, token:)
+          end
+
+          def on_close(token:, context:, registry:, tokens: nil)
+            # Auto-close open list item before closing list
+            context.pop if context.current.is_a?(AST::ListItem)
+
+            # Then use default closing behavior
+            super
+          end
+
+          attr_reader :element_class
+        end
+      end
+    end
+  end
+end

data/lib/markbridge/parsers/bbcode/handlers/list_item_handler.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module Parsers
+    module BBCode
+      module Handlers
+        # Handler for list item tags (*, li, .)
+        class ListItemHandler < BaseHandler
+          def initialize
+            @element_class = AST::ListItem
+          end
+
+          def on_open(token:, context:, registry:, tokens: nil)
+            # Auto-close previous list item if opening a new one
+            context.pop if context.current.is_a?(AST::ListItem)
+
+            element = AST::ListItem.new
+            context.push(element, token:)
+          end
+
+          attr_reader :element_class
+        end
+      end
+    end
+  end
+end

data/lib/markbridge/parsers/bbcode/handlers/quote_handler.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module Parsers
+    module BBCode
+      module Handlers
+        # Handler for QUOTE tags
+        # Supports:
+        # - [quote]text[/quote]
+        # - [quote=author]text[/quote]
+        # - [quote="author"]text[/quote]
+        # - [quote author=username]text[/quote]
+        # - [quote="username, post:123, topic:456"]text[/quote] (Discourse format)
+        class QuoteHandler < BaseHandler
+          def initialize
+            @element_class = AST::Quote
+          end
+
+          def on_open(token:, context:, registry:, tokens: nil)
+            # Extract quote attributes
+            author = nil
+            post = nil
+            topic = nil
+            username = nil
+
+            # Check for author attribute or option
+            if token.attrs[:author]
+              author = token.attrs[:author]
+            elsif token.attrs[:option]
+              # Parse Discourse-style quote: "username, post:123, topic:456"
+              option = token.attrs[:option]
+              if option.match?(/,\s*post:\d+/)
+                # Discourse format with post/topic
+                parts = option.split(",").map(&:strip)
+                username = parts[0]
+                parts[1..].each do |part|
+                  if part =~ /^post:(\d+)$/
+                    post = ::Regexp.last_match(1)
+                  elsif part =~ /^topic:(\d+)$/
+                    topic = ::Regexp.last_match(1)
+                  end
+                end
+                author = username
+              else
+                # Simple author attribution
+                author = option
+              end
+            end
+
+            # Check for explicit username, post, topic attributes (override option if present)
+            username = token.attrs[:username] if token.attrs[:username]
+            post = token.attrs[:post] if token.attrs[:post]
+            topic = token.attrs[:topic] if token.attrs[:topic]
+
+            element = AST::Quote.new(author:, post:, topic:, username:)
+            context.push(element, token:)
+          end
+
+          attr_reader :element_class
+        end
+      end
+    end
+  end
+end

data/lib/markbridge/parsers/bbcode/handlers/raw_handler.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module Parsers
+    module BBCode
+      module Handlers
+        # Handler for raw/preformatted tags that preserve content as-is
+        # Uses RawContentCollector strategy to consume tokens until closing tag
+        # without parsing nested BBCode
+        class RawHandler < BaseHandler
+          def initialize(element_class, collector: RawContentCollector.new)
+            @element_class = element_class
+            @collector = collector
+          end
+
+          def on_open(token:, context:, registry:, tokens:)
+            result = @collector.collect(token.tag, tokens)
+
+            # Track unclosed raw tags for diagnostics
+            context.mark_unclosed_raw!(token.tag) if result.unclosed?
+
+            element = create_element(token:, content: result.content)
+            context.add_child(element)
+          end
+
+          # RawHandler doesn't push to stack, so on_close should do nothing
+          def on_close(token:, context:, registry:, tokens: nil)
+            # Raw content was already consumed by collector
+            # Closing tag was consumed by collector, so this shouldn't be called
+            # If it is called, treat as text
+            context.add_child(AST::Text.new(token.source))
+          end
+
+          attr_reader :element_class
+
+          private
+
+          def create_element(token:, content:)
+            language = token.attrs[:lang] || token.attrs[:option]
+            element = @element_class.new(language:)
+            element << AST::Text.new(content) unless content.empty?
+            element
+          end
+        end
+      end
+    end
+  end
+end

data/lib/markbridge/parsers/bbcode/handlers/self_closing_handler.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module Parsers
+    module BBCode
+      module Handlers
+        # Handler for self-closing tags (br, hr, etc.)
+        class SelfClosingHandler < BaseHandler
+          def initialize(element_class)
+            @element_class = element_class
+          end
+
+          def on_open(token:, context:, registry:, tokens: nil)
+            element = @element_class.new
+            context.add_child(element)
+          end
+
+          def on_close(token:, context:, registry:, tokens: nil)
+            # Treat unexpected closing tag as text
+            context.add_child(AST::Text.new(token.source))
+          end
+
+          attr_reader :element_class
+        end
+      end
+    end
+  end
+end