bbortcodes 0.1.0

data/lib/bbortcodes/config.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "anyway_config"
+
+module BBortcodes
+  class Config < Anyway::Config
+    config_name :bbortcodes
+
+    # Error handling strategy when parsing fails
+    # :raise - raise ParseError
+    # :skip - skip malformed shortcodes and leave them as-is
+    # :strip - remove malformed shortcodes from output
+    attr_config on_parse_error: :raise
+
+    # Error handling strategy when encountering disallowed nested shortcodes
+    # :raise - raise DisallowedChildError
+    # :skip - skip the nested shortcode and leave it as-is
+    # :strip - remove the nested shortcode from output
+    attr_config on_disallowed_child: :raise
+
+    # Whether to validate shortcode classes on registration
+    attr_config validate_on_register: true
+
+    # Security settings
+
+    # Automatically escape HTML in attribute values to prevent XSS
+    # Set to false if you need raw HTML (not recommended)
+    attr_config auto_escape_attributes: true
+
+    # Maximum input text size in bytes (default: 1MB)
+    attr_config max_input_length: 1_000_000
+
+    # Parse timeout in seconds to prevent ReDoS attacks
+    attr_config parse_timeout: 5
+
+    # Maximum nesting depth for shortcodes to prevent stack overflow
+    attr_config max_nesting_depth: 50
+
+    # Allow overwriting existing shortcodes in the registry
+    attr_config allow_shortcode_overwrite: false
+  end
+end

data/lib/bbortcodes/context.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require "monitor"
+
+module BBortcodes
+  class Context
+    include MonitorMixin
+
+    def initialize(initial_data = {})
+      super() # Initialize MonitorMixin
+      @data = initial_data.dup
+      @counters = Hash.new(0)
+    end
+
+    # Get a value from the context
+    # @param key [String, Symbol] The key to look up (normalized to string)
+    def get(key)
+      synchronize do
+        @data[key.to_s]
+      end
+    end
+
+    # Set a value in the context
+    # @param key [String, Symbol] The key to set (normalized to string)
+    # @param value [Object] The value to set
+    def set(key, value)
+      synchronize do
+        @data[key.to_s] = value
+      end
+    end
+
+    # Check if a key exists
+    # @param key [String, Symbol] The key to check (normalized to string)
+    def key?(key)
+      synchronize do
+        @data.key?(key.to_s)
+      end
+    end
+
+    # Increment and return a counter (thread-safe atomic operation)
+    # Useful for generating unique IDs like SHORTCODE-1, SHORTCODE-2, etc.
+    # @param counter_name [String, Symbol] The counter name (normalized to string)
+    # @return [Integer] The incremented counter value
+    def increment(counter_name)
+      synchronize do
+        @counters[counter_name.to_s] += 1
+      end
+    end
+
+    # Get current counter value without incrementing
+    # @param counter_name [String, Symbol] The counter name (normalized to string)
+    # @return [Integer] The current counter value
+    def counter(counter_name)
+      synchronize do
+        @counters[counter_name.to_s]
+      end
+    end
+
+    # Reset a counter to 0
+    # @param counter_name [String, Symbol] The counter name (normalized to string)
+    def reset_counter(counter_name)
+      synchronize do
+        @counters[counter_name.to_s] = 0
+      end
+    end
+
+    # Access all data (returns a duplicate to prevent external modification)
+    # @return [Hash] A copy of the context data
+    def to_h
+      synchronize do
+        @data.dup
+      end
+    end
+
+    # Allow hash-like access
+    def [](key)
+      get(key)
+    end
+
+    def []=(key, value)
+      set(key, value)
+    end
+  end
+end

data/lib/bbortcodes/errors.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module BBortcodes
+  class Error < StandardError; end
+  class ParseError < Error; end
+  class RegistryError < Error; end
+  class InvalidShortcodeError < Error; end
+  class DisallowedChildError < Error; end
+end

data/lib/bbortcodes/grammar.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require "parslet"
+
+module BBortcodes
+  class Grammar < Parslet::Parser
+    # Whitespace
+    rule(:space) { match('\s').repeat(1) }
+    rule(:space?) { space.maybe }
+
+    # Attribute value - quoted string
+    rule(:quote) { str('"') | str("'") }
+    rule(:quoted_string) do
+      str('"') >> (str("\\") >> any | str('"').absent? >> any).repeat.as(:string) >> str('"') |
+        str("'") >> (str("\\") >> any | str("'").absent? >> any).repeat.as(:string) >> str("'")
+    end
+
+    # Attribute name - alphanumeric and underscore/hyphen
+    rule(:attr_name) { match("[a-zA-Z]") >> match("[a-zA-Z0-9_-]").repeat }
+
+    # Single attribute: name="value"
+    rule(:attribute) do
+      attr_name.as(:name) >> space? >> str("=") >> space? >> quoted_string.as(:value)
+    end
+
+    # Multiple attributes separated by spaces
+    rule(:attributes) do
+      (space >> attribute).repeat(1)
+    end
+
+    # Shortcode name - alphanumeric and underscore/hyphen
+    rule(:shortcode_name) { match("[a-zA-Z]") >> match("[a-zA-Z0-9_-]").repeat }
+
+    # Self-closing shortcode: [name] or [name attr="value"]
+    rule(:self_closing_shortcode) do
+      str("[") >>
+        shortcode_name.as(:name) >>
+        attributes.as(:attributes).maybe >>
+        space? >>
+        str("]")
+    end
+
+    # Opening tag: [name] or [name attr="value"]
+    rule(:opening_tag) do
+      str("[") >>
+        shortcode_name.as(:tag_name) >>
+        attributes.as(:attributes).maybe >>
+        space? >>
+        str("]")
+    end
+
+    # Closing tag: [/name]
+    rule(:closing_tag) do
+      str("[/") >>
+        shortcode_name.as(:tag_name) >>
+        space? >>
+        str("]")
+    end
+
+    # Content between tags - can contain text, nested shortcodes, or paired shortcodes
+    rule(:content_char) { str("[").absent? >> any }
+    rule(:plain_text) { content_char.repeat(1).as(:text) }
+
+    # Forward declaration for recursive content
+    rule(:content_element) { paired_shortcode | self_closing_shortcode | plain_text }
+    rule(:content) { content_element.repeat.as(:content) }
+
+    # Paired shortcode with content: [name]content[/name]
+    rule(:paired_shortcode) do
+      opening_tag.as(:opening) >>
+        content.maybe >>
+        closing_tag.as(:closing)
+    end
+
+    # Document is a sequence of text and shortcodes
+    rule(:document_element) { paired_shortcode | self_closing_shortcode | plain_text }
+    rule(:document) { document_element.repeat.as(:document) }
+
+    root(:document)
+  end
+end

data/lib/bbortcodes/parser.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+require "timeout"
+
+module BBortcodes
+  class Parser
+    attr_reader :registry, :config
+
+    def initialize(registry: nil, config: nil)
+      @registry = registry || BBortcodes.registry
+      @config = config || BBortcodes.config
+      @grammar = Grammar.new
+      @transform = Transform.new
+    end
+
+    # Parse a string containing shortcodes
+    # @param text [String] The text to parse
+    # @param context [Context, Hash, nil] The rendering context
+    # @param only [Array<String>, nil] Only process these shortcode types
+    # @return [Array<String, Array<Shortcode>>] The processed text and array of shortcode instances
+    def parse(text, context: nil, only: nil)
+      # Validate input size
+      max_length = config.max_input_length
+      if text.bytesize > max_length
+        raise ParseError, "Input too large: #{text.bytesize} bytes (max: #{max_length})"
+      end
+
+      context = prepare_context(context)
+
+      # Parse the text into a tree structure with timeout protection
+      begin
+        parsed = Timeout.timeout(config.parse_timeout) do
+          @grammar.parse(text)
+        end
+      rescue Timeout::Error
+        raise ParseError, "Parsing timeout exceeded (#{config.parse_timeout}s) - input may be too complex"
+      rescue Parslet::ParseFailed => e
+        handle_parse_error(e, text)
+        return [text, []]
+      end
+
+      # Transform the parse tree
+      tree = @transform.apply(parsed)
+
+      # Convert to shortcode instances and render
+      shortcodes = []
+      output = process_tree(tree, context, only, shortcodes, parent_shortcode: nil, depth: 0)
+
+      [output, shortcodes]
+    end
+
+    private
+
+    def prepare_context(context)
+      case context
+      when Context
+        context
+      when Hash
+        Context.new(context)
+      when nil
+        Context.new
+      else
+        raise ArgumentError, "context must be a Context, Hash, or nil"
+      end
+    end
+
+    def handle_parse_error(error, text)
+      case config.on_parse_error
+      when :raise
+        raise ParseError, "Failed to parse shortcodes: #{error.message}"
+      when :skip, :strip
+        # Return original text or empty string
+        nil
+      else
+        raise ArgumentError, "Invalid on_parse_error setting: #{config.on_parse_error}"
+      end
+    end
+
+    def process_tree(tree, context, only, shortcodes, parent_shortcode:, depth:)
+      return "" if tree.nil?
+
+      # Check nesting depth
+      if depth > config.max_nesting_depth
+        raise ParseError, "Maximum nesting depth exceeded (#{config.max_nesting_depth})"
+      end
+
+      tree.map do |node|
+        process_node(node, context, only, shortcodes, parent_shortcode: parent_shortcode, depth: depth)
+      end.join
+    end
+
+    def process_node(node, context, only, shortcodes, parent_shortcode:, depth:)
+      case node[:type]
+      when :text
+        node[:value]
+      when :shortcode
+        process_shortcode(node, context, only, shortcodes, parent_shortcode: parent_shortcode, depth: depth)
+      else
+        ""
+      end
+    end
+
+    def process_shortcode(node, context, only, shortcodes, parent_shortcode:, depth:)
+      # Check nesting depth
+      if depth > config.max_nesting_depth
+        raise ParseError, "Maximum nesting depth exceeded (#{config.max_nesting_depth})"
+      end
+
+      tag_name = node[:name]
+
+      # Check if this shortcode should be processed based on 'only' filter
+      if only && !only.include?(tag_name)
+        return reconstruct_shortcode_text(node)
+      end
+
+      # Find the shortcode class
+      shortcode_class = registry.find(tag_name)
+      unless shortcode_class
+        return handle_unknown_shortcode(node)
+      end
+
+      # Validate against parent's allowed children
+      if parent_shortcode && !parent_shortcode.class.allows_child?(shortcode_class)
+        return handle_disallowed_child(node, parent_shortcode)
+      end
+
+      # Process nested content with increased depth
+      processed_content = if node[:content]
+        process_content(node[:content], context, only, shortcodes, shortcode_class, depth: depth + 1)
+      else
+        []
+      end
+
+      # Create shortcode instance
+      shortcode = shortcode_class.new(
+        name: tag_name,
+        attributes: node[:attributes] || {},
+        content: processed_content,
+        self_closing: node[:self_closing]
+      )
+
+      # Add to collection
+      shortcodes << shortcode
+
+      # Render the shortcode
+      shortcode.render(context)
+    end
+
+    def process_content(content_nodes, context, only, shortcodes, parent_shortcode_class, depth:)
+      return [] if content_nodes.nil? || content_nodes.empty?
+
+      # Create a temporary parent shortcode for validation
+      parent = Object.new
+      parent.define_singleton_method(:class) { parent_shortcode_class }
+
+      content_nodes.map do |node|
+        case node[:type]
+        when :text
+          node[:value]
+        when :shortcode
+          # For nested shortcodes, we need to process them and collect them
+          process_shortcode(node, context, only, shortcodes, parent_shortcode: parent, depth: depth)
+        else
+          ""
+        end
+      end
+    end
+
+    def handle_unknown_shortcode(node)
+      case config.on_parse_error
+      when :raise
+        raise ParseError, "Unknown shortcode: #{node[:name]}"
+      when :skip
+        reconstruct_shortcode_text(node)
+      when :strip
+        ""
+      end
+    end
+
+    def handle_disallowed_child(node, parent)
+      case config.on_disallowed_child
+      when :raise
+        raise DisallowedChildError,
+          "Shortcode '#{node[:name]}' is not allowed as a child of '#{parent.class.tag_name}'"
+      when :skip
+        reconstruct_shortcode_text(node)
+      when :strip
+        ""
+      end
+    end
+
+    # Reconstruct the original shortcode text from a parsed node
+    def reconstruct_shortcode_text(node)
+      attrs = format_attributes(node[:attributes])
+      if node[:self_closing]
+        "[#{node[:name]}#{attrs}]"
+      else
+        content = reconstruct_content(node[:content])
+        "[#{node[:name]}#{attrs}]#{content}[/#{node[:name]}]"
+      end
+    end
+
+    def format_attributes(attributes)
+      return "" if attributes.nil? || attributes.empty?
+
+      " " + attributes.map { |k, v| "#{k}=\"#{v}\"" }.join(" ")
+    end
+
+    def reconstruct_content(content_nodes)
+      return "" if content_nodes.nil? || content_nodes.empty?
+
+      content_nodes.map do |node|
+        case node[:type]
+        when :text
+          node[:value]
+        when :shortcode
+          reconstruct_shortcode_text(node)
+        else
+          ""
+        end
+      end.join
+    end
+  end
+end

data/lib/bbortcodes/registry.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require "monitor"
+
+module BBortcodes
+  class Registry
+    include MonitorMixin
+
+    def initialize
+      super
+      @shortcodes = {}
+    end
+
+    # Register a shortcode class
+    # @param shortcode_class [Class] A class that inherits from Shortcode
+    def register(shortcode_class)
+      synchronize do
+        unless shortcode_class < Shortcode
+          raise RegistryError, "#{shortcode_class} must inherit from BBortcodes::Shortcode"
+        end
+
+        tag_name = shortcode_class.tag_name
+
+        if @shortcodes.key?(tag_name)
+          if BBortcodes.config.allow_shortcode_overwrite
+            @shortcodes.delete(tag_name)
+          else
+            raise RegistryError,
+              "Shortcode '#{tag_name}' is already registered by #{@shortcodes[tag_name].name}. " \
+              "Set allow_shortcode_overwrite: true in config to override, or call unregister('#{tag_name}') first."
+          end
+        end
+
+        @shortcodes[tag_name] = shortcode_class
+      end
+    end
+
+    # Find a shortcode class by tag name
+    # @param tag_name [String] The tag name to look up
+    # @return [Class, nil] The shortcode class or nil if not found
+    def find(tag_name)
+      synchronize do
+        @shortcodes[tag_name.to_s]
+      end
+    end
+
+    # Check if a shortcode is registered
+    # @param tag_name [String] The tag name to check
+    # @return [Boolean]
+    def registered?(tag_name)
+      synchronize do
+        @shortcodes.key?(tag_name.to_s)
+      end
+    end
+
+    # Get all registered shortcode classes
+    # @return [Hash] Hash of tag_name => shortcode_class
+    def all
+      synchronize do
+        @shortcodes.dup
+      end
+    end
+
+    # Get all registered tag names
+    # @return [Array<String>]
+    def tag_names
+      synchronize do
+        @shortcodes.keys
+      end
+    end
+
+    # Unregister a shortcode
+    # @param tag_name [String] The tag name to unregister
+    def unregister(tag_name)
+      synchronize do
+        @shortcodes.delete(tag_name.to_s)
+      end
+    end
+
+    # Clear all registered shortcodes
+    def clear
+      synchronize do
+        @shortcodes.clear
+      end
+    end
+
+    # Get the count of registered shortcodes
+    # @return [Integer]
+    def count
+      synchronize do
+        @shortcodes.size
+      end
+    end
+  end
+end

data/lib/bbortcodes/shortcode.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+require "literal"
+require "cgi"
+
+module BBortcodes
+  class Shortcode < Literal::Object
+    prop :name, String, reader: :public
+    prop :attributes, Hash, reader: :public
+    prop :content, Array, default: -> { [] }, reader: :public
+    prop :self_closing, _Boolean, default: -> { false }, reader: :public
+
+    class << self
+      #
+      # Override in subclasses to specify the shortcode tag name
+      # If not overridden, uses the class name converted to snake_case
+      #
+      def tag_name
+        name.split("::").last
+          .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+          .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+          .downcase
+      end
+
+      #
+      # Override in subclasses to specify allowed child shortcodes
+      # Return :all to allow all children
+      # Return [] to allow no children (content is just text)
+      # Return array of shortcode classes to allow specific children
+      #
+      def allowed_children
+        :all
+      end
+
+      # Check if a given shortcode class is allowed as a child
+      def allows_child?(shortcode_class)
+        return true if allowed_children == :all
+        return false if allowed_children.empty?
+
+        allowed_children.include?(shortcode_class)
+      end
+
+      # @!macro [attach] shortcode_attribute_reader
+      #   @!method $1
+      #   Retrieves the value of the shortcode attribute.
+      #   This method is generated by {ClassMethods#shortcode_attribute_reader} and calls
+      #   {#attribute} internally, respecting HTML escaping configuration.
+      #   @return [String, nil] the attribute value (HTML-escaped by default based on config)
+      #   @see #attribute
+      #
+      # Defines a helper method to retrieve a shortcode attribute.
+      #
+      # This macro creates an instance method that retrieves the specified attribute value.
+      # The generated method respects the +auto_escape_attributes+ configuration setting.
+      #
+      # @param name [Symbol] The method name to define
+      # @param attribute_name [Symbol, String] The attribute name to retrieve (defaults to method name)
+      # @return [void]
+      #
+      # @example Basic usage
+      #   class VideoShortcode < BBortcodes::Shortcode
+      #     shortcode_attribute_reader :url
+      #
+      #     def render(context)
+      #       "<video src=\"#{url}\"></video>"
+      #     end
+      #   end
+      #
+      # @example Custom attribute name mapping
+      #   class ImageShortcode < BBortcodes::Shortcode
+      #     shortcode_attribute_reader :image_url, attribute_name: "url"
+      #
+      #     def render(context)
+      #       "<img src=\"#{image_url}\" />"
+      #     end
+      #   end
+      #
+      # @example Multiple attribute readers
+      #   class ButtonShortcode < BBortcodes::Shortcode
+      #     shortcode_attribute_reader :href
+      #     shortcode_attribute_reader :color
+      #     shortcode_attribute_reader :size
+      #
+      #     def render(context)
+      #       "<a href=\"#{href}\" class=\"btn-#{color} btn-#{size}\">Click</a>"
+      #     end
+      #   end
+      def shortcode_attribute_reader(name, attribute_name: name)
+        define_method(name) { attribute(attribute_name) }
+      end
+    end
+
+    #
+    # Render the shortcode to a string
+    # Must be implemented by subclasses
+    # @param context [Context] The rendering context
+    # @return [String] The rendered output
+    #
+    def render(context)
+      raise NotImplementedError, "#{self.class.name} must implement #render"
+    end
+
+    #
+    # Helper method to render content (for paired shortcodes)
+    # This will recursively render nested shortcodes and text
+    # @param context [Context] The rendering context
+    # @param parser [Parser] The parser instance for rendering nested shortcodes
+    # @return [String] The rendered content
+    #
+    def render_content(context, parser)
+      return "" if @content.nil? || @content.empty?
+
+      @content.map do |node|
+        case node
+        when Shortcode
+          node.render(context)
+        when String
+          node
+        when Hash
+          # Handle raw parsed nodes that haven't been converted to Shortcode instances yet
+          if node[:type] == :text
+            node[:value]
+          else
+            # This is a parsed shortcode node, let the parser handle it
+            ""
+          end
+        else
+          node.to_s
+        end
+      end.join
+    end
+
+    #
+    # Escape HTML entities to prevent XSS attacks
+    # @param text [String] The text to escape
+    # @return [String] HTML-escaped text
+    #
+    def escape_html(text)
+      return text if text.nil?
+      CGI.escapeHTML(text.to_s)
+    end
+
+    #
+    # Get the value of an attribute with optional default
+    # Automatically escapes HTML if auto_escape_attributes is enabled
+    # @param name [String, Symbol] The attribute name
+    # @param default [Object] Default value if attribute not found
+    # @param escape [Boolean] Override auto-escape setting for this attribute
+    # @return [String, Object] The attribute value
+    #
+    def attribute(name, default = nil, escape: nil)
+      value = @attributes.fetch(name.to_s, default)
+      return value if value.nil?
+
+      # Determine if we should escape
+      should_escape = escape.nil? ? BBortcodes.config.auto_escape_attributes : escape
+
+      should_escape ? escape_html(value) : value
+    end
+
+    # Check if an attribute exists
+    def has_attribute?(name)
+      @attributes.key?(name.to_s)
+    end
+  end
+end