flutter_toon 1.0.0

A Flutter package for converting JSON to TOON and TOON to JSON.

flutter_toon

A small Dart/Flutter package for converting JSON to TOON and TOON back to JSON.

TOON is a compact, human-readable text format for structured data (think lightweight YAML tailored for predictable arrays/objects). This package provides a tiny, deterministic encoder/decoder focused on the TOON shapes commonly used in prompts and fixtures.

Highlights

• Encode JSON (decoded or as a string) to TOON via jsonToToon.
• Decode TOON back into a compact JSON string via toonToJson.
• Supports nested objects, primitive arrays, uniform object arrays (table form) and verbose object arrays.
• Small, dependency-free implementation intended for predictable, human-readable output.

Why TOON?

TOON is intentionally designed to be a small, predictable text format that sits between JSON and YAML. Typical reasons to use TOON:

• Human-readable: more compact and less noisy than JSON while remaining obvious to read and edit by hand.
• Compact: reduces visual clutter (less punctuation/quotes) which is useful in examples, docs, and LLM prompts.
• Predictable arrays: distinguishes primitive arrays, uniform object arrays (table form), and verbose arrays so encoded output is easier to consume programmatically.
• Easy to diff & review: fewer spurious changes (no reflowed JSON formatting) makes version control diffs clearer for fixtures and examples.
• Deterministic & round-trippable: designed for reliable encode/decode between JSON and TOON so you can round-trip data without surprises.

Common use-cases: examples and prompts for LLMs, small config/fixture files, human-edited data snippets, and any place you want readable, compact structured data.

Installation

Add the package to your pubspec.yaml (if published on pub.dev) or include it as a local package during development:

dependencies:
	flutter_toon:
		path: ../flutter_toon # adjust path when using the local package

Then run:

dart pub get

Quick start

Import the top-level helpers and convert a Dart map to TOON, and back:

import 'package:flutter_toon/flutter_toon.dart';

void main() {
	final json = {
		'name': 'Mickey',
		'age': 92,
		'isActive': true,
		'tags': ['mouse', 'cartoon'],
		'address': {
			'city': 'Orlando',
			'zip': '32830',
		},
	};

	final toon = jsonToToon(json);
	print('TOON:\n$toon');

	final jsonBack = toonToJson(toon);
	print('\nJSON back:\n$jsonBack');
}

You can also run the included example at example/main.dart:

dart run example/main.dart

API

Top-level helpers (re-exported from the library):

• String jsonToToon(Object? jsonInput)
  • Accepts either a decoded JSON value (Map) or a JSON string. Returns a TOON formatted string.
• String toonToJson(String toonInput)
  • Accepts a TOON string and returns a compact JSON string (suitable for jsonDecode).

Classes (for reference):

• ToonConverter - Convenience class exposing jsonToToon and toonToJson instance methods.

Notes on encoding rules

• Root value must be a JSON object (Map). Non-object root values will throw a FormatException.
• Primitive arrays (all items are strings/numbers/bools/null) are encoded inline: key[n]: a,b,c.
• Uniform object arrays with identical fields are encoded in compact table form: key[n]{field1,field2}: followed by rows.
• Non-uniform or complex arrays are encoded as verbose object arrays where each row is a - bullet with nested property lines.

Examples

1. Simple object:

jsonToToon({'user': {'id': 1, 'name': 'Ada'}});
//
// user:
//   id: 1
//   name: Ada

2. Primitive array:

jsonToToon({'tags': ['a', 'b', 'c']});
// tags[3]: a,b,c

3. Uniform object array (compact table form):

jsonToToon({
	'items': [
		{'id': 1, 'label': 'One'},
		{'id': 2, 'label': 'Two'},
	]
});
//
// items[2]{id,label}:
//   1,One
//   2,Two

4. Verbose object array (mixed/complex objects):

jsonToToon({'rows': [{'a': 1}, {'b': 2}]});
// rows[2]:
//   - a: 1
//   - b: 2

Testing

Run the package tests with:

dart test

Publishing

Before publishing to pub.dev:

• Ensure pubspec.yaml contains homepage, repository, and an appropriate version.
• Update CHANGELOG.md and bump the version if publishing a new release.
• Verify the package with a dry-run:

dart pub publish --dry-run

When you're ready, publish with:

dart pub publish

Publishing will open a browser to authenticate your account.

Contribution

Contributions are welcome. Suggested workflow:

1. Fork the repo and create a feature branch.
2. Run and add tests for bug fixes or features.
3. Keep changes focused and provide a clear commit message.
4. Open a pull request describing the change.

Please follow the repository style (small, focused diffs and tests where appropriate).

License

This project is licensed under the MIT License — see the LICENSE file for details.

Acknowledgements

• Created to provide a small, predictable text format for human-editable data used in prompts, fixtures, and lightweight config.

If you'd like any additional sections (badges, CI instructions, or publishing automation), tell me which one and I will add it.