markbridge 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 43b79ac6557f41fcce9274986295812dd9cbfccf10ce19d0f9b81424ef4f9a83
+  data.tar.gz: 63d7b2494828a885ceea8b333251d23e6400c2d84cb0a50e30c3112bb4c2a517
+SHA512:
+  metadata.gz: 387f752e9d6ae0eecc1c4e1e48cda6ac9e94390b16b75d8813a29400af10664913ca0dff8d9af2553753ed41ed5a5ed60d366f51246a3c814fb6034dfeb3660c
+  data.tar.gz: ea951ad454a6f6bfa86d902725394bf01605bff6307c1a6a6b10918d1267af12d41fd2bd1989151a90a3eec7d0670fbfb79c69e0ae256077ed5897f64870e036

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Gerhard Schlager
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/lib/markbridge/all.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "../markbridge"
+
+require_relative "ast"
+require_relative "parsers/bbcode"
+require_relative "parsers/html"
+require_relative "parsers/text_formatter"
+require_relative "renderers/discourse"

data/lib/markbridge/ast/align.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module AST
+    # Represents aligned text (left, center, right, justify).
+    # Note: Discourse has limited support for alignment.
+    #
+    # @example Center-aligned text
+    #   align = AST::Align.new(alignment: "center")
+    #   align << AST::Text.new("Centered text")
+    class Align < Element
+      # @return [String, nil] the alignment value (left, center, right, justify)
+      attr_reader :alignment
+
+      # Create a new Align element.
+      #
+      # @param alignment [String, nil] alignment value
+      def initialize(alignment: nil)
+        super()
+        @alignment = alignment
+      end
+    end
+  end
+end

data/lib/markbridge/ast/attachment.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module AST
+    # Represents an attachment reference (image/file).
+    #
+    # @example Attachment by absolute ID
+    #   attachment = AST::Attachment.new(id: "1234")
+    #
+    # @example Attachment by post-relative index with filename
+    #   attachment = AST::Attachment.new(index: "0", filename: "image.jpg")
+    #
+    # @example Attachment with alt text
+    #   attachment = AST::Attachment.new(id: "5678", alt: "diagram")
+    class Attachment < Node
+      # @return [String, Integer, nil] absolute attachment identifier
+      attr_reader :id
+
+      # @return [Integer, nil] post-relative index
+      attr_reader :index
+
+      # @return [String, nil] optional filename
+      attr_reader :filename
+
+      # @return [String, nil] optional alt text for the attachment
+      attr_reader :alt
+
+      # Create a new Attachment node.
+      #
+      # @param id [String, Integer, nil] absolute attachment identifier
+      # @param index [Integer, nil] post-relative index
+      # @param filename [String, nil] optional filename/caption
+      # @param alt [String, nil] optional alt text
+      def initialize(id: nil, index: nil, filename: nil, alt: nil)
+        @id = id
+        @index = index
+        @filename = filename
+        @alt = alt
+      end
+    end
+  end
+end

data/lib/markbridge/ast/bold.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module AST
+    # Represents bold/strong text formatting.
+    #
+    # @example
+    #   bold = AST::Bold.new
+    #   bold << AST::Text.new("important text")
+    class Bold < Element
+    end
+  end
+end

data/lib/markbridge/ast/code.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module AST
+    # Represents an inline or block code element.
+    #
+    # @example Inline code
+    #   code = AST::Code.new
+    #   code << AST::Text.new("puts 'hello'")
+    #
+    # @example Code with language for syntax highlighting
+    #   code = AST::Code.new(language: "ruby")
+    #   code << AST::Text.new("def hello\n  puts 'world'\nend")
+    class Code < Element
+      # @return [String, nil] the programming language for syntax highlighting
+      attr_reader :language
+
+      # Create a new code element.
+      #
+      # @param language [String, nil] optional language identifier for syntax highlighting
+      def initialize(language: nil)
+        super()
+        @language = language
+      end
+    end
+  end
+end

data/lib/markbridge/ast/color.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module AST
+    # Represents colored text.
+    # Note: Discourse doesn't support inline color by default,
+    # but this preserves color information for migration/custom rendering.
+    #
+    # @example Colored text
+    #   color = AST::Color.new(color: "red")
+    #   color << AST::Text.new("Important text")
+    class Color < Element
+      # @return [String, nil] the color value (name or hex)
+      attr_reader :color
+
+      # Create a new Color element.
+      #
+      # @param color [String, nil] color name or hex code
+      def initialize(color: nil)
+        super()
+        @color = color
+      end
+    end
+  end
+end

data/lib/markbridge/ast/document.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module AST
+    # Represents the root document node of the AST.
+    # This is the top-level container that holds all other elements.
+    #
+    # @example Creating a document
+    #   doc = AST::Document.new
+    #   doc << AST::Text.new("Hello, world!")
+    #
+    # @example Creating a document with initial children
+    #   doc = AST::Document.new([
+    #     AST::Text.new("Hello"),
+    #     AST::Bold.new
+    #   ])
+    class Document < Element
+      # Create a new document node.
+      #
+      # @param children [Array<Node>] optional array of initial child nodes
+      def initialize(children = [])
+        super()
+        Array(children).each { |c| self << c }
+      end
+    end
+  end
+end

data/lib/markbridge/ast/element.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module AST
+    # Base class for all AST elements that can contain children.
+    # Elements form the structural nodes of the AST tree, while Text nodes are leaves.
+    #
+    # @example Creating an element with children
+    #   element = AST::Bold.new
+    #   element << AST::Text.new("hello")
+    #   element << AST::Text.new(" world")
+    #   element.children.size # => 1 (consecutive text nodes are merged)
+    class Element < Node
+      # @return [Array<Node>] the child nodes of this element
+      attr_reader :children
+
+      def initialize
+        @children = []
+      end
+
+      # Add a child node to this element.
+      # Consecutive Text nodes are automatically merged for optimization.
+      #
+      # @param child [Node] the node to add as a child
+      # @return [Element] self for method chaining
+      # @raise [TypeError] if child is not a Node instance
+      #
+      # @example Adding children
+      #   element << AST::Text.new("hello")
+      #   element << AST::Bold.new
+      def <<(child)
+        unless child.is_a?(Node)
+          actual = child.nil? ? "nil" : child.class
+          raise TypeError, "child must be a #{Markbridge::AST::Node} (got #{actual})"
+        end
+
+        if child.is_a?(Text) && children.last.is_a?(Text)
+          @children.last.merge(child)
+        else
+          @children << child
+        end
+
+        self
+      end
+    end
+  end
+end

data/lib/markbridge/ast/email.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module AST
+    # Represents an email link element.
+    #
+    # @example Email with explicit address
+    #   email = AST::Email.new(address: "[email protected]")
+    #   email << AST::Text.new("Contact us")
+    #
+    # @example Email with text as address
+    #   email = AST::Email.new(address: "[email protected]")
+    #   email << AST::Text.new("[email protected]")
+    class Email < Element
+      # @return [String, nil] the email address for this link
+      attr_reader :address
+
+      # Create a new Email element.
+      #
+      # @param address [String, nil] the email address for this link
+      def initialize(address: nil)
+        super()
+        @address = address
+      end
+    end
+  end
+end

data/lib/markbridge/ast/event.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module AST
+    # Represents a Discourse event.
+    #
+    # @example Basic event
+    #   event = AST::Event.new(
+    #     name: "Team Meeting",
+    #     starts_at: "2025-12-15 14:00"
+    #   )
+    #
+    # @example Event with all attributes
+    #   event = AST::Event.new(
+    #     name: "Conference",
+    #     starts_at: "2025-12-15 09:00",
+    #     ends_at: "2025-12-15 17:00",
+    #     status: "public",
+    #     timezone: "Europe/Vienna",
+    #     raw: "[event name=\"Conference\"]...[/event]"
+    #   )
+    class Event < Node
+      # @return [String] the event name
+      attr_reader :name
+
+      # @return [String] start date/time
+      attr_reader :starts_at
+
+      # @return [String, nil] end date/time
+      attr_reader :ends_at
+
+      # @return [String, nil] event status (public, private, standalone)
+      attr_reader :status
+
+      # @return [String, nil] timezone
+      attr_reader :timezone
+
+      # @return [String, nil] the original raw BBCode
+      attr_reader :raw
+
+      # Create a new Event node.
+      #
+      # @param name [String] the event name
+      # @param starts_at [String] start date/time
+      # @param ends_at [String, nil] end date/time
+      # @param status [String, nil] event status
+      # @param timezone [String, nil] timezone
+      # @param raw [String, nil] the original raw BBCode
+      def initialize(name:, starts_at:, ends_at: nil, status: nil, timezone: nil, raw: nil)
+        @name = name
+        @starts_at = starts_at
+        @ends_at = ends_at
+        @status = status
+        @timezone = timezone
+        @raw = raw
+      end
+    end
+  end
+end

data/lib/markbridge/ast/heading.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module AST
+    # Represents a heading element with a level (1-6).
+    #
+    # @example
+    #   heading = AST::Heading.new(level: 2)
+    #   heading << AST::Text.new("Section Title")
+    class Heading < Element
+      # @return [Integer] the heading level (1-6)
+      attr_reader :level
+
+      # Create a new heading element.
+      #
+      # @param level [Integer] the heading level (1-6)
+      def initialize(level:)
+        super()
+        @level = level
+      end
+    end
+  end
+end

data/lib/markbridge/ast/horizontal_rule.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module AST
+    # Represents a horizontal rule/divider.
+    #
+    # @example
+    #   hr = AST::HorizontalRule.new
+    class HorizontalRule < Node
+    end
+  end
+end

data/lib/markbridge/ast/image.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module AST
+    # Represents an image element.
+    #
+    # @example Basic image
+    #   image = AST::Image.new(src: "https://example.com/img.png")
+    #
+    # @example Image with dimensions
+    #   image = AST::Image.new(src: "https://example.com/img.png", width: 100, height: 100)
+    class Image < Element
+      # @return [String, nil] the image source URL
+      attr_reader :src
+
+      # @return [Integer, nil] the image width
+      attr_reader :width
+
+      # @return [Integer, nil] the image height
+      attr_reader :height
+
+      # Create a new Image element.
+      #
+      # @param src [String, nil] the image source URL
+      # @param width [Integer, nil] the image width
+      # @param height [Integer, nil] the image height
+      def initialize(src: nil, width: nil, height: nil)
+        super()
+        @src = src
+        @width = width
+        @height = height
+      end
+    end
+  end
+end

data/lib/markbridge/ast/italic.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module AST
+    # Represents italic/emphasis text formatting.
+    #
+    # @example
+    #   italic = AST::Italic.new
+    #   italic << AST::Text.new("emphasized text")
+    class Italic < Element
+    end
+  end
+end

data/lib/markbridge/ast/line_break.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module AST
+    # Represents a line break within text.
+    #
+    # @example
+    #   br = AST::LineBreak.new
+    class LineBreak < Node
+    end
+  end
+end

data/lib/markbridge/ast/list.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module AST
+    # Represents an ordered or unordered list element.
+    #
+    # @example Unordered list
+    #   list = AST::List.new
+    #   list << AST::ListItem.new
+    #
+    # @example Ordered list
+    #   list = AST::List.new(ordered: true)
+    #   list << AST::ListItem.new
+    class List < Element
+      # Add content to this list.
+      # - ListItem children are added directly
+      # - Other nodes are wrapped in an implicit ListItem
+      # - Whitespace-only Text nodes are ignored
+      #
+      # @param child [Node] the node to add
+      # @return [List] self for chaining
+      # @raise [TypeError] if child is not a Node
+      def <<(child)
+        return self if child.is_a?(Text) && child.text.strip.empty?
+
+        if child.is_a?(ListItem)
+          super
+        else
+          @children << ListItem.new if @children.empty?
+          @children.last << child
+        end
+
+        self
+      end
+
+      # Create a new list element.
+      #
+      # @param ordered [Boolean] whether this is an ordered (numbered) list
+      def initialize(ordered: false)
+        super()
+        @ordered = ordered
+      end
+
+      # Check if this is an ordered list.
+      #
+      # @return [Boolean] true if this is an ordered (numbered) list
+      def ordered?
+        @ordered
+      end
+    end
+  end
+end

data/lib/markbridge/ast/list_item.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module AST
+    # Represents a list item within a {List}.
+    #
+    # @example
+    #   item = AST::ListItem.new
+    #   item << AST::Text.new("First item")
+    class ListItem < Element
+    end
+  end
+end

data/lib/markbridge/ast/markdown_text.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module AST
+    # Represents a text node containing pre-formatted Markdown content.
+    # Unlike AST::Text, this content will NOT be escaped by the renderer.
+    # Use this when you want to pass through Markdown formatting as-is.
+    #
+    # @example Creating a markdown text node
+    #   text = AST::MarkdownText.new("**bold** and *italic*")
+    #
+    # @example Use case: preserving user-provided Markdown
+    #   # When parsing HTML or other formats that allow embedded Markdown
+    #   element << AST::MarkdownText.new(markdown_content)
+    class MarkdownText < Node
+      # @return [String] the markdown text content of this node
+      attr_reader :text
+
+      # Create a new markdown text node with the given content.
+      #
+      # @param text [String] the markdown text content
+      def initialize(text)
+        @text = +text
+      end
+
+      # Merge another markdown text node's content into this one.
+      # This mutates the current text node by appending the other's text.
+      #
+      # @param other [MarkdownText] the text node to merge from
+      # @return [MarkdownText] self for method chaining
+      def merge(other)
+        @text << other.text
+        self
+      end
+    end
+  end
+end

data/lib/markbridge/ast/mention.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module AST
+    # Represents a user or group mention (@username or @groupname).
+    #
+    # @example User mention
+    #   mention = AST::Mention.new(name: "gerhard", type: :user)
+    #
+    # @example Group mention
+    #   mention = AST::Mention.new(name: "Testers", type: :group)
+    class Mention < Node
+      # @return [String] the username or group name (without @)
+      attr_reader :name
+
+      # @return [Symbol] the type of mention (:user or :group)
+      attr_reader :type
+
+      # Create a new Mention node.
+      #
+      # @param name [String] the username or group name (without @)
+      # @param type [Symbol] the type of mention (:user or :group), defaults to :user
+      def initialize(name:, type: :user)
+        @name = name
+        @type = type
+      end
+    end
+  end
+end

data/lib/markbridge/ast/node.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module AST
+    # Base class for all AST nodes.
+    # This is a marker class that serves as the common ancestor for all AST nodes.
+    #
+    # The AST hierarchy consists of:
+    # - {Element} - nodes that can contain children
+    # - {Text} - leaf nodes containing text content
+    #
+    # All node types inherit from this base class to enable type checking
+    # and polymorphic operations on the AST tree.
+    #
+    # @abstract Subclass and add specific behavior
+    class Node
+    end
+  end
+end

data/lib/markbridge/ast/paragraph.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module AST
+    # Represents a paragraph element.
+    #
+    # @example
+    #   paragraph = AST::Paragraph.new
+    #   paragraph << AST::Text.new("This is a paragraph.")
+    class Paragraph < Element
+    end
+  end
+end