toon-rb 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e1a18de600edbf8f9d7ad1869dccfd2c72ba5224b669ec715f4ee194b9d98c64
+  data.tar.gz: ba63932aa8ca6b7b5de8ed43435dd8ef95cbad8927c490317cc810625ba55c97
+SHA512:
+  metadata.gz: 99971c6f635a94138d6661439f9d1bc9c65e8e783063fe84c1f94a8e5c1de8dbc3c100513aeb710b9ab914546ee5f00f81ac765fac197733109c296a12932182
+  data.tar.gz: 866fd064fb06e7c73fd78934850ea0a7d0442a9c6ecca1834af88cc68de4ac100be6ed342191198b2455251041efa5953b2d77e0d1cb04694f94b13a12b84e96

data/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.1.0] - 2025-11-16
+
+- Initial release of the Ruby TOON gem.
+- Provides `Toon.encode`, `Toon.decode`, and `Toon.decode_safe` APIs.
+- Implements core encode/decode for typical Ruby types (strings, integers, floats, booleans, nil, arrays, hashes).
+- Includes RSpec unit tests and basic integration test that mirrors README usage.
+- Targets TOON specification baseline pinned conceptually to `v1.0.0`.
+
+

data/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2025 
+
+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,96 @@
+# Ruby TOON Gem
+
+A Ruby gem providing TOON-style encode/decode functionality with simple `encode` / `decode` APIs and containerized test setup.
+
+## Installation
+
+Add this line to your application's `Gemfile`:
+
+```ruby
+gem "toon"
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+### From GitHub
+
+Until published to RubyGems you can depend on the GitHub repository (note the `gem` subdirectory):
+
+```ruby
+gem "toon", git: "https://github.com/dobryakov/ruby-toon-gem", subdir: "gem"
+```
+
+### From local path (for development)
+
+```ruby
+gem "toon", path: "path/to/ruby-toon-gem/gem"
+```
+
+## Usage
+
+```ruby
+require "toon"
+
+data = {
+  "message" => "Hello, TOON!",
+  "answer" => 42,
+  "items" => [1, 2, 3],
+  "flags" => { "ok" => true, "admin" => false }
+}
+
+encoded = Toon.encode(data)
+decoded = Toon.decode(encoded)
+
+puts encoded         # TOON-encoded string (UTF-8 by default)
+puts decoded.inspect # => original Ruby structure
+```
+
+### Safe decode
+
+```ruby
+result = Toon.decode_safe("not-a-valid-payload")
+
+result.value       # => nil
+result.errors      # => ["...error message..."]
+result.diagnostics # => []
+```
+
+## Development
+
+This repository is designed to run tests via Docker and `docker-compose`.
+
+### Quickstart (docker-compose)
+
+From the repository root:
+
+```bash
+cp env.example .env
+
+docker-compose -f docker/compose/docker-compose.yml build
+```
+
+Run gem unit specs:
+
+```bash
+docker-compose -f docker/compose/docker-compose.yml run --rm gem sh -lc 'bundle install && bundle exec rake spec'
+```
+
+Run Rails-based specs:
+
+```bash
+docker-compose -f docker/compose/docker-compose.yml run --rm rails_app sh -lc 'bundle install && bundle exec rspec'
+```
+
+Or run both via the smoke test script:
+
+```bash
+./scripts/smoke_tests.sh
+```
+
+For more details, see `specs/001-implement-toon-gem/quickstart.md`.
+
+

data/lib/toon/codec_options.rb

@@ -0,0 +1,35 @@
+module Toon
+  class CodecOptions
+    attr_reader :binary_output,
+                :reject_special_floats,
+                :duplicate_key_policy,
+                :canonical_encode
+
+    def initialize(
+      binary_output: false,
+      reject_special_floats: false,
+      duplicate_key_policy: :raise,
+      canonical_encode: true
+    )
+      @binary_output = binary_output
+      @reject_special_floats = reject_special_floats
+      @duplicate_key_policy = duplicate_key_policy
+      @canonical_encode = canonical_encode
+    end
+
+    def self.from(options)
+      case options
+      when nil
+        new
+      when CodecOptions
+        options
+      when Hash
+        new(**options.transform_keys(&:to_sym))
+      else
+        raise ArgumentError, "Unsupported options type: #{options.class}"
+      end
+    end
+  end
+end
+
+

data/lib/toon/decoder.rb

@@ -0,0 +1,77 @@
+require "json"
+
+module Toon
+  DecodeResult = Struct.new(:value, :diagnostics, :errors, keyword_init: true)
+
+  class Decoder
+    def initialize(options = nil)
+      @options = CodecOptions.from(options)
+    end
+
+    def decode(input)
+      value = parse(input)
+      validate_decoded!(value)
+      value
+    rescue DecodingError => e
+      raise e
+    rescue StandardError => e
+      raise MalformedInputError, e.message
+    end
+
+    def decode_safe(input)
+      diagnostics = []
+      errors = []
+      value = nil
+
+      begin
+        value = decode(input)
+      rescue DecodingError => e
+        errors << e.message
+        value = nil
+      end
+
+      DecodeResult.new(value: value, diagnostics: diagnostics, errors: errors)
+    end
+
+    private
+
+    def parse(input)
+      str = case input
+            when String
+              input.dup
+            else
+              raise MalformedInputError, "Input must be a String"
+            end
+
+      JSON.parse(str)
+    rescue JSON::ParserError => e
+      raise MalformedInputError, e.message
+    end
+
+    def validate_decoded!(value)
+      case value
+      when nil, true, false, String, Integer
+        true
+      when Float
+        if @options.reject_special_floats && !value.finite?
+          raise SpecialFloatError, "NaN and Infinity not allowed when reject_special_floats is true"
+        end
+      when Array
+        value.each { |v| validate_decoded!(v) }
+      when Hash
+        # Ruby's JSON parser already applies last-wins semantics for duplicate keys.
+        # Here we only validate key/value types.
+        value.each do |k, v|
+          unless k.is_a?(String)
+            raise MalformedInputError, "Decoded hash keys must be strings, got #{k.class}"
+          end
+          validate_decoded!(v)
+        end
+      else
+        raise MalformedInputError, "Unsupported decoded type: #{value.class}"
+      end
+    end
+  end
+end
+
+

data/lib/toon/encoder.rb

@@ -0,0 +1,50 @@
+require "json"
+
+module Toon
+  class Encoder
+    def initialize(options = nil)
+      @options = CodecOptions.from(options)
+    end
+
+    def encode(value)
+      normalized = normalize(value)
+      json = JSON.generate(normalized)
+      if @options.binary_output
+        json.force_encoding(Encoding::ASCII_8BIT)
+      else
+        json.force_encoding(Encoding::UTF_8)
+      end
+    end
+
+    private
+
+    def normalize(value)
+      case value
+      when nil, true, false, String, Integer
+        value
+      when Float
+        raise SpecialFloatError, "NaN and Infinity are not allowed in encode" unless value.finite?
+        value
+      when Array
+        value.map { |v| normalize(v) }
+      when Hash
+        # Canonicalize by key (string representation) if enabled
+        pairs = value.to_a
+        if @options.canonical_encode
+          pairs = pairs.sort_by { |k, _| k.to_s }
+        end
+        pairs.each_with_object({}) do |(k, v), acc|
+          key = k.is_a?(Symbol) ? k.to_s : k
+          unless key.is_a?(String)
+            raise UnsupportedTypeError, "Hash keys must be strings or symbols, got #{k.class}"
+          end
+          acc[key] = normalize(v)
+        end
+      else
+        raise UnsupportedTypeError, "Unsupported type for encode: #{value.class}"
+      end
+    end
+  end
+end
+
+

data/lib/toon/errors.rb

@@ -0,0 +1,14 @@
+module Toon
+  class Error < StandardError; end
+
+  class EncodingError < Error; end
+  class DecodingError < Error; end
+
+  class UnsupportedTypeError < EncodingError; end
+  class SpecialFloatError < EncodingError; end
+
+  class DuplicateKeyError < DecodingError; end
+  class MalformedInputError < DecodingError; end
+end
+
+

data/lib/toon/version.rb

@@ -0,0 +1,5 @@
+module Toon
+  VERSION = "0.1.0"
+end
+
+

data/lib/toon.rb

@@ -0,0 +1,21 @@
+require_relative "toon/version"
+require_relative "toon/errors"
+require_relative "toon/codec_options"
+require_relative "toon/encoder"
+require_relative "toon/decoder"
+
+module Toon
+  def self.encode(value, options = nil)
+    Encoder.new(options).encode(value)
+  end
+
+  def self.decode(input, options = nil)
+    Decoder.new(options).decode(input)
+  end
+
+  def self.decode_safe(input, options = nil)
+    Decoder.new(options).decode_safe(input)
+  end
+end
+
+

metadata

@@ -0,0 +1,54 @@
+--- !ruby/object:Gem::Specification
+name: toon-rb
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ruby TOON Gem
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-11-16 00:00:00.000000000 Z
+dependencies: []
+description: A Ruby gem providing TOON encode/decode functionality with spec-aligned
+  behavior.
+email:
+- grigoriydobryakov@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/toon.rb
+- lib/toon/codec_options.rb
+- lib/toon/decoder.rb
+- lib/toon/encoder.rb
+- lib/toon/errors.rb
+- lib/toon/version.rb
+homepage: https://github.com/dobryakov/ruby-toon-gem
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/dobryakov/ruby-toon-gem
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.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: TOON encoder/decoder for Ruby
+test_files: []