toon-fu 0.0.1 → 4.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 209aece0889367dd31ee2cf3bd80fb03094022b6be61967c6b9f400c5b02d014
-  data.tar.gz: 33ce4ad50d1bc81088e25fa426c6b2cbd73e086593bd8b822240d6161f20b61b
+  metadata.gz: ea42b008c3b7cb955d4121725dc71cb9d0682383adb6f082fd59db8ed5d71da8
+  data.tar.gz: 8fd5631c7400ccd2eddfa648b2b4136a74e26fcf9b89927e5d143a0782205d0a
 SHA512:
-  metadata.gz: 12340212191070a117e650bec7d7861fdd05b57c4725816264474e30a4fa3c9244c70bc8ff2cc6c754f50ba5f948fef05f6b5841cb889bd367faa43432288bb6
-  data.tar.gz: 0c6e732a2adfdf17c7ca269dcfbcb3a83adcc4ea68b878244c565f5c1f0d4040746fe2098a36645e7baf0f47cbbcf1366bce6cd28add46de1abac15ba8ac1693
+  metadata.gz: 4a5c4ce7f285972990ca07320cea5484de95f560be64b714f847c9b703f015700f9369f2fdfaa5599216b59e5216f991b722cc7c3cd3faf694f8160d1ff9261a
+  data.tar.gz: afceb6dbe076e69b78b8c58a2d52d0baed6279eef642efc7d6023d0290c7b795b6c84b64f3c7200acbdb9057af21804a341a4e616275bb66cee13db0035ab14b

data/README.md

@@ -1,19 +1,178 @@
 # toon-fu
 
-[TOON](https://github.com/toon-format/spec) (Token-Oriented Object Notation) for Ruby.
+[![CI](https://github.com/hoblin/toon-fu/actions/workflows/ci.yml/badge.svg)](https://github.com/hoblin/toon-fu/actions/workflows/ci.yml)
+[![Spec drift](https://github.com/hoblin/toon-fu/actions/workflows/spec-drift.yml/badge.svg)](https://github.com/hoblin/toon-fu/actions/workflows/spec-drift.yml)
+[![Gem](https://img.shields.io/gem/v/toon-fu)](https://rubygems.org/gems/toon-fu)
 
-Written from the specification, with the reference test fixtures as the conformance suite.
+[TOON](https://toonformat.dev/) (Token-Oriented Object Notation) encoder for Ruby, versioned by the spec it implements: the gem's `MAJOR.MINOR` is the TOON spec version it speaks.
+
+## What is this?
+
+TOON is a compact, readable encoding of the JSON data model for LLM prompts: indentation instead of braces, quotes only where needed, and tables for arrays of uniform objects. toon-fu is written from the [specification](https://github.com/toon-format/spec) and runs the spec's reference fixtures as its conformance suite — every encode fixture of the spec version it implements passes.
+
+## Why?
+
+Every Ruby TOON gem on RubyGems was published in late 2025 and stopped at spec 1.2, three major versions behind. They leave strings starting with `#` or `+` unquoted, which a current reader takes for a comment or a number, and shift dates by a day east of Greenwich. toon-fu tracks the spec: its version is the spec version, and a daily check flags a newer spec.
+
+Yes, we know:
+
+[![xkcd 927: Standards](https://imgs.xkcd.com/comics/standards.png)](https://xkcd.com/927/)
+
+<sub>[xkcd #927 "Standards"](https://xkcd.com/927/) by Randall Munroe, [CC BY-NC 2.5](https://creativecommons.org/licenses/by-nc/2.5/).</sub>
+
+## Getting started
+
+Add it to your Gemfile:
+
+```ruby
+gem "toon-fu"
+```
+
+In a plain script: `gem install toon-fu` and `require "toon_fu"`. To pin the spec version, see [Versioning](#versioning).
+
+```ruby
+ToonFu.encode({users: [{id: 1, name: "Ada", role: "admin"}, {id: 2, name: "Bob", role: "user"}]})
+```
+
+```
+users[2]{id,name,role}:
+  1,Ada,admin
+  2,Bob,user
+```
+
+Arrays of uniform objects become tables that declare their fields once. Everything else reads like YAML:
+
+```ruby
+{order: {id: 7, tags: ["new", "paid"], customer: {name: "Ada"}}}.to_toon
+```
+
+```
+order:
+  id: 7
+  tags[2]: new,paid
+  customer:
+    name: Ada
+```
+
+`to_toon` is available on Hash, Array, String, Symbol, Integer, Float, `true`, `false`, `nil`, Set, Time and Date once `toon_fu` is loaded.
+
+### Options
+
+- `delimiter:` — `","` (default), `"\t"` or `"|"`. Tab usually costs the fewest tokens.
+- `indent_size:` — spaces per nesting level, default `2`.
+
+```ruby
+ToonFu.encode(data, delimiter: "\t")
+encoder = ToonFu::Encoder.new(delimiter: "|") # reuse for many documents
+encoder.encode(data)
+```
+
+### Your own objects
+
+Define `as_toon` to return plain data; it wins over every built-in mapping:
+
+```ruby
+Money = Struct.new(:cents, :currency) do
+  include ToonFu::Encodable # optional: adds #to_toon
+
+  def as_toon = {amount: cents / 100.0, currency:}
+end
+
+ToonFu.encode({price: Money.new(1999, "EUR")})
+# price:
+#   amount: 19.99
+#   currency: EUR
+```
+
+Any other value raises `ToonFu::Error`:
+
+```ruby
+ToonFu.encode({at: Object.new})
+# ToonFu::Error: cannot encode Object; convert it first or define #as_toon
+```
+
+For ActiveRecord models, pass `record.as_json` (or define `as_toon`).
+
+## What it accepts
+
+| Ruby value | TOON |
+|---|---|
+| `Hash` with String, Symbol or Integer keys | object; keys become strings, keys that collide raise |
+| `Array`, `Set` | array: inline, table, or list form |
+| `String` | string, quoted only when needed; other encodings are transcoded to UTF-8, invalid UTF-8 raises |
+| `Symbol` | its name |
+| `Integer` | its exact digits, any size |
+| `Float`, `BigDecimal` | canonical number; NaN and infinities become `null` |
+| `true`, `false`, `nil` | `true`, `false`, `null` |
+| `Date` | `2026-05-31` |
+| `Time`, `DateTime` | ISO 8601 with its offset: `2026-05-31T10:00:05.25Z` |
+| objects with `to_hash`, `to_ary`, `to_str` | the value they convert to |
+| objects with `as_toon` | whatever `as_toon` returns, encoded in turn |
+
+Everything else raises `ToonFu::Error` — including a `Struct` or `Data` without `as_toon`, circular references, and nesting too deep for the stack.
+
+## Compared with other Ruby TOON gems
+
+The only one that passes every spec fixture: toon-fu passes all 179 encode fixtures; the table compares the 154 that use default options, which every gem can run.
+
+| Gem | Spec fixtures passed | Speed vs toon-fu |
+|---|---:|---:|
+| **toon-fu** | **154 / 154** | **1.00×** |
+| sorbet-toon 0.1.0 | 119 / 154 | 0.59× |
+| toon-ruby 0.1.1 | 117 / 154 | 0.62× |
+| toon_my_json 0.1.0 | 57 / 154 | 1.68× |
+| toon-format 0.1.2 | 45 / 154 | 1.18× |
+
+The Ruby TOON encoders with more than 10,000 downloads, measured by [`benchmark/run.rb`](benchmark/run.rb) on Ruby 3.4.10 (2026-09-24). **Spec fixtures** are the spec's own encode fixtures that use default options. **Speed** is the geometric mean of encodes per second over five workloads — tables of 100 and 1000 rows, nested objects, a list of mixed objects, strings needing quotes — relative to toon-fu.
+
+What falls through the gaps:
+
+- **sorbet-toon, toon-ruby** — `#tag` and `+1` go out unquoted, so a current reader sees a comment and a number; arrays of objects with nested columns lose their table form; no keyed tables. Unknown objects slip through instead of raising: toon-ruby writes `null`, sorbet-toon `"#<Foo:0x…>"`. toon-ruby also moves a `Date` a day back east of Greenwich.
+- **toon_my_json, toon-format** — output a TOON reader cannot read: the table header on its own line, a `[2,]` length, rows at the wrong depth, nested objects in cells as broken text; toon_my_json also writes `false` as `null`. They do less work, and it shows in both columns.
+
+Rerun it:
+
+```bash
+BUNDLE_GEMFILE=benchmark/Gemfile bundle install
+BUNDLE_GEMFILE=benchmark/Gemfile bundle exec ruby benchmark/run.rb
+```
+
+To see where toon-fu itself spends time and allocates, profile one workload (CPU by stackprof, allocation sites by memory_profiler):
+
+```bash
+BUNDLE_GEMFILE=benchmark/Gemfile bundle exec ruby benchmark/profile.rb "table, 1000 rows"
+```
 
 ## Versioning
 
 The gem version tracks the TOON specification it implements:
 
-- `MAJOR.MINOR` is the spec version. `4.1.x` speaks TOON 4.1.
-- `PATCH` is the gem's own: fixes and improvements that do not change the dialect.
+- `MAJOR.MINOR` is the spec version: `X.Y.Z` speaks TOON `X.Y`.
+- `PATCH` is the gem's own: fixes and improvements within the same dialect.
+
+Pin the spec line with `gem "toon-fu", "~> X.Y.0"`: it takes our fixes and keeps you on the dialect you speak. The gem badge above shows the current release; the spec-drift badge turns red when a newer spec is released and toon-fu has not caught up yet.
+
+Release notes: [GitHub releases](https://github.com/hoblin/toon-fu/releases).
+
+## Development
+
+```bash
+git clone --recurse-submodules git@github.com:hoblin/toon-fu.git
+cd toon-fu
+bundle install
+bundle exec rspec        # unit specs + the spec's conformance fixtures
+bundle exec standardrb   # lint
+```
+
+The TOON spec is a git submodule at `spec/toon-spec`, pinned to its release tag; the fixtures run from there.
+
+## Releasing
 
-Pin to the spec line you need: `gem "toon-fu", "~> 4.1.0"`.
+1. Bump `lib/toon_fu/version.rb` in a pull request and merge it.
+2. `git tag vX.Y.Z && git push origin vX.Y.Z` on `main`.
+3. Approve the `release` deployment in Actions.
 
-`0.0.1` is a placeholder that claims the name. The first real release will be `4.1.0`.
+The [release workflow](.github/workflows/release.yml) checks the tag matches the version, runs CI, and publishes to RubyGems via [trusted publishing](https://guides.rubygems.org/trusted-publishing/).
 
 ## License
 

data/lib/toon-fu.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "toon_fu"

data/lib/toon_fu/decimal_literal.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module ToonFu
+  class DecimalLiteral
+    def initialize(value)
+      @value = value
+    end
+
+    def to_s
+      return "null" unless @value.finite?
+      return "0" if @value.zero?
+      return @value.to_s("F").delete_suffix(".0") if FloatLiteral::DECIMAL_RANGE.cover?(@value.abs)
+
+      sign, digits, _base, exponent = @value.split
+      mantissa = (digits.size > 1) ? "#{digits[0]}.#{digits[1..]}" : digits
+      "#{"-" if sign.negative?}#{mantissa}e#{format("%+d", exponent - 1)}"
+    end
+  end
+end

data/lib/toon_fu/encodable.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module ToonFu
+  # Adds +to_toon+ to the core and standard-library classes TOON encodes.
+  # +BigDecimal+ is left out: it is a bundled gem the encoder accepts but
+  # does not load. Include this module into a class that defines +as_toon+
+  # to give that class +to_toon+ as well.
+  module Encodable
+    # @param options [Hash] see {Encoder#initialize}
+    # @return [String] the receiver encoded as TOON, as {ToonFu.encode} would
+    # @raise [Error] see {Encoder#encode}
+    def to_toon(**options)
+      ToonFu.encode(self, **options)
+    end
+  end
+
+  [Hash, Array, Set, String, Symbol, Integer, Float, TrueClass, FalseClass, NilClass, Time, Date].each do |klass|
+    klass.include(Encodable)
+  end
+end

data/lib/toon_fu/encoder.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module ToonFu
+  # Encodes values with one set of options, for callers that encode many.
+  class Encoder
+    DELIMITERS = [",", "\t", "|"].freeze
+
+    # @param delimiter [String] the document delimiter, one of {DELIMITERS};
+    #   strings containing it are quoted
+    # @param indent_size [Integer] spaces per nesting level
+    # @raise [ArgumentError] when the delimiter is not one of {DELIMITERS}
+    #   or indent_size is not a positive Integer
+    def initialize(delimiter: ",", indent_size: 2)
+      raise ArgumentError, "delimiter must be one of #{DELIMITERS.inspect}, got #{delimiter.inspect}" unless DELIMITERS.include?(delimiter)
+      raise ArgumentError, "indent_size must be a positive Integer, got #{indent_size.inspect}" unless indent_size.is_a?(Integer) && indent_size.positive?
+
+      @delimiter = delimiter
+      @indent = " " * indent_size
+    end
+
+    # Encodes a value as TOON.
+    #
+    # Accepts the JSON data model plus these Ruby types, nested in any
+    # combination:
+    #
+    # - +Hash+ with String, Symbol or Integer keys, which become strings;
+    #   +Array+; +Set+ as an array
+    # - +String+ in UTF-8, in an encoding that transcodes to it, or binary
+    #   bytes that are valid UTF-8; +Symbol+ as its name
+    # - +Integer+ of any size as its exact digits; +Float+ and +BigDecimal+,
+    #   with NaN and infinities as +null+, +BigDecimal+ as its exact digits;
+    #   +true+, +false+, +nil+
+    # - +Date+ as an ISO 8601 date; +Time+ and +DateTime+ as ISO 8601
+    #   timestamps keeping their offset, fraction digits up to the last
+    #   non-zero one
+    # - objects that declare themselves a Hash, Array or String through
+    #   Ruby's implicit conversions: +to_hash+, +to_ary+, +to_str+
+    # - any object responding to +as_toon+: its result is encoded instead,
+    #   ahead of the mappings above
+    #
+    # @param value [Object] one of the types above
+    # @return [String] UTF-8
+    # @raise [Error] for any other value type; for keys other than String,
+    #   Symbol or Integer, and keys that collide once converted to strings;
+    #   for strings that are not valid UTF-8; for circular references,
+    #   including an +as_toon+ or implicit conversion that leads back to its
+    #   own object, and for nesting too deep for the stack
+    def encode(value)
+      Writer.new(@delimiter, @indent).write(Normalizer.new.call(value))
+    rescue SystemStackError
+      raise Error, "cannot encode a circular reference or nesting too deep"
+    end
+  end
+end

data/lib/toon_fu/fields.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module ToonFu
+  class Fields
+    attr_reader :columns
+
+    def self.of(rows)
+      return if rows.empty? || !rows.all?(Hash)
+
+      keys = rows.first.keys
+      return if keys.empty?
+      return unless rows.all? { |row| row.size == keys.size && keys.all? { |key| row.key?(key) } }
+
+      columns = keys.to_h do |key|
+        values = rows.map { |row| row[key] }
+        next [key, nil] if values.none? { |value| value.is_a?(Hash) || value.is_a?(Array) }
+
+        nested = of(values)
+        return nil unless nested
+
+        [key, nested]
+      end
+      new(columns)
+    end
+
+    attr_reader :paths
+
+    def initialize(columns)
+      @columns = columns
+      @paths = columns.flat_map { |key, nested| nested ? nested.paths.map { |path| [key, *path] } : [[key]] }
+    end
+
+    def cells(row)
+      @paths.map { |path| path.reduce(row) { |node, key| node[key] } }
+    end
+  end
+end

data/lib/toon_fu/float_literal.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module ToonFu
+  class FloatLiteral
+    DECIMAL_RANGE = (1e-6...1e21)
+
+    def self.format(value)
+      plain = value.to_s
+      return new(value).to_s if plain.include?("e") || !value.finite?
+
+      return "0" if value.zero?
+
+      plain.end_with?(".0") ? plain.delete_suffix(".0") : plain
+    end
+
+    def initialize(value)
+      @value = value
+    end
+
+    def to_s
+      return "null" unless @value.finite?
+      return "0" if @value.zero?
+
+      DECIMAL_RANGE.cover?(@value.abs) ? decimal : exponential
+    end
+
+    private
+
+    def decimal
+      plain = @value.to_s
+      return plain.delete_suffix(".0") unless plain.include?("e")
+
+      digits, point = significand
+      text =
+        if point <= 0
+          "0.#{"0" * -point}#{digits}"
+        elsif point >= digits.length
+          digits.ljust(point, "0")
+        else
+          "#{digits[0, point]}.#{digits[point..]}"
+        end
+      sign + text
+    end
+
+    def exponential
+      mantissa, exponent = @value.abs.to_s.split("e")
+      "#{sign}#{mantissa.delete_suffix(".0")}e#{format("%+d", exponent.to_i)}"
+    end
+
+    def significand
+      mantissa, exponent = @value.abs.to_s.split("e")
+      whole, fraction = mantissa.split(".")
+      fraction = "" if fraction == "0"
+      [whole + fraction, whole.length + exponent.to_i]
+    end
+
+    def sign
+      @value.negative? ? "-" : ""
+    end
+  end
+end

data/lib/toon_fu/normalizer.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module ToonFu
+  class Normalizer
+    TRAILING_FRACTION_ZEROS = /\.?0+\z/
+
+    def call(value)
+      raise Error, "cannot encode a BasicObject" unless Kernel === value
+      return core(value) unless value.respond_to?(:as_toon)
+
+      call(value.as_toon)
+    end
+
+    private
+
+    def core(value)
+      case value
+      when nil, true, false, Integer, Float then value
+      when String then utf8(value)
+      when Symbol then utf8(value.name)
+      when Hash then object(value)
+      when Array then array(value)
+      when Set then value.map { |element| call(element) }
+      when Time then timestamp(value)
+      when DateTime then date_time(value)
+      when Date then value.iso8601
+      else convert(value)
+      end
+    end
+
+    def convert(value)
+      if defined?(BigDecimal) && value.is_a?(BigDecimal) then DecimalLiteral.new(value)
+      elsif value.respond_to?(:to_hash) then call(value.to_hash)
+      elsif value.respond_to?(:to_ary) then call(value.to_ary)
+      elsif value.respond_to?(:to_str) then call(value.to_str)
+      else raise Error, "cannot encode #{value.class}; convert it first or define #as_toon"
+      end
+    end
+
+    def array(values)
+      return values.map { |element| call(element) } unless values.instance_of?(Array)
+
+      copy = nil
+      index = 0
+      while index < values.size
+        element = values[index]
+        normal = call(element)
+        unless copy.nil? && normal.equal?(element)
+          copy ||= values.first(index)
+          copy << normal
+        end
+        index += 1
+      end
+      copy || values
+    end
+
+    def object(hash)
+      return rebuild(hash) unless plain?(hash)
+
+      copy = nil
+      hash.each do |key, value|
+        normal = call(value)
+        next if copy.nil? && normal.equal?(value)
+
+        copy ||= hash.take_while { |pair_key, _| !pair_key.equal?(key) }.to_h
+        copy[key] = normal
+      end
+      copy || hash
+    end
+
+    def plain?(hash)
+      hash.instance_of?(Hash) && !hash.compare_by_identity? &&
+        hash.all? { |key, _| key.instance_of?(String) && key.encoding == Encoding::UTF_8 && key.valid_encoding? }
+    end
+
+    def rebuild(hash)
+      hash.each_with_object({}) do |(key, value), result|
+        name = key_name(key)
+        raise Error, "duplicate key #{name.inspect} after converting keys to strings" if result.key?(name)
+
+        result[name] = call(value)
+      end
+    end
+
+    def key_name(key)
+      case key
+      when String then utf8(key)
+      when Symbol then utf8(key.name)
+      when Integer then key.to_s
+      else raise Error, "cannot encode #{key.class} keys; use String, Symbol or Integer keys"
+      end
+    end
+
+    def timestamp(time)
+      moment = time.strftime("%Y-%m-%dT%H:%M:%S.%9N").sub(TRAILING_FRACTION_ZEROS, "")
+      "#{moment}#{time.utc? ? "Z" : time.strftime("%:z")}"
+    end
+
+    def date_time(value)
+      moment, offset = value.iso8601(9).split(/(?=[+-]\d\d:\d\d\z)/)
+      "#{moment.sub(TRAILING_FRACTION_ZEROS, "")}#{offset}"
+    end
+
+    def utf8(string)
+      return string if string.encoding == Encoding::UTF_8 && string.valid_encoding?
+
+      string = string.dup.force_encoding(Encoding::UTF_8) if string.encoding == Encoding::BINARY
+      string = string.encode(Encoding::UTF_8) unless string.encoding == Encoding::UTF_8
+      raise Error, "cannot encode a string that is not valid UTF-8: #{string.inspect}" unless string.valid_encoding?
+
+      string
+    rescue EncodingError => error
+      raise Error, "cannot encode a string as UTF-8: #{error.message}"
+    end
+  end
+end

data/lib/toon_fu/string_literal.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module ToonFu
+  class StringLiteral
+    READS_AS_LITERAL = /\A(?:true|false|null|[+-]?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?)\z/
+    UNSAFE = Encoder::DELIMITERS.to_h do |delimiter|
+      [delimiter, /\A[ \t#-]|[ \t]\z|[:"\\\[\]{}\x00-\x1f#{Regexp.escape(delimiter) if delimiter.ord > 0x1f}]/]
+    end.freeze
+    BARE_KEY = /\A[A-Za-z_][A-Za-z0-9_.]*\z/
+    ESCAPABLE = /["\\\x00-\x1f]/
+    ESCAPES = (0x00..0x1f).to_h { |code| [code.chr, format("\\u%04x", code)] }
+      .merge("\\" => "\\\\", '"' => '\\"', "\n" => "\\n", "\r" => "\\r", "\t" => "\\t").freeze
+
+    def initialize(delimiter)
+      @unsafe = UNSAFE.fetch(delimiter)
+    end
+
+    def encode(string)
+      quote?(string) ? quote(string) : string
+    end
+
+    def key(string)
+      BARE_KEY.match?(string) ? string : quote(string)
+    end
+
+    private
+
+    def quote(string)
+      %("#{string.gsub(ESCAPABLE, ESCAPES)}")
+    end
+
+    def quote?(string)
+      string.empty? || READS_AS_LITERAL.match?(string) || @unsafe.match?(string)
+    end
+  end
+end

data/lib/toon_fu/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ToonFu
-  VERSION = "0.0.1"
+  VERSION = "4.1.1"
 end

data/lib/toon_fu/writer.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module ToonFu
+  class Writer
+    def initialize(delimiter, indent)
+      @delimiter = delimiter
+      @marker = (delimiter == ",") ? "" : delimiter
+      @strings = StringLiteral.new(delimiter)
+      @unit = indent
+      @indent = ""
+      @hyphen = nil
+      @lines = []
+    end
+
+    def write(value)
+      value(value)
+      @lines.join("\n").force_encoding(Encoding::UTF_8)
+    end
+
+    private
+
+    def value(value)
+      case value
+      when Hash then mapping("", value)
+      when Array then array("", value)
+      else line(scalar(value))
+      end
+    end
+
+    def object(hash)
+      hash.each do |key, value|
+        name = @strings.key(key)
+        case value
+        when Hash then mapping(name, value)
+        when Array then array(name, value)
+        else line("#{name}: #{scalar(value)}")
+        end
+      end
+    end
+
+    def mapping(name, hash)
+      if hash.size >= 2 && (fields = Fields.of(hash.values))
+        line("#{name}#{header(hash.size, fields, keyed: true)}")
+        nested { hash.each { |key, entry| line("#{@strings.key(key)}: #{row(fields.cells(entry))}") } }
+      elsif name.empty?
+        object(hash)
+      else
+        line("#{name}:")
+        nested { object(hash) }
+      end
+    end
+
+    def array(name, values)
+      listed = name.empty? && @hyphen
+      if values.empty? && !listed
+        line(name.empty? ? "[]" : "#{name}: []")
+      elsif !listed && (fields = Fields.of(values))
+        line("#{name}#{header(values.size, fields)}")
+        nested { values.each { |element| line(row(fields.cells(element))) } }
+      elsif values.none? { |value| value.is_a?(Hash) || value.is_a?(Array) }
+        line("#{name}#{inline(values)}")
+      else
+        line("#{name}#{header(values.size)}")
+        nested { values.each { |element| item(element) } }
+      end
+    end
+
+    def item(element)
+      @hyphen = @indent
+      case element
+      when Array then array("", element)
+      when Hash then nested { object(element) }
+      else line(scalar(element))
+      end
+      return unless @hyphen
+
+      @lines << "#{@hyphen}-"
+      @hyphen = nil
+    end
+
+    def inline(values)
+      return header(values.size) if values.empty?
+
+      "#{header(values.size)} #{row(values)}"
+    end
+
+    def row(values)
+      values.map { |value| scalar(value) }.join(@delimiter)
+    end
+
+    def header(count, fields = nil, keyed: false)
+      "[#{count}#{":" if keyed}#{@marker}]#{field_list(fields) if fields}:"
+    end
+
+    def field_list(fields)
+      names = fields.columns.map { |key, nested| "#{@strings.key(key)}#{field_list(nested) if nested}" }
+      "{#{names.join(@delimiter)}}"
+    end
+
+    def line(text)
+      if @hyphen
+        @lines << "#{@hyphen}- #{text}"
+        @hyphen = nil
+      else
+        @lines << "#{@indent}#{text}"
+      end
+    end
+
+    def nested
+      outer = @indent
+      @indent += @unit
+      yield
+    ensure
+      @indent = outer
+    end
+
+    def scalar(value)
+      case value
+      when nil then "null"
+      when true, false, Integer then value.to_s
+      when Float then FloatLiteral.format(value)
+      when DecimalLiteral then value.to_s
+      when String then @strings.encode(value)
+      else raise Error, "cannot encode #{value.class}"
+      end
+    end
+  end
+end

data/lib/toon_fu.rb

@@ -1,8 +1,48 @@
 # frozen_string_literal: true
 
+require "date"
+
 require_relative "toon_fu/version"
+require_relative "toon_fu/encoder"
+require_relative "toon_fu/float_literal"
+require_relative "toon_fu/decimal_literal"
+require_relative "toon_fu/string_literal"
+require_relative "toon_fu/normalizer"
+require_relative "toon_fu/fields"
+require_relative "toon_fu/writer"
+require_relative "toon_fu/encodable"
 
 # TOON (Token-Oriented Object Notation) for Ruby.
 module ToonFu
+  # Raised when a value has no TOON representation; see {Encoder#encode}.
   class Error < StandardError; end
+
+  private_constant :FloatLiteral, :DecimalLiteral, :StringLiteral, :Normalizer, :Fields, :Writer
+
+  # Encodes a value as TOON.
+  #
+  #   ToonFu.encode("hello")                # => "hello"
+  #   ToonFu.encode("a,b")                  # => "\"a,b\""
+  #   ToonFu.encode("a,b", delimiter: "|")  # => "a,b"
+  #   ToonFu.encode(1e-7)                   # => "1e-7"
+  #   ToonFu.encode({user: {id: 1}})        # => "user:\n  id: 1"
+  #   ToonFu.encode({tags: ["a", "b"]})     # => "tags[2]: a,b"
+  #   ToonFu.encode([{id: 1}, {id: 2}])     # => "[2]{id}:\n  1\n  2"
+  #   ToonFu.encode({a: {x: 1}, b: {x: 2}}) # => "[2:]{x}:\n  a: 1\n  b: 2"
+  #
+  # @param value [Object] see {Encoder#encode} for the accepted types; a Hash
+  #   needs braces, since bare +key: value+ pairs are Ruby keyword arguments
+  # @param options [Hash] see {Encoder#initialize}
+  # @return [String]
+  # @raise [Error] see {Encoder#encode}
+  # @raise [ArgumentError] when no value is given, as with a Hash written
+  #   without braces
+  def self.encode(value = (missing = true), **options)
+    raise ArgumentError, "ToonFu.encode takes the value as its first argument; wrap a Hash in braces: ToonFu.encode({key: value})" if missing
+
+    (options.empty? ? DEFAULT_ENCODER : Encoder.new(**options)).encode(value)
+  end
+
+  DEFAULT_ENCODER = Ractor.make_shareable(Encoder.new)
+  private_constant :DEFAULT_ENCODER
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: toon-fu
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 4.1.1
 platform: ruby
 authors:
 - Yevhenii Hurin
@@ -18,17 +18,27 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- CHANGELOG.md
 - LICENSE
 - README.md
+- lib/toon-fu.rb
 - lib/toon_fu.rb
+- lib/toon_fu/decimal_literal.rb
+- lib/toon_fu/encodable.rb
+- lib/toon_fu/encoder.rb
+- lib/toon_fu/fields.rb
+- lib/toon_fu/float_literal.rb
+- lib/toon_fu/normalizer.rb
+- lib/toon_fu/string_literal.rb
 - lib/toon_fu/version.rb
+- lib/toon_fu/writer.rb
 homepage: https://github.com/hoblin/toon-fu
 licenses:
 - MIT
 metadata:
   source_code_uri: https://github.com/hoblin/toon-fu
-  changelog_uri: https://github.com/hoblin/toon-fu/blob/main/CHANGELOG.md
+  changelog_uri: https://github.com/hoblin/toon-fu/releases
+  documentation_uri: https://rubydoc.info/gems/toon-fu
+  bug_tracker_uri: https://github.com/hoblin/toon-fu/issues
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:

data/CHANGELOG.md

@@ -1,5 +0,0 @@
-# Changelog
-
-## 0.0.1
-
-Name claimed. No encoder yet.