toon_plus 0.0.4 copy "toon_plus: ^0.0.4" to clipboard
toon_plus: ^0.0.4 copied to clipboard

Published 19 days ago
SDKDartFlutter
PlatformAndroidiOSLinuxmacOSwebWindows
β†’

Metadata

A compact, human-readable data serialization format that reduces token usage by 30-50% compared to JSON while maintaining readability. Perfect for LLM applications and API optimization.

More...

TOON Plus #

pub package License: MIT

A compact, human-readable data serialization format that reduces token usage by 30-50% compared to JSON. Perfect for LLM applications, API optimization, and anywhere you need efficient data encoding.

🎯 Key Features #

  • πŸš€ Compact: 30-50% fewer tokens than JSON
  • πŸ“– Human Readable: Easy to read, write, and debug
  • πŸ”„ Bidirectional: Full encode/decode support with type preservation
  • ⚑ Pure Dart: Zero dependencies, works everywhere
  • 🎯 Type Safe: Preserves primitives, objects, and arrays
  • πŸ› οΈ Customizable: Configure indentation and delimiters
  • πŸ’― Well Tested: Comprehensive test coverage
  • πŸ“š Well Documented: Extensive examples and API documentation

πŸ“¦ Installation #

Add to your pubspec.yaml:

dependencies:
  toon_plus: ^0.0.4

Then run:

dart pub get

πŸš€ Quick Start #

Encoding #

import 'package:toon_plus/toon_plus.dart';

void main() {
  final data = {
    'user': 'Alice',
    'age': 30,
    'active': true,
    'scores': [95, 87, 92],
  };
  
  final toon = encode(data);
  print(toon);
}

Output:

user: Alice
age: 30
active: true
scores[3]: 95,87,92

Decoding #

import 'package:toon_plus/toon_plus.dart';

void main() {
  final toon = '''
user: Alice
age: 30
active: true
scores[3]: 95,87,92
''';
  
  final data = decode(toon);
  print(data);
  // {user: Alice, age: 30, active: true, scores: [95, 87, 92]}
}

πŸ“– Complete Examples #

Complex Nested Structures #

final data = {
  'project': 'TOON Format',
  'version': '0.0.4',
  'author': {
    'name': 'Vardon Bainbridge',
    'email': 'vardon.bainbridge@gmail.com',
  },
  'features': ['encoding', 'decoding', 'compression'],
  'stats': {
    'stars': 100,
    'downloads': 5000,
  },
};

final toon = encode(data);
print(toon);

Output:

project: TOON Format
version: 0.0.4
author:
  name: Vardon Bainbridge
  email: vardon.bainbridge@gmail.com
features[3]: encoding,decoding,compression
stats:
  stars: 100
  downloads: 5000

Arrays of Objects #

final users = {
  'users': [
    {'name': 'Alice', 'role': 'admin'},
    {'name': 'Bob', 'role': 'user'},
    {'name': 'Charlie', 'role': 'moderator'},
  ],
};

print(encode(users));

Output:

users[3]:
  - name: Alice
    role: admin
  - name: Bob
    role: user
  - name: Charlie
    role: moderator

Custom Configuration #

// 4-space indentation
final toon1 = encode(data, indent: 4);

// Pipe-delimited arrays
final toon2 = encode(data, delimiter: '|');

// Custom decode indentation
final decoded = decode(toonString, indent: 4);

πŸ’‘ Why TOON? #

Token Efficiency #

TOON significantly reduces token count compared to JSON, crucial for LLM applications where token usage affects both cost and context window limits.

JSON (145 characters, ~40 tokens):

{
  "name": "Alice",
  "age": 30,
  "city": "New York",
  "hobbies": ["reading", "coding", "gaming"]
}

TOON (87 characters, ~24 tokens):

name: Alice
age: 30
city: New York
hobbies[3]: reading,coding,gaming

Savings: ~40% fewer tokens! πŸŽ‰

Use Cases #

  • LLM Prompts: Reduce token usage in prompts and responses
  • API Payloads: Smaller request/response bodies
  • Configuration Files: More readable than JSON, more compact than YAML
  • Data Exchange: Efficient serialization for microservices
  • Log Files: Compact, human-readable log entries
  • Cache Keys: Smaller serialized values for caching

πŸ“š TOON Format Specification #

Primitives #

  • Strings: Unquoted when safe, double-quoted otherwise
  • Numbers: As-is (integers and decimals)
  • Booleans: true or false
  • Null: null

Objects #

Key-value pairs with colon separator:

name: Alice
age: 30

Nested Objects #

Indentation-based nesting:

user:
  name: Alice
  profile:
    bio: Software Engineer
    location: NYC

Arrays #

Inline (for primitives):

numbers[5]: 1,2,3,4,5
colors[3]: red,green,blue

Multi-line (for complex items):

users[2]:
  - name: Alice
  - name: Bob

Quoted Strings #

Strings requiring quotes (contain special chars, numbers, or keywords):

"key with spaces": value
url: "https://example.com"
special: "value,with,commas"
numeric: "12345"

πŸ”§ API Reference #

encode(dynamic value, {int indent = 2, String delimiter = ','}) #

Encodes a Dart value into TOON format.

Parameters:

  • value: Map, List, or primitive to encode
  • indent: Spaces per indentation level (default: 2)
  • delimiter: Array item delimiter (default: ',')

Returns: String in TOON format

Example:

final toon = encode({'name': 'Alice', 'age': 30});
final toon4 = encode(data, indent: 4);
final toonPipe = encode(data, delimiter: '|');

decode(String toonString, {int indent = 2}) #

Decodes TOON format into a Dart value.

Parameters:

  • toonString: TOON formatted string
  • indent: Expected indentation size (default: 2)

Returns: Decoded Map, List, or primitive

Example:

final data = decode('name: Alice\\nage: 30');
final data4 = decode(toonString, indent: 4);

Delimiters #

Available delimiters for array encoding:

  • Delimiters.comma - , (default)
  • Delimiters.tab - \\t
  • Delimiters.pipe - |

πŸ§ͺ Testing #

Run the test suite:

dart test

Run the example:

dart run example/main.dart

🀝 Contributing #

Contributions are welcome! Please feel free to submit a Pull Request.

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

πŸ“„ License #

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

πŸ‘€ Author #

Vardon Bainbridge

🌟 Show Your Support #

Give a ⭐️ if this project helped you!

πŸ“ Changelog #

See CHANGELOG.md for a list of changes.

πŸ”— Links #

🎯 Key Features #

  • πŸš€ Compact: 30-50% fewer tokens than JSON
  • πŸ“– Human Readable: Easy to read, write, and debug
  • πŸ”„ Bidirectional: Full encode/decode support with type preservation
  • ⚑ Pure Dart: Zero dependencies, works everywhere
  • 🎯 Type Safe: Preserves primitives, objects, and arrays
  • πŸ› οΈ Customizable: Configure indentation and delimiters
  • πŸ’― Well Tested: Comprehensive test coverage
  • πŸ“š Well Documented: Extensive examples and API documentation

πŸ“¦ Installation #

Add to your pubspec.yaml:

dependencies:
  toon: ^0.0.1

Then run:

dart pub get

πŸš€ Quick Start #

Encoding #

import 'package:toon/toon.dart';

void main() {
  final data = {
    'user': 'Alice',
    'age': 30,
    'active': true,
    'scores': [95, 87, 92],
  };
  
  final toon = encode(data);
  print(toon);
}

Output:

user: Alice
age: 30
active: true
scores[3]: 95,87,92

Decoding #

import 'package:toon/toon.dart';

void main() {
  final toon = '''
user: Alice
age: 30
active: true
scores[3]: 95,87,92
''';
  
  final data = decode(toon);
  print(data);
  // {user: Alice, age: 30, active: true, scores: [95, 87, 92]}
}

πŸ“– Complete Examples #

Complex Nested Structures #

final data = {
  'project': 'TOON Format',
  'version': '0.0.1',
  'author': {
    'name': 'Vardon Bainbridge',
    'email': 'vardon.bainbridge@gmail.com',
  },
  'features': ['encoding', 'decoding', 'compression'],
  'stats': {
    'stars': 100,
    'downloads': 5000,
  },
};

final toon = encode(data);
print(toon);

Output:

project: TOON Format
version: 1.0.0
author:
  name: Vardon Bainbridge
  email: vardon.bainbridge@gmail.com
features[3]: encoding,decoding,compression
stats:
  stars: 100
  downloads: 5000

Arrays of Objects #

final users = {
  'users': [
    {'name': 'Alice', 'role': 'admin'},
    {'name': 'Bob', 'role': 'user'},
    {'name': 'Charlie', 'role': 'moderator'},
  ],
};

print(encode(users));

Output:

users[3]:
  - name: Alice
    role: admin
  - name: Bob
    role: user
  - name: Charlie
    role: moderator

Custom Configuration #

// 4-space indentation
final toon1 = encode(data, indent: 4);

// Pipe-delimited arrays
final toon2 = encode(data, delimiter: '|');

// Custom decode indentation
final decoded = decode(toonString, indent: 4);

πŸ’‘ Why TOON? #

Token Efficiency #

TOON significantly reduces token count compared to JSON, crucial for LLM applications where token usage affects both cost and context window limits.

JSON (145 characters, ~40 tokens):

{
  "name": "Alice",
  "age": 30,
  "city": "New York",
  "hobbies": ["reading", "coding", "gaming"]
}

TOON (87 characters, ~24 tokens):

name: Alice
age: 30
city: New York
hobbies[3]: reading,coding,gaming

Savings: ~40% fewer tokens! πŸŽ‰

Use Cases #

  • LLM Prompts: Reduce token usage in prompts and responses
  • API Payloads: Smaller request/response bodies
  • Configuration Files: More readable than JSON, more compact than YAML
  • Data Exchange: Efficient serialization for microservices
  • Log Files: Compact, human-readable log entries
  • Cache Keys: Smaller serialized values for caching

πŸ“š TOON Format Specification #

Primitives #

  • Strings: Unquoted when safe, double-quoted otherwise
  • Numbers: As-is (integers and decimals)
  • Booleans: true or false
  • Null: null

Objects #

Key-value pairs with colon separator:

name: Alice
age: 30

Nested Objects #

Indentation-based nesting:

user:
  name: Alice
  profile:
    bio: Software Engineer
    location: NYC

Arrays #

Inline (for primitives):

numbers[5]: 1,2,3,4,5
colors[3]: red,green,blue

Multi-line (for complex items):

users[2]:
  - name: Alice
  - name: Bob

Quoted Strings #

Strings requiring quotes (contain special chars, numbers, or keywords):

"key with spaces": value
url: "https://example.com"
special: "value,with,commas"
numeric: "12345"

πŸ”§ API Reference #

encode(dynamic value, {int indent = 2, String delimiter = ','}) #

Encodes a Dart value into TOON format.

Parameters:

  • value: Map, List, or primitive to encode
  • indent: Spaces per indentation level (default: 2)
  • delimiter: Array item delimiter (default: ',')

Returns: String in TOON format

Example:

final toon = encode({'name': 'Alice', 'age': 30});
final toon4 = encode(data, indent: 4);
final toonPipe = encode(data, delimiter: '|');

decode(String toonString, {int indent = 2}) #

Decodes TOON format into a Dart value.

Parameters:

  • toonString: TOON formatted string
  • indent: Expected indentation size (default: 2)

Returns: Decoded Map, List, or primitive

Example:

final data = decode('name: Alice\nage: 30');
final data4 = decode(toonString, indent: 4);

Delimiters #

Available delimiters for array encoding:

  • Delimiters.comma - , (default)
  • Delimiters.tab - \t
  • Delimiters.pipe - |

πŸ§ͺ Testing #

Run the test suite:

dart test

Run the example:

dart run example/main.dart

🀝 Contributing #

Contributions are welcome! Please feel free to submit a Pull Request.

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

πŸ“„ License #

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

πŸ‘€ Author #

Vardon Bainbridge

🌟 Show Your Support #

Give a ⭐️ if this project helped you!

πŸ“ Changelog #

See CHANGELOG.md for a list of changes.

πŸ”— Links #

← Metadata

1
likes
140
points
168
downloads

Publisher

unverified uploader

Weekly Downloads

Metadata

A compact, human-readable data serialization format that reduces token usage by 30-50% compared to JSON while maintaining readability. Perfect for LLM applications and API optimization.

Repository (GitHub)
View/report issues

Topics

#toon #json #decoding #encoding #token-optimization

Documentation

Documentation
API reference

License

MIT (license)

More

Packages that depend on toon_plus

Back