philiprehberger-xml_builder 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3fb9d2343ef89b02de12422a8ca7632e3d16634876c8d602f93966f35f4f8287
-  data.tar.gz: 7a21d2d73ddfe6d7d2305527fc1305425965197eb5950809d3168308ed4a7d4e
+  metadata.gz: c3469bf0da4d625250b3e99c2659f1c5299d344a7b6b7f60f24af0cc9fd07f71
+  data.tar.gz: c806ec833b1d176a5907fb977c39c54b3e35f1103314cd2abfd335b260faff39
 SHA512:
-  metadata.gz: 7c0d1c868566984cc1656049d2705a2b7af30293e567b0d66ff065edeeea004d257e5d3164b2e288949dfcc0654f0dddc3dea2d81a0c64ccebd1cd05c14afbb8
-  data.tar.gz: 8094d77d65803ac2ad438e1eee6c9c32218e60e6548a09d18874796bad2a17ba891178aa6f0198b6d756ea4d067abcca2a8492a391b7e8d8409d381fcf652df2
+  metadata.gz: 9d8b31224c876a05e5d71619d80ad32a6cff4b7df989b21344d6b7063313e5a7454f1fb58ad0a506f3b49205258d5c9a4937231368e37f82572c8dbaf47230d2
+  data.tar.gz: fe9aba2f34358d9f54fce39e6894fa3959aa1c8dc29588fcb568112c24eaf432e84909cec5c78716f149b8803c8cdff080ab23241060af8a0a67b20c4e3e4c19

data/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-05-07
+
+### Added
+- `Document#pretty(indent: 2)` — convenience renderer for pretty-printed XML, equivalent to `to_xml(indent: 2)` but with sane defaults.
+
+## [0.4.0] - 2026-04-16
+
+### Added
+- Processing instruction (PI) node support via `Document#processing_instruction` / `#pi`
+
 ## [0.3.0] - 2026-04-10
 
 ### Added

data/README.md

@@ -68,6 +68,20 @@ end
 
 ### Processing Instructions
 
+Pass keyword attributes to emit a structured PI with XML-escaped values:
+
+```ruby
+xml = Philiprehberger::XmlBuilder.build do |doc|
+  doc.pi("xml-stylesheet", href: "style.xsl", type: "text/xsl")
+  doc.tag(:root) { doc.text("content") }
+end
+
+puts xml
+# <?xml version="1.0" encoding="UTF-8"?><?xml-stylesheet href="style.xsl" type="text/xsl"?><root>content</root>
+```
+
+A legacy positional content string is also supported:
+
 ```ruby
 xml = Philiprehberger::XmlBuilder.build do |doc|
   doc.processing_instruction("xml-stylesheet", 'type="text/xsl" href="style.xsl"')
@@ -90,6 +104,16 @@ puts doc.to_xml(indent: 2)
 # </root>
 ```
 
+Or use `#pretty` for the same output with sane defaults:
+
+```ruby
+puts doc.pretty
+# Equivalent to doc.to_xml(indent: 2)
+
+puts doc.pretty(indent: 4)
+# Equivalent to doc.to_xml(indent: 4)
+```
+
 ### Raw XML
 
 ```ruby
@@ -209,6 +233,7 @@ end
 | `#cdata(content)` | Add a CDATA section |
 | `#comment(text)` | Add an XML comment |
 | `#processing_instruction(target, content)` | Add a processing instruction |
+| `#processing_instruction(target, **attrs)` | Append an XML processing instruction (alias: `#pi`) |
 | `#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 |
@@ -217,6 +242,7 @@ end
 | `#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 |
+| `#pretty(indent: 2)` | Renders with default 2-space indentation |
 
 ### `Escaper`
 

data/lib/philiprehberger/xml_builder/document.rb

@@ -66,15 +66,33 @@ module Philiprehberger
         current_parent.push("<!-- #{text} -->")
       end
 
+      # Valid PI target pattern per the XML spec (simplified).
+      PI_TARGET_PATTERN = /\A[A-Za-z_][\w.-]*\z/
+
       # Add a processing instruction.
       #
-      # @param target [String] the PI target
-      # @param content [String] the PI content
+      # Accepts either a legacy positional content string or keyword attributes.
+      # When attrs are given, renders as <?target key="value" key2="value2"?>.
+      # When a content string is given, renders as <?target content?>.
+      #
+      # @param target [String] the PI target (must match PI_TARGET_PATTERN; "xml" is forbidden)
+      # @param content [String, nil] optional raw PI content string (legacy)
+      # @param attrs [Hash] attribute key/value pairs (XML-escaped)
       # @return [void]
-      def processing_instruction(target, content)
-        current_parent.push("<?#{target} #{content}?>")
+      # @raise [ArgumentError] if target is empty, invalid, or equal to "xml" (case-insensitive)
+      def processing_instruction(target, content = nil, **attrs)
+        validate_pi_target!(target)
+
+        if content.is_a?(String)
+          current_parent.push("<?#{target} #{content}?>")
+        else
+          current_parent.push(ProcessingInstruction.new(target, attrs))
+        end
       end
 
+      # Alias for #processing_instruction.
+      alias pi processing_instruction
+
       # Add raw XML content without escaping.
       #
       # @param string [String] raw XML string
@@ -90,6 +108,14 @@ module Philiprehberger
         to_xml
       end
 
+      # Render the document as a pretty-printed XML string with default 2-space indentation.
+      #
+      # @param indent [Integer] number of spaces per indentation level (default 2)
+      # @return [String] the rendered XML document
+      def pretty(indent: 2)
+        to_xml(indent: indent)
+      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
@@ -236,10 +262,18 @@ module Philiprehberger
         @node_stack.last&.children || @children
       end
 
+      def validate_pi_target!(target)
+        raise ArgumentError, 'PI target must be a non-empty String' unless target.is_a?(String) && !target.empty?
+        raise ArgumentError, 'PI target "xml" is reserved by the XML specification' if target.casecmp('xml').zero?
+        raise ArgumentError, "Invalid PI target: #{target.inspect}" unless target.match?(PI_TARGET_PATTERN)
+      end
+
       def render_child(child, indent:, level:)
         case child
         when Node
           child.render(indent: indent, level: level)
+        when ProcessingInstruction
+          child.to_xml(indent: indent, level: level, pretty: !indent.nil?)
         when String
           if indent
             "#{' ' * (indent * level)}#{child}\n"

data/lib/philiprehberger/xml_builder/processing_instruction.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module XmlBuilder
+    # Represents an XML processing instruction (PI).
+    #
+    # Renders as <?target key="value" key2="value2"?>, with attribute
+    # values escaped via Escaper.
+    class ProcessingInstruction
+      attr_reader :target, :attributes
+
+      # @param target [String] the PI target name
+      # @param attributes [Hash] attribute key/value pairs
+      def initialize(target, attributes = {})
+        @target = target.to_s
+        @attributes = attributes
+      end
+
+      # Render this processing instruction 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)
+      # @param pretty [Boolean] whether to apply pretty-print formatting
+      # @return [String] the rendered processing instruction
+      def to_xml(indent: nil, level: 0, pretty: false)
+        prefix = indent && pretty ? ' ' * (indent * level) : ''
+        newline = indent && pretty ? "\n" : ''
+        "#{prefix}<?#{@target}#{render_attributes}?>#{newline}"
+      end
+
+      # Alias for to_xml to match Node#render semantics.
+      def render(indent: nil, level: 0)
+        to_xml(indent: indent, level: level, pretty: !indent.nil?)
+      end
+
+      private
+
+      def render_attributes
+        return '' if @attributes.empty?
+
+        pairs = @attributes.map do |key, value|
+          attr_name = key.to_s.gsub('__', ':')
+          " #{attr_name}=\"#{Escaper.escape(value)}\""
+        end
+        pairs.join
+      end
+    end
+  end
+end

data/lib/philiprehberger/xml_builder/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module XmlBuilder
-    VERSION = '0.3.0'
+    VERSION = '0.5.0'
   end
 end

data/lib/philiprehberger/xml_builder.rb

@@ -3,6 +3,7 @@
 require_relative 'xml_builder/version'
 require_relative 'xml_builder/escaper'
 require_relative 'xml_builder/node'
+require_relative 'xml_builder/processing_instruction'
 require_relative 'xml_builder/document'
 
 module Philiprehberger

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-xml_builder
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-11 00:00:00.000000000 Z
+date: 2026-05-07 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.
@@ -25,6 +25,7 @@ files:
 - lib/philiprehberger/xml_builder/document.rb
 - lib/philiprehberger/xml_builder/escaper.rb
 - lib/philiprehberger/xml_builder/node.rb
+- lib/philiprehberger/xml_builder/processing_instruction.rb
 - lib/philiprehberger/xml_builder/version.rb
 homepage: https://philiprehberger.com/open-source-packages/ruby/philiprehberger-xml_builder
 licenses: