{"id":42132043,"url":"https://github.com/mamantoha/toon-crystal","last_synced_at":"2026-03-02T22:38:50.878Z","repository":{"id":321761309,"uuid":"1086607951","full_name":"mamantoha/toon-crystal","owner":"mamantoha","description":"Crystal implementation of the Token-Oriented Object Notation(TOON) serialization format","archived":false,"fork":false,"pushed_at":"2026-02-25T12:46:39.000Z","size":112,"stargazers_count":9,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-25T16:42:03.681Z","etag":null,"topics":["data-format","llm","serialization","tokenizer"],"latest_commit_sha":null,"homepage":"","language":"Crystal","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mamantoha.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-30T16:44:47.000Z","updated_at":"2026-02-25T12:45:50.000Z","dependencies_parsed_at":"2026-01-08T11:04:51.534Z","dependency_job_id":null,"html_url":"https://github.com/mamantoha/toon-crystal","commit_stats":null,"previous_names":["mamantoha/toon-crystal"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/mamantoha/toon-crystal","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mamantoha%2Ftoon-crystal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mamantoha%2Ftoon-crystal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mamantoha%2Ftoon-crystal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mamantoha%2Ftoon-crystal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mamantoha","download_url":"https://codeload.github.com/mamantoha/toon-crystal/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mamantoha%2Ftoon-crystal/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30022939,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-02T22:30:10.381Z","status":"ssl_error","status_checked_at":"2026-03-02T22:23:34.650Z","response_time":60,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["data-format","llm","serialization","tokenizer"],"created_at":"2026-01-26T16:00:23.286Z","updated_at":"2026-03-02T22:38:50.855Z","avatar_url":"https://github.com/mamantoha.png","language":"Crystal","funding_links":[],"categories":["Data Formats"],"sub_categories":[],"readme":"# TOON Format for Crystal\n\n[![Crystal CI](https://github.com/mamantoha/toon-crystal/actions/workflows/crystal.yml/badge.svg)](https://github.com/mamantoha/toon-crystal/actions/workflows/crystal.yml)\n[![GitHub release](https://img.shields.io/github/release/mamantoha/toon-crystal.svg)](https://github.com/mamantoha/flag_emoji/releases)\n[![License](https://img.shields.io/github/license/mamantoha/toon-crystal.svg)](https://github.com/mamantoha/toon-crystal/blob/main/LICENSE)\n\n**Token-Oriented Object Notation** is a compact, human-readable serialization format designed for passing structured data to Large Language Models with significantly reduced token usage. It's intended for LLM input, not output.\n\nThis is a Crystal reference implementation of the [TOON format specification](https://github.com/toon-format/spec).\n\n\u003e **Note:** This implementation supports **TOON Format Specification Version** 3.0.3 (2026-02-23).\n\n## Installation\n\nAdd this to your `shard.yml`:\n\n```yaml\ndependencies:\n  toon:\n    github: mamantoha/toon-crystal\n```\n\nThen run:\n\n```bash\nshards install\n```\n\n## Quick Start\n\n```crystal\nrequire \"toon\"\n\ndata = {\n  \"user\" =\u003e {\n    \"id\" =\u003e 123,\n    \"name\" =\u003e \"Ada\",\n    \"tags\" =\u003e [\"reading\", \"gaming\"],\n    \"active\" =\u003e true,\n    \"preferences\" =\u003e [] of String\n  }\n}\n\nputs Toon.encode(data)\n```\n\nOutput:\n\n```\nuser:\n  id: 123\n  name: Ada\n  tags[2]: reading,gaming\n  active: true\n  preferences[0]:\n```\n\nYou can also decode TOON back to Crystal values:\n\n```crystal\ntoon = \u003c\u003c-TOON\n  user:\n    id: 123\n    name: Ada\n    tags[2]: reading,gaming\n    active: true\n    preferences[0]:\n  TOON\n\nvalue = Toon.decode(toon)\n# =\u003e {\"user\" =\u003e {\"id\" =\u003e 123, \"name\" =\u003e \"Ada\", \"tags\" =\u003e [\"reading\", \"gaming\"], \"active\" =\u003e true, \"preferences\" =\u003e []}}\n```\n\n## API\n\n### `Toon.encode(value, *, indent = 2, delimiter = ',', key_folding = KeyFoldingMode::Off, flatten_depth = nil)`\n\nConverts any value to TOON format.\n\n**Parameters:**\n\n- `value` – Any value to encode (Hash, Array, primitives, or nested structures)\n- `indent` – Number of spaces per indentation level (default: `2`)\n- `delimiter` – Delimiter for array values and tabular rows: `','`, `'\\t'`, or `'|'` (default: `','`)\n- `key_folding` – Optional key folding mode (`KeyFoldingMode::Off` | `KeyFoldingMode::Safe`), defaults to `Off`\n- `flatten_depth` – Optional max number of segments to fold when `key_folding` is `Safe` (default: Infinity when `nil`)\n\n**Returns:**\n\nA TOON-formatted string with no trailing newline or spaces.\n\n**Examples:**\n\n```crystal\n# Basic usage\nToon.encode({ \"id\" =\u003e 1, \"name\" =\u003e \"Ada\" })\n# =\u003e \"id: 1\\nname: Ada\"\n\n# Key folding (safe)\nToon.encode({ \"a\" =\u003e { \"b\" =\u003e { \"c\" =\u003e 1 } } }, key_folding: :safe)\n# =\u003e \"a.b.c: 1\"\n\n# Key folding with flattenDepth\nToon.encode({ \"a\" =\u003e { \"b\" =\u003e { \"c\" =\u003e 1 } } }, key_folding: :safe, flatten_depth: 2)\n# =\u003e \"a.b:\\n  c: 1\"\n\n# Tabular arrays\nitems = [\n  { \"sku\" =\u003e \"A1\", \"qty\" =\u003e 2, \"price\" =\u003e 9.99 },\n  { \"sku\" =\u003e \"B2\", \"qty\" =\u003e 1, \"price\" =\u003e 14.5 }\n]\nToon.encode({ \"items\" =\u003e items })\n# =\u003e \"items[2]{sku,qty,price}:\\n  A1,2,9.99\\n  B2,1,14.5\"\n\n# Custom delimiter (tab)\nToon.encode({ \"items\" =\u003e items }, delimiter: '\\t')\n# =\u003e \"items[2\t]{sku\tqty\tprice}:\\n  A1\\t2\\t9.99\\n  B2\\t1\\t14.5\"\n```\n\n### `Toon.decode(input, *, indent = 2, strict = true, expand_paths = ExpandPathsMode::Off)`\n\nParses a TOON-formatted string into native Crystal values.\n\n**Parameters:**\n\n- `input` – TOON-formatted string\n- `indent` – Number of spaces per indentation level (default: `2`)\n- `strict` – Enable validations for indentation, tabs, blank lines, and extra rows/items (default: `true`)\n- `expand_paths` – Optional path expansion mode (`ExpandPathsMode::Off` | `ExpandPathsMode::Safe`) to split dotted keys into nested objects (default: `Off`)\n\n**Returns:**\n\nA Crystal value (`Nil | Bool | Int64 | Float64 | String | Array | Hash(String, _)`).\n\n**Examples:**\n\n```crystal\nToon.decode(\"tags[3]: a,b,c\")\n# =\u003e {\"tags\" =\u003e [\"a\", \"b\", \"c\"]}\n\nToon.decode(\"[2]{id}:\\n  1\\n  2\")\n# =\u003e [{\"id\" =\u003e 1}, {\"id\" =\u003e 2}]\n\nToon.decode(\"items[2]:\\n  - id: 1\\n    name: First\\n  - id: 2\\n    name: Second\")\n# =\u003e {\"items\" =\u003e [{\"id\" =\u003e 1, \"name\" =\u003e \"First\"}, {\"id\" =\u003e 2, \"name\" =\u003e \"Second\"}]}\n\n# Path expansion (safe)\nToon.decode(\"a.b.c: 1\", expand_paths: :safe)\n# =\u003e {\"a\" =\u003e {\"b\" =\u003e {\"c\" =\u003e 1}}}\n```\n\n## Development\n\nAfter checking out the repo, run:\n\n```bash\nshards install\n```\n\n### Updating the Spec Submodule\n\nThis project uses the [TOON specification repository](https://github.com/toon-format/spec) as a git submodule at `ext/spec`. This contains the language-agnostic test fixtures.\n\n**Initial setup** (when cloning the repo):\n```bash\ngit submodule update --init --recursive\n```\n\n**Update the spec submodule** to get the latest test fixtures:\n```bash\ngit submodule update --remote ext/spec\n```\n\nThis will pull the latest commits from the upstream spec repository and update the submodule reference.\n\n### Running Tests\n\nRun the test suite:\n\n```bash\ncrystal spec\n```\n\nThe test suite uses fixtures from `ext/spec/tests/fixtures/` and automatically discovers all fixture files in the encode and decode directories.\n\n## Resources\n\n- [TOON Specification](https://github.com/toon-format/spec/blob/main/SPEC.md)\n- [Main Repository](https://github.com/toon-format/toon)\n- [Benchmarks \u0026 Performance](https://github.com/toon-format/toon#benchmarks)\n- [Other Language Implementations](https://github.com/toon-format/toon#other-implementations)\n\n## Contributing\n\n1. Fork it (\u003chttps://github.com/mamantoha/toon-crystal/fork\u003e)\n2. Create your feature branch (`git checkout -b my-new-feature`)\n3. Commit your changes (`git commit -am 'Add some feature'`)\n4. Push to the branch (`git push origin my-new-feature`)\n5. Create a new Pull Request\n\n## Contributors\n\n- [Anton Maminov](https://github.com/mamantoha) - creator and maintainer\n\n## License\n\nThe project is available as open source under the terms of the [MIT License](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmamantoha%2Ftoon-crystal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmamantoha%2Ftoon-crystal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmamantoha%2Ftoon-crystal/lists"}