markbridge 0.1.0

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

@@ -0,0 +1,231 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module Parsers
+    module BBCode
+      # High-performance character-by-character BBCode scanner
+      # Tokenizes BBCode in O(n) time with minimal allocations and bounded backtracking
+      class Scanner
+        def initialize(input)
+          @input = input
+          @length = input.length
+          @current_pos = 0
+        end
+
+        def next_token
+          return nil if end_of_input?
+          start_pos = @current_pos
+          bracket_index = @input.index("[", @current_pos)
+
+          if bracket_index.nil?
+            text = @input[@current_pos..]
+            @current_pos = @length
+            return TextToken.new(text:, pos: start_pos)
+          end
+
+          if bracket_index > @current_pos
+            text = @input[@current_pos...bracket_index]
+            @current_pos = bracket_index
+            return TextToken.new(text:, pos: start_pos)
+          end
+
+          if (tag_token = parse_tag_at_cursor)
+            tag_token
+          else
+            @current_pos += 1
+            TextToken.new(text: "[", pos: start_pos)
+          end
+        end
+
+        private
+
+        TAG_INITIAL_CHAR = /[a-z*]/i
+        TAG_NAME_CHAR = /[a-z0-9]/i
+        UID_HEX_CHAR = /[0-9a-f]/i
+        ATTR_NAME_CHAR = /\w/
+        WHITESPACE_CHAR = /\s/
+        UNQUOTED_VALUE_STOP = /[\[\]\s]/
+
+        private_constant :TAG_INITIAL_CHAR,
+                         :TAG_NAME_CHAR,
+                         :UID_HEX_CHAR,
+                         :ATTR_NAME_CHAR,
+                         :WHITESPACE_CHAR,
+                         :UNQUOTED_VALUE_STOP
+
+        def parse_tag_at_cursor
+          return nil if current_char != "["
+
+          tag_start_pos = @current_pos
+          @current_pos += 1 # skip '['
+
+          # Check for closing tag
+          closing = current_char == "/"
+          @current_pos += 1 if closing
+
+          # Parse tag name
+          tag_name = scan_tag_name
+          return rollback(tag_start_pos) unless tag_name
+
+          # Parse attributes (only for opening tags)
+          attrs = closing ? {} : scan_attributes
+          return rollback(tag_start_pos) if current_char != "]"
+
+          @current_pos += 1 # skip ']'
+
+          # Capture original source text
+          source = @input[tag_start_pos...@current_pos]
+
+          normalized_tag_name = tag_name.downcase
+
+          if closing
+            TagEndToken.new(tag: normalized_tag_name, pos: tag_start_pos, source:)
+          else
+            TagStartToken.new(tag: normalized_tag_name, attrs:, pos: tag_start_pos, source:)
+          end
+        end
+
+        def rollback(pos)
+          @current_pos = pos
+          nil
+        end
+
+        # Scan a tag name: [a-z*.][a-z0-9]*(:uid)?
+        # @return [String, nil]
+        def scan_tag_name
+          start = @current_pos
+
+          # First character: letter, *, or .
+          return nil unless current_char&.match?(TAG_INITIAL_CHAR)
+          @current_pos += 1
+
+          # Remaining characters: letters or digits
+          @current_pos += 1 while current_char&.match?(TAG_NAME_CHAR)
+
+          # Optional :uid suffix (e.g., [quote:abc123])
+          if current_char == ":"
+            @current_pos += 1
+            @current_pos += 1 while current_char&.match?(UID_HEX_CHAR)
+          end
+
+          @input[start...@current_pos]
+        end
+
+        # Scan tag attributes
+        # The first `=value` (if present) becomes the `:option` attribute
+        # Additional `key=value` pairs become named attributes
+        # @return [Hash]
+        def scan_attributes
+          attrs = {}
+          skip_whitespace
+
+          # First attribute might be option: [tag=value]
+          if current_char == "="
+            @current_pos += 1
+            skip_whitespace
+            if (val = scan_attribute_value)
+              attrs[:option] = val
+            end
+            skip_whitespace
+          end
+
+          # Named attributes: [tag key=value key=value ...]
+          while (char = current_char) && char != "]"
+            name = scan_while(ATTR_NAME_CHAR)
+            break if name.nil?
+
+            skip_whitespace
+            break if current_char != "="
+
+            @current_pos += 1
+            skip_whitespace
+
+            value = scan_attribute_value
+            attrs[name.downcase.to_sym] = value if value
+            skip_whitespace
+          end
+
+          attrs
+        end
+
+        def scan_attribute_value
+          char = current_char
+          if char == '"' || char == "'"
+            scan_quoted_string
+          else
+            scan_unquoted_value
+          end
+        end
+
+        # Scans a quoted attribute value (double or single quoted)
+        #
+        # IMPORTANT: This method does NOT support escape sequences (e.g., \" or \\).
+        # This is intentional - standard BBCode does not define escape syntax.
+        # The scanner stops at the first matching quote character.
+        #
+        # Examples:
+        #   [url="http://example.com"]     → option: "http://example.com" ✓
+        #   [url='single quotes']          → option: "single quotes" ✓
+        #   [url="has \"quotes\" inside"]  → FAILS (stops at first inner quote) ✗
+        #
+        # Workaround: Use single quotes if you need double quotes in the value:
+        #   [url='has "quotes" inside']    → option: "has \"quotes\" inside" ✓
+        #
+        # @return [String] the unescaped attribute value
+        def scan_quoted_string
+          quote_char = current_char
+          start = (@current_pos += 1) # skip opening quote
+
+          closing_index = @input.index(quote_char, start)
+
+          if closing_index
+            value = @input[start...closing_index]
+            @current_pos = closing_index + 1 # position after closing quote
+          else
+            value = @input[start..] || ""
+            @current_pos = @length
+          end
+
+          value
+        end
+
+        def scan_unquoted_value
+          scan_until(UNQUOTED_VALUE_STOP)
+        end
+
+        # Consumes characters matching +pattern+; returns substring or nil if empty
+        def scan_while(pattern)
+          start = @current_pos
+          while (char = current_char) && char.match?(pattern)
+            @current_pos += 1
+          end
+
+          return nil if @current_pos == start
+          @input[start...@current_pos]
+        end
+
+        # Consumes characters until +pattern+ matches; returns substring or nil if empty
+        def scan_until(pattern)
+          stop_index = @input.index(pattern, @current_pos) || @length
+          return nil if stop_index == @current_pos
+
+          value = @input[@current_pos...stop_index]
+          @current_pos = stop_index
+          value
+        end
+
+        def current_char
+          @input[@current_pos]
+        end
+
+        def skip_whitespace
+          @current_pos += 1 while current_char&.match?(WHITESPACE_CHAR)
+        end
+
+        def end_of_input?
+          @current_pos >= @length
+        end
+      end
+    end
+  end
+end

data/lib/markbridge/parsers/bbcode/tokens/tag_end_token.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module Parsers
+    module BBCode
+      # Token representing a closing BBCode tag like [/b]
+      class TagEndToken < Token
+        attr_reader :tag
+
+        def initialize(tag:, pos: 0, source: nil)
+          super(pos:, source:)
+          @tag = tag.freeze
+        end
+
+        def inspect
+          "#<TagEndToken [/#{tag}]>"
+        end
+      end
+    end
+  end
+end

data/lib/markbridge/parsers/bbcode/tokens/tag_start_token.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module Parsers
+    module BBCode
+      # Token representing an opening BBCode tag like [b] or [url=...]
+      class TagStartToken < Token
+        attr_reader :tag, :attrs
+
+        def initialize(tag:, attrs: {}, pos: 0, source: nil)
+          super(pos:, source:)
+          @tag = tag.freeze
+          @attrs = attrs.freeze
+        end
+
+        def inspect
+          attrs_str = attrs.empty? ? "" : " #{attrs.inspect}"
+          "#<TagStartToken [#{tag}]#{attrs_str}>"
+        end
+      end
+    end
+  end
+end

data/lib/markbridge/parsers/bbcode/tokens/text_token.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module Parsers
+    module BBCode
+      # Token representing text content
+      class TextToken < Token
+        attr_reader :text
+
+        def initialize(text:, pos: 0)
+          super(pos:, source: text)
+          @text = text.freeze
+        end
+
+        alias source text
+
+        def inspect
+          "#<TextToken #{text.inspect}>"
+        end
+      end
+    end
+  end
+end

data/lib/markbridge/parsers/bbcode/tokens/token.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module Parsers
+    module BBCode
+      class Token
+        attr_reader :pos, :source
+
+        def initialize(pos: 0, source: nil)
+          @pos = pos
+          @source = source
+        end
+      end
+    end
+  end
+end

data/lib/markbridge/parsers/bbcode.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+# AST Nodes
+require_relative "../ast"
+
+# Errors
+require_relative "bbcode/errors/max_depth_exceeded_error"
+
+# Tokens
+require_relative "bbcode/tokens/token"
+require_relative "bbcode/tokens/text_token"
+require_relative "bbcode/tokens/tag_start_token"
+require_relative "bbcode/tokens/tag_end_token"
+
+# Closing Strategies
+require_relative "bbcode/closing_strategies/tag_reconciler"
+require_relative "bbcode/closing_strategies/base"
+require_relative "bbcode/closing_strategies/strict"
+require_relative "bbcode/closing_strategies/reordering"
+
+# Base Handlers
+require_relative "bbcode/handlers/base_handler"
+require_relative "bbcode/handlers/raw_handler"
+
+# Handlers
+require_relative "bbcode/handlers/align_handler"
+require_relative "bbcode/handlers/attachment_handler"
+require_relative "bbcode/handlers/color_handler"
+require_relative "bbcode/handlers/email_handler"
+require_relative "bbcode/handlers/image_handler"
+require_relative "bbcode/handlers/list_handler"
+require_relative "bbcode/handlers/list_item_handler"
+require_relative "bbcode/handlers/quote_handler"
+require_relative "bbcode/handlers/self_closing_handler"
+require_relative "bbcode/handlers/simple_handler"
+require_relative "bbcode/handlers/size_handler"
+require_relative "bbcode/handlers/spoiler_handler"
+require_relative "bbcode/handlers/url_handler"
+
+# Parser components
+require_relative "bbcode/handler_registry"
+require_relative "bbcode/parser_state"
+require_relative "bbcode/peekable_enumerator"
+require_relative "bbcode/raw_content_result"
+require_relative "bbcode/raw_content_collector"
+require_relative "bbcode/scanner"
+
+# Parser
+require_relative "bbcode/parser"
+
+module Markbridge
+  module Parsers
+    module BBCode
+    end
+  end
+end

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

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module Parsers
+    module HTML
+      # Registry of HTML tag handlers
+      class HandlerRegistry
+        def initialize
+          @handlers = {}
+        end
+
+        # Register a handler for one or more tag names
+        # @param tag_names [String, Array<String>] tag name(s) to register
+        # @param handler [BaseHandler, Proc] the handler instance or proc
+        def register(tag_names, handler)
+          Array(tag_names).each { |tag_name| @handlers[tag_name.to_s.downcase] = handler }
+          self
+        end
+
+        # Get handler for a tag name
+        # @param tag_name [String]
+        # @return [BaseHandler, Proc, nil]
+        def [](tag_name)
+          @handlers[tag_name.to_s.downcase]
+        end
+
+        # Create the default handler registry with common HTML tags
+        # @return [HandlerRegistry]
+        def self.default
+          registry = new
+
+          # Simple formatting handlers
+          registry.register(%w[b strong], Handlers::SimpleHandler.new(AST::Bold))
+          registry.register(%w[i em], Handlers::SimpleHandler.new(AST::Italic))
+          registry.register(%w[s strike del], Handlers::SimpleHandler.new(AST::Strikethrough))
+          registry.register("u", Handlers::SimpleHandler.new(AST::Underline))
+          registry.register("sup", Handlers::SimpleHandler.new(AST::Superscript))
+          registry.register("sub", Handlers::SimpleHandler.new(AST::Subscript))
+
+          # Code handlers (raw content)
+          registry.register(%w[code pre tt], Handlers::RawHandler.new(AST::Code))
+
+          # Link and image handlers
+          registry.register("a", Handlers::UrlHandler.new)
+          registry.register("img", Handlers::ImageHandler.new)
+
+          # Blockquote handler
+          registry.register("blockquote", Handlers::QuoteHandler.new)
+
+          # Void elements - use simple inline handlers
+          registry.register(
+            "br",
+            lambda do |element:, parent:|
+              parent << AST::LineBreak.new
+              nil # Return nil - void element, no children
+            end,
+          )
+          registry.register(
+            "hr",
+            lambda do |element:, parent:|
+              parent << AST::HorizontalRule.new
+              nil # Return nil - void element, no children
+            end,
+          )
+
+          # List handlers
+          registry.register(%w[ul ol], Handlers::ListHandler.new)
+          registry.register("li", Handlers::ListItemHandler.new)
+
+          # Paragraph handler (transparent - doesn't create AST node)
+          registry.register("p", Handlers::ParagraphHandler.new)
+
+          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
+      end
+    end
+  end
+end

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

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module Parsers
+    module HTML
+      module Handlers
+        class BaseHandler
+          # Process a Nokogiri node and add it to the parent AST node
+          # Subclasses should override this method
+          # @param node [Nokogiri::XML::Element] the HTML element
+          # @param parent [AST::Element] the parent AST node
+          # @return [AST::Element, nil] the created element if children should be processed, nil otherwise
+          def process(element:, parent:)
+            node = element # Alias for compatibility
+            # Default: do nothing, subclasses override
+            nil
+          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/html/handlers/image_handler.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module Parsers
+    module HTML
+      module Handlers
+        # Handler for <img> tags
+        class ImageHandler < BaseHandler
+          def initialize
+            @element_class = AST::Image
+          end
+
+          def process(element:, parent:)
+            src = element["src"]
+            width = sanitize_dimension(element["width"])
+            height = sanitize_dimension(element["height"])
+
+            ast_element = AST::Image.new(src:, width:, height:)
+            parent << ast_element
+
+            # Return nil to signal: don't process children (void element)
+            nil
+          end
+
+          attr_reader :element_class
+
+          private
+
+          # Convert dimension to positive integer or nil
+          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/html/handlers/list_handler.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module Parsers
+    module HTML
+      module Handlers
+        # Handler for list tags (<ul>, <ol>)
+        class ListHandler < BaseHandler
+          def initialize
+            @element_class = AST::List
+          end
+
+          def process(element:, parent:)
+            # Check if ordered: <ol> tag
+            ordered = element.name.downcase == "ol"
+
+            ast_element = AST::List.new(ordered:)
+            parent << ast_element
+
+            # Return element to signal: process children into this element
+            ast_element
+          end
+
+          attr_reader :element_class
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module Parsers
+    module HTML
+      module Handlers
+        # Handler for list item tags (<li>)
+        class ListItemHandler < BaseHandler
+          def initialize
+            @element_class = AST::ListItem
+          end
+
+          def process(element:, parent:)
+            ast_element = AST::ListItem.new
+            parent << ast_element
+
+            # Return element to signal: process children into this element
+            ast_element
+          end
+
+          attr_reader :element_class
+        end
+      end
+    end
+  end
+end

data/lib/markbridge/parsers/html/handlers/paragraph_handler.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module Parsers
+    module HTML
+      module Handlers
+        # Handler for <p> tags
+        # Creates AST::Paragraph nodes to preserve paragraph boundaries
+        class ParagraphHandler < SimpleHandler
+          def initialize
+            super(AST::Paragraph)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module Parsers
+    module HTML
+      module Handlers
+        # Handler for <blockquote> tags
+        class QuoteHandler < BaseHandler
+          def initialize
+            @element_class = AST::Quote
+          end
+
+          def process(element:, parent:)
+            # Extract optional author from cite attribute
+            author = element["cite"]
+            ast_element = AST::Quote.new(author:)
+            parent << ast_element
+
+            # Return element to signal: process children into this element
+            ast_element
+          end
+
+          attr_reader :element_class
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module Parsers
+    module HTML
+      module Handlers
+        # Handler for raw/preformatted tags that preserve content as-is
+        class RawHandler < BaseHandler
+          def initialize(element_class)
+            @element_class = element_class
+          end
+
+          def process(element:, parent:)
+            # Get the inner text content
+            content = element.inner_text
+
+            # Extract language from class or lang attribute
+            language = element["class"] || element["lang"]
+
+            ast_element = @element_class.new(language:)
+            ast_element << AST::Text.new(content) unless content.empty?
+            parent << ast_element
+
+            # Return nil to signal: don't process children (we handled content directly)
+            nil
+          end
+
+          attr_reader :element_class
+        end
+      end
+    end
+  end
+end

data/lib/markbridge/parsers/html/handlers/simple_handler.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module Parsers
+    module HTML
+      module Handlers
+        # Simple formatting handlers that create an element and process children
+        class SimpleHandler < BaseHandler
+          def initialize(element_class)
+            @element_class = element_class
+          end
+
+          def process(element:, parent:)
+            ast_element = @element_class.new
+            parent << ast_element
+
+            # Return element to signal: process children into this element
+            ast_element
+          end
+
+          attr_reader :element_class
+        end
+      end
+    end
+  end
+end