bbortcodes 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 84f733c21d25ceaaf619d48918acad7c2b9ce8591d4c377229f96d938dff75b9
+  data.tar.gz: cb0c54df42dc99db3dc621ae75470b1700e91d03193658669f7f50f770f79ef4
+SHA512:
+  metadata.gz: be9a9d74d3cc2962c24d26acf3bb7a0450bfb6cc51f44cd334e5f65b12e47eb8795cf2ab83d2a1414cd2028113a7e8cf735c9bda5e3bd2192848fbe3e2195b9c
+  data.tar.gz: 0641d34d28eb37e3d12b7915d053308fd5e3352d609b1d9b290824a18c5ca2e48257e177735fac9afefe99cb65e8ff50babbf5e63ee6cf60aeca107709039ee4

data/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2025-10-15
+
+### Added
+- Initial release
+- Grammar-based parsing using Parslet
+- Type safety with Literal gem
+- Support for self-closing shortcodes
+- Support for paired shortcodes with content
+- Support for shortcode attributes
+- Support for nested shortcodes with configurable depth limits
+- Configurable child shortcode validation
+- Shared rendering context with thread-safe operations
+- Thread-safe global registry with overwrite protection
+- Flexible error handling via Anyway Config
+- Comprehensive documentation and examples
+
+### Security
+- **XSS Protection**: Automatic HTML escaping for attribute values via `escape_html()` method
+  - Configurable via `auto_escape_attributes` setting (default: true)
+  - Per-attribute opt-out with `escape: false` parameter
+- **DoS Protection**: Input size limits to prevent memory exhaustion
+  - Configurable via `max_input_length` setting (default: 1MB)
+- **ReDoS Protection**: Parse timeout to prevent Regular Expression Denial of Service
+  - Configurable via `parse_timeout` setting (default: 5 seconds)
+- **Stack Overflow Protection**: Maximum nesting depth enforcement
+  - Configurable via `max_nesting_depth` setting (default: 50 levels)
+- **Registry Integrity**: Protection against accidental shortcode overwrites
+  - Configurable via `allow_shortcode_overwrite` setting (default: false)
+- **Thread Safety**: All registry and context operations are thread-safe using Monitor

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Bbortcodes Contributors
+
+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/README.md

@@ -0,0 +1,648 @@
+# BBortcodes
+
+A state-of-the-art Ruby gem for parsing WordPress-like shortcodes with grammar-based parsing, type safety, and support for nested shortcodes.
+
+## Features
+
+- **Grammar-based parsing** using [Parslet](https://github.com/kschiess/parslet) - no fragile regex matching
+- **Type safety** with [Literal](https://github.com/joeldrapper/literal) for runtime type checking
+- **Nested shortcodes** with configurable child validation
+- **Self-closing and paired shortcodes** support
+- **Named attributes** with quoted values
+- **Shared rendering context** for state management across shortcodes
+- **Flexible error handling** via [Anyway Config](https://github.com/palkan/anyway_config)
+- **Pure Ruby** - no Rails dependencies required
+- **Thread-safe** shortcode registry
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'bbortcodes'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install bbortcodes
+```
+
+## Quick Start
+
+### 1. Define a Shortcode
+
+```ruby
+class YoutubeShortcode < BBortcodes::Shortcode
+  def self.tag_name
+    "youtube"
+  end
+
+  def render(context)
+    url = attribute("url")
+    "<iframe src=\"#{url}\" frameborder=\"0\"></iframe>"
+  end
+end
+```
+
+### 2. Register the Shortcode
+
+```ruby
+BBortcodes.register(YoutubeShortcode)
+```
+
+### 3. Parse Text
+
+```ruby
+text = "Check out this video: [youtube url=\"https://youtube.com/watch?v=abc\"]"
+output, shortcodes = BBortcodes.parse(text)
+
+puts output
+# => "Check out this video: <iframe src=\"https://youtube.com/watch?v=abc\" frameborder=\"0\"></iframe>"
+
+puts shortcodes.length
+# => 1
+
+puts shortcodes.first.class
+# => YoutubeShortcode
+```
+
+## Usage
+
+### Defining Shortcodes
+
+All shortcodes inherit from `BBortcodes::Shortcode` and use Literal for type safety:
+
+```ruby
+class BoldShortcode < BBortcodes::Shortcode
+  # Optional: customize the tag name (defaults to snake_case of class name)
+  def self.tag_name
+    "bold"
+  end
+
+  # Required: implement the render method
+  def render(context)
+    content_text = render_content(context, nil)
+    "<strong>#{content_text}</strong>"
+  end
+end
+```
+
+### Types of Shortcodes
+
+#### Self-Closing Shortcodes
+
+```ruby
+# Usage: [image url="photo.jpg" alt="A photo"]
+
+class ImageShortcode < BBortcodes::Shortcode
+  def self.tag_name
+    "image"
+  end
+
+  def render(context)
+    url = attribute("url")
+    alt = attribute("alt", "")
+    "<img src=\"#{url}\" alt=\"#{alt}\" />"
+  end
+end
+```
+
+#### Paired Shortcodes with Content
+
+```ruby
+# Usage: [bold]This is bold text[/bold]
+
+class BoldShortcode < BBortcodes::Shortcode
+  def self.tag_name
+    "bold"
+  end
+
+  def render(context)
+    content_text = render_content(context, nil)
+    "<strong>#{content_text}</strong>"
+  end
+end
+```
+
+#### Shortcodes with Attributes and Content
+
+```ruby
+# Usage: [button url="/signup" color="blue"]Sign Up[/button]
+
+class ButtonShortcode < BBortcodes::Shortcode
+  def self.tag_name
+    "button"
+  end
+
+  def render(context)
+    url = attribute("url", "#")
+    color = attribute("color", "primary")
+    text = render_content(context, nil)
+
+    "<a href=\"#{url}\" class=\"btn btn-#{color}\">#{text}</a>"
+  end
+end
+```
+
+### Nested Shortcodes
+
+Control which shortcodes can be nested within others:
+
+```ruby
+# Gallery that only allows Image children
+class GalleryShortcode < BBortcodes::Shortcode
+  def self.tag_name
+    "gallery"
+  end
+
+  # Only allow ImageShortcode children
+  def self.allowed_children
+    [ImageShortcode]
+  end
+
+  def render(context)
+    content_html = render_content(context, nil)
+    "<div class=\"gallery\">#{content_html}</div>"
+  end
+end
+
+# Allow any children
+class QuoteShortcode < BBortcodes::Shortcode
+  def self.tag_name
+    "quote"
+  end
+
+  def self.allowed_children
+    :all # Allow any nested shortcodes
+  end
+
+  def render(context)
+    content_html = render_content(context, nil)
+    author = attribute("author")
+
+    html = "<blockquote>#{content_html}"
+    html += "<cite>#{author}</cite>" if author
+    html += "</blockquote>"
+    html
+  end
+end
+
+# Allow no children (content is plain text only)
+class CodeShortcode < BBortcodes::Shortcode
+  def self.tag_name
+    "code"
+  end
+
+  def self.allowed_children
+    [] # No nested shortcodes allowed
+  end
+
+  def render(context)
+    # Content will only be plain text
+    content_text = render_content(context, nil)
+    "<code>#{content_text}</code>"
+  end
+end
+```
+
+### Using Context for Shared State
+
+The context allows shortcodes to share state during rendering:
+
+```ruby
+class NumberedItemShortcode < BBortcodes::Shortcode
+  def self.tag_name
+    "item"
+  end
+
+  def render(context)
+    # Increment a counter
+    number = context.increment(:item_counter)
+
+    content_text = render_content(context, nil)
+    "<div class=\"item\">#{number}. #{content_text}</div>"
+  end
+end
+
+# Usage
+context = BBortcodes::Context.new
+text = "[item]First[/item] [item]Second[/item] [item]Third[/item]"
+output, _ = BBortcodes.parse(text, context: context)
+
+# Output:
+# <div class="item">1. First</div> <div class="item">2. Second</div> <div class="item">3. Third</div>
+```
+
+### Placeholder Pattern (API Use Case)
+
+For APIs that need to separate shortcode data from content, you can use the returned `shortcodes` array:
+
+```ruby
+class VideoShortcode < BBortcodes::Shortcode
+  def self.tag_name
+    "video"
+  end
+
+  def render(context)
+    # Generate unique placeholder ID using context counter
+    id = context.increment(:shortcode)
+    "{{SHORTCODE-#{id}}}"
+  end
+end
+
+# Usage
+context = BBortcodes::Context.new
+text = "Watch this: [video url=\"video.mp4\" thumbnail=\"thumb.jpg\"]"
+output, shortcodes = BBortcodes.parse(text, context: context)
+
+puts output
+# => "Watch this: {{SHORTCODE-1}}"
+
+# Build API response data directly from the shortcodes array
+shortcodes_data = {}
+shortcodes.each_with_index do |shortcode, index|
+  id = index + 1
+  shortcodes_data["SHORTCODE-#{id}"] = {
+    type: shortcode.name,
+    attributes: shortcode.attributes,
+    self_closing: shortcode.self_closing
+  }
+end
+
+# In your API response:
+{
+  content: output,
+  shortcodes: shortcodes_data
+}
+# => {
+#   content: "Watch this: {{SHORTCODE-1}}",
+#   shortcodes: {
+#     "SHORTCODE-1" => {
+#       type: "video",
+#       attributes: {"url" => "video.mp4", "thumbnail" => "thumb.jpg"},
+#       self_closing: true
+#     }
+#   }
+# }
+```
+
+Note: The `context` object can still be used for shared state (like the counter above) or for passing data between nested shortcodes, but for API responses, it's better to use the returned `shortcodes` array to access all shortcode data.
+
+### Filtering Shortcodes
+
+Process only specific shortcode types using the `only:` option:
+
+```ruby
+text = "Text with [youtube url=\"video.mp4\"] and [button url=\"/click\"]Click[/button]"
+
+# Only process youtube shortcodes, leave others as-is
+output, shortcodes = BBortcodes.parse(text, only: ["youtube"])
+
+puts output
+# => "Text with <iframe...> and [button url=\"/click\"]Click[/button]"
+
+puts shortcodes.length
+# => 1 (only youtube was processed)
+```
+
+## Security
+
+BBortcodes includes multiple security features to protect against common attacks:
+
+### HTML Escaping (XSS Protection)
+
+By default, all attribute values are automatically HTML-escaped to prevent Cross-Site Scripting (XSS) attacks:
+
+```ruby
+text = '[quote author="<script>alert(1)</script>"]Hello[/quote]'
+output, _ = BBortcodes.parse(text)
+
+# Output: <blockquote>Hello<cite>&lt;script&gt;alert(1)&lt;/script&gt;</cite></blockquote>
+# The script tag is escaped and won't execute
+```
+
+You can disable escaping for specific attributes when you need raw HTML:
+
+```ruby
+class MyShortcode < BBortcodes::Shortcode
+  def render(context)
+    # Escaped by default
+    safe_value = attribute("safe_attr")
+
+    # Explicitly disable escaping for this attribute
+    raw_html = attribute("html_attr", escape: false)
+
+    # Or use escape_html() helper manually
+    user_input = escape_html(attribute("user_attr", escape: false))
+  end
+end
+```
+
+**Warning**: Only disable escaping when you fully control the input source. Never disable escaping for user-provided content.
+
+### Input Size Limits
+
+BBortcodes limits the maximum input size to prevent memory exhaustion:
+
+```ruby
+BBortcodes.configure do |config|
+  config.max_input_length = 1_000_000  # 1MB default
+end
+
+# Inputs larger than the limit will raise BBortcodes::ParseError
+```
+
+### Parse Timeout Protection
+
+Parsing is protected by a timeout to prevent ReDoS (Regular Expression Denial of Service) attacks:
+
+```ruby
+BBortcodes.configure do |config|
+  config.parse_timeout = 5  # 5 seconds default
+end
+
+# Complex inputs that take too long to parse will raise BBortcodes::ParseError
+```
+
+### Nesting Depth Limits
+
+Maximum nesting depth prevents stack overflow from deeply nested shortcodes:
+
+```ruby
+BBortcodes.configure do |config|
+  config.max_nesting_depth = 50  # default
+end
+
+# Deeply nested shortcodes exceeding the limit will raise BBortcodes::ParseError
+```
+
+### Registry Overwrite Protection
+
+By default, shortcodes cannot be silently overwritten in the registry:
+
+```ruby
+BBortcodes.register(MyShortcode)
+BBortcodes.register(MyShortcode)  # Raises BBortcodes::RegistryError
+
+# Allow overwrites if needed
+BBortcodes.configure do |config|
+  config.allow_shortcode_overwrite = true
+end
+```
+
+### Thread Safety
+
+Both the Registry and Context classes are thread-safe using Ruby's Monitor:
+
+```ruby
+# Safe to use across threads
+context = BBortcodes::Context.new
+
+threads = 10.times.map do
+  Thread.new do
+    context.increment(:counter)
+  end
+end
+
+threads.each(&:join)
+puts context.counter(:counter)  # Reliably outputs 10
+```
+
+### Security Best Practices
+
+1. **Always escape user input**: Keep `auto_escape_attributes: true` (default)
+2. **Set appropriate limits**: Adjust `max_input_length`, `parse_timeout`, and `max_nesting_depth` based on your use case
+3. **Validate shortcode sources**: Only parse content from trusted sources or properly sanitize user input
+4. **Use `only:` filter**: When parsing untrusted content, use the `only:` parameter to limit which shortcodes can be processed
+5. **Audit custom shortcodes**: Ensure your custom shortcode `render()` methods properly escape output
+
+## Configuration
+
+Configure error handling and security settings:
+
+```ruby
+BBortcodes.configure do |config|
+  # Error handling
+  # ---------------
+
+  # How to handle parse errors for unknown shortcodes
+  # Options: :raise, :skip (leave as-is), :strip (remove)
+  config.on_parse_error = :raise # default
+
+  # How to handle disallowed nested shortcodes
+  # Options: :raise, :skip (leave as-is), :strip (remove)
+  config.on_disallowed_child = :raise # default
+
+  # Validate shortcode classes on registration
+  config.validate_on_register = true # default
+
+  # Security settings
+  # -----------------
+
+  # Automatically escape HTML in attribute values to prevent XSS
+  config.auto_escape_attributes = true # default (recommended)
+
+  # Maximum input text size in bytes (default: 1MB)
+  config.max_input_length = 1_000_000
+
+  # Parse timeout in seconds to prevent ReDoS attacks
+  config.parse_timeout = 5
+
+  # Maximum nesting depth for shortcodes to prevent stack overflow
+  config.max_nesting_depth = 50
+
+  # Allow overwriting existing shortcodes in the registry
+  config.allow_shortcode_overwrite = false # default (recommended)
+end
+```
+
+#### Example: Skip Unknown Shortcodes
+
+```ruby
+BBortcodes.configure do |config|
+  config.on_parse_error = :skip
+end
+
+text = "Text with [unknown]shortcode[/unknown]"
+output, _ = BBortcodes.parse(text)
+
+puts output
+# => "Text with [unknown]shortcode[/unknown]"
+```
+
+#### Example: Strip Disallowed Children
+
+```ruby
+BBortcodes.configure do |config|
+  config.on_disallowed_child = :strip
+end
+
+# Assuming GalleryShortcode only allows ImageShortcode children
+text = "[gallery][image url=\"1.jpg\"][bold]Invalid[/bold][/gallery]"
+output, _ = BBortcodes.parse(text)
+
+puts output
+# => "<div class=\"gallery\"><img src=\"1.jpg\" /></div>"
+# The [bold] shortcode was stripped
+```
+
+### Environment-based Configuration
+
+Using [Anyway Config](https://github.com/palkan/anyway_config), you can configure via environment variables or YAML:
+
+```bash
+# Environment variables
+BBORTCODES_ON_PARSE_ERROR=skip
+BBORTCODES_ON_DISALLOWED_CHILD=strip
+```
+
+Or via `config/bbortcodes.yml`:
+
+```yaml
+production:
+  on_parse_error: skip
+  on_disallowed_child: skip
+
+development:
+  on_parse_error: raise
+  on_disallowed_child: raise
+```
+
+## Advanced Usage
+
+### Custom Parser Instance
+
+Create isolated parser instances with custom registries:
+
+```ruby
+# Create a custom registry
+registry = BBortcodes::Registry.new
+registry.register(MyShortcode)
+
+# Create a parser with custom registry
+parser = BBortcodes::Parser.new(registry: registry)
+output, shortcodes = parser.parse(text)
+```
+
+### Accessing Attributes
+
+Several helper methods are available for working with attributes:
+
+```ruby
+class MyShortcode < BBortcodes::Shortcode
+  def render(context)
+    # Get attribute with default value
+    color = attribute("color", "blue")
+
+    # Check if attribute exists
+    if has_attribute?("url")
+      url = attribute("url")
+    end
+
+    # Access all attributes
+    attributes.each do |key, value|
+      puts "#{key}: #{value}"
+    end
+  end
+end
+```
+
+### Working with Content
+
+```ruby
+class WrapperShortcode < BBortcodes::Shortcode
+  def render(context)
+    # Check if shortcode has content
+    if content.nil? || content.empty?
+      return "<div>No content</div>"
+    end
+
+    # Render nested content
+    content_html = render_content(context, nil)
+
+    "<div class=\"wrapper\">#{content_html}</div>"
+  end
+end
+```
+
+## Architecture
+
+### Grammar-based Parsing
+
+BBortcodes uses [Parslet](https://github.com/kschiess/parslet), a PEG (Parsing Expression Grammar) parser, instead of regular expressions. This provides:
+
+- **Robust parsing** of complex nested structures
+- **Better error messages** when syntax is invalid
+- **Composable grammar rules** for maintainability
+- **Unambiguous parsing** of edge cases
+
+### Type Safety
+
+Using [Literal](https://github.com/joeldrapper/literal), shortcode properties are type-checked at runtime:
+
+```ruby
+shortcode = MyShortcode.new(
+  name: "my_shortcode",
+  attributes: {"key" => "value"},
+  content: [],
+  self_closing: false
+)
+
+# Properties are type-checked
+shortcode.name # => String
+shortcode.attributes # => Hash
+shortcode.content # => Array
+shortcode.self_closing # => Boolean
+```
+
+### Thread Safety
+
+The global registry uses a Monitor for thread-safe concurrent access:
+
+```ruby
+# Safe to use across threads
+Thread.new { BBortcodes.register(Shortcode1) }
+Thread.new { BBortcodes.register(Shortcode2) }
+```
+
+## Development
+
+After checking out the repo, run:
+
+```bash
+bundle install
+```
+
+Run the examples:
+
+```bash
+ruby examples/basic_shortcodes.rb
+ruby examples/error_handling.rb
+```
+
+Run tests:
+
+```bash
+bundle exec rspec
+```
+
+Run linter:
+
+```bash
+bundle exec standardrb
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/yourusername/bbortcodes.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).