philiprehberger-toml_kit 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d199d5d8f8d7b28944c260c28a87887b56fd3cdc3e98b5c759035fd1f80d6bce
-  data.tar.gz: b23ad52472d7bfc481f0480fa5db4ec759d0883aefa5e8184ab702ae9d802b7e
+  metadata.gz: 74417b867e192747c92bc5db6a147f1d52333718a6461f3dce72ee5e15ca5b45
+  data.tar.gz: 2f26751f1f266724a4493ceb5ec76bfde3e3832b05e7b804b0db8c452b2da93e
 SHA512:
-  metadata.gz: fa8701b149c8f928413485936ed95072d6cd4dd4fc363ec6314b26161cc1718092d2a7147ed6ab5f4ca728cf7d2731cfc1a3b91abb933c97f60ee202e67978b8
-  data.tar.gz: 7b100b0df6a733b3b97a8239c93c90c646a158bcc828827f786b1102d7aa44eb6f0c9bef4c8bdf268d700d3b2b0939b0e0c5e725b28ac192b3958de5240b0df9
+  metadata.gz: 197a2730afb7c93d928ced99cb39d3d328970a611738051dfb23289ad426fbdd87e2d967cf55c5a65d0cd2f4d1e9abd44b00dbc56e3d5683c0a6abb126d56705
+  data.tar.gz: 7460f7dcb52085a7f29150239d27bb03a657e62c90d433a3de6c421dc0e97b9890188aa9840f126a36b2c08e08fcace823fcc976e88369b3eff98458b8b9632d

data/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-03-28
+
+### Added
+
+- Comment preservation during round-trip parse/serialize via `TomlKit.parse_with_comments` and `CommentDocument`
+- TOML schema validation with `Schema` class supporting required keys, type checks, nested properties, and array items
+- TOML merging with conflict resolution strategies (`:override`, `:keep_existing`, `:error_on_conflict`) via `TomlKit.merge`
+- Dot-path query support via `TomlKit.query` with array indexing, `Query.set`, `Query.exists?`, and `Query.delete`
+- Type coercion hooks via `TypeCoercion` for custom serializer/deserializer registration with optional tagged round-trips
+- TOML diff via `TomlKit.diff` to compare two documents reporting additions, removals, and changes
+
 ## [0.1.1] - 2026-03-26
 
 ### Added

data/README.md

@@ -1,11 +1,8 @@
 # philiprehberger-toml_kit
 
-[![Tests](https://github.com/philiprehberger/rb-toml-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/philiprehberger/rb-toml-kit/actions/workflows/ci.yml)
-[![Gem Version](https://badge.fury.io/rb/philiprehberger-toml_kit.svg)](https://rubygems.org/gems/philiprehberger-toml_kit)
-[![License](https://img.shields.io/github/license/philiprehberger/rb-toml-kit)](LICENSE)
-[![Sponsor](https://img.shields.io/badge/sponsor-GitHub%20Sponsors-ec6cb9)](https://github.com/sponsors/philiprehberger)
+[![Tests](https://github.com/philiprehberger/rb-toml-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/philiprehberger/rb-toml-kit/actions/workflows/ci.yml) [![Gem Version](https://img.shields.io/gem/v/philiprehberger-toml_kit)](https://rubygems.org/gems/philiprehberger-toml_kit) [![GitHub release](https://img.shields.io/github/v/release/philiprehberger/rb-toml-kit)](https://github.com/philiprehberger/rb-toml-kit/releases) [![GitHub last commit](https://img.shields.io/github/last-commit/philiprehberger/rb-toml-kit)](https://github.com/philiprehberger/rb-toml-kit/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-toml-kit/issues) [![Feature Requests](https://img.shields.io/badge/feature-requests-blue.svg)](https://github.com/philiprehberger/rb-toml-kit/issues) [![GitHub Sponsors](https://img.shields.io/badge/sponsor-philiprehberger-ea4aaa.svg?logo=github)](https://github.com/sponsors/philiprehberger)
 
-TOML v1.0 parser and serializer for Ruby
+TOML v1.0 parser and serializer for Ruby with comment preservation, schema validation, merging, querying, type coercion, and diffing.
 
 ## Requirements
 
@@ -108,6 +105,147 @@ TOML
 data = Philiprehberger::TomlKit.parse(toml)
 ```
 
+### Comment Preservation
+
+Parse a TOML document while preserving comments for round-trip editing:
+
+```ruby
+toml = <<~TOML
+  # Application config
+  title = "My App"
+
+  # Database settings
+  [database]
+  host = "localhost" # primary host
+TOML
+
+doc = Philiprehberger::TomlKit.parse_with_comments(toml)
+doc["title"]                    # => "My App"
+doc["database"]["host"]         # => "localhost" (via doc.data)
+doc.header_comments             # => ["# Application config"]
+doc.comments["database.host"]   # => {inline: "# primary host"}
+
+# Modify and re-serialize with comments intact
+doc["title"] = "New App"
+output = doc.to_toml
+# Comments are preserved in the output
+```
+
+### Schema Validation
+
+Define expected structure and validate parsed TOML against it:
+
+```ruby
+schema = Philiprehberger::TomlKit::Schema.new(
+  "name" => { type: String, required: true },
+  "port" => { type: Integer, required: true },
+  "database" => {
+    type: Hash,
+    required: true,
+    properties: {
+      "host" => { type: String, required: true },
+      "port" => { type: Integer }
+    }
+  },
+  "tags" => { type: Array, items: { type: String } }
+)
+
+data = Philiprehberger::TomlKit.parse(toml_string)
+errors = schema.validate(data)
+# => [] if valid, or ["Missing required key: name", ...]
+
+schema.validate!(data) # raises SchemaError if invalid
+```
+
+### Merging
+
+Deep merge two TOML hashes with conflict resolution:
+
+```ruby
+base = Philiprehberger::TomlKit.parse(base_toml)
+overrides = Philiprehberger::TomlKit.parse(override_toml)
+
+# Right-side wins (default)
+merged = Philiprehberger::TomlKit.merge(base, overrides)
+
+# Left-side wins
+merged = Philiprehberger::TomlKit.merge(base, overrides, strategy: :keep_existing)
+
+# Raise on conflict
+merged = Philiprehberger::TomlKit.merge(base, overrides, strategy: :error_on_conflict)
+# raises MergeConflictError if keys conflict
+```
+
+### Query Support
+
+Access nested values using dot-paths:
+
+```ruby
+data = Philiprehberger::TomlKit.parse(toml_string)
+
+Philiprehberger::TomlKit.query(data, "database.host")
+# => "localhost"
+
+Philiprehberger::TomlKit.query(data, "servers[0].name")
+# => "alpha"
+
+Philiprehberger::TomlKit.query(data, "missing.path", default: "N/A")
+# => "N/A"
+
+# Additional Query methods
+Philiprehberger::TomlKit::Query.set(data, "database.timeout", 30)
+Philiprehberger::TomlKit::Query.exists?(data, "database.host")  # => true
+Philiprehberger::TomlKit::Query.delete(data, "database.timeout") # => 30
+```
+
+### Type Coercion Hooks
+
+Register custom serializers and deserializers for Ruby types:
+
+```ruby
+coercion = Philiprehberger::TomlKit::TypeCoercion.new
+
+coercion.register(
+  Symbol,
+  tag: "symbol",
+  serializer: ->(v) { v.to_s },
+  deserializer: ->(v) { v.to_sym }
+)
+
+# Serialize: converts symbols to tagged strings
+data = { "key" => :hello }
+serialized = coercion.coerce_for_serialize(data)
+toml = Philiprehberger::TomlKit.dump(serialized)
+
+# Deserialize: converts tagged strings back to symbols
+parsed = Philiprehberger::TomlKit.parse(toml)
+restored = coercion.coerce_for_deserialize(parsed)
+restored["key"] # => :hello
+```
+
+### TOML Diff
+
+Compare two TOML documents and report differences:
+
+```ruby
+old_config = Philiprehberger::TomlKit.parse(old_toml)
+new_config = Philiprehberger::TomlKit.parse(new_toml)
+
+changes = Philiprehberger::TomlKit.diff(old_config, new_config)
+changes.each do |change|
+  puts "#{change.type}: #{change.path}"
+  # => :added, :removed, or :changed
+end
+
+# Filter by type
+Philiprehberger::TomlKit::Diff.additions(old_config, new_config)
+Philiprehberger::TomlKit::Diff.removals(old_config, new_config)
+Philiprehberger::TomlKit::Diff.changes(old_config, new_config)
+
+# Check equality
+Philiprehberger::TomlKit::Diff.identical?(old_config, new_config)
+```
+
 ## API
 
 | Method | Description |
@@ -116,6 +254,26 @@ data = Philiprehberger::TomlKit.parse(toml)
 | `TomlKit.load(path)` | Parse a TOML file into a Hash |
 | `TomlKit.dump(hash)` | Serialize a Hash to a TOML string |
 | `TomlKit.save(hash, path)` | Write a Hash as a TOML file |
+| `TomlKit.parse_with_comments(string)` | Parse TOML preserving comments, returns `CommentDocument` |
+| `TomlKit.query(data, path, default:)` | Dot-path access into nested hashes |
+| `TomlKit.merge(left, right, strategy:)` | Deep merge two hashes with conflict resolution |
+| `TomlKit.diff(left, right)` | Compare two hashes, returns array of `Diff::Change` |
+| `Schema.new(properties)` | Create a schema for validation |
+| `Schema#validate(data)` | Validate data, returns array of error strings |
+| `Schema#validate!(data)` | Validate data, raises `SchemaError` on failure |
+| `Query.get(data, path, default:)` | Retrieve nested value by dot-path |
+| `Query.set(data, path, value)` | Set nested value by dot-path |
+| `Query.exists?(data, path)` | Check if a dot-path exists |
+| `Query.delete(data, path)` | Delete value at dot-path |
+| `Diff.diff(left, right)` | Full diff between two hashes |
+| `Diff.additions(left, right)` | Keys added in right |
+| `Diff.removals(left, right)` | Keys removed from left |
+| `Diff.changes(left, right)` | Keys with changed values |
+| `Diff.identical?(left, right)` | Check if two hashes are equal |
+| `TypeCoercion#register(type, ...)` | Register custom type handler |
+| `TypeCoercion#coerce_for_serialize(value)` | Apply serialization coercions |
+| `TypeCoercion#coerce_for_deserialize(value)` | Apply deserialization coercions |
+| `Merger.merge(left, right, strategy:)` | Merge with strategy |
 
 ## Development
 
@@ -125,6 +283,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/toml_kit/comment_document.rb

@@ -0,0 +1,396 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module TomlKit
+    # Represents a TOML document that preserves comments during round-trip
+    # parse/serialize operations.
+    #
+    # Comments are stored as metadata attached to keys or sections:
+    #   - :header_comments -> comments at the top of the document
+    #   - :comments -> hash mapping "path.to.key" to { before: [...], inline: "..." }
+    #   - :table_comments -> hash mapping "[table]" to { before: [...], inline: "..." }
+    class CommentDocument
+      attr_reader :data, :comments, :table_comments, :header_comments
+
+      def initialize(data = {}, comments: {}, table_comments: {}, header_comments: [])
+        @data = data
+        @comments = comments
+        @table_comments = table_comments
+        @header_comments = header_comments
+      end
+
+      # Parse a TOML string preserving comments.
+      #
+      # @param input [String] TOML document
+      # @return [CommentDocument]
+      def self.parse(input)
+        CommentPreservingParser.new.parse(input)
+      end
+
+      # Serialize back to a TOML string with comments preserved.
+      #
+      # @return [String] TOML formatted string with comments
+      def to_toml
+        CommentPreservingSerializer.new.serialize(self)
+      end
+
+      # Access the underlying data hash.
+      #
+      # @param key [String] top-level key
+      # @return [Object] value
+      def [](key)
+        @data[key]
+      end
+
+      # Set a value in the underlying data hash.
+      #
+      # @param key [String] top-level key
+      # @param value [Object] value to set
+      def []=(key, value)
+        @data[key] = value
+      end
+
+      # Return the data hash for compatibility.
+      #
+      # @return [Hash]
+      def to_h
+        @data
+      end
+    end
+
+    # Parser that tracks comments alongside parsed data.
+    class CommentPreservingParser
+      # @param input [String] TOML document
+      # @return [CommentDocument]
+      def parse(input)
+        @lines = input.lines
+        @data = {}
+        @comments = {}
+        @table_comments = {}
+        @header_comments = []
+        @current_path = []
+        @pending_comments = []
+
+        parse_lines
+        CommentDocument.new(@data, comments: @comments, table_comments: @table_comments,
+                                   header_comments: @header_comments)
+      end
+
+      private
+
+      def parse_lines
+        in_header = true
+
+        @lines.each do |line|
+          stripped = line.strip
+
+          if stripped.empty?
+            @pending_comments << '' unless @pending_comments.empty? || !in_header
+            next
+          end
+
+          if stripped.start_with?('#')
+            @pending_comments << stripped
+            next
+          end
+
+          in_header = false
+
+          if stripped.start_with?('[[')
+            parse_array_table_line(stripped)
+          elsif stripped.start_with?('[')
+            parse_table_line(stripped)
+          else
+            parse_key_value_line(stripped)
+          end
+        end
+      end
+
+      def parse_table_line(line)
+        # Extract inline comment
+        inline_comment = nil
+        table_part = line
+
+        # Find the closing bracket, then check for comment
+        bracket_end = line.index(']')
+        if bracket_end
+          rest = line[(bracket_end + 1)..]
+          if rest && (comment_idx = rest.index('#'))
+            inline_comment = rest[comment_idx..].strip
+            table_part = line[0..bracket_end]
+          end
+        end
+
+        # Extract table name
+        table_name = table_part.strip.sub(/\A\[/, '').sub(/\]\s*\z/, '').strip
+        @current_path = table_name.split('.')
+
+        # Navigate/create nested structure
+        navigate_to_table(@data, @current_path)
+
+        table_key = "[#{table_name}]"
+        store_table_comments(table_key, inline_comment)
+      end
+
+      def parse_array_table_line(line)
+        inline_comment = nil
+        table_part = line
+
+        bracket_end = line.index(']]')
+        if bracket_end
+          rest = line[(bracket_end + 2)..]
+          if rest && (comment_idx = rest.index('#'))
+            inline_comment = rest[comment_idx..].strip
+            table_part = line[0..(bracket_end + 1)]
+          end
+        end
+
+        table_name = table_part.strip.sub(/\A\[\[/, '').sub(/\]\]\s*\z/, '').strip
+        @current_path = table_name.split('.')
+
+        # Navigate to parent
+        parent = navigate_to_table(@data, @current_path[0...-1])
+        last_key = @current_path.last
+        parent[last_key] = [] unless parent.key?(last_key)
+        parent[last_key] << {}
+
+        table_key = "[[#{table_name}]]"
+        store_table_comments(table_key, inline_comment)
+      end
+
+      def store_table_comments(table_key, inline_comment)
+        entry = {}
+        entry[:before] = @pending_comments.dup unless @pending_comments.empty?
+        entry[:inline] = inline_comment if inline_comment
+        @table_comments[table_key] = entry unless entry.empty?
+        @pending_comments.clear
+      end
+
+      def parse_key_value_line(line)
+        # Extract inline comment - be careful not to match # inside strings
+        inline_comment = nil
+        key_part = extract_key_value_without_comment(line)
+        remaining = line[key_part.length..]
+        if remaining && (comment_idx = remaining.index('#'))
+          inline_comment = remaining[comment_idx..].strip
+        end
+
+        # Parse the key from the line
+        eq_idx = find_equals_index(key_part)
+        return unless eq_idx
+
+        raw_key = key_part[0...eq_idx].strip
+
+        # Build full path for comment storage
+        full_path = (@current_path + [raw_key]).join('.')
+
+        # Store comments
+        entry = {}
+        entry[:before] = @pending_comments.dup unless @pending_comments.empty?
+        entry[:inline] = inline_comment if inline_comment
+        @comments[full_path] = entry unless entry.empty?
+        @pending_comments.clear
+
+        # Actually parse the value using the real parser
+        value_str = key_part[(eq_idx + 1)..].strip
+        table = navigate_to_table(@data, @current_path)
+        keys = raw_key.split('.')
+        set_nested(table, keys, parse_value_simple(value_str))
+      end
+
+      def extract_key_value_without_comment(line)
+        in_string = false
+        string_char = nil
+        i = 0
+
+        # Skip past the = sign first
+        past_equals = false
+
+        while i < line.length
+          ch = line[i]
+
+          if in_string
+            if ch == '\\' && string_char == '"'
+              i += 2
+              next
+            end
+            in_string = false if ch == string_char
+          else
+            if ch == '=' && !past_equals
+              past_equals = true
+              i += 1
+              next
+            end
+
+            if past_equals
+              if ['"', "'"].include?(ch)
+                in_string = true
+                string_char = ch
+              elsif ch == '#'
+                return line[0...i].rstrip
+              end
+            end
+          end
+
+          i += 1
+        end
+
+        line.rstrip
+      end
+
+      def find_equals_index(str)
+        in_string = false
+        string_char = nil
+
+        str.each_char.with_index do |ch, i|
+          if in_string
+            if ch == '\\' && string_char == '"'
+              next
+            elsif ch == string_char
+              in_string = false
+            end
+          elsif ['"', "'"].include?(ch)
+            in_string = true
+            string_char = ch
+          elsif ch == '='
+            return i
+          end
+        end
+        nil
+      end
+
+      def parse_value_simple(str)
+        # Delegate to the real parser for proper type handling
+        Parser.new.parse("__key__ = #{str}")['__key__']
+      end
+
+      def navigate_to_table(root, keys)
+        current = root
+        keys.each do |key|
+          if current.key?(key)
+            val = current[key]
+            if val.is_a?(Array)
+              current = val.last
+            elsif val.is_a?(Hash)
+              current = val
+            else
+              return current
+            end
+          else
+            new_table = {}
+            current[key] = new_table
+            current = new_table
+          end
+        end
+        current
+      end
+
+      def set_nested(table, keys, value)
+        current = table
+        keys[0...-1].each do |key|
+          current[key] = {} unless current.key?(key)
+          current = current[key]
+        end
+        current[keys.last] = value
+      end
+    end
+
+    # Serializer that outputs comments from a CommentDocument.
+    class CommentPreservingSerializer
+      # @param doc [CommentDocument]
+      # @return [String] TOML with comments
+      def serialize(doc)
+        # Header comments
+        lines = doc.header_comments.map { |c| c }
+        lines << '' unless doc.header_comments.empty?
+
+        serialize_table(doc.data, [], lines, doc)
+        lines.join("\n") << "\n"
+      end
+
+      private
+
+      def serialize_table(hash, path, lines, doc)
+        simple_keys = []
+        table_keys = []
+        array_table_keys = []
+
+        hash.each do |key, value|
+          if value.is_a?(Hash) && !local_time_hash?(value)
+            table_keys << key
+          elsif value.is_a?(Array) && value.all?(Hash)
+            array_table_keys << key
+          else
+            simple_keys << key
+          end
+        end
+
+        serializer = Serializer.new
+
+        simple_keys.each do |key|
+          full_path = (path + [key]).join('.')
+          comment_entry = doc.comments[full_path]
+
+          if comment_entry
+            comment_entry[:before]&.each { |c| lines << c }
+          end
+
+          line = "#{format_key(key)} = #{serializer.send(:format_value, hash[key])}"
+          line = "#{line} #{comment_entry[:inline]}" if comment_entry&.dig(:inline)
+          lines << line
+        end
+
+        table_keys.each do |key|
+          full_path = path + [key]
+          table_key = "[#{full_path.map { |k| format_key(k) }.join('.')}]"
+
+          comment_entry = doc.table_comments[table_key]
+
+          lines << '' unless lines.empty?
+          if comment_entry
+            comment_entry[:before]&.each { |c| lines << c }
+          end
+
+          table_line = table_key
+          table_line = "#{table_line} #{comment_entry[:inline]}" if comment_entry&.dig(:inline)
+          lines << table_line
+
+          serialize_table(hash[key], full_path, lines, doc)
+        end
+
+        array_table_keys.each do |key|
+          full_path = path + [key]
+          table_key = "[[#{full_path.map { |k| format_key(k) }.join('.')}]]"
+
+          hash[key].each_with_index do |element, idx|
+            comment_entry = doc.table_comments[table_key] if idx.zero?
+
+            lines << '' unless lines.empty?
+            if comment_entry
+              comment_entry[:before]&.each { |c| lines << c }
+            end
+
+            aot_line = table_key
+            aot_line = "#{aot_line} #{comment_entry[:inline]}" if idx.zero? && comment_entry&.dig(:inline)
+            lines << aot_line
+
+            serialize_table(element, full_path, lines, doc)
+          end
+        end
+      end
+
+      def format_key(key)
+        key = key.to_s
+        if key.match?(/\A[A-Za-z0-9_-]+\z/)
+          key
+        else
+          "\"#{key}\""
+        end
+      end
+
+      def local_time_hash?(hash)
+        hash.key?(:hour) && hash.key?(:minute) && hash.key?(:second)
+      end
+    end
+  end
+end

data/lib/philiprehberger/toml_kit/diff.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module TomlKit
+    # Compares two TOML documents (as hashes) and reports differences.
+    #
+    # Returns a structured diff with:
+    #   - :added    -> keys present only in the right document
+    #   - :removed  -> keys present only in the left document
+    #   - :changed  -> keys present in both but with different values
+    module Diff
+      # A single change entry.
+      Change = Struct.new(:path, :type, :left_value, :right_value, keyword_init: true)
+
+      # Compare two parsed TOML hashes.
+      #
+      # @param left [Hash] first document
+      # @param right [Hash] second document
+      # @return [Array<Change>] list of differences
+      def self.diff(left, right)
+        changes = []
+        compare(left, right, [], changes)
+        changes
+      end
+
+      # Return only additions (keys in right but not left).
+      #
+      # @param left [Hash]
+      # @param right [Hash]
+      # @return [Array<Change>]
+      def self.additions(left, right)
+        diff(left, right).select { |c| c.type == :added }
+      end
+
+      # Return only removals (keys in left but not right).
+      #
+      # @param left [Hash]
+      # @param right [Hash]
+      # @return [Array<Change>]
+      def self.removals(left, right)
+        diff(left, right).select { |c| c.type == :removed }
+      end
+
+      # Return only changes (keys in both with different values).
+      #
+      # @param left [Hash]
+      # @param right [Hash]
+      # @return [Array<Change>]
+      def self.changes(left, right)
+        diff(left, right).select { |c| c.type == :changed }
+      end
+
+      # Check if two documents are identical.
+      #
+      # @param left [Hash]
+      # @param right [Hash]
+      # @return [Boolean]
+      def self.identical?(left, right)
+        diff(left, right).empty?
+      end
+
+      # @api private
+      def self.compare(left, right, path, changes)
+        all_keys = ((left.is_a?(Hash) ? left.keys : []) | (right.is_a?(Hash) ? right.keys : [])).uniq
+
+        all_keys.each do |key|
+          current_path = (path + [key]).join('.')
+          left_has = left.is_a?(Hash) && left.key?(key)
+          right_has = right.is_a?(Hash) && right.key?(key)
+
+          if left_has && !right_has
+            changes << Change.new(path: current_path, type: :removed, left_value: left[key], right_value: nil)
+          elsif !left_has && right_has
+            changes << Change.new(path: current_path, type: :added, left_value: nil, right_value: right[key])
+          elsif left[key].is_a?(Hash) && right[key].is_a?(Hash)
+            compare(left[key], right[key], path + [key], changes)
+          elsif left[key] != right[key]
+            # Handle NaN comparison (NaN != NaN is always true)
+            next if left[key].is_a?(Float) && right[key].is_a?(Float) && left[key].nan? && right[key].nan?
+
+            changes << Change.new(path: current_path, type: :changed, left_value: left[key],
+                                  right_value: right[key])
+          end
+        end
+      end
+
+      private_class_method :compare
+    end
+  end
+end

data/lib/philiprehberger/toml_kit/merger.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module TomlKit
+    class MergeConflictError < Error; end
+
+    # Deep merge two TOML hashes with configurable conflict resolution.
+    #
+    # Strategies:
+    #   - :override       -> right-side wins (default)
+    #   - :keep_existing  -> left-side wins
+    #   - :error_on_conflict -> raise MergeConflictError
+    class Merger
+      STRATEGIES = %i[override keep_existing error_on_conflict].freeze
+
+      # Merge two hashes.
+      #
+      # @param left [Hash] base hash
+      # @param right [Hash] hash to merge in
+      # @param strategy [Symbol] conflict resolution strategy
+      # @return [Hash] merged result
+      # @raise [MergeConflictError] when strategy is :error_on_conflict and a conflict exists
+      def self.merge(left, right, strategy: :override)
+        new(strategy).merge(left, right)
+      end
+
+      # @param strategy [Symbol]
+      def initialize(strategy = :override)
+        unless STRATEGIES.include?(strategy)
+          raise ArgumentError, "Unknown merge strategy: #{strategy}. Use one of: #{STRATEGIES.join(', ')}"
+        end
+
+        @strategy = strategy
+      end
+
+      # @param left [Hash]
+      # @param right [Hash]
+      # @param path [Array<String>] internal tracking for error messages
+      # @return [Hash]
+      def merge(left, right, path = [])
+        result = left.dup
+
+        right.each do |key, right_value|
+          current_path = path + [key]
+
+          if result.key?(key)
+            left_value = result[key]
+
+            result[key] = if left_value.is_a?(Hash) && right_value.is_a?(Hash)
+                            merge(left_value, right_value, current_path)
+                          else
+                            resolve_conflict(left_value, right_value, current_path)
+                          end
+          else
+            result[key] = deep_copy(right_value)
+          end
+        end
+
+        result
+      end
+
+      private
+
+      def resolve_conflict(left_value, right_value, path)
+        case @strategy
+        when :override
+          deep_copy(right_value)
+        when :keep_existing
+          left_value
+        when :error_on_conflict
+          path_str = path.join('.')
+          raise MergeConflictError, "Conflict at key: #{path_str}"
+        end
+      end
+
+      def deep_copy(value)
+        case value
+        when Hash
+          value.transform_values { |v| deep_copy(v) }
+        when Array
+          value.map { |v| deep_copy(v) }
+        else
+          value
+        end
+      end
+    end
+  end
+end

data/lib/philiprehberger/toml_kit/query.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module TomlKit
+    # Dot-path query access for nested TOML hashes.
+    #
+    # Supports:
+    #   - Simple dot paths: "database.host"
+    #   - Array indexing: "servers[0].name"
+    #   - Deep nesting: "a.b.c.d"
+    module Query
+      # Retrieve a value from a nested hash using a dot-path.
+      #
+      # @param data [Hash] parsed TOML hash
+      # @param path [String] dot-separated path (e.g., "database.host")
+      # @param default [Object] value to return if the path does not exist
+      # @return [Object] the value at the path, or default
+      def self.get(data, path, default: nil)
+        segments = parse_path(path)
+        current = data
+
+        segments.each do |segment|
+          case segment
+          when Integer
+            return default unless current.is_a?(Array) && segment < current.length
+
+            current = current[segment]
+          when String
+            return default unless current.is_a?(Hash) && current.key?(segment)
+
+            current = current[segment]
+          end
+        end
+
+        current
+      end
+
+      # Set a value in a nested hash using a dot-path.
+      # Creates intermediate hashes/arrays as needed.
+      #
+      # @param data [Hash] target hash
+      # @param path [String] dot-separated path
+      # @param value [Object] value to set
+      # @return [Object] the value that was set
+      def self.set(data, path, value)
+        segments = parse_path(path)
+        current = data
+
+        segments[0...-1].each_with_index do |segment, idx|
+          next_segment = segments[idx + 1]
+
+          case segment
+          when Integer
+            current[segment] = next_segment.is_a?(Integer) ? [] : {} unless current[segment]
+            current = current[segment]
+          when String
+            current[segment] = next_segment.is_a?(Integer) ? [] : {} unless current.key?(segment)
+            current = current[segment]
+          end
+        end
+
+        current[segments.last] = value
+        value
+      end
+
+      # Check whether a path exists in the data.
+      #
+      # @param data [Hash] parsed TOML hash
+      # @param path [String] dot-separated path
+      # @return [Boolean]
+      def self.exists?(data, path)
+        sentinel = Object.new
+        get(data, path, default: sentinel) != sentinel
+      end
+
+      # Delete a value at the given path.
+      #
+      # @param data [Hash] target hash
+      # @param path [String] dot-separated path
+      # @return [Object, nil] the removed value, or nil
+      def self.delete(data, path)
+        segments = parse_path(path)
+        return nil if segments.empty?
+
+        parent = segments.length > 1 ? get(data, build_path(segments[0...-1])) : data
+        return nil unless parent
+
+        last = segments.last
+        case last
+        when Integer
+          parent.is_a?(Array) ? parent.delete_at(last) : nil
+        when String
+          parent.is_a?(Hash) ? parent.delete(last) : nil
+        end
+      end
+
+      # Parse a dot-path into segments.
+      # Handles array indexing like "servers[0]".
+      #
+      # @param path [String]
+      # @return [Array<String, Integer>]
+      def self.parse_path(path)
+        segments = []
+        path.split('.').each do |part|
+          if part =~ /\A(.+?)\[(\d+)\]\z/
+            segments << ::Regexp.last_match(1)
+            segments << ::Regexp.last_match(2).to_i
+          else
+            segments << part
+          end
+        end
+        segments
+      end
+
+      # Build a dot-path from segments.
+      #
+      # @param segments [Array<String, Integer>]
+      # @return [String]
+      def self.build_path(segments)
+        result = +''
+        segments.each_with_index do |seg, i|
+          if seg.is_a?(Integer)
+            result << "[#{seg}]"
+          else
+            result << '.' if i.positive?
+            result << seg
+          end
+        end
+        result
+      end
+
+      private_class_method :parse_path, :build_path
+    end
+  end
+end

data/lib/philiprehberger/toml_kit/schema.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module TomlKit
+    class SchemaError < Error; end
+
+    # Validates a parsed TOML hash against a schema definition.
+    #
+    # Schema format:
+    #   {
+    #     "key" => { type: String, required: true },
+    #     "port" => { type: Integer, required: false, default: 8080 },
+    #     "database" => {
+    #       type: Hash,
+    #       properties: {
+    #         "host" => { type: String, required: true },
+    #         "port" => { type: Integer }
+    #       }
+    #     },
+    #     "tags" => { type: Array, items: { type: String } }
+    #   }
+    class Schema
+      attr_reader :properties
+
+      # Build a new schema.
+      #
+      # @param properties [Hash] schema definition
+      def initialize(properties)
+        @properties = properties
+      end
+
+      # Validate a hash against this schema.
+      #
+      # @param data [Hash] parsed TOML data
+      # @return [Array<String>] list of validation errors (empty if valid)
+      def validate(data)
+        errors = []
+        validate_properties(data, @properties, [], errors)
+        errors
+      end
+
+      # Validate and raise if invalid.
+      #
+      # @param data [Hash] parsed TOML data
+      # @raise [SchemaError] if validation fails
+      # @return [true]
+      def validate!(data)
+        errors = validate(data)
+        raise SchemaError, "Schema validation failed: #{errors.join('; ')}" unless errors.empty?
+
+        true
+      end
+
+      private
+
+      def validate_properties(data, properties, path, errors)
+        properties.each do |key, rules|
+          full_path = (path + [key]).join('.')
+          value = data.is_a?(Hash) ? data[key] : nil
+          has_key = data.is_a?(Hash) && data.key?(key)
+
+          if rules[:required] && !has_key
+            errors << "Missing required key: #{full_path}"
+            next
+          end
+
+          next unless has_key
+
+          validate_value(value, rules, full_path, errors)
+        end
+      end
+
+      def validate_value(value, rules, path, errors)
+        expected_type = rules[:type]
+        if expected_type && !type_matches?(value, expected_type)
+          errors << "Type mismatch at #{path}: expected #{expected_type}, got #{value.class}"
+          return
+        end
+
+        # Validate nested properties for Hash types
+        if value.is_a?(Hash) && rules[:properties]
+          validate_properties(value, rules[:properties], path.split('.'), errors)
+        end
+
+        # Validate array items
+        return unless value.is_a?(Array) && rules[:items]
+
+        value.each_with_index do |item, idx|
+          item_path = "#{path}[#{idx}]"
+          validate_value(item, rules[:items], item_path, errors)
+        end
+      end
+
+      def type_matches?(value, expected)
+        case expected
+        when :boolean
+          value.is_a?(TrueClass) || value.is_a?(FalseClass)
+        else
+          value.is_a?(expected)
+        end
+      end
+    end
+  end
+end

data/lib/philiprehberger/toml_kit/type_coercion.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module TomlKit
+    # Registry for custom type serialization and deserialization hooks.
+    #
+    # Allows registering custom handlers for Ruby types that are not natively
+    # supported by TOML. Coercions are applied during dump (serialize) and
+    # can be applied after parse (deserialize).
+    class TypeCoercion
+      # A single coercion rule.
+      Rule = Struct.new(:type, :serializer, :deserializer, :tag, keyword_init: true)
+
+      def initialize
+        @rules = []
+      end
+
+      # Register a custom type coercion.
+      #
+      # @param type [Class] the Ruby class to handle
+      # @param tag [String, nil] optional tag prefix for round-trip identification
+      # @param serializer [Proc] converts an instance to a TOML-native value
+      # @param deserializer [Proc, nil] converts a TOML-native value back to the Ruby type
+      # @return [self]
+      def register(type, serializer:, tag: nil, deserializer: nil)
+        @rules << Rule.new(type: type, serializer: serializer, deserializer: deserializer, tag: tag)
+        self
+      end
+
+      # Apply serialization coercions to a value (for dump).
+      # Walks hashes and arrays recursively.
+      #
+      # @param value [Object]
+      # @return [Object] coerced value
+      def coerce_for_serialize(value)
+        rule = find_rule(value)
+        if rule
+          result = rule.serializer.call(value)
+          if rule.tag
+            "__coerced:#{rule.tag}:#{result}"
+          else
+            result
+          end
+        elsif value.is_a?(Hash)
+          value.transform_values { |v| coerce_for_serialize(v) }
+        elsif value.is_a?(Array)
+          value.map { |v| coerce_for_serialize(v) }
+        else
+          value
+        end
+      end
+
+      # Apply deserialization coercions to a value (after parse).
+      # Walks hashes and arrays recursively looking for tagged strings.
+      #
+      # @param value [Object]
+      # @return [Object] coerced value
+      def coerce_for_deserialize(value)
+        case value
+        when String
+          if value.start_with?('__coerced:')
+            parts = value.split(':', 3)
+            tag = parts[1]
+            raw = parts[2]
+            rule = @rules.find { |r| r.tag == tag }
+            if rule&.deserializer
+              rule.deserializer.call(raw)
+            else
+              value
+            end
+          else
+            value
+          end
+        when Hash
+          value.transform_values { |v| coerce_for_deserialize(v) }
+        when Array
+          value.map { |v| coerce_for_deserialize(v) }
+        else
+          value
+        end
+      end
+
+      # Check if there is a registered rule for the given value.
+      #
+      # @param value [Object]
+      # @return [Boolean]
+      def handles?(value)
+        !find_rule(value).nil?
+      end
+
+      # Return all registered rules.
+      #
+      # @return [Array<Rule>]
+      def rules
+        @rules.dup
+      end
+
+      private
+
+      def find_rule(value)
+        @rules.find { |r| value.is_a?(r.type) }
+      end
+    end
+  end
+end

data/lib/philiprehberger/toml_kit/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module TomlKit
-    VERSION = '0.1.1'
+    VERSION = '0.2.0'
   end
 end

data/lib/philiprehberger/toml_kit.rb

@@ -1,14 +1,25 @@
 # frozen_string_literal: true
 
 require_relative 'toml_kit/version'
-require_relative 'toml_kit/parser'
-require_relative 'toml_kit/serializer'
 
 module Philiprehberger
   module TomlKit
     class Error < StandardError; end
     class ParseError < Error; end
+  end
+end
 
+require_relative 'toml_kit/parser'
+require_relative 'toml_kit/serializer'
+require_relative 'toml_kit/comment_document'
+require_relative 'toml_kit/schema'
+require_relative 'toml_kit/merger'
+require_relative 'toml_kit/query'
+require_relative 'toml_kit/type_coercion'
+require_relative 'toml_kit/diff'
+
+module Philiprehberger
+  module TomlKit
     # Parse a TOML string into a Ruby Hash.
     #
     # @param string [String] TOML document
@@ -44,5 +55,42 @@ module Philiprehberger
     def self.save(hash, path)
       File.write(path, dump(hash), encoding: 'utf-8')
     end
+
+    # Parse a TOML string preserving comments for round-trip editing.
+    #
+    # @param string [String] TOML document
+    # @return [CommentDocument] document with data and comments
+    def self.parse_with_comments(string)
+      CommentDocument.parse(string)
+    end
+
+    # Query a nested value using a dot-path.
+    #
+    # @param data [Hash] parsed TOML hash
+    # @param path [String] dot-separated path (e.g., "database.host")
+    # @param default [Object] fallback value
+    # @return [Object]
+    def self.query(data, path, default: nil)
+      Query.get(data, path, default: default)
+    end
+
+    # Deep merge two TOML hashes.
+    #
+    # @param left [Hash] base hash
+    # @param right [Hash] hash to merge in
+    # @param strategy [Symbol] :override, :keep_existing, or :error_on_conflict
+    # @return [Hash]
+    def self.merge(left, right, strategy: :override)
+      Merger.merge(left, right, strategy: strategy)
+    end
+
+    # Compare two TOML hashes and return differences.
+    #
+    # @param left [Hash] first document
+    # @param right [Hash] second document
+    # @return [Array<Diff::Change>]
+    def self.diff(left, right)
+      Diff.diff(left, right)
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-toml_kit
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  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: Parse and generate TOML v1.0 documents with full type support including
   datetimes, inline tables, and array of tables. Zero dependencies.
@@ -22,8 +22,14 @@ files:
 - LICENSE
 - README.md
 - lib/philiprehberger/toml_kit.rb
+- lib/philiprehberger/toml_kit/comment_document.rb
+- lib/philiprehberger/toml_kit/diff.rb
+- lib/philiprehberger/toml_kit/merger.rb
 - lib/philiprehberger/toml_kit/parser.rb
+- lib/philiprehberger/toml_kit/query.rb
+- lib/philiprehberger/toml_kit/schema.rb
 - lib/philiprehberger/toml_kit/serializer.rb
+- lib/philiprehberger/toml_kit/type_coercion.rb
 - lib/philiprehberger/toml_kit/version.rb
 homepage: https://github.com/philiprehberger/rb-toml-kit
 licenses: