ruby-toon 1.0.0 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7f006a20c57bdd904663ccfd5294101e625934bc5a1df303a6f2cf471f3745df
-  data.tar.gz: 80e3c4cd371b9eca3c47855bc79fdf67102e6c04272c69c3c1f752957c240e5d
+  metadata.gz: d6ebe1e066311203869e7a9c6f0d6d54e7016eddf9d8b50a47d85198ee84c458
+  data.tar.gz: bc1e3ab72636edc57c512c327c3802a14505ce968b197882dfd6e8093bca9069
 SHA512:
-  metadata.gz: 6c6ef31232a2209e64815eae5f25f9bf195caee071323777eeac4a4217b45ae3937c7a8cb937d5dd60bc46f4b6c3ca0b757b0e61de58d314e67454d03f3a5b9a
-  data.tar.gz: 1f7ee09ca1533d1ac7cb4ce3b7233f27dae0389ddfda99e9771b3087918c47e5528e858d83ddcfe69496973412a846107c80d01e6f3995a9953da8d658788870
+  metadata.gz: 8dc9df86a1128eb5263feb7f382398671df45d0751175ba2c1b45804fb6bb9a456e04f15de59ffa7bd5536b6dd64f429a2e74aa8f554ca42f965a451bdfd68d6
+  data.tar.gz: f4b9f5594635a708a9ef96a93aeba12cd395cb276e56d77a08aadcd5f0cbef7b4eee16d5db09133b052703881349c70831d0b257826f1d26bb723d9270a8c715

data/README.md

@@ -1,22 +1,24 @@
-````markdown
-# 🎋 Toon — Token-Oriented Object Notation for Ruby
+# **Toon** (Token-Oriented Object Notation for Ruby)
+[![Gem Version](https://badge.fury.io/rb/ruby-toon.svg)](https://badge.fury.io/rb/ruby-toon)
+[![Build Status](https://github.com/anilyanduri/toon/actions/workflows/ruby.yml/badge.svg?branch=main)](https://github.com/anilyanduri/toon/actions/workflows/ruby.yml)
 
-`toon` is a Ruby implementation of **TOON (Token-Oriented Object Notation)** —
+`toon` is a Ruby implementation of **TOON (Token-Oriented Object Notation)**
 a compact, readable, indentation-based data format designed for humans *and* machines.
 
 This gem provides:
 
-- A **TOON encoder** (Ruby → TOON)
-- A **TOON decoder** (TOON → Ruby)
+- A **TOON encoder** (Ruby to TOON)
+- A **TOON decoder** (TOON to Ruby)
 - A **CLI** (`bin/toon`) for converting TOON ↔ JSON
 - Optional **ActiveSupport integration** (`Object#to_toon`)
+- Built-in `Hash#to_toon` / `Array#to_toon` plus lightweight `#to_json` helpers
 - Full RSpec test suite
 
 ---
 
-## ✨ Features
+## Features
 
-### ✔ Encode Ruby objects → TOON
+### Encode Ruby objects to TOON
 ```ruby
 Toon.generate({ "name" => "Alice", "age" => 30 })
 ````
@@ -28,7 +30,7 @@ name:Alice
 age:30
 ```
 
-### ✔ Decode TOON → Ruby
+### Decode TOON to Ruby
 
 ```ruby
 Toon.parse("name:Alice\nage:30")
@@ -42,7 +44,7 @@ Returns:
 
 ---
 
-## 🧩 Arrays
+## Arrays
 
 ### Nested arrays (encoder output)
 
@@ -67,7 +69,7 @@ Both decode correctly.
 
 ---
 
-## 📊 Tabular Arrays
+## Tabular Arrays
 
 ### Nested tabular (encoder output)
 
@@ -78,7 +80,7 @@ users:
     2,B
 ```
 
-→ numeric fields parsed (`id` becomes integer)
+numeric fields parsed (`id` becomes integer)
 
 ### Flat tabular (user input)
 
@@ -88,27 +90,49 @@ users[2]{id,name}:
   2,Bob
 ```
 
-→ fields remain **strings**
+fields remain **strings**
 
 ---
 
-## ⚙️ ActiveSupport Integration
+## ActiveSupport Integration
 
-If ActiveSupport is installed:
+If ActiveSupport (and by extension Rails/Active Record) is installed—regardless of whether it loads before or after `toon`—every object gains `#to_toon`.
 
 ```ruby
+require "toon"
 require "active_support"
+
+class User < ApplicationRecord; end
+
+User.first.to_toon
+# => "id:1\nname:Alice\n..."
+```
+
+- Automatically hooks in as soon as ActiveSupport finishes loading (thanks to a TracePoint watcher)
+- Falls back to `#as_json` when present, so Active Record / ActiveModel instances serialize their attributes instead of opaque object IDs
+
+## Core Extensions
+
+`toon` now provides handy helpers even without ActiveSupport:
+
+```ruby
 require "toon"
 
-{a: 1}.to_toon
-# => "a:1\n"
+{foo: "bar"}.to_toon
+# => "foo:bar"
+
+[1, 2, 3].to_toon
+# => "[3]:\n  1\n  2\n  3\n"
+
+{foo: "bar"}.to_json
+# => "{\"foo\":\"bar\"}"
 ```
 
-Adds `Object#to_toon` for convenience.
+Both `Hash` and `Array` gain `#to_toon` and `#to_json` implementations so you can round-trip data between TOON and JSON with a single method call.
 
 ---
 
-## 🚀 Installation
+## Installation
 
 Gem coming soon. For now:
 
@@ -126,15 +150,15 @@ require_relative "lib/toon"
 
 ---
 
-## 🧰 CLI Usage
+## CLI Usage
 
-### Encode JSON → TOON
+### Encode JSON to TOON
 
 ```bash
 echo '{"name":"Alice","age":30}' | bin/toon --encode
 ```
 
-### Decode TOON → JSON
+### Decode TOON to JSON
 
 ```bash
 echo "name:Alice\nage:30" | bin/toon --decode
@@ -148,7 +172,7 @@ bin/toon --encode < input.json
 
 ---
 
-## 🧪 Running Tests
+## Running Tests
 
 Ensure CLI is executable:
 
@@ -171,7 +195,7 @@ Tests include:
 
 ---
 
-## 📚 Supported TOON Grammar (Current)
+## Supported TOON Grammar (Current)
 
 ### Key-value
 
@@ -225,7 +249,7 @@ users[2]{id,name}:
 
 ---
 
-## ⚠️ Error Handling
+## Error Handling
 
 Malformed input (e.g., missing indentation):
 
@@ -237,7 +261,7 @@ Decoder stops with a friendly `Toon::Error`.
 
 ---
 
-## 🗺️ Roadmap
+## Roadmap
 
 * Multiline values
 * Quoted strings

data/lib/extensions/active_support.rb

@@ -1,12 +1,50 @@
-# Optional ActiveSupport integration
-begin
-  require 'active_support'
-  require 'active_support/core_ext/object'
-  class Object
-    def to_toon(**opts)
-      Toon.generate(self, **opts)
+module Toon
+  module Extensions
+    module ActiveSupport
+      module ObjectMethods
+        # Serialize the object into TOON, preferring +as_json+ when available.
+        # @param opts [Hash] encoder options passed to {Toon.generate}.
+        # @return [String] TOON payload.
+        def to_toon(**opts)
+          payload = respond_to?(:as_json) ? as_json : self
+          Toon.generate(payload, **opts)
+        end
+      end
+
+      module_function
+
+      # Inject +to_toon+ into Object so any model can be exported.
+      # @return [void]
+      def install!
+        return if Object.method_defined?(:to_toon)
+        Object.include(ObjectMethods)
+      end
+
+      # Install Object methods only when ActiveSupport is present.
+      # @return [void]
+      def ensure_installed!
+        return unless defined?(::ActiveSupport)
+        install!
+      end
+
+      # Attach a TracePoint that installs hooks once ActiveSupport loads.
+      # @return [void]
+      def watch_for_active_support!
+        return if defined?(@tracepoint) && @tracepoint&.enabled?
+        @tracepoint = TracePoint.new(:end) do |tp|
+          next unless tp.self.is_a?(Module)
+          next unless tp.self.name == "ActiveSupport"
+          ensure_installed!
+          @tracepoint.disable
+        end
+        @tracepoint.enable
+      end
     end
   end
-rescue LoadError
-  # no activesupport available
+end
+
+if defined?(::ActiveSupport)
+  Toon::Extensions::ActiveSupport.ensure_installed!
+else
+  Toon::Extensions::ActiveSupport.watch_for_active_support!
 end

data/lib/extensions/core.rb

@@ -0,0 +1,73 @@
+require 'json'
+
+module Toon
+  module Extensions
+    module Core
+      module_function
+
+      # Serialize a Hash-like object into TOON using the global encoder.
+      # @param target [Hash] structure to encode.
+      # @param opts [Hash] options passed through to {Toon.generate}.
+      # @return [String] TOON string.
+      def hash_to_toon(target, **opts)
+        Toon.generate(target, **opts)
+      end
+
+      # Serialize an Array into TOON by delegating to {Toon.generate}.
+      # @param target [Array] structure to encode.
+      # @param opts [Hash] options passed through to the encoder.
+      # @return [String] TOON string.
+      def array_to_toon(target, **opts)
+        Toon.generate(target, **opts)
+      end
+
+      # Convert the object to JSON using the bundled JSON gem.
+      # @param target [Object] structure to encode.
+      # @param args [Array] options forwarded to {JSON.generate}.
+      # @return [String] JSON payload.
+      def to_json_payload(target, *args)
+        JSON.generate(target, *args)
+      end
+    end
+  end
+end
+
+class Hash
+  unless method_defined?(:to_toon)
+    # Serialize the hash into TOON format.
+    # @param opts [Hash] encoder options.
+    # @return [String] TOON payload.
+    def to_toon(**opts)
+      Toon::Extensions::Core.hash_to_toon(self, **opts)
+    end
+  end
+
+  unless method_defined?(:to_json)
+    # Serialize the hash into JSON via the core extension helper.
+    # @param args [Array] JSON serialization options.
+    # @return [String] JSON payload.
+    def to_json(*args)
+      Toon::Extensions::Core.to_json_payload(self, *args)
+    end
+  end
+end
+
+class Array
+  unless method_defined?(:to_toon)
+    # Serialize the array into TOON format.
+    # @param opts [Hash] encoder options.
+    # @return [String] TOON payload.
+    def to_toon(**opts)
+      Toon::Extensions::Core.array_to_toon(self, **opts)
+    end
+  end
+
+  unless method_defined?(:to_json)
+    # Serialize the array into JSON via the core extension helper.
+    # @param args [Array] JSON serialization options.
+    # @return [String] JSON payload.
+    def to_json(*args)
+      Toon::Extensions::Core.to_json_payload(self, *args)
+    end
+  end
+end

data/lib/toon/decoder.rb

@@ -2,181 +2,199 @@ module Toon
   module Decoder
     module_function
 
-    def parse(str, **opts)
-      lines = str.gsub("\r\n", "\n").split("\n")
-      parse_lines(lines)
-    end
-
-    def load(io, **opts)
-      parse(io.read, **opts)
-    end
+      # Parse a TOON string and produce the corresponding Ruby structure.
+      # @param str [String] TOON payload.
+      # @param opts [Hash] reserved for future parser options.
+      # @return [Object] reconstructed Ruby data.
+      def parse(str, **opts)
+        lines = str.gsub("\r\n", "\n").split("\n")
+        parse_lines(lines)
+      end
 
-    def parse_lines(lines)
-      root = {}
-      stack = [ { indent: -1, obj: root, parent: nil, key: nil } ]
+      # Read all data from an IO-like object and parse it as TOON.
+      # @param io [#read] source stream.
+      # @param opts [Hash] reserved for future parser options.
+      # @return [Object] reconstructed Ruby data.
+      def load(io, **opts)
+        parse(io.read, **opts)
+      end
 
-      i = 0
-      while i < lines.length
-        raw = lines[i].rstrip
-        i += 1
+      # Core parser that works on an array of sanitized TOON lines.
+      # @param lines [Array<String>] TOON lines without newlines.
+      # @return [Hash] root object constructed from the input.
+      def parse_lines(lines)
+        root = {}
+        stack = [ { indent: -1, obj: root, parent: nil, key: nil } ]
 
-        next if raw.strip.empty? || raw.strip.start_with?('#')
+        i = 0
+        while i < lines.length
+          raw = lines[i].rstrip
+          i += 1
 
-        indent = leading_spaces(raw)
-        content = raw.strip
+          next if raw.strip.empty? || raw.strip.start_with?('#')
 
-        # Fix indentation
-        while indent <= stack.last[:indent]
-          stack.pop
-        end
+          indent = leading_spaces(raw)
+          content = raw.strip
 
-        current = stack.last
-        parent_obj = current[:obj]
-
-        # ============================================================
-        # FLAT TABULAR ARRAY: users[2]{id,name}:
-        # ============================================================
-        if m = content.match(/^(\w+)\[(\d+)\]\{([^}]*)\}:$/)
-          key     = m[1]
-          count   = m[2].to_i
-          fields  = m[3].split(",").map(&:strip)
-
-          rows = []
-          count.times do
-            row = lines[i]&.strip
-            i += 1
-            next unless row
-            values = split_row(row.strip)
-            rows << Hash[fields.zip(values)]
+          # Fix indentation
+          while indent <= stack.last[:indent]
+            stack.pop
           end
 
-          parent_obj[key] = rows
-          next
-        end
-
-        # ============================================================
-        # FLAT PRIMITIVE ARRAY: colors[3]:
-        # ============================================================
-        if m = content.match(/^(\w+)\[(\d+)\]:$/)
-          key   = m[1]
-          count = m[2].to_i
-
-          values = []
-          count.times do
-            row = lines[i]&.strip
-            i += 1
-            next unless row
-            values << parse_scalar(row)
+          current = stack.last
+          parent_obj = current[:obj]
+
+          # ============================================================
+          # FLAT TABULAR ARRAY: users[2]{id,name}:
+          # ============================================================
+          if m = content.match(/^(\w+)\[(\d+)\]\{([^}]*)\}:$/)
+            key     = m[1]
+            count   = m[2].to_i
+            fields  = m[3].split(",").map(&:strip)
+
+            rows = []
+            count.times do
+              row = lines[i]&.strip
+              i += 1
+              next unless row
+              values = split_row(row.strip)
+              rows << Hash[fields.zip(values)]
+            end
+
+            parent_obj[key] = rows
+            next
           end
 
-          parent_obj[key] = values
-          next
-        end
-
-        # ============================================================
-        # NESTED OBJECT KEY: key:
-        # ============================================================
-        if m = content.match(/^(\w+):$/)
-          key = m[1]
-          new_obj = {}
-
-          parent_obj[key] = new_obj
-          stack << { indent: indent, obj: new_obj, parent: parent_obj, key: key }
-          next
-        end
-
-        # Refresh frame for nested array parsing
-        frame = stack.last
-        parent = frame[:parent]
-        key    = frame[:key]
-
-        # ============================================================
-        # NESTED TABULAR ARRAY:
-        #   users:
-        #     [2]{id,name}:
-        # ============================================================
-        if m = content.match(/^\[(\d+)\]\{([^}]*)\}:$/)
-          count   = m[1].to_i
-          fields  = m[2].split(',').map(&:strip)
-
-          rows = []
-          count.times do
-            row = lines[i]&.strip
-            i += 1
-            next unless row
-            values = split_row(row).map { |v| parse_scalar(v) }
-            rows << Hash[fields.zip(values)]
+          # ============================================================
+          # FLAT PRIMITIVE ARRAY: colors[3]:
+          # ============================================================
+          if m = content.match(/^(\w+)\[(\d+)\]:$/)
+            key   = m[1]
+            count = m[2].to_i
+
+            values = []
+            count.times do
+              row = lines[i]&.strip
+              i += 1
+              next unless row
+              values << parse_scalar(row)
+            end
+
+            parent_obj[key] = values
+            next
           end
 
-          parent[key] = rows
-          stack.pop
-          next
-        end
+          # ============================================================
+          # NESTED OBJECT KEY: key:
+          # ============================================================
+          if m = content.match(/^(\w+):$/)
+            key = m[1]
+            new_obj = {}
 
-        # ============================================================
-        # NESTED PRIMITIVE ARRAY:
-        #   colors:
-        #     [3]:
-        # ============================================================
-        if m = content.match(/^\[(\d+)\]:$/)
-          count = m[1].to_i
+            parent_obj[key] = new_obj
+            stack << { indent: indent, obj: new_obj, parent: parent_obj, key: key }
+            next
+          end
 
-          if key.nil?
-            raise Toon::Error, "Malformed TOON: array header '#{content}' must be under a key (e.g., 'colors:')"
+          # Refresh frame for nested array parsing
+          frame = stack.last
+          parent = frame[:parent]
+          key    = frame[:key]
+
+          # ============================================================
+          # NESTED TABULAR ARRAY:
+          #   users:
+          #     [2]{id,name}:
+          # ============================================================
+          if m = content.match(/^\[(\d+)\]\{([^}]*)\}:$/)
+            count   = m[1].to_i
+            fields  = m[2].split(',').map(&:strip)
+
+            rows = []
+            count.times do
+              row = lines[i]&.strip
+              i += 1
+              next unless row
+              values = split_row(row).map { |v| parse_scalar(v) }
+              rows << Hash[fields.zip(values)]
+            end
+
+            parent[key] = rows
+            stack.pop
+            next
           end
 
-          values = []
-          count.times do
-            row = lines[i]&.strip
-            i += 1
-            next unless row
-            values << parse_scalar(row)
+          # ============================================================
+          # NESTED PRIMITIVE ARRAY:
+          #   colors:
+          #     [3]:
+          # ============================================================
+          if m = content.match(/^\[(\d+)\]:$/)
+            count = m[1].to_i
+
+            if key.nil?
+              raise Toon::Error, "Malformed TOON: array header '#{content}' must be under a key (e.g., 'colors:')"
+            end
+
+            values = []
+            count.times do
+              row = lines[i]&.strip
+              i += 1
+              next unless row
+              values << parse_scalar(row)
+            end
+
+            parent[key] = values
+            stack.pop
+            next
           end
 
-          parent[key] = values
-          stack.pop
-          next
+          # ============================================================
+          # SIMPLE KEY: VALUE
+          # ============================================================
+          if m = content.match(/^(\w+):\s*(.*)$/)
+            k = m[1]
+            v = parse_scalar(m[2])
+            parent_obj[k] = v
+            next
+          end
         end
 
-        # ============================================================
-        # SIMPLE KEY: VALUE
-        # ============================================================
-        if m = content.match(/^(\w+):\s*(.*)$/)
-          k = m[1]
-          v = parse_scalar(m[2])
-          parent_obj[k] = v
-          next
-        end
+        root
       end
 
-      root
-    end
-
-
-
-    def leading_spaces(line)
-      line[/^ */].length
-    end
+      # Count the indentation depth (in spaces) at the beginning of +line+.
+      # @param line [String] line from the TOON payload.
+      # @return [Integer] number of leading spaces.
+      def leading_spaces(line)
+        line[/^ */].length
+      end
 
-    def parse_scalar(str)
-      # strip quotes
-      if str == 'null' then nil
-      elsif str == 'true' then true
-      elsif str == 'false' then false
-      elsif str.match?(/^".*"$/)
-        str[1..-2].gsub('\\"','"')
-      elsif str =~ /^-?\d+$/
-        str.to_i
-      elsif str =~ /^-?\d+\.\d+$/
-        str.to_f
-      else
-        str
+      # Convert a scalar token into the appropriate Ruby object.
+      # @param str [String] textual token.
+      # @return [Object] decoded scalar (String, Numeric, true/false, nil).
+      def parse_scalar(str)
+        # strip quotes
+        if str == 'null' then nil
+        elsif str == 'true' then true
+        elsif str == 'false' then false
+        elsif str.match?(/^".*"$/)
+          str[1..-2].gsub('\\"','"')
+        elsif str =~ /^-?\d+$/
+          str.to_i
+        elsif str =~ /^-?\d+\.\d+$/
+          str.to_f
+        else
+          str
+        end
       end
-    end
 
-    def split_row(row)
-      # simplistic split on comma that ignores quoted commas - naive
-      row.scan(/(?:\"([^\"]*)\"|([^,]+))(?:,|$)/).map { |m| (m[0] || m[1]).to_s.strip }
-    end
+      # Split a comma-delimited row while preserving quoted delimiters.
+      # @param row [String] raw row contents.
+      # @return [Array<String>] tokenized column values.
+      def split_row(row)
+        # simplistic split on comma that ignores quoted commas - naive
+        row.scan(/(?:\"([^\"]*)\"|([^,]+))(?:,|$)/).map { |m| (m[0] || m[1]).to_s.strip }
+      end
   end
 end

data/lib/toon/encoder.rb

@@ -10,117 +10,161 @@ module Toon
       pretty: false
     }
 
-    def generate(obj, **opts)
-      options = DEFAULT_OPTIONS.merge(opts)
-      io = StringIO.new
-      write_object(io, obj, 0, options)
-      io.string
-    end
+      # Generate a TOON string for +obj+ with the desired encoder options.
+      # @param obj [Object] structure to serialize.
+      # @param opts [Hash] overrides for {DEFAULT_OPTIONS}.
+      # @return [String] TOON payload.
+      def generate(obj, **opts)
+        options = DEFAULT_OPTIONS.merge(opts)
+        io = StringIO.new
+        write_object(io, obj, 0, options)
+        io.string
+      end
 
-    def pretty_generate(obj, **opts)
-      generate(obj, **opts.merge(pretty: true))
-    end
+      # Generate a human-friendly TOON payload irrespective of caller options.
+      # @param obj [Object] structure to serialize.
+      # @param opts [Hash] encoder overrides.
+      # @return [String] prettified TOON payload.
+      def pretty_generate(obj, **opts)
+        generate(obj, **opts.merge(pretty: true))
+      end
 
-    def dump(obj, io = STDOUT, **opts)
-      str = generate(obj, **opts)
-      io.write(str)
-      nil
-    end
+      # Stream the serialized payload directly to an IO target.
+      # @param obj [Object] data to encode.
+      # @param io [#write] destination stream (defaults to STDOUT).
+      # @param opts [Hash] encoder overrides.
+      # @return [nil]
+      def dump(obj, io = STDOUT, **opts)
+        str = generate(obj, **opts)
+        io.write(str)
+        nil
+      end
 
-    private
+      private
 
-    def write_object(io, obj, level, options)
-      case obj
-      when Hash
-        obj.each do |k, v|
-          write_key(io, k, level)
-          if simple_value?(v)
-            io.write(format_simple(v))
-            io.write("\n")
+      # Dispatch encoding logic for hashes, arrays, or scalar values.
+      # @param io [#write] accumulating stream.
+      # @param obj [Object] value to encode.
+      # @param level [Integer] depth in the output tree.
+      # @param options [Hash] encoder configuration.
+      def write_object(io, obj, level, options)
+        case obj
+        when Hash
+          obj.each do |k, v|
+            write_key(io, k, level)
+            if simple_value?(v)
+              io.write(format_simple(v))
+              io.write("\n")
+            else
+              io.write("\n")
+              write_object(io, v, level + 1, options)
+            end
+          end
+        when Array
+          # Try to detect uniform objects for tabular style
+          if options[:compact_arrays] && array_uniform_hashes?(obj)
+            write_tabular(io, obj, level, options)
           else
-            io.write("\n")
-            write_object(io, v, level + 1, options)
+            write_list(io, obj, level, options)
           end
-        end
-      when Array
-        # Try to detect uniform objects for tabular style
-        if options[:compact_arrays] && array_uniform_hashes?(obj)
-          write_tabular(io, obj, level, options)
         else
-          write_list(io, obj, level, options)
+          # scalar
+          io.write(indent(level))
+          io.write(format_simple(obj))
+          io.write("\n")
         end
-      else
-        # scalar
-        io.write(indent(level))
-        io.write(format_simple(obj))
-        io.write("\n")
       end
-    end
-
-    def write_key(io, key, level)
-      io.write(indent(level))
-      io.write("#{key}:")
-    end
 
-    def write_tabular(io, arr, level, options)
-      keys = (arr.map(&:keys).reduce(:|) || []).uniq
-      io.write(indent(level))
-      io.write("[#{arr.length}]{#{keys.join(',')}}:\n")
-      arr.each do |row|
-        io.write(indent(level + 1))
-        vals = keys.map { |k| format_simple(row[k]) }
-        io.write(vals.join(options[:delimiter]))
-        io.write("\n")
+      # Emit a hash key label aligned to the requested indentation depth.
+      # @param io [#write] accumulating stream.
+      # @param key [String, Symbol] key to render.
+      # @param level [Integer] indentation level.
+      def write_key(io, key, level)
+        io.write(indent(level))
+        io.write("#{key}:")
       end
-    end
 
-    def write_list(io, arr, level, options)
-      io.write(indent(level))
-      io.write("[#{arr.length}]:\n")
-      arr.each do |el|
-        io.write(indent(level + 1))
-        if simple_value?(el)
-          io.write(format_simple(el))
+      # Render an array of hashes using the compact tabular notation.
+      # @param io [#write] accumulating stream.
+      # @param arr [Array<Hash>] rows to encode.
+      # @param level [Integer] indentation level.
+      # @param options [Hash] encoder configuration.
+      def write_tabular(io, arr, level, options)
+        keys = (arr.map(&:keys).reduce(:|) || []).uniq
+        io.write(indent(level))
+        io.write("[#{arr.length}]{#{keys.join(',')}}:\n")
+        arr.each do |row|
+          io.write(indent(level + 1))
+          vals = keys.map { |k| format_simple(row[k]) }
+          io.write(vals.join(options[:delimiter]))
           io.write("\n")
-        else
-          # nested object or array
-          write_object(io, el, level + 1, options)
         end
       end
-    end
 
-    def indent(level)
-      ' ' * (level * 2)
-    end
+      # Render a heterogeneous array in the multi-line list form.
+      # @param io [#write] accumulating stream.
+      # @param arr [Array] values to encode.
+      # @param level [Integer] indentation level.
+      # @param options [Hash] encoder configuration.
+      def write_list(io, arr, level, options)
+        io.write(indent(level))
+        io.write("[#{arr.length}]:\n")
+        arr.each do |el|
+          io.write(indent(level + 1))
+          if simple_value?(el)
+            io.write(format_simple(el))
+            io.write("\n")
+          else
+            # nested object or array
+            write_object(io, el, level + 1, options)
+          end
+        end
+      end
 
-    def simple_value?(v)
-      v.nil? || v.is_a?(Numeric) || v.is_a?(String) || v == true || v == false
-    end
+      # Produce indentation padding for the supplied level.
+      # @param level [Integer] nesting depth.
+      # @return [String] spaces for indent.
+      def indent(level)
+        ' ' * (level * 2)
+      end
+
+      # Identify whether +v+ is a scalar that can be inlined.
+      # @param v [Object] value to test.
+      # @return [Boolean] true if +v+ is nil, numeric, boolean, or string.
+      def simple_value?(v)
+        v.nil? || v.is_a?(Numeric) || v.is_a?(String) || v == true || v == false
+      end
 
-    def format_simple(v)
-      case v
-      when String
-        # naive quoting: quote when contains delimiter or colon or newline
-        if v.empty? || v.match(/[,:\n{}\[\]]/)
-          '"' + v.gsub('"', '\\"') + '"'
+      # Convert a scalar value into its TOON string representation.
+      # @param v [Object] scalar value.
+      # @return [String] formatted representation.
+      def format_simple(v)
+        case v
+        when String
+          # naive quoting: quote when contains delimiter or colon or newline
+          if v.empty? || v.match(/[,:\n{}\[\]]/)
+            '"' + v.gsub('"', '\\"') + '"'
+          else
+            v
+          end
+        when nil
+          'null'
+        when true
+          'true'
+        when false
+          'false'
         else
-          v
+          v.to_s
         end
-      when nil
-        'null'
-      when true
-        'true'
-      when false
-        'false'
-      else
-        v.to_s
       end
-    end
 
-    def array_uniform_hashes?(arr)
-      return false if arr.empty?
-      arr.all? { |e| e.is_a?(Hash) } && (arr.map { |h| h.keys.sort } .uniq.length == 1)
-    end
+      # Check whether +arr+ contains only hashes sharing the same keys.
+      # @param arr [Array] array to test.
+      # @return [Boolean] true when the compact tabular format applies.
+      def array_uniform_hashes?(arr)
+        return false if arr.empty?
+        arr.all? { |e| e.is_a?(Hash) } && (arr.map { |h| h.keys.sort }.uniq.length == 1)
+      end
 
     module_function :write_object, :write_key, :write_tabular, :write_list,
                 :indent, :simple_value?, :format_simple, :array_uniform_hashes?

data/lib/toon/version.rb

@@ -1,3 +1,3 @@
 module Toon
-  VERSION = '0.1.0'
+  VERSION = '1.0.2'
 end

data/lib/toon.rb

@@ -1,27 +1,49 @@
 require_relative "toon/version"
 require_relative "toon/encoder"
 require_relative "toon/decoder"
+require_relative "extensions/core"
 require_relative "extensions/active_support"
 
 module Toon
   class Error < StandardError; end
 
+  # Generate a TOON-formatted String from any serializable Ruby object.
+  # @param obj [Object] the object to encode.
+  # @param opts [Hash] encoder options forwarded to `Toon::Encoder`.
+  # @return [String] the TOON payload.
   def self.generate(obj, **opts)
     Toon::Encoder.generate(obj, **opts)
   end
 
+  # Generate a human-friendly TOON String with extra spacing and indentation.
+  # @param obj [Object] the object to encode.
+  # @param opts [Hash] encoder options forwarded to `Toon::Encoder`.
+  # @return [String] the prettified TOON payload.
   def self.pretty_generate(obj, **opts)
     Toon::Encoder.pretty_generate(obj, **opts)
   end
 
+  # Parse a TOON String and reconstruct the Ruby data structure.
+  # @param str [String] the TOON representation.
+  # @param opts [Hash] decoder options forwarded to `Toon::Decoder`.
+  # @return [Object] the decoded Ruby structure.
   def self.parse(str, **opts)
     Toon::Decoder.parse(str, **opts)
   end
 
+  # Read a TOON payload from any IO-like object and parse it.
+  # @param io [#read] an IO that responds to `#read`.
+  # @param opts [Hash] decoder options forwarded to `Toon::Decoder`.
+  # @return [Object] the decoded Ruby structure.
   def self.load(io, **opts)
     Toon::Decoder.load(io, **opts)
   end
 
+  # Stream a TOON payload for +obj+ into the provided IO target.
+  # @param obj [Object] the object to encode.
+  # @param io [#write] where the payload should be written.
+  # @param opts [Hash] encoder options forwarded to `Toon::Encoder`.
+  # @return [nil]
   def self.dump(obj, io = STDOUT, **opts)
     Toon::Encoder.dump(obj, io, **opts)
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby-toon
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.2
 platform: ruby
 authors:
 - Anil Yanduri
@@ -49,6 +49,7 @@ files:
 - LICENSE
 - README.md
 - lib/extensions/active_support.rb
+- lib/extensions/core.rb
 - lib/toon.rb
 - lib/toon/decoder.rb
 - lib/toon/encoder.rb