J Toon

JToon–Java的TOON格式

   Coverage  

⚠️ 测试状态（v1.x.x）： 该库正在积极开发中，并致力于规范合规性。Beta已发布到Maven Central。API可能会在2.0.0版本之前更改。

LLM上下文的紧凑、人类可读的序列化格式 代币减少30-60% vs JSON。将类似YAML的缩进与类似CSV的表格数组相结合。努力实现与 官方TOON规范.

主要特点： 最小语法•TOON编码和解码•用于统一数据的表格数组•数组长度验证•Java 17•完整 杰克逊注释 支持•全面的测试覆盖。

安装

Maven 中央仓库

JToon可在Maven Central上使用。使用首选构建工具将其添加到您的项目中：

Gradle（Groovy DSL）：

dependencies {
    implementation 'dev.toonformat:jtoon:1.0.9'
}

Gradle（Kotlin DSL）：

dependencies {
    implementation("dev.toonformat:jtoon:1.0.9")
}

Maven：

    dev.toonformat
    jtoon
    1.0.9

注： 请参阅 最新版本 在Maven Central上（也显示在上面的徽章中）。

替代方案：手动安装

您还可以直接从以下网址下载JAR 页面并将其添加到项目的类路径中。

快速开始

import dev.toonformat.jtoon.JToon;
import java.util.*;

record User(int id, String name, List tags, boolean active, List preferences) {}
record Data(User user) {}

User user = new User(123, "Ada", List.of("reading", "gaming"), true, List.of());
Data data = new Data(user);

System.out.println(JToon.encode(data));

输出：

user:
  id: 123
  name: Ada
  tags[2]: reading,gaming
  active: true
  preferences[0]:

类型转换

一些特定于Java的类型会自动规范化为LLM安全输出：

API

JToon.encode(Object value): String

JToon.encode(Object value, EncodeOptions options): String

JToon.encodeJson(String json): String

JToon.encodeJson(String json, EncodeOptions options): String

将任何Java对象或JSON字符串转换为TOON格式。

参数：

• value 任何Java对象（映射、列表、基元或嵌套结构）。不可序列化的值被转换为 nullJava时态类型被转换为ISO字符串，Optional被解包，Stream被物化。
• options –可选编码选项(EncodeOptions 记录）：

- indent –每个缩进级别的空格数（默认值： 2) - delimiter –数组值和表格行的分隔符枚举： Delimiter.COMMA （默认）， Delimiter.TAB，或 Delimiter.PIPE - lengthMarker –布尔值用于在数组长度前加上前缀 # （默认值： false) - flatten –布尔值用于折叠单个钥匙包装链（默认值： OFF). - flattenDepth –要折叠的最大分段数（默认值： Infinity)

对于 encodeJson 过载：

• json –要解析和编码的有效JSON字符串。JSON抛出无效或为空 IllegalArgumentException.

退货：

一个TOON格式的字符串，没有换行符或空格。

例子：

import dev.toonformat.jtoon.JToon;
import com.fasterxml.jackson.annotation.JsonIgnore;
import java.util.*;

record Item(String sku, int qty, double price,  @JsonIgnore double internPrice) {}
record Data(List items) {}

Item item1 = new Item("A1", 2, 9.99, 8.50);
Item item2 = new Item("B2", 1, 14.5, 14.0);
Data data = new Data(List.of(item1, item2));

System.out.println(JToon.encode(data));

输出：

items[2]{sku,qty,price}:
  A1,2,9.99
  B2,1,14.5

这 杰克逊注释 @JsonIgnore将有助于防止字段暴露。

对纯JSON字符串进行编码

String json = """
{
  "user": {
    "id": 123,
    "name": "Ada",
    "tags": ["reading", "gaming"]
  }
}
""";
System.out.println(JToon.encodeJson(json));

输出：

user:
  id: 123
  name: Ada
  tags[2]: reading,gaming

分隔符选项

这 delimiter 选项允许您在逗号（默认）、制表符或管道分隔符之间为数组值和表格行进行选择。替代分隔符可以在特定上下文中提供额外的令牌节省。

制表符分隔符(\t)

使用制表符而不是逗号可以进一步减少标记计数，特别是对于表格数据：

import dev.toonformat.jtoon.*;
import java.util.*;

record Item(String sku, String name, int qty, double price) {}

record Data(List items) {}

Item item1 = new Item("A1", "Widget", 2, 9.99);
Item item2 = new Item("B2", "Gadget", 1, 14.5);
Data data = new Data(List.of(item1, item2));

EncodeOptions options = new EncodeOptions(2, Delimiter.TAB, false, KeyFolding.OFF, 3);
System.out.println(JToon.encode(data, options));

输出：

items[2 ]{sku name qty price}:
  A1 Widget 2 9.99
  B2 Gadget 1 14.5

优点：

• 制表符是单个字符，通常比逗号更有效地进行标记。
• 制表符很少出现在自然文本中，减少了引号转义的需要。
• 分隔符在数组头中显式编码，使其具有自描述性。

注意事项：

• 某些终端和编辑器可能会在视觉上折叠或展开选项卡。
• 包含制表符的字符串值仍需要引用。

管道分隔符(|)

管道分隔符在逗号和制表符之间提供了一个中间地带：

// Using the same Item and Data records from above
EncodeOptions options = new EncodeOptions(2, Delimiter.PIPE, false, KeyFolding.OFF, 3);
System.out.println(JToon.encode(data, options));

输出：

items[2|]{sku|name|qty|price}:
  A1|Widget|2|9.99
  B2|Gadget|1|14.5

长度标记选项

这 lengthMarker 选项添加可选哈希(#)在数组长度前添加前缀，以强调括号内的值表示计数，而不是索引：

import dev.toonformat.jtoon.*;
import java.util.*;

record Item(String sku, int qty, double price) {}

record Data(List tags, List items) {}

Item item1 = new Item("A1", 2, 9.99);
Item item2 = new Item("B2", 1, 14.5);
Data data = new Data(List.of("reading", "gaming", "coding"), List.of(item1, item2));

System.out.println(JToon.encode(data, new EncodeOptions(2, Delimiter.COMMA, true, KeyFolding.OFF, 3)));
// tags[#3]: reading,gaming,coding
// items[#2]{sku,qty,price}:
//   A1,2,9.99
//   B2,1,14.5

// Works with custom delimiters
System.out.println(JToon.encode(data, new EncodeOptions(2, Delimiter.PIPE, true, KeyFolding.OFF, 3)));
// tags[#3|]: reading|gaming|coding
// items[#2|]{sku|qty|price}:
//   A1|2|9.99
//   B2|1|14.5

JToon.decode(String toon): Object

JToon.decode(String toon, DecodeOptions options): Object

JToon.decodeToJson(String toon): String

JToon.decodeToJson(String toon, DecodeOptions options): String

将TOON格式的字符串转换回Java对象或JSON。

参数：

• toon –TOON格式的输入字符串
• options –可选解码选项(DecodeOptions 记录）：

- indent –每个缩进级别的空格数（默认值： 2) - delimiter –预期分隔符： Delimiter.COMMA （默认）， Delimiter.TAB，或 Delimiter.PIPE - strict –用于验证模式的布尔值。当 true （默认），throws IllegalArgumentException 输入无效。当 false，返回 null 关于错误。 - expandPaths –虚线键的布尔路径扩展模式（默认值： OFF).

退货：

对于 decode：Java对象(Map 对于物体， List 对于数组，标量的基元，或 null)

对于 decodeToJson：JSON字符串表示

例子：

import dev.toonformat.jtoon.JToon;

String toon = """
    users[2]{id,name,role}:
      1,Alice,admin
      2,Bob,user
    """;

// Decode to Java objects
Object result = JToon.decode(toon);

// Decode directly to JSON string
String json = JToon.decodeToJson(toon);

往返转换

import dev.toonformat.jtoon.*;
import java.util.*;

// Original data
Map data = new LinkedHashMap<>();
data.put("id", 123);
data.put("name", "Ada");
data.put("tags", Arrays.asList("dev", "admin"));

 // Encode to TOON
String toon = JToon.encode(data);

// Decode back to objects
 Object decoded = JToon.decode(toon);

// Values are preserved (note: integers decode as Long)

自定义解码选项

import dev.toonformat.jtoon.*;

String toon = "tags[3|]: a|b|c";

// Decode with pipe delimiter
DecodeOptions options = new DecodeOptions(2, Delimiter.PIPE, true);
Object result = JToon.decode(toon, options);

// Lenient mode (returns null on errors instead of throwing)
DecodeOptions lenient = DecodeOptions.withStrict(false);
Object result2 = JToon.decode(invalidToon, lenient);

CI/CD： GitHub操作•Java 17•覆盖执行•PR覆盖评论

项目状态

该项目100%符合TOON规范。在CI/CD上强制执行发布一致性。

看 贡献.md 详细指南。

文档

• 📘 全部文件 -扩展指南和参考
• 🔧 API 参考 -详细Javadoc
• 📋 格式规范 -TOON语法和规则
• 📜 TOON规格 -官方规范
• 🐛 问题 -Bug报告和功能
• 🤝 贡献 -贡献指南

许可证

MIT许可证——见 许可证 详情