philiprehberger-xml_builder 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3fb9d2343ef89b02de12422a8ca7632e3d16634876c8d602f93966f35f4f8287
-  data.tar.gz: 7a21d2d73ddfe6d7d2305527fc1305425965197eb5950809d3168308ed4a7d4e
+  metadata.gz: 720c31767f0706544320e00c6fb4ed6e3dd946f601c68c947c6eaf409c324dd2
+  data.tar.gz: a8dafaef9908d5f485cdf57fc65654a8b11610e93575a27f78b668f6b9e342e4
 SHA512:
-  metadata.gz: 7c0d1c868566984cc1656049d2705a2b7af30293e567b0d66ff065edeeea004d257e5d3164b2e288949dfcc0654f0dddc3dea2d81a0c64ccebd1cd05c14afbb8
-  data.tar.gz: 8094d77d65803ac2ad438e1eee6c9c32218e60e6548a09d18874796bad2a17ba891178aa6f0198b6d756ea4d067abcca2a8492a391b7e8d8409d381fcf652df2
+  metadata.gz: 466443cf83706000e5ae81f7a8fd5cf673cb7aad9306a4de70d189182af0459e75a415b047063af46feaffe227342f3c1b51ac8288e312cca5ba2983efd38233
+  data.tar.gz: 5c904af4d1da2f0899771115ac35632ebd0c871c65236e24a98001522821a23e93d003723c4b4b98470da8579d8267a52443ba91243e16e46571a76fd6164515

data/CHANGELOG.md

@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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"')
@@ -209,6 +223,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 |

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
@@ -236,10 +254,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.4.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.4.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-11 00:00:00.000000000 Z
+date: 2026-04-16 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: