philiprehberger-xml_builder 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 922733a983681c827ed0fc8e94454e002abf37679785f1daba0153b9fff1dc01
-  data.tar.gz: 6826f30ce35d4c783862d55aee71819b643a0c41e1636d30d774afaba8928e37
+  metadata.gz: 02c1eeed30ddee688b0bee7143b27ad18d90c649a1b1d1d98d5d7f72f437e4e8
+  data.tar.gz: 3b01559a4ebfdf722c7992a1f6f844ad3ae40ff809e287ca2925f7297274ddcb
 SHA512:
-  metadata.gz: 2a1c52baeb6dd26956f6d6b0662742cc61872bc1a27cd45e3512bc99bd0db1486e30953cecf7661540dd66097b68e9cd1083b75d33d5aa90f0bbd34ea658ba19
-  data.tar.gz: 4eb32107f4e5007bb7f6afea092cfbd25f927fc73bd4251d81384ae97d46d7931e858295ca0f7970d8c28111d84f55bc697448069ec03dba7ffe32ef1711e627
+  metadata.gz: e9b4ebc5605369a8f6e0ee94238ea1797d56728ee32f63d3254808240f789c8637cce12b9f386112ebd2115aa4e558b2b3601eb130a436d84e04e28bfd9e11bc
+  data.tar.gz: 4ae1e0ecdc135accc90eec5704ec175e5344cf98b65ee851d98937f478f9cbfcb000b62d167b03dfc1b2ac77ccd4898f9c669885122d7873dc5cca51a827e8f3

data/CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-03-28
+
+### Added
+
+- XML namespace support with `namespace` and `namespace_tag` methods for prefix declarations and namespace-aware elements
+- SOAP envelope builder with `soap_envelope` DSL and `build_soap` convenience method supporting SOAP 1.1 and 1.2
+- XML fragment composition with `append` (merge Document objects) and `insert_fragment` (insert raw XML strings)
+- Support for double-underscore to colon conversion in symbol attribute keys (e.g. `xmlns__soap:` becomes `xmlns:soap=`)
+
+## [0.1.1] - 2026-03-26
+
+### Added
+
+- Add GitHub funding configuration
+
 ## [0.1.0] - 2026-03-26
 
 ### Added

data/README.md

@@ -1,9 +1,6 @@
 # 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)
+[![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://img.shields.io/gem/v/philiprehberger-xml_builder)](https://rubygems.org/gems/philiprehberger-xml_builder) [![GitHub release](https://img.shields.io/github/v/release/philiprehberger/rb-xml-builder)](https://github.com/philiprehberger/rb-xml-builder/releases) [![GitHub last commit](https://img.shields.io/github/last-commit/philiprehberger/rb-xml-builder)](https://github.com/philiprehberger/rb-xml-builder/commits/main) [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![Bug Reports](https://img.shields.io/badge/bug-reports-red.svg)](https://github.com/philiprehberger/rb-xml-builder/issues) [![Feature Requests](https://img.shields.io/badge/feature-requests-blue.svg)](https://github.com/philiprehberger/rb-xml-builder/issues) [![GitHub Sponsors](https://img.shields.io/badge/sponsor-philiprehberger-ea4aaa.svg?logo=github)](https://github.com/sponsors/philiprehberger)
 
 Lightweight XML builder DSL without Nokogiri dependency
 
@@ -27,6 +24,8 @@ gem install philiprehberger-xml_builder
 
 ## Usage
 
+### Basic Elements
+
 ```ruby
 require "philiprehberger/xml_builder"
 
@@ -97,6 +96,86 @@ xml = Philiprehberger::XmlBuilder.build do |doc|
 end
 ```
 
+### XML Namespaces
+
+Register namespace prefixes and create namespace-aware elements:
+
+```ruby
+xml = Philiprehberger::XmlBuilder.build do |doc|
+  doc.namespace(:soap, "http://schemas.xmlsoap.org/soap/envelope/")
+  doc.namespace(:wsse, "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd")
+
+  doc.namespace_tag(:soap, :Envelope) do
+    doc.namespace_tag(:soap, :Header) do
+      doc.namespace_tag(:wsse, :Security)
+    end
+    doc.namespace_tag(:soap, :Body)
+  end
+end
+```
+
+You can also use string tag names directly:
+
+```ruby
+xml = Philiprehberger::XmlBuilder.build do |doc|
+  doc.tag("soap:Envelope", "xmlns:soap" => "http://schemas.xmlsoap.org/soap/envelope/") do
+    doc.tag("soap:Body")
+  end
+end
+```
+
+### SOAP Envelope Builder
+
+Build SOAP 1.1 or 1.2 envelopes with a convenience DSL:
+
+```ruby
+xml = Philiprehberger::XmlBuilder.build do |doc|
+  doc.soap_envelope(version: "1.1") do |header, body|
+    header << ->(d) { d.tag("auth") { d.text("token123") } }
+    body << ->(d) { d.tag("GetPrice") { d.text("Widget") } }
+  end
+end
+```
+
+Or use the top-level shortcut:
+
+```ruby
+xml = Philiprehberger::XmlBuilder.build_soap(soap_version: "1.2") do |header, body|
+  body << ->(d) { d.tag("GetStockPrice") { d.tag("Symbol") { d.text("AAPL") } } }
+end
+```
+
+### XML Fragment Composition
+
+Combine separately built document fragments:
+
+```ruby
+# Build fragments independently
+header = Philiprehberger::XmlBuilder::Document.new
+header.tag(:title) { header.text("My Document") }
+
+body = Philiprehberger::XmlBuilder::Document.new
+body.tag(:paragraph) { body.text("Hello world") }
+
+# Compose into a single document
+xml = Philiprehberger::XmlBuilder.build do |doc|
+  doc.tag(:document) do
+    doc.tag(:header) { doc.append(header) }
+    doc.tag(:body) { doc.append(body) }
+  end
+end
+```
+
+Insert raw XML fragment strings:
+
+```ruby
+xml = Philiprehberger::XmlBuilder.build do |doc|
+  doc.tag(:root) do
+    doc.insert_fragment('<existing>data</existing>')
+  end
+end
+```
+
 ## API
 
 ### `Philiprehberger::XmlBuilder`
@@ -104,6 +183,7 @@ end
 | Method | Description |
 |--------|-------------|
 | `.build(encoding: "UTF-8", version: "1.0") { \|doc\| ... }` | Build an XML document and return the string |
+| `.build_soap(soap_version: "1.1", encoding: "UTF-8", version: "1.0") { \|header, body\| ... }` | Build a SOAP envelope document |
 
 ### `Document`
 
@@ -115,6 +195,11 @@ end
 | `#comment(text)` | Add an XML comment |
 | `#processing_instruction(target, content)` | Add a processing instruction |
 | `#raw(string)` | Add raw unescaped XML |
+| `#namespace(prefix, uri)` | Register an XML namespace prefix and URI |
+| `#namespace_tag(prefix, name, attributes = {}) { ... }` | Add a namespace-prefixed element with auto xmlns |
+| `#soap_envelope(version: "1.1") { \|header, body\| ... }` | Build a SOAP envelope with Header and Body |
+| `#append(other_document)` | Append children from another Document |
+| `#insert_fragment(xml_string)` | Insert a raw XML fragment string |
 | `#to_s` | Render compact XML string |
 | `#to_xml(indent: nil)` | Render XML with optional indentation |
 
@@ -132,6 +217,10 @@ bundle exec rspec
 bundle exec rubocop
 ```
 
+## Support
+
+[![LinkedIn](https://img.shields.io/badge/LinkedIn-Philip%20Rehberger-blue?logo=linkedin)](https://linkedin.com/in/philiprehberger) [![More Packages](https://img.shields.io/badge/more-packages-blue.svg)](https://github.com/philiprehberger?tab=repositories)
+
 ## License
 
 [MIT](LICENSE)

data/lib/philiprehberger/xml_builder/document.rb

@@ -6,7 +6,7 @@ module Philiprehberger
     #
     # Used as the context object inside XmlBuilder.build blocks.
     class Document
-      attr_reader :version, :encoding
+      attr_reader :version, :encoding, :children
 
       # @param version [String] XML version for the declaration
       # @param encoding [String] XML encoding for the declaration
@@ -15,6 +15,7 @@ module Philiprehberger
         @encoding = encoding
         @children = []
         @node_stack = []
+        @namespaces = {}
       end
 
       # Add an XML element with optional attributes and nested children.
@@ -99,6 +100,96 @@ module Philiprehberger
         parts.join
       end
 
+      # Register an XML namespace prefix and URI.
+      #
+      # Registered namespaces are automatically added as xmlns attributes
+      # when using namespace_tag.
+      #
+      # @param prefix [String, Symbol] the namespace prefix
+      # @param uri [String] the namespace URI
+      # @return [void]
+      def namespace(prefix, uri)
+        @namespaces[prefix.to_s] = uri
+      end
+
+      # Add a namespace-prefixed element.
+      #
+      # Automatically includes the xmlns declaration for the prefix if it was
+      # registered via #namespace and this is the first use in the current scope.
+      #
+      # @param prefix [String, Symbol] the namespace prefix
+      # @param name [String, Symbol] the local element name
+      # @param attributes [Hash] additional element attributes
+      # @yield optional block for adding child elements
+      # @return [Node] the created node
+      def namespace_tag(prefix, name, attributes = {}, &)
+        prefixed_name = "#{prefix}:#{name}"
+        uri = @namespaces[prefix.to_s]
+        attrs = if uri
+                  { "xmlns:#{prefix}" => uri }.merge(attributes)
+                else
+                  attributes
+                end
+        tag(prefixed_name, attrs, &)
+      end
+
+      # Build a SOAP envelope using a block-based DSL.
+      #
+      # Supports SOAP 1.1 (default) and 1.2. Automatically sets the correct
+      # namespace URI and creates the Envelope, Header, and Body elements.
+      #
+      # @param version [String] SOAP version: "1.1" or "1.2"
+      # @yield [header, body] yields two procs for adding header and body content
+      # @return [void]
+      def soap_envelope(version: '1.1')
+        uri = case version
+              when '1.1' then 'http://schemas.xmlsoap.org/soap/envelope/'
+              when '1.2' then 'http://www.w3.org/2003/05/soap-envelope'
+              else
+                raise Error, "Unsupported SOAP version: #{version}. Use '1.1' or '1.2'."
+              end
+
+        header_children = []
+        body_children = []
+
+        yield(header_children, body_children) if block_given?
+
+        tag('soap:Envelope', 'xmlns:soap' => uri) do
+          tag('soap:Header') do
+            header_children.each { |child_block| child_block.call(self) }
+          end
+          tag('soap:Body') do
+            body_children.each { |child_block| child_block.call(self) }
+          end
+        end
+      end
+
+      # Append children from another Document into this document.
+      #
+      # Copies all top-level children from the source document into the current
+      # insertion point (either the document root or the current parent element).
+      #
+      # @param other [Document] the source document whose children to import
+      # @return [void]
+      def append(other)
+        raise Error, 'append expects a Document' unless other.is_a?(Document)
+
+        other.children.each do |child|
+          current_parent.push(child)
+        end
+      end
+
+      # Insert a raw XML fragment string into the current position.
+      #
+      # This is an alias for #raw, provided for semantic clarity when composing
+      # fragments.
+      #
+      # @param xml_string [String] the XML fragment to insert
+      # @return [void]
+      def insert_fragment(xml_string)
+        raw(xml_string)
+      end
+
       # Support method_missing for DSL-style tag creation.
       #
       # @example

data/lib/philiprehberger/xml_builder/node.rb

@@ -50,7 +50,8 @@ module Philiprehberger
         return '' if @attributes.empty?
 
         pairs = @attributes.map do |key, value|
-          " #{key}=\"#{Escaper.escape(value)}\""
+          attr_name = key.to_s.gsub('__', ':')
+          " #{attr_name}=\"#{Escaper.escape(value)}\""
         end
         pairs.join
       end

data/lib/philiprehberger/xml_builder/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module XmlBuilder
-    VERSION = '0.1.0'
+    VERSION = '0.2.0'
   end
 end

data/lib/philiprehberger/xml_builder.rb

@@ -20,5 +20,21 @@ module Philiprehberger
       block.call(doc)
       doc.to_s
     end
+
+    # Build a SOAP envelope document.
+    #
+    # Convenience wrapper around Document#soap_envelope that creates
+    # a full XML document with the proper SOAP structure.
+    #
+    # @param soap_version [String] SOAP version: "1.1" or "1.2"
+    # @param encoding [String] XML encoding declaration (default: "UTF-8")
+    # @param version [String] XML version declaration (default: "1.0")
+    # @yield [header, body] yields two arrays; push lambdas that accept a doc
+    # @return [String] the rendered SOAP XML string
+    def self.build_soap(soap_version: '1.1', encoding: 'UTF-8', version: '1.0', &block)
+      doc = Document.new(version: version, encoding: encoding)
+      doc.soap_envelope(version: soap_version, &block)
+      doc.to_s
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-xml_builder
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-27 00:00:00.000000000 Z
+date: 2026-03-28 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.