philiprehberger-xml_builder 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 922733a983681c827ed0fc8e94454e002abf37679785f1daba0153b9fff1dc01
+  data.tar.gz: 6826f30ce35d4c783862d55aee71819b643a0c41e1636d30d774afaba8928e37
+SHA512:
+  metadata.gz: 2a1c52baeb6dd26956f6d6b0662742cc61872bc1a27cd45e3512bc99bd0db1486e30953cecf7661540dd66097b68e9cd1083b75d33d5aa90f0bbd34ea658ba19
+  data.tar.gz: 4eb32107f4e5007bb7f6afea092cfbd25f927fc73bd4251d81384ae97d46d7931e858295ca0f7970d8c28111d84f55bc697448069ec03dba7ffe32ef1711e627

data/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to this gem 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] - 2026-03-26
+
+### Added
+- Initial release
+- Block-based DSL for building XML documents
+- XML declaration with configurable version and encoding
+- Element creation with attributes via `tag` method
+- Escaped text content via `text` method
+- CDATA sections via `cdata` method
+- XML comments via `comment` method
+- Processing instructions via `processing_instruction` method
+- Raw XML insertion via `raw` method
+- method_missing DSL for natural element creation
+- Pretty printing with configurable indentation via `to_xml(indent:)`
+- XML entity escaping for all five standard entities (&, <, >, ", ')

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 philiprehberger
+
+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,137 @@
+# philiprehberger-xml_builder
+
+[![Tests](https://github.com/philiprehberger/rb-xml-builder/actions/workflows/ci.yml/badge.svg)](https://github.com/philiprehberger/rb-xml-builder/actions/workflows/ci.yml)
+[![Gem Version](https://badge.fury.io/rb/philiprehberger-xml_builder.svg)](https://rubygems.org/gems/philiprehberger-xml_builder)
+[![License](https://img.shields.io/github/license/philiprehberger/rb-xml-builder)](LICENSE)
+[![Sponsor](https://img.shields.io/badge/sponsor-GitHub%20Sponsors-ec6cb9)](https://github.com/sponsors/philiprehberger)
+
+Lightweight XML builder DSL without Nokogiri dependency
+
+## Requirements
+
+- Ruby >= 3.1
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "philiprehberger-xml_builder"
+```
+
+Or install directly:
+
+```bash
+gem install philiprehberger-xml_builder
+```
+
+## Usage
+
+```ruby
+require "philiprehberger/xml_builder"
+
+xml = Philiprehberger::XmlBuilder.build do |doc|
+  doc.tag(:root) do
+    doc.tag(:item, id: "1") { doc.text("Hello") }
+  end
+end
+
+puts xml
+# <?xml version="1.0" encoding="UTF-8"?><root><item id="1">Hello</item></root>
+```
+
+### Method Missing DSL
+
+Use method names directly as tag names for a cleaner syntax:
+
+```ruby
+xml = Philiprehberger::XmlBuilder.build do |doc|
+  doc.person(name: "John") do
+    doc.age("30")
+    doc.email("john@example.com")
+  end
+end
+# <person name="John"><age>30</age><email>john@example.com</email></person>
+```
+
+### CDATA and Comments
+
+```ruby
+xml = Philiprehberger::XmlBuilder.build do |doc|
+  doc.tag(:root) do
+    doc.comment("Generated XML")
+    doc.tag(:script) { doc.cdata('var x = 1 < 2;') }
+  end
+end
+```
+
+### Processing Instructions
+
+```ruby
+xml = Philiprehberger::XmlBuilder.build do |doc|
+  doc.processing_instruction("xml-stylesheet", 'type="text/xsl" href="style.xsl"')
+  doc.tag(:root) { doc.text("content") }
+end
+```
+
+### Pretty Printing
+
+```ruby
+doc = Philiprehberger::XmlBuilder::Document.new
+doc.tag(:root) do
+  doc.tag(:child) { doc.text("value") }
+end
+
+puts doc.to_xml(indent: 2)
+# <?xml version="1.0" encoding="UTF-8"?>
+# <root>
+#   <child>value</child>
+# </root>
+```
+
+### Raw XML
+
+```ruby
+xml = Philiprehberger::XmlBuilder.build do |doc|
+  doc.tag(:root) { doc.raw("<pre>formatted</pre>") }
+end
+```
+
+## API
+
+### `Philiprehberger::XmlBuilder`
+
+| Method | Description |
+|--------|-------------|
+| `.build(encoding: "UTF-8", version: "1.0") { \|doc\| ... }` | Build an XML document and return the string |
+
+### `Document`
+
+| Method | Description |
+|--------|-------------|
+| `#tag(name, attributes = {}) { ... }` | Add an element with optional attributes and children |
+| `#text(content)` | Add escaped text content |
+| `#cdata(content)` | Add a CDATA section |
+| `#comment(text)` | Add an XML comment |
+| `#processing_instruction(target, content)` | Add a processing instruction |
+| `#raw(string)` | Add raw unescaped XML |
+| `#to_s` | Render compact XML string |
+| `#to_xml(indent: nil)` | Render XML with optional indentation |
+
+### `Escaper`
+
+| Method | Description |
+|--------|-------------|
+| `.escape(text)` | Escape XML entities (&, <, >, ", ') |
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+[MIT](LICENSE)

data/lib/philiprehberger/xml_builder/document.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module XmlBuilder
+    # Accumulates XML nodes and renders the final document.
+    #
+    # Used as the context object inside XmlBuilder.build blocks.
+    class Document
+      attr_reader :version, :encoding
+
+      # @param version [String] XML version for the declaration
+      # @param encoding [String] XML encoding for the declaration
+      def initialize(version: '1.0', encoding: 'UTF-8')
+        @version = version
+        @encoding = encoding
+        @children = []
+        @node_stack = []
+      end
+
+      # Add an XML element with optional attributes and nested children.
+      #
+      # @param name [String, Symbol] the element tag name
+      # @param attributes [Hash] element attributes
+      # @yield optional block for adding child elements
+      # @return [Node] the created node
+      def tag(name, attributes = {}, &block)
+        node = Node.new(name, attributes)
+
+        if block
+          @node_stack.push(node)
+          block.call
+          @node_stack.pop
+        end
+
+        current_parent.push(node)
+        node
+      end
+
+      # Add escaped text content to the current element.
+      #
+      # @param content [String] the text content to escape and add
+      # @return [void]
+      def text(content)
+        current_parent.push(Escaper.escape(content.to_s))
+      end
+
+      # Add a CDATA section.
+      #
+      # @param content [String] the CDATA content (must not contain "]]>")
+      # @return [void]
+      def cdata(content)
+        current_parent.push("<![CDATA[#{content}]]>")
+      end
+
+      # Add an XML comment.
+      #
+      # @param text [String] the comment text
+      # @return [void]
+      def comment(text)
+        current_parent.push("<!-- #{text} -->")
+      end
+
+      # Add a processing instruction.
+      #
+      # @param target [String] the PI target
+      # @param content [String] the PI content
+      # @return [void]
+      def processing_instruction(target, content)
+        current_parent.push("<?#{target} #{content}?>")
+      end
+
+      # Add raw XML content without escaping.
+      #
+      # @param string [String] raw XML string
+      # @return [void]
+      def raw(string)
+        current_parent.push(string.to_s)
+      end
+
+      # Render the document as a compact XML string (no indentation).
+      #
+      # @return [String] the rendered XML document
+      def to_s
+        to_xml
+      end
+
+      # Render the document as an XML string with optional indentation.
+      #
+      # @param indent [Integer, nil] number of spaces per indentation level, or nil for compact output
+      # @return [String] the rendered XML document
+      def to_xml(indent: nil)
+        parts = ["<?xml version=\"#{@version}\" encoding=\"#{@encoding}\"?>"]
+        parts << (indent ? "\n" : '')
+
+        @children.each do |child|
+          parts << render_child(child, indent: indent, level: 0)
+        end
+
+        parts.join
+      end
+
+      # Support method_missing for DSL-style tag creation.
+      #
+      # @example
+      #   xml.person(name: "John") { xml.age("30") }
+      #   # => <person name="John"><age>30</age></person>
+      def method_missing(method_name, *args, &block)
+        first_arg = args.first
+        attributes = {}
+        text_content = nil
+
+        if first_arg.is_a?(Hash)
+          attributes = first_arg
+        elsif first_arg
+          text_content = first_arg.to_s
+          attributes = args[1] if args[1].is_a?(Hash)
+        end
+
+        if text_content
+          tag(method_name, attributes) { text(text_content) }
+        elsif block
+          tag(method_name, attributes, &block)
+        else
+          tag(method_name, attributes)
+        end
+      end
+
+      # @return [Boolean]
+      def respond_to_missing?(_method_name, _include_private = false)
+        true
+      end
+
+      private
+
+      def current_parent
+        @node_stack.last&.children || @children
+      end
+
+      def render_child(child, indent:, level:)
+        case child
+        when Node
+          child.render(indent: indent, level: level)
+        when String
+          if indent
+            "#{' ' * (indent * level)}#{child}\n"
+          else
+            child
+          end
+        else
+          child.to_s
+        end
+      end
+    end
+  end
+end

data/lib/philiprehberger/xml_builder/escaper.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module XmlBuilder
+    # XML entity escaping for text content and attribute values.
+    module Escaper
+      ENTITIES = {
+        '&' => '&',
+        '<' => '&lt;',
+        '>' => '&gt;',
+        '"' => '&quot;',
+        "'" => '&apos;'
+      }.freeze
+
+      ENTITY_PATTERN = Regexp.union(ENTITIES.keys).freeze
+
+      # Escape special XML characters in a string.
+      #
+      # @param text [String] the text to escape
+      # @return [String] the escaped text
+      def self.escape(text)
+        text.to_s.gsub(ENTITY_PATTERN, ENTITIES)
+      end
+    end
+  end
+end

data/lib/philiprehberger/xml_builder/node.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module XmlBuilder
+    # Represents a single XML element with optional attributes and children.
+    class Node
+      attr_reader :name, :attributes, :children
+
+      # @param name [String, Symbol] the element tag name
+      # @param attributes [Hash] element attributes
+      def initialize(name, attributes = {})
+        @name = name.to_s
+        @attributes = attributes
+        @children = []
+      end
+
+      # Render this node and its children as an XML string.
+      #
+      # @param indent [Integer, nil] number of spaces per indentation level, or nil for compact output
+      # @param level [Integer] current nesting depth (used internally)
+      # @return [String] the rendered XML
+      def render(indent: nil, level: 0)
+        prefix = indent ? ' ' * (indent * level) : ''
+        newline = indent ? "\n" : ''
+
+        attrs = render_attributes
+        tag_open = "#{prefix}<#{@name}#{attrs}"
+
+        if @children.empty?
+          "#{tag_open} />#{newline}"
+        else
+          parts = ["#{tag_open}>"]
+          inline = !indent || @children.all?(String)
+
+          if inline
+            @children.each { |child| parts << render_child(child, indent: nil, level: 0) }
+            parts << "</#{@name}>#{newline}"
+          else
+            parts[0] << newline
+            @children.each { |child| parts << render_child(child, indent: indent, level: level + 1) }
+            parts << "#{prefix}</#{@name}>#{newline}"
+          end
+          parts.join
+        end
+      end
+
+      private
+
+      def render_attributes
+        return '' if @attributes.empty?
+
+        pairs = @attributes.map do |key, value|
+          " #{key}=\"#{Escaper.escape(value)}\""
+        end
+        pairs.join
+      end
+
+      def render_child(child, indent:, level:)
+        case child
+        when Node
+          child.render(indent: indent, level: level)
+        when String
+          if indent && level.positive?
+            "#{' ' * (indent * level)}#{child}\n"
+          else
+            child
+          end
+        else
+          child.to_s
+        end
+      end
+    end
+  end
+end

data/lib/philiprehberger/xml_builder/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module XmlBuilder
+    VERSION = '0.1.0'
+  end
+end

data/lib/philiprehberger/xml_builder.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative 'xml_builder/version'
+require_relative 'xml_builder/escaper'
+require_relative 'xml_builder/node'
+require_relative 'xml_builder/document'
+
+module Philiprehberger
+  module XmlBuilder
+    class Error < StandardError; end
+
+    # Build an XML document using a block-based DSL.
+    #
+    # @param encoding [String] XML encoding declaration (default: "UTF-8")
+    # @param version [String] XML version declaration (default: "1.0")
+    # @yield [Document] the document builder
+    # @return [String] the rendered XML string
+    def self.build(encoding: 'UTF-8', version: '1.0', &block)
+      doc = Document.new(version: version, encoding: encoding)
+      block.call(doc)
+      doc.to_s
+    end
+  end
+end

metadata

@@ -0,0 +1,57 @@
+--- !ruby/object:Gem::Specification
+name: philiprehberger-xml_builder
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Philip Rehberger
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-03-27 00:00:00.000000000 Z
+dependencies: []
+description: Programmatic XML construction with a clean DSL, auto-escaping, CDATA,
+  comments, processing instructions, and pretty printing. Zero dependencies.
+email:
+- me@philiprehberger.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/philiprehberger/xml_builder.rb
+- lib/philiprehberger/xml_builder/document.rb
+- lib/philiprehberger/xml_builder/escaper.rb
+- lib/philiprehberger/xml_builder/node.rb
+- lib/philiprehberger/xml_builder/version.rb
+homepage: https://github.com/philiprehberger/rb-xml-builder
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/philiprehberger/rb-xml-builder
+  source_code_uri: https://github.com/philiprehberger/rb-xml-builder
+  changelog_uri: https://github.com/philiprehberger/rb-xml-builder/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/philiprehberger/rb-xml-builder/issues
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Lightweight XML builder DSL without Nokogiri dependency
+test_files: []