toon-ruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: aa973e72399a80aea212aefe4128d37ee2f25951962b5f7eb42573c4ba8c297f
+  data.tar.gz: 29e84d1f0c664914ea03c349922c6a47bcfe97d34374ab724197984cffe96870
+SHA512:
+  metadata.gz: 97a54e987de421c56c2f736c873d567f1ab5f82b1dc022f560d8b3677fe826a7b42b6bbda26a4715bdad3fbf085ef8cff849c8d7f9a0c2892eb6c12436e1f685
+  data.tar.gz: bb30d9a9f276fa9f0666c45f1238f84ef6c30dd57025627d0e17d36100e600e3b2f408be8b9e667857fca4e6b39a6d7e5c69ce0ee54abb8468268a60e6d10479

data/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025-PRESENT André Perdigão
+
+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,330 @@
+# TOON for Ruby
+
+**Token-Oriented Object Notation** is a compact, human-readable format designed for passing structured data to Large Language Models with significantly reduced token usage.
+
+This is a Ruby port of the [TOON library](https://github.com/johannschopplich/toon) originally written in TypeScript.
+
+## Why TOON?
+
+AI is becoming cheaper and more accessible, but larger context windows allow for larger data inputs as well. **LLM tokens still cost money** – and standard JSON is verbose and token-expensive:
+
+```json
+{
+  "users": [
+    { "id": 1, "name": "Alice", "role": "admin" },
+    { "id": 2, "name": "Bob", "role": "user" }
+  ]
+}
+```
+
+TOON conveys the same information with **fewer tokens**:
+
+```
+users[2]{id,name,role}:
+  1,Alice,admin
+  2,Bob,user
+```
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'toon'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install toon
+```
+
+## Quick Start
+
+```ruby
+require 'toon'
+
+data = {
+  'user' => {
+    'id' => 123,
+    'name' => 'Ada',
+    'tags' => ['reading', 'gaming'],
+    'active' => true,
+    'preferences' => []
+  }
+}
+
+puts Toon.encode(data)
+```
+
+Output:
+
+```
+user:
+  id: 123
+  name: Ada
+  tags[2]: reading,gaming
+  active: true
+  preferences[0]:
+```
+
+## Key Features
+
+- 💸 **Token-efficient:** typically 30–60% fewer tokens than JSON
+- 🤿 **LLM-friendly guardrails:** explicit lengths and field lists help models validate output
+- 🍱 **Minimal syntax:** removes redundant punctuation (braces, brackets, most quotes)
+- 📐 **Indentation-based structure:** replaces braces with whitespace for better readability
+- 🧺 **Tabular arrays:** declare keys once, then stream rows without repetition
+
+## API
+
+### `Toon.encode(value, **options)`
+
+Converts any value to TOON format.
+
+**Parameters:**
+
+- `value` – Any value to encode (Hash, Array, primitives, or nested structures)
+- `indent` – Number of spaces per indentation level (default: `2`)
+- `delimiter` – Delimiter for array values and tabular rows: `','`, `"\t"`, or `'|'` (default: `','`)
+- `length_marker` – Optional marker to prefix array lengths: `'#'` or `false` (default: `false`)
+
+**Returns:**
+
+A TOON-formatted string with no trailing newline or spaces.
+
+**Examples:**
+
+```ruby
+# Basic usage
+Toon.encode({ 'id' => 1, 'name' => 'Ada' })
+# => "id: 1\nname: Ada"
+
+# Tabular arrays
+items = [
+  { 'sku' => 'A1', 'qty' => 2, 'price' => 9.99 },
+  { 'sku' => 'B2', 'qty' => 1, 'price' => 14.5 }
+]
+Toon.encode({ 'items' => items })
+# => "items[2]{sku,qty,price}:\n  A1,2,9.99\n  B2,1,14.5"
+
+# Custom delimiter (tab)
+Toon.encode(items, delimiter: "\t")
+# => "items[2\t]{sku\tqty\tprice}:\n  A1\t2\t9.99\n  B2\t1\t14.5"
+
+# Length marker
+Toon.encode({ 'tags' => ['a', 'b', 'c'] }, length_marker: '#')
+# => "tags[#3]: a,b,c"
+```
+
+## Format Overview
+
+### Objects
+
+Simple objects with primitive values:
+
+```ruby
+Toon.encode({
+  'id' => 123,
+  'name' => 'Ada',
+  'active' => true
+})
+```
+
+```
+id: 123
+name: Ada
+active: true
+```
+
+Nested objects:
+
+```ruby
+Toon.encode({
+  'user' => {
+    'id' => 123,
+    'name' => 'Ada'
+  }
+})
+```
+
+```
+user:
+  id: 123
+  name: Ada
+```
+
+### Arrays
+
+#### Primitive Arrays (Inline)
+
+```ruby
+Toon.encode({ 'tags' => ['admin', 'ops', 'dev'] })
+```
+
+```
+tags[3]: admin,ops,dev
+```
+
+#### Arrays of Objects (Tabular)
+
+When all objects share the same primitive fields, TOON uses an efficient **tabular format**:
+
+```ruby
+Toon.encode({
+  'items' => [
+    { 'sku' => 'A1', 'qty' => 2, 'price' => 9.99 },
+    { 'sku' => 'B2', 'qty' => 1, 'price' => 14.5 }
+  ]
+})
+```
+
+```
+items[2]{sku,qty,price}:
+  A1,2,9.99
+  B2,1,14.5
+```
+
+#### Mixed and Non-Uniform Arrays
+
+Arrays that don't meet the tabular requirements use list format:
+
+```ruby
+Toon.encode({
+  'items' => [1, { 'a' => 1 }, 'text']
+})
+```
+
+```
+items[3]:
+  - 1
+  - a: 1
+  - text
+```
+
+### Delimiter Options
+
+The `delimiter` option allows you to choose between comma (default), tab, or pipe delimiters:
+
+```ruby
+# Tab delimiter (can save additional tokens)
+data = {
+  'items' => [
+    { 'sku' => 'A1', 'name' => 'Widget', 'qty' => 2 },
+    { 'sku' => 'B2', 'name' => 'Gadget', 'qty' => 1 }
+  ]
+}
+
+Toon.encode(data, delimiter: "\t")
+```
+
+Output:
+
+```
+items[2	]{sku	name	qty}:
+  A1	Widget	2
+  B2	Gadget	1
+```
+
+### Length Marker Option
+
+The `length_marker` option adds a hash (`#`) prefix to array lengths:
+
+```ruby
+data = {
+  'tags' => ['reading', 'gaming', 'coding'],
+  'items' => [
+    { 'sku' => 'A1', 'qty' => 2 },
+    { 'sku' => 'B2', 'qty' => 1 }
+  ]
+}
+
+Toon.encode(data, length_marker: '#')
+```
+
+Output:
+
+```
+tags[#3]: reading,gaming,coding
+items[#2]{sku,qty}:
+  A1,2
+  B2,1
+```
+
+## Type Conversions
+
+Some Ruby types are automatically normalized:
+
+| Input | Output |
+|---|---|
+| `Symbol` | String (`:hello` → `"hello"`) |
+| `Time`, `DateTime` | ISO8601 string |
+| `Date` | ISO8601 string |
+| `Float::INFINITY`, `Float::NAN` | `null` |
+| `Set` | Array |
+
+## Quoting Rules
+
+TOON quotes strings **only when necessary** to maximize token efficiency:
+
+- Empty strings are quoted: `""`
+- Strings with leading/trailing spaces: `" padded "`
+- Strings that look like booleans/numbers: `"true"`, `"42"`
+- Strings with structural characters: `"a,b"`, `"a:b"`, `"[5]"`
+- The active delimiter triggers quoting
+
+Keys follow similar rules and are quoted when needed.
+
+## Using TOON in LLM Prompts
+
+When incorporating TOON into your LLM workflows:
+
+- Wrap TOON data in a fenced code block in your prompt
+- Tell the model: "Do not add extra punctuation or spaces; follow the exact TOON format."
+- When asking the model to generate TOON, specify the same rules (2-space indentation, no trailing spaces, quoting rules)
+
+## Notes and Limitations
+
+- **Token counts vary by tokenizer and model.** Benchmarks use a GPT-style tokenizer; actual savings will differ with other models.
+- **TOON is designed for LLM contexts** where human readability and token efficiency matter. It's **not** a drop-in replacement for JSON in APIs or storage.
+- **Tabular arrays** require all objects to have exactly the same keys with primitive values only.
+- **Object key order** is preserved from the input. In tabular arrays, header order follows the first object's keys.
+
+## Development
+
+After checking out the repo, run:
+
+```bash
+bundle install
+```
+
+Run the test suite:
+
+```bash
+bundle exec rspec
+```
+
+Or simply:
+
+```bash
+rake
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/johannschopplich/toon.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](LICENSE).
+
+## Credits
+
+This is a Ruby port of the original [TOON library](https://github.com/johannschopplich/toon) by [Johann Schopplich](https://github.com/johannschopplich).
+

data/lib/toon/constants.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Toon
+  # List markers
+  LIST_ITEM_MARKER = '-'
+  LIST_ITEM_PREFIX = '- '
+
+  # Structural characters
+  COMMA = ','
+  COLON = ':'
+  SPACE = ' '
+  PIPE = '|'
+
+  # Brackets and braces
+  OPEN_BRACKET = '['
+  CLOSE_BRACKET = ']'
+  OPEN_BRACE = '{'
+  CLOSE_BRACE = '}'
+
+  # Literals
+  NULL_LITERAL = 'null'
+  TRUE_LITERAL = 'true'
+  FALSE_LITERAL = 'false'
+
+  # Escape characters
+  BACKSLASH = '\\'
+  DOUBLE_QUOTE = '"'
+  NEWLINE = "\n"
+  CARRIAGE_RETURN = "\r"
+  TAB = "\t"
+
+  # Delimiters
+  DELIMITERS = {
+    comma: COMMA,
+    tab: TAB,
+    pipe: PIPE
+  }.freeze
+
+  DEFAULT_DELIMITER = DELIMITERS[:comma]
+end

data/lib/toon/encoders.rb

@@ -0,0 +1,261 @@
+# frozen_string_literal: true
+
+require_relative 'constants'
+require_relative 'writer'
+require_relative 'normalizer'
+require_relative 'primitives'
+
+module Toon
+  module Encoders
+    module_function
+
+    extend Normalizer
+    extend Primitives
+
+    # Encode normalized value
+    def encode_value(value, options)
+      if json_primitive?(value)
+        return encode_primitive(value, options[:delimiter])
+      end
+
+      writer = LineWriter.new(options[:indent])
+
+      if json_array?(value)
+        encode_array(nil, value, writer, 0, options)
+      elsif json_object?(value)
+        encode_object(value, writer, 0, options)
+      end
+
+      writer.to_s
+    end
+
+    # Object encoding
+    def encode_object(value, writer, depth, options)
+      keys = value.keys
+
+      keys.each do |key|
+        encode_key_value_pair(key, value[key], writer, depth, options)
+      end
+    end
+
+    def encode_key_value_pair(key, value, writer, depth, options)
+      encoded_key = encode_key(key)
+
+      if json_primitive?(value)
+        writer.push(depth, "#{encoded_key}: #{encode_primitive(value, options[:delimiter])}")
+      elsif json_array?(value)
+        encode_array(key, value, writer, depth, options)
+      elsif json_object?(value)
+        nested_keys = value.keys
+        if nested_keys.empty?
+          # Empty object
+          writer.push(depth, "#{encoded_key}:")
+        else
+          writer.push(depth, "#{encoded_key}:")
+          encode_object(value, writer, depth + 1, options)
+        end
+      end
+    end
+
+    # Array encoding
+    def encode_array(key, value, writer, depth, options)
+      if value.empty?
+        header = format_header(0, key: key, delimiter: options[:delimiter], length_marker: options[:length_marker])
+        writer.push(depth, header)
+        return
+      end
+
+      # Primitive array
+      if array_of_primitives?(value)
+        encode_inline_primitive_array(key, value, writer, depth, options)
+        return
+      end
+
+      # Array of arrays (all primitives)
+      if array_of_arrays?(value)
+        all_primitive_arrays = value.all? { |arr| array_of_primitives?(arr) }
+        if all_primitive_arrays
+          encode_array_of_arrays_as_list_items(key, value, writer, depth, options)
+          return
+        end
+      end
+
+      # Array of objects
+      if array_of_objects?(value)
+        header = detect_tabular_header(value)
+        if header
+          encode_array_of_objects_as_tabular(key, value, header, writer, depth, options)
+        else
+          encode_mixed_array_as_list_items(key, value, writer, depth, options)
+        end
+        return
+      end
+
+      # Mixed array: fallback to expanded format
+      encode_mixed_array_as_list_items(key, value, writer, depth, options)
+    end
+
+    # Primitive array encoding (inline)
+    def encode_inline_primitive_array(prefix, values, writer, depth, options)
+      formatted = format_inline_array(values, options[:delimiter], prefix, options[:length_marker])
+      writer.push(depth, formatted)
+    end
+
+    # Array of arrays (expanded format)
+    def encode_array_of_arrays_as_list_items(prefix, values, writer, depth, options)
+      header = format_header(values.length, key: prefix, delimiter: options[:delimiter], length_marker: options[:length_marker])
+      writer.push(depth, header)
+
+      values.each do |arr|
+        if array_of_primitives?(arr)
+          inline = format_inline_array(arr, options[:delimiter], nil, options[:length_marker])
+          writer.push(depth + 1, "#{LIST_ITEM_PREFIX}#{inline}")
+        end
+      end
+    end
+
+    def format_inline_array(values, delimiter, prefix = nil, length_marker = false)
+      header = format_header(values.length, key: prefix, delimiter: delimiter, length_marker: length_marker)
+      joined_value = join_encoded_values(values, delimiter)
+      # Only add space if there are values
+      if values.empty?
+        header
+      else
+        "#{header} #{joined_value}"
+      end
+    end
+
+    # Array of objects (tabular format)
+    def encode_array_of_objects_as_tabular(prefix, rows, header, writer, depth, options)
+      header_str = format_header(rows.length, key: prefix, fields: header, delimiter: options[:delimiter], length_marker: options[:length_marker])
+      writer.push(depth, header_str)
+
+      write_tabular_rows(rows, header, writer, depth + 1, options)
+    end
+
+    def detect_tabular_header(rows)
+      return nil if rows.empty?
+
+      first_row = rows[0]
+      first_keys = first_row.keys
+      return nil if first_keys.empty?
+
+      if tabular_array?(rows, first_keys)
+        first_keys
+      else
+        nil
+      end
+    end
+
+    def tabular_array?(rows, header)
+      rows.all? do |row|
+        keys = row.keys
+
+        # All objects must have the same keys (but order can differ)
+        return false if keys.length != header.length
+
+        # Check that all header keys exist in the row and all values are primitives
+        header.all? do |key|
+          row.key?(key) && json_primitive?(row[key])
+        end
+      end
+    end
+
+    def write_tabular_rows(rows, header, writer, depth, options)
+      rows.each do |row|
+        values = header.map { |key| row[key] }
+        joined_value = join_encoded_values(values, options[:delimiter])
+        writer.push(depth, joined_value)
+      end
+    end
+
+    # Array of objects (expanded format)
+    def encode_mixed_array_as_list_items(prefix, items, writer, depth, options)
+      header = format_header(items.length, key: prefix, delimiter: options[:delimiter], length_marker: options[:length_marker])
+      writer.push(depth, header)
+
+      items.each do |item|
+        if json_primitive?(item)
+          # Direct primitive as list item
+          writer.push(depth + 1, "#{LIST_ITEM_PREFIX}#{encode_primitive(item, options[:delimiter])}")
+        elsif json_array?(item)
+          # Direct array as list item
+          if array_of_primitives?(item)
+            inline = format_inline_array(item, options[:delimiter], nil, options[:length_marker])
+            writer.push(depth + 1, "#{LIST_ITEM_PREFIX}#{inline}")
+          end
+        elsif json_object?(item)
+          # Object as list item
+          encode_object_as_list_item(item, writer, depth + 1, options)
+        end
+      end
+    end
+
+    def encode_object_as_list_item(obj, writer, depth, options)
+      keys = obj.keys
+      if keys.empty?
+        writer.push(depth, LIST_ITEM_MARKER)
+        return
+      end
+
+      # First key-value on the same line as "- "
+      first_key = keys[0]
+      encoded_key = encode_key(first_key)
+      first_value = obj[first_key]
+
+      if json_primitive?(first_value)
+        writer.push(depth, "#{LIST_ITEM_PREFIX}#{encoded_key}: #{encode_primitive(first_value, options[:delimiter])}")
+      elsif json_array?(first_value)
+        if array_of_primitives?(first_value)
+          # Inline format for primitive arrays
+          formatted = format_inline_array(first_value, options[:delimiter], first_key, options[:length_marker])
+          writer.push(depth, "#{LIST_ITEM_PREFIX}#{formatted}")
+        elsif array_of_objects?(first_value)
+          # Check if array of objects can use tabular format
+          header = detect_tabular_header(first_value)
+          if header
+            # Tabular format for uniform arrays of objects
+            header_str = format_header(first_value.length, key: first_key, fields: header, delimiter: options[:delimiter], length_marker: options[:length_marker])
+            writer.push(depth, "#{LIST_ITEM_PREFIX}#{header_str}")
+            write_tabular_rows(first_value, header, writer, depth + 1, options)
+          else
+            # Fall back to list format for non-uniform arrays of objects
+            writer.push(depth, "#{LIST_ITEM_PREFIX}#{encoded_key}[#{first_value.length}]:")
+            first_value.each do |item|
+              encode_object_as_list_item(item, writer, depth + 1, options)
+            end
+          end
+        else
+          # Complex arrays on separate lines (array of arrays, etc.)
+          writer.push(depth, "#{LIST_ITEM_PREFIX}#{encoded_key}[#{first_value.length}]:")
+
+          # Encode array contents at depth + 1
+          first_value.each do |item|
+            if json_primitive?(item)
+              writer.push(depth + 1, "#{LIST_ITEM_PREFIX}#{encode_primitive(item, options[:delimiter])}")
+            elsif json_array?(item) && array_of_primitives?(item)
+              inline = format_inline_array(item, options[:delimiter], nil, options[:length_marker])
+              writer.push(depth + 1, "#{LIST_ITEM_PREFIX}#{inline}")
+            elsif json_object?(item)
+              encode_object_as_list_item(item, writer, depth + 1, options)
+            end
+          end
+        end
+      elsif json_object?(first_value)
+        nested_keys = first_value.keys
+        if nested_keys.empty?
+          writer.push(depth, "#{LIST_ITEM_PREFIX}#{encoded_key}:")
+        else
+          writer.push(depth, "#{LIST_ITEM_PREFIX}#{encoded_key}:")
+          encode_object(first_value, writer, depth + 2, options)
+        end
+      end
+
+      # Remaining keys on indented lines
+      (1...keys.length).each do |i|
+        key = keys[i]
+        encode_key_value_pair(key, obj[key], writer, depth + 1, options)
+      end
+    end
+  end
+end

data/lib/toon/normalizer.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require 'set'
+require 'date'
+
+module Toon
+  module Normalizer
+    module_function
+
+    # Normalization (unknown → JSON-compatible value)
+    def normalize_value(value)
+      # null
+      return nil if value.nil?
+
+      # Primitives
+      return value if value.is_a?(String) || value.is_a?(TrueClass) || value.is_a?(FalseClass)
+
+      # Numbers: handle special cases
+      if value.is_a?(Numeric)
+        # Float special cases
+        if value.is_a?(Float)
+          # -0.0 becomes 0
+          return 0 if value.zero? && (1.0 / value).negative?
+          # NaN and Infinity become nil
+          return nil unless value.finite?
+        end
+        return value
+      end
+
+      # Symbol → string
+      return value.to_s if value.is_a?(Symbol)
+
+      # Time → ISO8601 string
+      if value.is_a?(Time)
+        return value.utc.strftime('%Y-%m-%dT%H:%M:%SZ')
+      end
+
+      # DateTime → ISO8601 string
+      if value.respond_to?(:iso8601) && !value.is_a?(Date)
+        return value.iso8601
+      end
+
+      # Date → ISO8601 string
+      if value.is_a?(Date)
+        return value.to_time.utc.iso8601
+      end
+
+      # Array
+      if value.is_a?(Array)
+        return value.map { |v| normalize_value(v) }
+      end
+
+      # Set → array
+      if value.is_a?(Set)
+        return value.to_a.map { |v| normalize_value(v) }
+      end
+
+      # Hash/object
+      if value.is_a?(Hash)
+        result = {}
+        value.each do |k, v|
+          result[k.to_s] = normalize_value(v)
+        end
+        return result
+      end
+
+      # Fallback: anything else becomes nil (functions, etc.)
+      nil
+    end
+
+    # Type guards
+    def json_primitive?(value)
+      value.nil? ||
+        value.is_a?(String) ||
+        value.is_a?(Numeric) ||
+        value.is_a?(TrueClass) ||
+        value.is_a?(FalseClass)
+    end
+
+    def json_array?(value)
+      value.is_a?(Array)
+    end
+
+    def json_object?(value)
+      value.is_a?(Hash)
+    end
+
+    # Array type detection
+    def array_of_primitives?(value)
+      return false unless value.is_a?(Array)
+      value.all? { |item| json_primitive?(item) }
+    end
+
+    def array_of_arrays?(value)
+      return false unless value.is_a?(Array)
+      value.all? { |item| json_array?(item) }
+    end
+
+    def array_of_objects?(value)
+      return false unless value.is_a?(Array)
+      value.all? { |item| json_object?(item) }
+    end
+  end
+end

data/lib/toon/primitives.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require_relative 'constants'
+
+module Toon
+  module Primitives
+    module_function
+
+    # Primitive encoding
+    def encode_primitive(value, delimiter = COMMA)
+      return NULL_LITERAL if value.nil?
+      return value.to_s if value.is_a?(TrueClass) || value.is_a?(FalseClass)
+      return value.to_s if value.is_a?(Numeric)
+
+      encode_string_literal(value, delimiter)
+    end
+
+    def encode_string_literal(value, delimiter = COMMA)
+      if safe_unquoted?(value, delimiter)
+        value
+      else
+        "#{DOUBLE_QUOTE}#{escape_string(value)}#{DOUBLE_QUOTE}"
+      end
+    end
+
+    def escape_string(value)
+      value
+        .gsub(BACKSLASH, "#{BACKSLASH}#{BACKSLASH}")
+        .gsub(DOUBLE_QUOTE, "#{BACKSLASH}#{DOUBLE_QUOTE}")
+        .gsub("\n", "#{BACKSLASH}n")
+        .gsub("\r", "#{BACKSLASH}r")
+        .gsub("\t", "#{BACKSLASH}t")
+    end
+
+    def safe_unquoted?(value, delimiter = COMMA)
+      return false if value.empty?
+      return false if padded_with_whitespace?(value)
+      return false if value == TRUE_LITERAL || value == FALSE_LITERAL || value == NULL_LITERAL
+      return false if numeric_like?(value)
+      return false if value.include?(COLON)
+      return false if value.include?(DOUBLE_QUOTE) || value.include?(BACKSLASH)
+      return false if value.match?(/[\[\]{}]/)
+      return false if value.match?(/[\n\r\t]/)
+      return false if value.include?(delimiter)
+      return false if value.start_with?(LIST_ITEM_MARKER)
+
+      true
+    end
+
+    def numeric_like?(value)
+      # Match numbers like: 42, -3.14, 1e-6, 05, etc.
+      value.match?(/^-?\d+(?:\.\d+)?(?:e[+-]?\d+)?$/i) || value.match?(/^0\d+$/)
+    end
+
+    def padded_with_whitespace?(value)
+      value != value.strip
+    end
+
+    # Key encoding
+    def encode_key(key)
+      if valid_unquoted_key?(key)
+        key
+      else
+        "#{DOUBLE_QUOTE}#{escape_string(key)}#{DOUBLE_QUOTE}"
+      end
+    end
+
+    def valid_unquoted_key?(key)
+      # Keys must not contain control characters or special characters
+      return false if key.match?(/[\n\r\t]/)
+      return false if key.include?(COLON)
+      return false if key.include?(DOUBLE_QUOTE) || key.include?(BACKSLASH)
+      return false if key.match?(/[\[\]{}]/)
+      return false if key.include?(COMMA)
+      return false if key.start_with?(LIST_ITEM_MARKER)
+      return false if key.empty?
+      return false if key.match?(/^\d+$/)  # Numeric keys
+      return false if key != key.strip  # Leading/trailing spaces
+
+      key.match?(/^[A-Z_][\w.]*$/i)
+    end
+
+    # Value joining
+    def join_encoded_values(values, delimiter = COMMA)
+      values.map { |v| encode_primitive(v, delimiter) }.join(delimiter)
+    end
+
+    # Header formatters
+    def format_header(length, key: nil, fields: nil, delimiter: COMMA, length_marker: false)
+      header = ''
+
+      header += encode_key(key) if key
+
+      # Only include delimiter if it's not the default (comma)
+      delimiter_suffix = delimiter != DEFAULT_DELIMITER ? delimiter : ''
+      length_prefix = length_marker ? length_marker : ''
+      header += "[#{length_prefix}#{length}#{delimiter_suffix}]"
+
+      if fields
+        quoted_fields = fields.map { |f| encode_key(f) }
+        header += "{#{quoted_fields.join(delimiter)}}"
+      end
+
+      header += COLON
+
+      header
+    end
+  end
+end

data/lib/toon/version.rb

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

data/lib/toon/writer.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Toon
+  class LineWriter
+    def initialize(indent_size)
+      @lines = []
+      @indentation_string = ' ' * indent_size
+    end
+
+    def push(depth, content)
+      indent = @indentation_string * depth
+      @lines << indent + content
+    end
+
+    def to_s
+      @lines.join("\n")
+    end
+  end
+end

data/lib/toon.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative 'toon/version'
+require_relative 'toon/constants'
+require_relative 'toon/writer'
+require_relative 'toon/normalizer'
+require_relative 'toon/primitives'
+require_relative 'toon/encoders'
+
+module Toon
+  module_function
+
+  # Encode any value to TOON format
+  #
+  # @param input [Object] Any value to encode
+  # @param indent [Integer] Number of spaces per indentation level (default: 2)
+  # @param delimiter [String] Delimiter for array values and tabular rows (default: ',')
+  # @param length_marker [String, false] Optional marker to prefix array lengths (default: false)
+  # @return [String] TOON-formatted string
+  def encode(input, indent: 2, delimiter: DEFAULT_DELIMITER, length_marker: false)
+    normalized_value = Normalizer.normalize_value(input)
+    options = resolve_options(indent: indent, delimiter: delimiter, length_marker: length_marker)
+    Encoders.encode_value(normalized_value, options)
+  end
+
+  def resolve_options(indent:, delimiter:, length_marker:)
+    {
+      indent: indent,
+      delimiter: delimiter,
+      length_marker: length_marker
+    }
+  end
+end

metadata

@@ -0,0 +1,84 @@
+--- !ruby/object:Gem::Specification
+name: toon-ruby
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- André Perdigão
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2025-10-27 00:00:00.000000000 Z
+dependencies:
+- !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.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+description: TOON is a compact, human-readable format designed for passing structured
+  data to Large Language Models with significantly reduced token usage.
+email:
+- andrepcg@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/toon.rb
+- lib/toon/constants.rb
+- lib/toon/encoders.rb
+- lib/toon/normalizer.rb
+- lib/toon/primitives.rb
+- lib/toon/version.rb
+- lib/toon/writer.rb
+homepage: https://github.com/andrepcg/toon-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/andrepcg/toon-ruby
+  source_code_uri: https://github.com/andrepcg/toon-ruby
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key: 
+specification_version: 4
+summary: Token-Oriented Object Notation – a token-efficient JSON alternative for LLM
+  prompts
+test_files: []