philiprehberger-toml_kit 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b5a839127b00750fc45d36aad221cad5df5320e80077950ce024ecf665d60471
+  data.tar.gz: e39bfae29986a5aa2d06e124d3944390b47cd27db75803971852da6236f58f84
+SHA512:
+  metadata.gz: be8644f17293ba8b240b020b0ec900ea674df859e473f29ae563c500ff96d3aed3c2be697d972e4c5bba6875493f5446fa7cd4977082e98b37761be171ef2827
+  data.tar.gz: f3d17fe3cb22e6328d79d0d52671529a460a623c6832c60432e456b3ae883d2e38da8e763bdff61d024a6afe8089432a0790a6a737432e135432bc10bd323454

data/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to this gem will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-03-26
+
+### Added
+- Initial release
+- TOML v1.0 parser with full type support
+- Key types: bare keys, quoted keys, dotted keys
+- Value types: strings, integers, floats, booleans, datetimes, arrays, inline tables
+- Integer formats: decimal, hexadecimal (0x), octal (0o), binary (0b)
+- Special float values: inf, -inf, nan
+- Date/time types: offset datetime, local datetime, local date, local time
+- Standard tables and array of tables
+- Multiline basic and literal strings
+- Hash to TOML serializer
+- `TomlKit.parse` for parsing TOML strings
+- `TomlKit.load` for parsing TOML files
+- `TomlKit.dump` for serializing hashes to TOML strings
+- `TomlKit.save` for writing hashes to TOML files

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 philiprehberger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,130 @@
+# 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)
+
+TOML v1.0 parser and serializer for Ruby
+
+## Requirements
+
+- Ruby >= 3.1
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "philiprehberger-toml_kit"
+```
+
+Or install directly:
+
+```bash
+gem install philiprehberger-toml_kit
+```
+
+## Usage
+
+```ruby
+require "philiprehberger/toml_kit"
+
+data = Philiprehberger::TomlKit.parse('title = "TOML Example"')
+# => {"title" => "TOML Example"}
+```
+
+### Parsing Strings
+
+```ruby
+toml = <<~TOML
+  [database]
+  host = "localhost"
+  port = 5432
+  enabled = true
+
+  [[servers]]
+  name = "alpha"
+  port = 8001
+
+  [[servers]]
+  name = "beta"
+  port = 8002
+TOML
+
+config = Philiprehberger::TomlKit.parse(toml)
+config["database"]["host"]   # => "localhost"
+config["servers"][0]["name"]  # => "alpha"
+```
+
+### Loading Files
+
+```ruby
+config = Philiprehberger::TomlKit.load("config.toml")
+```
+
+### Serializing to TOML
+
+```ruby
+hash = {
+  "title" => "My App",
+  "database" => { "host" => "localhost", "port" => 5432 },
+  "servers" => [
+    { "name" => "alpha", "port" => 8001 },
+    { "name" => "beta", "port" => 8002 }
+  ]
+}
+
+toml_string = Philiprehberger::TomlKit.dump(hash)
+```
+
+### Saving to Files
+
+```ruby
+Philiprehberger::TomlKit.save(hash, "output.toml")
+```
+
+### Supported Types
+
+All TOML v1.0 types are supported:
+
+```ruby
+toml = <<~TOML
+  str = "hello"
+  int = 42
+  hex = 0xDEADBEEF
+  oct = 0o755
+  bin = 0b11010110
+  flt = 3.14
+  inf_val = inf
+  bool = true
+  dt = 1979-05-27T07:32:00Z
+  date = 1979-05-27
+  time = 07:32:00
+  arr = [1, 2, 3]
+  inline = {x = 1, y = 2}
+TOML
+
+data = Philiprehberger::TomlKit.parse(toml)
+```
+
+## API
+
+| Method | Description |
+|--------|-------------|
+| `TomlKit.parse(string)` | Parse a TOML string into a Hash |
+| `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 |
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+[MIT](LICENSE)

data/lib/philiprehberger/toml_kit/parser.rb

@@ -0,0 +1,544 @@
+# frozen_string_literal: true
+
+require 'date'
+require 'time'
+require 'strscan'
+
+module Philiprehberger
+  module TomlKit
+    # TOML v1.0 parser.
+    #
+    # Parses a TOML string into a Ruby Hash with proper type mapping:
+    #   - Strings -> String
+    #   - Integers -> Integer
+    #   - Floats -> Float
+    #   - Booleans -> true/false
+    #   - Offset Date-Time -> Time
+    #   - Local Date-Time -> Time (local)
+    #   - Local Date -> Date
+    #   - Local Time -> Hash with :hour, :minute, :second keys
+    #   - Arrays -> Array
+    #   - Inline Tables -> Hash
+    #   - Tables -> Hash (nested)
+    #   - Array of Tables -> Array of Hashes
+    class Parser
+      # @param input [String] TOML document
+      # @return [Hash] parsed result
+      def parse(input)
+        @scanner = StringScanner.new(input)
+        @result = {}
+        @current_table = @result
+        @current_path = []
+        @implicit_tables = {}
+        @defined_tables = {}
+        @defined_array_tables = {}
+
+        parse_document
+        @result
+      end
+
+      private
+
+      def parse_document
+        skip_whitespace_and_newlines
+        until @scanner.eos?
+          skip_whitespace
+          case @scanner.peek(1)
+          when '#'
+            skip_comment
+          when '['
+            parse_table_header
+          when "\n", "\r"
+            skip_newline
+          when ''
+            break
+          else
+            key, value = parse_key_value
+            set_value(@current_table, key, value)
+          end
+          skip_whitespace_and_newlines
+        end
+      end
+
+      def skip_whitespace
+        @scanner.scan(/[ \t]*/)
+      end
+
+      def skip_newline
+        @scanner.scan(/\r?\n/)
+      end
+
+      def skip_whitespace_and_newlines
+        @scanner.scan(/\s*/)
+      end
+
+      def skip_comment
+        @scanner.scan(/#[^\n]*/)
+      end
+
+      def skip_whitespace_and_comments
+        loop do
+          skip_whitespace
+          break unless @scanner.peek(1) == '#'
+
+          skip_comment
+        end
+      end
+
+      def parse_table_header
+        if @scanner.peek(2) == '[['
+          parse_array_table
+        else
+          parse_standard_table
+        end
+      end
+
+      def parse_standard_table
+        @scanner.scan('[')
+        skip_whitespace
+        keys = parse_key
+        skip_whitespace
+        expect(']')
+
+        skip_whitespace_and_comments
+        consume_newline_or_eof
+
+        path_str = keys.join('.')
+        raise ParseError, "Table [#{path_str}] already defined" if @defined_tables[path_str]
+
+        @defined_tables[path_str] = true
+        @current_path = keys
+        @current_table = navigate_to_table(@result, keys, define: true)
+      end
+
+      def parse_array_table
+        @scanner.scan('[[')
+        skip_whitespace
+        keys = parse_key
+        skip_whitespace
+        expect(']]')
+
+        skip_whitespace_and_comments
+        consume_newline_or_eof
+
+        path_str = keys.join('.')
+        @defined_array_tables[path_str] = true
+        @current_path = keys
+
+        parent = navigate_to_table(@result, keys[0...-1], define: false)
+        last_key = keys.last
+
+        parent[last_key] = [] unless parent.key?(last_key)
+        arr = parent[last_key]
+        raise ParseError, "Key #{last_key} is not an array of tables" unless arr.is_a?(Array)
+
+        new_table = {}
+        arr << new_table
+        @current_table = new_table
+      end
+
+      def navigate_to_table(root, keys, define:)
+        current = root
+        keys.each_with_index do |key, idx|
+          partial_path = keys[0..idx].join('.')
+          if current.key?(key)
+            val = current[key]
+            if val.is_a?(Array)
+              current = val.last
+            elsif val.is_a?(Hash)
+              current = val
+            else
+              raise ParseError, "Key #{key} already exists as a non-table value"
+            end
+          else
+            new_table = {}
+            current[key] = new_table
+            @implicit_tables[partial_path] = true if !define || idx < keys.length - 1
+            current = new_table
+          end
+        end
+        current
+      end
+
+      def parse_key_value
+        keys = parse_key
+        skip_whitespace
+        expect('=')
+        skip_whitespace
+        value = parse_value
+        skip_whitespace_and_comments
+        consume_newline_or_eof
+        [keys, value]
+      end
+
+      def set_value(table, keys, value)
+        current = table
+        keys[0...-1].each do |key|
+          if current.key?(key)
+            existing = current[key]
+            if existing.is_a?(Array)
+              current = existing.last
+            elsif existing.is_a?(Hash)
+              current = existing
+            else
+              raise ParseError, "Key #{key} already exists as a non-table value"
+            end
+          else
+            new_table = {}
+            current[key] = new_table
+            current = new_table
+          end
+        end
+        last_key = keys.last
+        raise ParseError, "Duplicate key: #{last_key}" if current.key?(last_key)
+
+        current[last_key] = value
+        current
+      end
+
+      def parse_key
+        keys = [parse_simple_key]
+        keys << parse_simple_key while @scanner.scan(/[ \t]*\.[ \t]*/)
+        keys
+      end
+
+      def parse_simple_key
+        if @scanner.peek(1) == '"'
+          parse_basic_string
+        elsif @scanner.peek(1) == "'"
+          parse_literal_string
+        else
+          parse_bare_key
+        end
+      end
+
+      def parse_bare_key
+        key = @scanner.scan(/[A-Za-z0-9_-]+/)
+        raise ParseError, "Expected bare key at position #{@scanner.pos}" unless key
+
+        key
+      end
+
+      def parse_value
+        case @scanner.peek(1)
+        when '"'
+          if @scanner.peek(3) == '"""'
+            parse_multiline_basic_string
+          else
+            parse_basic_string
+          end
+        when "'"
+          if @scanner.peek(3) == "'''"
+            parse_multiline_literal_string
+          else
+            parse_literal_string
+          end
+        when 't'
+          parse_true
+        when 'f'
+          parse_false
+        when '['
+          parse_array
+        when '{'
+          parse_inline_table
+        when 'i', 'n'
+          parse_special_float
+        when '+', '-'
+          if @scanner.rest.match?(/\A[+-](inf|nan)/)
+            parse_special_float
+          else
+            parse_number_or_date
+          end
+        else
+          parse_number_or_date
+        end
+      end
+
+      def parse_basic_string
+        expect('"')
+        result = +''
+        until @scanner.eos?
+          ch = @scanner.scan(/[^"\\]+/)
+          result << ch if ch
+          if @scanner.peek(1) == '\\'
+            result << parse_escape_sequence
+          elsif @scanner.peek(1) == '"'
+            @scanner.scan('"')
+            return result
+          else
+            raise ParseError, 'Unterminated basic string'
+          end
+        end
+        raise ParseError, 'Unterminated basic string'
+      end
+
+      def parse_escape_sequence
+        @scanner.scan('\\')
+        ch = @scanner.getch
+        case ch
+        when 'b' then "\b"
+        when 't' then "\t"
+        when 'n' then "\n"
+        when 'f' then "\f"
+        when 'r' then "\r"
+        when '"' then '"'
+        when '\\' then '\\'
+        when 'u'
+          hex = @scanner.scan(/[0-9A-Fa-f]{4}/)
+          raise ParseError, 'Invalid unicode escape' unless hex
+
+          hex.to_i(16).chr(Encoding::UTF_8)
+        when 'U'
+          hex = @scanner.scan(/[0-9A-Fa-f]{8}/)
+          raise ParseError, 'Invalid unicode escape' unless hex
+
+          hex.to_i(16).chr(Encoding::UTF_8)
+        else
+          raise ParseError, "Invalid escape sequence: \\#{ch}"
+        end
+      end
+
+      def parse_multiline_basic_string
+        @scanner.scan('"""')
+        # skip first newline if immediately after opening
+        @scanner.scan(/\r?\n/)
+        result = +''
+        until @scanner.eos?
+          if @scanner.peek(3) == '"""'
+            @scanner.scan('"""')
+            return result
+          elsif @scanner.peek(1) == '\\'
+            if @scanner.rest.match?(/\\\s*\n/)
+              # line-ending backslash: trim whitespace
+              @scanner.scan(/\\[ \t]*\r?\n\s*/)
+            else
+              result << parse_escape_sequence
+            end
+          else
+            ch = @scanner.getch
+            raise ParseError, 'Unterminated multiline basic string' unless ch
+
+            result << ch
+          end
+        end
+        raise ParseError, 'Unterminated multiline basic string'
+      end
+
+      def parse_literal_string
+        expect("'")
+        content = @scanner.scan(/[^']*/)
+        expect("'")
+        content || ''
+      end
+
+      def parse_multiline_literal_string
+        @scanner.scan('\'\'\'')
+        @scanner.scan(/\r?\n/)
+        result = +''
+        until @scanner.eos?
+          if @scanner.peek(3) == "'''"
+            @scanner.scan('\'\'\'')
+            return result
+          else
+            ch = @scanner.getch
+            raise ParseError, 'Unterminated multiline literal string' unless ch
+
+            result << ch
+          end
+        end
+        raise ParseError, 'Unterminated multiline literal string'
+      end
+
+      def parse_true
+        @scanner.scan('true') or raise ParseError, "Expected 'true'"
+        true
+      end
+
+      def parse_false
+        @scanner.scan('false') or raise ParseError, "Expected 'false'"
+        false
+      end
+
+      def parse_special_float
+        str = @scanner.scan(/[+-]?(inf|nan)/)
+        raise ParseError, 'Expected inf or nan' unless str
+
+        case str
+        when 'inf', '+inf' then Float::INFINITY
+        when '-inf' then -Float::INFINITY
+        when 'nan', '+nan', '-nan' then Float::NAN
+        end
+      end
+
+      def parse_number_or_date
+        # Peek ahead to determine type
+        rest = @scanner.rest
+
+        # Offset date-time: 1979-05-27T07:32:00Z or 1979-05-27T07:32:00+00:00
+        case rest
+        when /\A\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})/
+          parse_offset_datetime
+        # Local date-time: 1979-05-27T07:32:00
+        when /\A\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}/
+          parse_local_datetime
+        # Local date: 1979-05-27
+        when /\A\d{4}-\d{2}-\d{2}(?![T \d])/
+          parse_local_date
+        # Local time: 07:32:00
+        when /\A\d{2}:\d{2}:\d{2}/
+          parse_local_time
+        # Hex integer: 0x...
+        when /\A[+-]?0x/
+          parse_hex_integer
+        # Octal integer: 0o...
+        when /\A[+-]?0o/
+          parse_octal_integer
+        # Binary integer: 0b...
+        when /\A[+-]?0b/
+          parse_binary_integer
+        # Float (has dot or exponent)
+        when /\A[+-]?\d[\d_]*(\.\d[\d_]*)?[eE]/, /\A[+-]?\d[\d_]*\.\d/
+          parse_float
+        else
+          parse_integer
+        end
+      end
+
+      def parse_offset_datetime
+        str = @scanner.scan(/\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})/)
+        raise ParseError, 'Invalid offset datetime' unless str
+
+        Time.parse(str)
+      end
+
+      def parse_local_datetime
+        str = @scanner.scan(/\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}(\.\d+)?/)
+        raise ParseError, 'Invalid local datetime' unless str
+
+        Time.parse(str)
+      end
+
+      def parse_local_date
+        str = @scanner.scan(/\d{4}-\d{2}-\d{2}/)
+        raise ParseError, 'Invalid local date' unless str
+
+        Date.parse(str)
+      end
+
+      def parse_local_time
+        str = @scanner.scan(/\d{2}:\d{2}:\d{2}(\.\d+)?/)
+        raise ParseError, 'Invalid local time' unless str
+
+        parts = str.split(':')
+        hour = parts[0].to_i
+        minute = parts[1].to_i
+        sec_parts = parts[2].split('.')
+        second = sec_parts[0].to_i
+        nanosecond = sec_parts[1] ? sec_parts[1].ljust(9, '0')[0, 9].to_i : 0
+
+        { hour: hour, minute: minute, second: second, nanosecond: nanosecond }
+      end
+
+      def parse_integer
+        str = @scanner.scan(/[+-]?\d[\d_]*/)
+        raise ParseError, "Invalid integer at position #{@scanner.pos}" unless str
+
+        str.delete('_').to_i
+      end
+
+      def parse_hex_integer
+        str = @scanner.scan(/[+-]?0x[0-9A-Fa-f_]+/)
+        raise ParseError, 'Invalid hex integer' unless str
+
+        str.delete('_').to_i(16)
+      end
+
+      def parse_octal_integer
+        str = @scanner.scan(/[+-]?0o[0-7_]+/)
+        raise ParseError, 'Invalid octal integer' unless str
+
+        str.delete('_').to_i(8)
+      end
+
+      def parse_binary_integer
+        str = @scanner.scan(/[+-]?0b[01_]+/)
+        raise ParseError, 'Invalid binary integer' unless str
+
+        str.delete('_').to_i(2)
+      end
+
+      def parse_float
+        str = @scanner.scan(/[+-]?\d[\d_]*(\.\d[\d_]*)?([eE][+-]?\d[\d_]*)?/)
+        raise ParseError, 'Invalid float' unless str
+
+        str.delete('_').to_f
+      end
+
+      def parse_array
+        @scanner.scan('[')
+        arr = []
+        skip_whitespace_and_newlines
+        skip_comments_in_collection
+
+        until @scanner.peek(1) == ']'
+          arr << parse_value
+          skip_whitespace_and_newlines
+          skip_comments_in_collection
+          @scanner.scan(',')
+          skip_whitespace_and_newlines
+          skip_comments_in_collection
+        end
+        expect(']')
+        arr
+      end
+
+      def parse_inline_table
+        @scanner.scan('{')
+        table = {}
+        skip_whitespace
+        unless @scanner.peek(1) == '}'
+          loop do
+            keys = parse_key
+            skip_whitespace
+            expect('=')
+            skip_whitespace
+            value = parse_value
+            set_value(table, keys, value)
+            skip_whitespace
+            break unless @scanner.scan(',')
+
+            skip_whitespace
+          end
+        end
+        expect('}')
+        table
+      end
+
+      def skip_comments_in_collection
+        loop do
+          skip_whitespace_and_newlines
+          break unless @scanner.peek(1) == '#'
+
+          skip_comment
+        end
+      end
+
+      def expect(str)
+        return if @scanner.scan(Regexp.new(Regexp.escape(str)))
+
+        raise ParseError, "Expected '#{str}' at position #{@scanner.pos}"
+      end
+
+      def consume_newline_or_eof
+        return if @scanner.eos?
+
+        skip_whitespace
+        return if @scanner.eos?
+        return if @scanner.scan(/\r?\n/)
+        return if @scanner.peek(1) == '#'
+
+        raise ParseError, "Expected newline or EOF at position #{@scanner.pos}, got '#{@scanner.peek(10)}'"
+      end
+    end
+  end
+end

data/lib/philiprehberger/toml_kit/serializer.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require 'date'
+require 'time'
+
+module Philiprehberger
+  module TomlKit
+    # Converts a Ruby Hash into a TOML v1.0 formatted string.
+    #
+    # Type mapping:
+    #   - String -> TOML basic string (with escapes)
+    #   - Integer -> TOML integer
+    #   - Float -> TOML float (handles inf, nan)
+    #   - true/false -> TOML boolean
+    #   - Time -> TOML offset or local date-time
+    #   - Date -> TOML local date
+    #   - Hash with :hour/:minute/:second -> TOML local time
+    #   - Array -> TOML array (or array of tables if all elements are Hashes)
+    #   - Hash -> TOML table
+    class Serializer
+      # @param hash [Hash] Ruby hash to serialize
+      # @return [String] TOML formatted string
+      def serialize(hash)
+        lines = []
+        serialize_table(hash, [], lines)
+        lines.join("\n") << "\n"
+      end
+
+      private
+
+      def serialize_table(hash, path, lines)
+        # First pass: emit simple key/value pairs and inline structures
+        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
+
+        simple_keys.each do |key|
+          lines << "#{format_key(key)} = #{format_value(hash[key])}"
+        end
+
+        table_keys.each do |key|
+          full_path = path + [key]
+          lines << '' unless lines.empty?
+          lines << "[#{full_path.map { |k| format_key(k) }.join('.')}]"
+          serialize_table(hash[key], full_path, lines)
+        end
+
+        array_table_keys.each do |key|
+          full_path = path + [key]
+          hash[key].each do |element|
+            lines << '' unless lines.empty?
+            lines << "[[#{full_path.map { |k| format_key(k) }.join('.')}]]"
+            serialize_table(element, full_path, lines)
+          end
+        end
+      end
+
+      def format_key(key)
+        key = key.to_s
+        if key.match?(/\A[A-Za-z0-9_-]+\z/)
+          key
+        else
+          format_basic_string(key)
+        end
+      end
+
+      def format_value(value)
+        case value
+        when String then format_basic_string(value)
+        when Integer then value.to_s
+        when Float then format_float(value)
+        when true then 'true'
+        when false then 'false'
+        when Time then value.strftime('%Y-%m-%dT%H:%M:%S%:z')
+        when Date then value.strftime('%Y-%m-%d')
+        when Array then format_array(value)
+        when Hash
+          if local_time_hash?(value)
+            format_local_time(value)
+          else
+            format_inline_table(value)
+          end
+        else
+          format_basic_string(value.to_s)
+        end
+      end
+
+      def format_basic_string(str)
+        escaped = str.gsub('\\', '\\\\\\\\')
+                     .gsub('"', '\\"')
+                     .gsub("\b", '\\b')
+                     .gsub("\t", '\\t')
+                     .gsub("\n", '\\n')
+                     .gsub("\f", '\\f')
+                     .gsub("\r", '\\r')
+        "\"#{escaped}\""
+      end
+
+      def format_float(value)
+        if value.infinite? == 1
+          'inf'
+        elsif value.infinite? == -1
+          '-inf'
+        elsif value.nan?
+          'nan'
+        else
+          # Ensure float always has a decimal point
+          str = value.to_s
+          str.include?('.') || str.include?('e') ? str : "#{str}.0"
+        end
+      end
+
+      def format_array(arr)
+        elements = arr.map { |v| format_value(v) }
+        "[#{elements.join(', ')}]"
+      end
+
+      def format_inline_table(hash)
+        pairs = hash.map { |k, v| "#{format_key(k)} = #{format_value(v)}" }
+        "{#{pairs.join(', ')}}"
+      end
+
+      def format_local_time(hash)
+        hour = hash[:hour].to_s.rjust(2, '0')
+        minute = hash[:minute].to_s.rjust(2, '0')
+        second = hash[:second].to_s.rjust(2, '0')
+        nano = hash[:nanosecond] || 0
+        if nano.positive?
+          frac = nano.to_s.rjust(9, '0').sub(/0+\z/, '')
+          "#{hour}:#{minute}:#{second}.#{frac}"
+        else
+          "#{hour}:#{minute}:#{second}"
+        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/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module TomlKit
+    VERSION = '0.1.0'
+  end
+end

data/lib/philiprehberger/toml_kit.rb

@@ -0,0 +1,48 @@
+# 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
+
+    # Parse a TOML string into a Ruby Hash.
+    #
+    # @param string [String] TOML document
+    # @return [Hash] parsed result
+    # @raise [ParseError] if the input is not valid TOML
+    def self.parse(string)
+      Parser.new.parse(string)
+    end
+
+    # Parse a TOML file into a Ruby Hash.
+    #
+    # @param path [String] path to a TOML file
+    # @return [Hash] parsed result
+    # @raise [ParseError] if the file contents are not valid TOML
+    # @raise [Errno::ENOENT] if the file does not exist
+    def self.load(path)
+      parse(File.read(path, encoding: 'utf-8'))
+    end
+
+    # Serialize a Ruby Hash into a TOML string.
+    #
+    # @param hash [Hash] data to serialize
+    # @return [String] TOML formatted string
+    def self.dump(hash)
+      Serializer.new.serialize(hash)
+    end
+
+    # Write a Ruby Hash to a TOML file.
+    #
+    # @param hash [Hash] data to serialize
+    # @param path [String] output file path
+    # @return [void]
+    def self.save(hash, path)
+      File.write(path, dump(hash), encoding: 'utf-8')
+    end
+  end
+end

metadata

@@ -0,0 +1,56 @@
+--- !ruby/object:Gem::Specification
+name: philiprehberger-toml_kit
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Philip Rehberger
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-03-27 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.
+email:
+- me@philiprehberger.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/philiprehberger/toml_kit.rb
+- lib/philiprehberger/toml_kit/parser.rb
+- lib/philiprehberger/toml_kit/serializer.rb
+- lib/philiprehberger/toml_kit/version.rb
+homepage: https://github.com/philiprehberger/rb-toml-kit
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/philiprehberger/rb-toml-kit
+  source_code_uri: https://github.com/philiprehberger/rb-toml-kit
+  changelog_uri: https://github.com/philiprehberger/rb-toml-kit/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/philiprehberger/rb-toml-kit/issues
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: TOML v1.0 parser and serializer for Ruby
+test_files: []