json-to-toon 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: dce3c47c0ea7444146b729dea48cbb14a7a229e54b93ea88cdbadf0b17e4cb2c
+  data.tar.gz: afb955c2c2e23d89cc17c8f59aaef420df0fa8c1d33df491ade236b386ba5a0d
+SHA512:
+  metadata.gz: d282c4fdbe66511c3348a0ec69fadefd0ab0c68fb3752846ff42258bd7ce4cdd5e6d83856208f315a9f241d6a48ec62edbb03ebcb050079b6e5c358f60e6476a
+  data.tar.gz: 175b6822ca8893d779c972810b97de44087328ed06aa07e8a3988178ca5611c4a9cfa0fa0044cef4bde376ef2409e6782899356f2f1a03759a1ae2813131994c

data/LICENSE.txt

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) [2025] [Daniele Frisanco]
+
+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,147 @@
+JsonToToon
+
+JsonToToon is a unique Ruby gem designed to convert standard JSON strings into a custom, highly structured text format (dubbed the "Toon Format") optimized for human readability and specific parsing needs.
+
+Unlike standard JSON or YAML, the Toon Format includes structural metadata like array counts and keys for tabular data, making it useful for configuration systems or structured data display.
+
+✨ Features
+
+- **Deep Symbolization**: All JSON keys are deeply symbolized internally for easy processing.
+- **Tree Structure Conversion**: JSON is converted into a hierarchical `DataNode` tree (`ObjectNode`, `ArrayNode`, `ValueNode`).
+- **Custom Toon Format Output**: Converts the structure into a custom, indented string output.
+- **Tabular Array Detection**: Automatically detects arrays containing homogenous records (hash keys are all the same, values are primitive) and outputs them using a concise tabular syntax: `array_key[count]{key1,key2}:`.
+- **Clean Error Handling**: Uses custom `JsonToToon::ConversionError` for invalid input.
+- **Deeply Nested JSONs Handling**: The gem is specifically designed to handle and accurately represent highly complex and **deeply nested** JSON structures in the Toon Format.
+
+⚙️ Installation
+
+Add this line to your application's `Gemfile`:
+```ruby
+gem 'json-to-toon'
+```
+
+And then execute:
+```bash
+bundle install
+```
+
+Or install it yourself as:
+```bash
+gem install json-to-toon
+```
+
+🚀 Usage
+
+The primary function of the gem is the `JsonToToon.convert` class method, which takes a JSON string and returns the formatted Toon string.
+
+Simple Example
+
+```ruby
+require 'json-to-toon'
+
+json_string = '{"title": "The Report", "version": 1.0}'
+toon_output = JsonToToon.convert(json_string)
+
+puts toon_output
+
+# Output:
+# title: The Report
+# version: 1.0
+```
+
+📝 What is the Toon Format?
+
+This gem converts JSON into the Toon Format, a custom, structured data serialization format designed for specialized hierarchical data display.
+
+The format is characterized by:
+
+- Two-space indentation.
+
+- The use of special notation for arrays, particularly when detecting tabular data (arrays of uniform hashes).
+
+- Keys containing structural metadata (like the count and keys in `team_members[2]{id,role}:`).
+
+- You can find the full specification and details on this format here: [Toon Format Specification](https://toonformat.dev/).
+
+Complex Example (Demonstrating Tabular Arrays and Nesting)
+
+Given this input JSON:
+```json
+{
+  "project_details": {
+    "name": "Project Alpha",
+    "status": "In Progress"
+  },
+  "team_members": [
+    { "id": 1, "role": "Engineer" },
+    { "id": 2, "role": "Designer" }
+  ],
+  "tasks": [
+    "documentation",
+    "refactoring"
+  ]
+}
+```
+
+The output "Toon Format" string will be:
+```ruby
+require 'json-to-toon'
+
+complex_json = File.read('input.json') # Assume file reading here
+
+toon_output = JsonToToon.convert(complex_json)
+
+puts toon_output
+
+# Output:
+# project_details:
+# name: Project Alpha
+# status: In Progress
+# team_members[2]{id,role}:
+# 1,Engineer
+# 2,Designer
+# tasks:
+# - documentation
+# - refactoring
+```
+Notice the key differences:
+
+1. `project_details` is indented normally.
+
+2. `team_members` is detected as a tabular array (`[2]{id,role}:`) and its items are output as comma-separated values (CSV style).
+
+3. `tasks` (an array of simple values) is output as a standard dashed list.
+
+🛑 Error Handling
+
+The gem uses custom exceptions for easy handling within your application:
+
+ | Exception | Base Class | Triggered When
+|-|-|-|
+`ArgumentError` | `StandardError` | Input is not a String.
+`JsonToToon::ConversionError` | `JsonToToon::Error` | The input string is syntactically invalid JSON (wraps `JSON::ParserError`).
+
+Example of catching a conversion failure:
+```ruby
+require 'json-to-toon'
+
+begin
+  JsonToToon.convert('{broken:')
+rescue JsonToToon::ConversionError => e
+  puts "Conversion failed: #{e.message}"
+end
+
+# Output: Conversion failed: Invalid JSON input: expected ',' or '}' after object key and value
+```
+
+🧑‍💻 Development
+
+After checking out the repository, run `bundle install` to install dependencies.
+
+To run the tests and linting:
+
+```bash
+bundle exec rspec # Runs the test suite
+
+bundle exec rubocop -a # Runs the linter and auto-corrects offenses
+```

data/lib/json-to-toon.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative 'json_to_toon/version'
+require_relative 'json_to_toon/converter'
+
+module JsonToToon
+  def self.convert(json_string)
+    Converter.convert(json_string)
+  end
+end

data/lib/json_to_toon/array_node.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require_relative 'container_node'
+
+module JsonToToon
+  class ArrayNode < ContainerNode
+    def initialize(parent = nil)
+      super
+    end
+
+    def standard_tabular_array?
+      arr = @children
+
+      return true if arr.empty?
+
+      first_node = arr[0]
+      return false unless first_node.is_a?(ObjectNode)
+
+      first_hash_keys = first_node.keys.sort
+
+      arr.all? do |item_node|
+        next false unless item_node.is_a?(ObjectNode)
+        next false unless item_node.keys.sort == first_hash_keys
+
+        item_node.children.all? do |key_value_node|
+          value_node = key_value_node.value_node
+          value_node.is_a?(ValueNode)
+        end
+      end
+    end
+
+    def single_indent(spaces = 2)
+      ' ' * (@indentation_level * spaces)
+    end
+
+    def to_s
+      output = +''
+      if standard_tabular_array?
+        unless @children.empty?
+          type = "{#{@children.first&.keys&.join(',')}}"
+          output = type.to_s
+        end
+        output += ":\n"
+
+        output += @children.map do |item|
+          "#{indent}#{item.children.map { |c| c.to_s.chomp.lstrip }.join(',')}"
+        end.join("\n")
+        return output
+      end
+
+      output = +':'
+      output_inline = true
+
+      child_strings = @children.map do |child|
+        output_inline = false if child.is_a?(ObjectNode) || child.is_a?(ArrayNode)
+        child.to_s.chomp.lstrip
+      end
+      if output_inline
+        output = +'' if parent.is_a?(ArrayNode)
+        output << ' '
+        output << child_strings.join(',')
+      else
+        output << "\n#{indent}- "
+        output << child_strings.join("\n#{indent}- ")
+      end
+
+      output << "\n"
+
+      output
+    end
+  end
+end

data/lib/json_to_toon/container_node.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative 'data_node'
+
+module JsonToToon
+  class ContainerNode < DataNode
+    attr_reader :children
+
+    def initialize(parent = nil)
+      super
+      @children = []
+    end
+
+    def add_child(child)
+      raise ArgumentError, 'Can only add objects of type DataNode as children.' unless child.is_a?(DataNode)
+
+      @children << child
+    end
+
+    def to_s
+      raise NotImplementedError, "#{self.class} must implement the 'to_s' method for specific formatting."
+    end
+  end
+end

data/lib/json_to_toon/converter.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'node_builder'
+require_relative 'errors'
+
+module JsonToToon
+  class Converter
+    def self.convert(json_string)
+      raise ArgumentError, 'Input must be a String.' unless json_string.is_a?(String)
+
+      data_hash = JSON.parse(json_string, symbolize_names: true)
+
+      root_node = NodeBuilder.build(data_hash)
+      root_node.to_s
+    rescue JSON::ParserError => e
+      raise ConversionError, "Invalid JSON structure provided: #{e.message}"
+    rescue StandardError => e
+      raise Error, "An unexpected error occurred during conversion: #{e.message}"
+    end
+  end
+end

data/lib/json_to_toon/data_node.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module JsonToToon
+  class DataNode
+    attr_accessor :parent
+
+    attr_reader :indentation_level
+
+    def initialize(parent = nil)
+      @parent = parent
+      @indentation_level = parent ? parent.indentation_level + 1 : 0
+    end
+
+    def to_s
+      raise NotImplementedError, "#{self.class} must implement the 'to_s' method."
+    end
+
+    def add_child(child)
+      raise NotImplementedError, "#{self.class} does not support adding children."
+    end
+
+    def indent(spaces = 2)
+      ' ' * (@indentation_level * spaces)
+    end
+
+    def root
+      current = self
+      current = current.parent until current.parent.nil?
+      current
+    end
+  end
+end

data/lib/json_to_toon/errors.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module JsonToToon
+  class Error < StandardError; end
+  class ConversionError < Error; end
+end

data/lib/json_to_toon/node_builder.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative 'object_node'
+require_relative 'array_node'
+require_relative 'value_node'
+
+module JsonToToon
+  class NodeBuilder
+    def self.build(data, parent = nil)
+      case data
+      when Hash
+        node = ObjectNode.new(parent)
+        data.each do |key, value|
+          child_node = self.build(value, node)
+
+          node.add_key_value(key, child_node)
+        end
+
+        node
+
+      when Array
+        node = ArrayNode.new(parent)
+
+        data.each do |item|
+          child_node = self.build(item, node)
+
+          node.add_child(child_node)
+        end
+
+        node
+
+      when String, Numeric, TrueClass, FalseClass, NilClass
+        ValueNode.new(data, parent)
+      else
+        ValueNode.new(data.to_s, parent)
+      end
+    end
+  end
+end

data/lib/json_to_toon/object_node.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require_relative 'container_node'
+
+module JsonToToon
+  class ObjectNode < ContainerNode
+    class KeyedValue
+      attr_reader :key, :value_node
+
+      def initialize(key, value_node)
+        @key = key.to_s
+        @value_node = value_node
+      end
+
+      def to_s
+        @value_node.to_s
+      end
+    end
+
+    def initialize(parent = nil)
+      super
+    end
+
+    def keys
+      @children.map(&:key)
+    end
+
+    def add_key_value(key, value_node)
+      raise ArgumentError, 'Can only add DataNode objects as values.' unless value_node.is_a?(DataNode)
+
+      @children << KeyedValue.new(key, value_node)
+    end
+
+    def to_s
+      return indent.to_s if @children.empty?
+
+      output = if parent
+                 "#{indent}\n"
+               else
+                 String.new(encoding: Encoding::UTF_8)
+               end
+
+      child_strings = @children.map do |keyed_value|
+        value_indent = '  ' * @indentation_level
+        value_string = keyed_value.value_node.to_s.chomp
+        if keyed_value.value_node.is_a?(ArrayNode)
+          "#{value_indent}#{keyed_value.key}[#{keyed_value.value_node.children.size}]#{value_string.lstrip}"
+
+        else
+
+          newline = ''
+          if keyed_value.value_node.is_a?(ObjectNode) && !keyed_value.value_node.children.empty?
+            newline = "\n#{'  ' * keyed_value.value_node.indentation_level}"
+          end
+
+          "#{value_indent}#{keyed_value.key}: #{newline}#{value_string.lstrip}"
+        end
+      end
+
+      output << child_strings.join("\n")
+
+      output
+    end
+  end
+end

data/lib/json_to_toon/value_node.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative 'data_node'
+
+module JsonToToon
+  class ValueNode < DataNode
+    attr_reader :value
+
+    def initialize(value, parent = nil)
+      super(parent)
+      @value = value
+    end
+
+    def escape(value)
+      return 'null' if value.nil?
+      return value unless value.is_a?(String)
+      return "\"#{value.gsub('"', '\"')}\"" if value.match(/"/)
+      return "\"#{value}\"" if value.match(/,/)
+      return "\"#{value}\"" if value.match(/^(-\s)/)
+      return "\"#{value.gsub("\n", '\n')}\"" if value.match(/\n/)
+
+      value
+    end
+
+    def to_s
+      formatted_value = case @value
+                        when String
+                          escape(@value)
+                        when Numeric, TrueClass, FalseClass
+                          @value.to_s
+                        when NilClass
+                          'null'
+                        else
+                          @value.to_s
+                        end
+
+      "#{indent}#{formatted_value}"
+    end
+
+    def add_child(_child)
+      raise NoMethodError, "A #{self.class} cannot have children."
+    end
+  end
+end

data/lib/json_to_toon/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module JsonToToon
+  VERSION = '0.1.0'
+end

metadata

@@ -0,0 +1,130 @@
+--- !ruby/object:Gem::Specification
+name: json-to-toon
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Daniele Frisanco
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2025-11-16 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.61'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.61'
+description: Transforms JSON into the custom, human-readable Toon Format. Features
+  deep nesting support and optimized tabular array display.
+email:
+- daniele.frisanco@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/json-to-toon.rb
+- lib/json_to_toon/array_node.rb
+- lib/json_to_toon/container_node.rb
+- lib/json_to_toon/converter.rb
+- lib/json_to_toon/data_node.rb
+- lib/json_to_toon/errors.rb
+- lib/json_to_toon/node_builder.rb
+- lib/json_to_toon/object_node.rb
+- lib/json_to_toon/value_node.rb
+- lib/json_to_toon/version.rb
+homepage: https://github.com/danielefrisanco/json-to-toon
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/danielefrisanco/json-to-toon
+  source_code_uri: https://github.com/danielefrisanco/json-to-toon
+  changelog_uri: https://github.com/danielefrisanco/json-to-toon/CHANGELOG.md
+  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: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.26
+signing_key: 
+specification_version: 4
+summary: Transforms JSON into the custom, human-readable Toon Format.
+test_files: []