ruby-toon 1.0.1 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e32d5758d404c58449d7d8100a0d40d445c0595997620832c48f45dfd36bff9c
-  data.tar.gz: cc942b447807a72d595e66bf76479c525545ac6ad8b2c3dd2686d04669075f89
+  metadata.gz: d6ebe1e066311203869e7a9c6f0d6d54e7016eddf9d8b50a47d85198ee84c458
+  data.tar.gz: bc1e3ab72636edc57c512c327c3802a14505ce968b197882dfd6e8093bca9069
 SHA512:
-  metadata.gz: ca22d215cf9b70115a6e9da0d5ba29dbd1788c8d19d5c7ddbb579521bb8826604c1f3a53ad3322ea298101126cf826b31eec65265d0d55b5b4d9cc883c4ef3e4
-  data.tar.gz: bffb33b3605dccf8a0cb011ed7c3cf1c1c27bf0a41ef8d52f2d1d09e03ea038949b35fd8fab9848c857fc6335ec97573462df8619836d7e6bf8fe78869f186de
+  metadata.gz: 8dc9df86a1128eb5263feb7f382398671df45d0751175ba2c1b45804fb6bb9a456e04f15de59ffa7bd5536b6dd64f429a2e74aa8f554ca42f965a451bdfd68d6
+  data.tar.gz: f4b9f5594635a708a9ef96a93aeba12cd395cb276e56d77a08aadcd5f0cbef7b4eee16d5db09133b052703881349c70831d0b257826f1d26bb723d9270a8c715

data/README.md

@@ -1,4 +1,6 @@
 # **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)**
 a compact, readable, indentation-based data format designed for humans *and* machines.

data/lib/extensions/active_support.rb

@@ -2,6 +2,9 @@ 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)
@@ -10,16 +13,22 @@ module Toon
 
       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|

data/lib/extensions/core.rb

@@ -5,14 +5,26 @@ module Toon
     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
@@ -22,12 +34,18 @@ 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
@@ -36,12 +54,18 @@ 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

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 = '1.0.1'
+  VERSION = '1.0.2'
 end

data/lib/toon.rb

@@ -7,22 +7,43 @@ 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.1
+  version: 1.0.2
 platform: ruby
 authors:
 - Anil Yanduri