philiprehberger-xml_builder 0.2.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 82e57a50119722850b37aea9fb4dc8d4ed53774c8377750baee25faf0b118b76
-  data.tar.gz: 41d22968c8eff5a8e31c1223f6169d40aa65ac5b2c9eb07034495681a0dcd94f
+  metadata.gz: 720c31767f0706544320e00c6fb4ed6e3dd946f601c68c947c6eaf409c324dd2
+  data.tar.gz: a8dafaef9908d5f485cdf57fc65654a8b11610e93575a27f78b668f6b9e342e4
 SHA512:
-  metadata.gz: 7923d521f4ad86f86d608541cb482b4cadc1a41a378d4a228a4e9e48dc9068047dadfb4670d3e3a2060bac706f2df02f1c426ea48a1421bb4570eb3c52524c05
-  data.tar.gz: 53aa3ea970baf6adf08387b2a9900f61390ea8ec316d9de912205bab2095f2d3c90a3fb6ffa0affb847e5598ff2d60ce73dcb998a99cb2a4dd1da17763f69fac
+  metadata.gz: 466443cf83706000e5ae81f7a8fd5cf673cb7aad9306a4de70d189182af0459e75a415b047063af46feaffe227342f3c1b51ac8288e312cca5ba2983efd38233
+  data.tar.gz: 5c904af4d1da2f0899771115ac35632ebd0c871c65236e24a98001522821a23e93d003723c4b4b98470da8579d8267a52443ba91243e16e46571a76fd6164515

data/CHANGELOG.md

@@ -7,6 +7,24 @@ 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
+- Add `declaration:` option to `build`, `build_soap`, and `Document.new` to omit the XML declaration when building fragments
+- Add CDATA content validation — raises `Error` if content contains `]]>`
+- Add comment text validation — raises `Error` if text contains `--`
+- Add Ruby 3.4 to CI test matrix
+
+## [0.2.2] - 2026-03-31
+
+### Added
+- Add GitHub issue templates, dependabot config, and PR template
+
 ## [0.2.1] - 2026-03-31
 
 ### Changed

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"')
@@ -98,6 +112,19 @@ xml = Philiprehberger::XmlBuilder.build do |doc|
 end
 ```
 
+### Without XML Declaration
+
+Omit the `<?xml ... ?>` declaration when building fragments:
+
+```ruby
+xml = Philiprehberger::XmlBuilder.build(declaration: false) do |doc|
+  doc.tag(:item, id: "1") { doc.text("fragment") }
+end
+
+puts xml
+# <item id="1">fragment</item>
+```
+
 ### XML Namespaces
 
 Register namespace prefixes and create namespace-aware elements:
@@ -184,8 +211,8 @@ 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 |
+| `.build(encoding: "UTF-8", version: "1.0", declaration: true) { \|doc\| ... }` | Build an XML document and return the string |
+| `.build_soap(soap_version: "1.1", encoding: "UTF-8", version: "1.0", declaration: true) { \|header, body\| ... }` | Build a SOAP envelope document |
 
 ### `Document`
 
@@ -196,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

@@ -10,9 +10,10 @@ module Philiprehberger
 
       # @param version [String] XML version for the declaration
       # @param encoding [String] XML encoding for the declaration
-      def initialize(version: '1.0', encoding: 'UTF-8')
+      def initialize(version: '1.0', encoding: 'UTF-8', declaration: true)
         @version = version
         @encoding = encoding
+        @declaration = declaration
         @children = []
         @node_stack = []
         @namespaces = {}
@@ -50,6 +51,8 @@ module Philiprehberger
       # @param content [String] the CDATA content (must not contain "]]>")
       # @return [void]
       def cdata(content)
+        raise Error, 'CDATA content must not contain "]]>"' if content.to_s.include?(']]>')
+
         current_parent.push("<![CDATA[#{content}]]>")
       end
 
@@ -58,18 +61,38 @@ module Philiprehberger
       # @param text [String] the comment text
       # @return [void]
       def comment(text)
+        raise Error, 'Comment text must not contain "--"' if text.to_s.include?('--')
+
         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,8 +113,12 @@ module Philiprehberger
       # @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" : '')
+        parts = []
+
+        if @declaration
+          parts << "<?xml version=\"#{@version}\" encoding=\"#{@encoding}\"?>"
+          parts << (indent ? "\n" : '')
+        end
 
         @children.each do |child|
           parts << render_child(child, indent: indent, level: 0)
@@ -227,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.2.1'
+    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
@@ -15,8 +16,8 @@ module Philiprehberger
     # @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)
+    def self.build(encoding: 'UTF-8', version: '1.0', declaration: true, &block)
+      doc = Document.new(version: version, encoding: encoding, declaration: declaration)
       block.call(doc)
       doc.to_s
     end
@@ -31,8 +32,8 @@ module Philiprehberger
     # @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)
+    def self.build_soap(soap_version: '1.1', encoding: 'UTF-8', version: '1.0', declaration: true, &block)
+      doc = Document.new(version: version, encoding: encoding, declaration: declaration)
       doc.soap_envelope(version: soap_version, &block)
       doc.to_s
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-xml_builder
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-31 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,12 +25,13 @@ 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://github.com/philiprehberger/rb-xml-builder
+homepage: https://philiprehberger.com/open-source-packages/ruby/philiprehberger-xml_builder
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/philiprehberger/rb-xml-builder
+  homepage_uri: https://philiprehberger.com/open-source-packages/ruby/philiprehberger-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