module RbToon

RbToon: Toon decoder for Ruby

Toon is a structural text format optimized for LLM input. RbToon is a Racc-based decoder gem that decodes Toon input into Ruby objects.

Constants

VERSION: Version string of RbToon.

Public Class Methods

decode ( string_or_io, filename: 'unknown', symbolize_names: false, strict: true, path_expansion: false, indent_size: 2, debug: false )

Source

    # File lib/rbtoon.rb
 90 def decode(
 91   string_or_io,
 92   filename: 'unknown', symbolize_names: false,
 93   strict: true, path_expansion: false, indent_size: 2, debug: false
 94 )
 95   toon =
 96     if string_or_io.is_a?(String)
 97       string_or_io
 98     else
 99       string_or_io.read
100     end
101 
102   output = parse(toon, filename, strict, indent_size, debug)
103   output.validate(strict:)
104   output.to_ruby(symbolize_names:, strict:, path_expansion:)
105 end

Decode the given Toon string into Ruby objects.

Example:

toon = RbToon.decode(<<~'TOON')
context:
  task: Our favorite hikes together
  location: Boulder
  season: spring_2025
friends[3]: ana,luis,sam
hikes[3]{id,name,distanceKm,elevationGain,companion,wasSunny}:
  1,Blue Lake Trail,7.5,320,ana,true
  2,Ridge Overlook,9.2,540,luis,false
  3,Wildflower Loop,5.1,180,sam,true
TOON
# =>
# {
#   "context" => {
#     "task" => "Our favorite hikes together",
#     "location" => "Boulder", "season" => "spring_2025"
#   },
# ...

Error Handling:

RbToon::ParseError is raised when the given Toon includes errors listed in the Toon spec.

begin
  RbToon.decode('freends[4]: ana,Luis,sam')
rescue RbToon::ParseError => e
  e
end
# => #<RbToon::ParseError: expected 4 array items, but got 3 -- filename: unknown line: 1 column: 8>

Arguments:

string_or_io: String or IO object containing Toon string to be parsed.
filename: Filename string which is used for the exception message. (default: ‘unknown’)
symbolize_names: All hash keys are symbolized when this option is true. (default: false)
strict: The strict mode is disabled and some error checks are not performed when this option is false. See the Toon spec for more details. (default: true)
path_expansion: Dotted keys are split into nested objects when this option is true. See the Toon spec for more details. (default: false)
indent_size: Indentation unit used to calucurate indentation depth. See the Toon spec for more details. (default: 2)
debug: Debug messages are displayed when this option is set to true. (default: false)

decode_file (filename, **optargs)

Source

    # File lib/rbtoon.rb
111 def decode_file(filename, **optargs)
112   File.open(filename, 'r:bom|utf-8') do |fp|
113     decode(fp, filename:, **optargs)
114   end
115 end

Similar to RbToon.decode, but the Toon string is read from the file specified by the filename argument.