markbridge 0.1.0

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module Parsers
+    module BBCode
+      module Handlers
+        # Simple formatting handlers that just push an element
+        class SimpleHandler < BaseHandler
+          def initialize(element_class, auto_closeable: false)
+            @element_class = element_class
+            @auto_closeable = auto_closeable
+          end
+
+          def on_open(token:, context:, registry:, tokens: nil)
+            element = @element_class.new
+            context.push(element, token:)
+          end
+
+          def auto_closeable?
+            @auto_closeable
+          end
+
+          attr_reader :element_class
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module Parsers
+    module BBCode
+      module Handlers
+        # Handler for SIZE tags
+        # Supports:
+        # - [size=20]text[/size]
+        # - [size=large]text[/size]
+        class SizeHandler < BaseHandler
+          def initialize
+            @element_class = AST::Size
+          end
+
+          def on_open(token:, context:, registry:, tokens: nil)
+            size = token.attrs[:size] || token.attrs[:option]
+            element = AST::Size.new(size:)
+            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/spoiler_handler.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module Parsers
+    module BBCode
+      module Handlers
+        # Handler for SPOILER tags
+        # Supports:
+        # - [spoiler]text[/spoiler]
+        # - [spoiler=title]text[/spoiler]
+        # - [hide]text[/hide] (alias for spoiler)
+        class SpoilerHandler < BaseHandler
+          def initialize
+            @element_class = AST::Spoiler
+          end
+
+          def on_open(token:, context:, registry:, tokens: nil)
+            title = token.attrs[:title] || token.attrs[:option]
+            element = AST::Spoiler.new(title:)
+            context.push(element, token:)
+          end
+
+          attr_reader :element_class
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module Parsers
+    module BBCode
+      module Handlers
+        # Handler for URL tags
+        class UrlHandler < BaseHandler
+          def initialize
+            @element_class = AST::Url
+          end
+
+          def on_open(token:, context:, registry:, tokens: nil)
+            href = token.attrs[:href] || token.attrs[:url] || token.attrs[:option]
+            element = AST::Url.new(href:)
+            context.push(element, token:)
+          end
+
+          attr_reader :element_class
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module Parsers
+    module BBCode
+      # Parses BBCode into an AST using handlers from HandlerRegistry
+      class Parser
+        attr_reader :unknown_tags,
+                    :auto_closed_tags_count,
+                    :depth_exceeded_count,
+                    :unclosed_raw_tags
+
+        # Create a new parser with optional custom handlers
+        # @param handlers [HandlerRegistry, nil] custom handler registry, defaults to HandlerRegistry.default
+        # @yield [HandlerRegistry] optional block to customize the default registry
+        # @example Using default handlers
+        #   parser = Parser.new
+        # @example Using custom handlers
+        #   parser = Parser.new(handlers: my_registry)
+        # @example Customizing default handlers
+        #   parser = Parser.new do |registry|
+        #     registry.register("quote", QuoteHandler.new)
+        #   end
+        def initialize(handlers: nil, &block)
+          @handlers =
+            if block_given?
+              HandlerRegistry.build_from_default(&block)
+            else
+              handlers || HandlerRegistry.default
+            end
+          @unknown_tags = Hash.new(0)
+        end
+
+        # Parse BBCode string into an AST
+        # @param input [String] BBCode source
+        # @return [AST::Document]
+        def parse(input)
+          @unknown_tags.clear
+
+          normalized = normalize_line_endings(input)
+
+          document = AST::Document.new
+          context = ParserState.new(document)
+
+          scanner = Scanner.new(normalized)
+          parse_tokens(scanner, context)
+
+          @auto_closed_tags_count = context.auto_closed_count
+          @depth_exceeded_count = context.depth_exceeded_count
+          @unclosed_raw_tags = context.unclosed_raw_tags
+          document
+        end
+
+        private
+
+        # Normalize line endings (CR, CRLF, and Unicode separators)
+        # @param input [String]
+        # @return [String]
+        def normalize_line_endings(input)
+          input.gsub(/\r\n?|[\u2028\u2029]+/, "\n")
+        end
+
+        # Parse tokens using scanner
+        # @param scanner [Scanner]
+        # @param context [ParserState]
+        def parse_tokens(scanner, context)
+          tokens = PeekableEnumerator.new(scanner)
+
+          while tokens.has_next?
+            token = tokens.next
+            case token
+            when TextToken
+              process_text(token, context)
+            when TagStartToken
+              process_tag_start(token, context, tokens)
+            when TagEndToken
+              process_tag_end(token, context, tokens)
+            end
+          end
+        end
+
+        # Process text token
+        # @param token [TextToken]
+        # @param context [ParserState]
+        def process_text(token, context)
+          context.add_child(AST::Text.new(token.text))
+        end
+
+        # Process opening tag
+        # @param token [TagStartToken]
+        # @param context [ParserState]
+        # @param tokens [PeekableEnumerator]
+        def process_tag_start(token, context, tokens)
+          if (handler = @handlers[token.tag])
+            handler.on_open(token:, context:, registry: @handlers, tokens:)
+          else
+            handle_unknown_tag(token, context)
+          end
+        end
+
+        # Process closing tag
+        # @param token [TagEndToken]
+        # @param context [ParserState]
+        # @param tokens [PeekableEnumerator]
+        def process_tag_end(token, context, tokens)
+          if (handler = @handlers[token.tag])
+            handler.on_close(token:, context:, registry: @handlers, tokens:)
+          else
+            handle_unknown_tag(token, context)
+          end
+        end
+
+        # Handle unknown tag by tracking it and ignoring the wrapper
+        # while still processing its children
+        # @param token [Token]
+        # @param context [ParserState]
+        def handle_unknown_tag(token, context)
+          @unknown_tags[token.tag] += 1
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module Parsers
+    module BBCode
+      # Manages parsing state
+      class ParserState
+        MAX_DEPTH = 100
+
+        attr_reader :current, :depth, :auto_closed_count, :depth_exceeded_count, :unclosed_raw_tags
+
+        def initialize(root)
+          @root = root
+          @current = root
+          @depth = 0
+          @node_stack = [root]
+          @auto_closed_count = 0
+          @depth_exceeded_count = 0
+          @unclosed_raw_tags = Hash.new(0)
+        end
+
+        # Add element as child to current node and push the element onto the stack
+        # Uses graceful degradation: if max depth is exceeded and token is provided,
+        # treats the tag as text instead of raising. If no token is provided,
+        # raises MaxDepthExceededError (for backwards compatibility).
+        # @param element [AST::Element]
+        # @param token [Token, nil] the token that created this element (for graceful degradation)
+        # @return [Boolean] true if pushed successfully, false if depth exceeded
+        # @raise [MaxDepthExceededError] when pushing would exceed MAX_DEPTH and no token provided
+        def push(element, token: nil)
+          if @depth >= MAX_DEPTH
+            if token
+              # Graceful degradation: treat as text
+              @current << AST::Text.new(token.source)
+              @depth_exceeded_count += 1
+              return false
+            else
+              # Legacy behavior: raise error
+              raise MaxDepthExceededError, MAX_DEPTH
+            end
+          end
+
+          @current << element
+          @current = element
+          @node_stack << element
+          @depth += 1
+          true
+        end
+
+        # Pop current element and return to parent
+        # @return [AST::Element] the parent node
+        def pop
+          return @root if @node_stack.size <= 1
+
+          @node_stack.pop
+          @current = @node_stack.last
+          @depth -= 1
+          @current
+        end
+
+        # Add a child to current node without changing context
+        # @param node [AST::Node]
+        def add_child(node)
+          @current << node
+        end
+
+        # Increment the count of auto-closed tags after external reconciliation
+        # @param count [Integer]
+        def auto_close!(count = 1)
+          @auto_closed_count += count
+        end
+
+        # Mark a raw tag as unclosed (for tracking parsing issues)
+        # @param tag_name [String]
+        def mark_unclosed_raw!(tag_name)
+          @unclosed_raw_tags[tag_name] += 1
+        end
+
+        # Return elements from the current node downward
+        # @param limit [Integer, nil] number of elements to include from the top
+        # @return [Array<AST::Node>]
+        def elements_from_current(limit = nil)
+          return [] if @node_stack.empty?
+
+          limit = (@node_stack.size - 1) if limit.nil?
+          limit = [limit, @node_stack.size - 1].min
+
+          (0..limit).map { |offset| @node_stack[@node_stack.size - 1 - offset] }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module Parsers
+    module BBCode
+      # Wrapper around a scanner that allows peeking at upcoming tokens
+      # without consuming them.
+      #
+      # This class buffers tokens pulled from a scanner (which must implement
+      # `next_token`) so callers can:
+      # - inspect the next token with {#peek} without advancing the scanner
+      # - inspect several upcoming tokens with {#peek_ahead}
+      # - consume tokens with {#next}
+      #
+      # The enumerator is lazy: tokens are only requested from the scanner
+      # when needed. Once the underlying scanner returns `nil`, the enumerator
+      # is marked finished and further peeks return `nil` (for single peeks)
+      # or an empty array (for multi-peeks).
+      #
+      # @example Basic usage
+      #   scanner = YourScanner.new("...") # responds to `next_token`
+      #   enum = PeekableEnumerator.new(scanner)
+      #   enum.peek        # => next token (no consume)
+      #   enum.peek_ahead(3) # => array of up to 3 upcoming tokens
+      #   enum.next        # => consumes and returns next token
+      #
+      # @see Markbridge::Parsers::BBCode::Scanner
+      class PeekableEnumerator
+        # Initialize a new PeekableEnumerator.
+        #
+        # @param scanner [Object] the scanner object that responds to `next_token`
+        def initialize(scanner)
+          @scanner = scanner
+          @peeked = []
+          @finished = false
+        end
+
+        # Consume and return the next token.
+        #
+        # If there are tokens in the internal buffer (from prior peeks) the
+        # buffered token is returned. Otherwise, the next token is requested
+        # from the underlying scanner via `next_token`.
+        #
+        # @return [Object, nil] next token or `nil` when exhausted
+        def next
+          return @peeked.shift if @peeked.any?
+          return nil if @finished
+
+          value = @scanner.next_token
+          @finished = true if value.nil?
+          value
+        end
+
+        # Return whether more tokens are available.
+        #
+        # This will attempt to fetch one token from the scanner if necessary
+        # to determine whether more tokens remain.
+        #
+        # @return [Boolean] `true` if at least one token is available
+        def has_next?
+          return true if @peeked.any?
+          return false if @finished
+
+          value = @scanner.next_token
+          if value.nil?
+            @finished = true
+            false
+          else
+            @peeked << value
+            true
+          end
+        end
+
+        # Peek at the next single token without consuming it.
+        #
+        # If the enumerator has been exhausted this returns `nil`.
+        #
+        # @return [Object, nil] the next token or `nil` when exhausted
+        def peek
+          return @peeked.first if @peeked.any?
+          return nil if @finished
+
+          ensure_peeked(1)
+          @peeked.first
+        end
+
+        # Peek ahead at up to `count` upcoming tokens without consuming them.
+        #
+        # The method will return an array with at most `count` elements.
+        # If fewer tokens remain, a shorter array is returned. When the
+        # enumerator is exhausted an empty array is returned.
+        #
+        # @param count [Integer] number of tokens to peek ahead (non\-negative)
+        # @return [Array<Object>] array of upcoming tokens (possibly empty)
+        def peek_ahead(count)
+          return [] if count <= 0
+
+          ensure_peeked(count)
+          @peeked.take(count)
+        end
+
+        alias next_token next
+
+        private
+
+        # Ensure at least `count` items are present in the peek buffer.
+        #
+        # This will repeatedly call `next_token` on the scanner until the
+        # buffer contains `count` items or the scanner returns `nil`.
+        #
+        # @param count [Integer] desired buffer size
+        # @return [void]
+        def ensure_peeked(count)
+          while !@finished && @peeked.size < count
+            value = @scanner.next_token
+            if value.nil?
+              @finished = true
+              break
+            end
+            @peeked << value
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module Parsers
+    module BBCode
+      # Strategy for collecting raw unparsed content between BBCode tags
+      class RawContentCollector
+        # Collect raw unparsed content between BBCode tags
+        # @param tag_name [String] the tag to match
+        # @param scanner [Scanner] the token source
+        # @return [RawContentResult] result with content and closed status
+        def collect(tag_name, scanner)
+          depth = 1
+          content = +""
+          closed = false
+
+          while (token = scanner.next_token)
+            if token.is_a?(TagStartToken) && token.tag == tag_name
+              depth += 1
+            elsif token.is_a?(TagEndToken) && token.tag == tag_name
+              if (depth -= 1) == 0
+                closed = true
+                break
+              end
+            end
+
+            content << token.source
+          end
+
+          RawContentResult.new(content:, closed:)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module Parsers
+    module BBCode
+      # Result object for raw content collection
+      class RawContentResult
+        attr_reader :content, :closed
+
+        def initialize(content:, closed:)
+          @content = content
+          @closed = closed
+        end
+
+        def closed?
+          @closed
+        end
+
+        def unclosed?
+          !@closed
+        end
+      end
+    end
+  end
+end